How to write image metadata (HTML)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This shows you how to use a BitmapEncoder object to write image metadata. You can write metadata using Windows properties or the Windows Imaging Component (WIC) metadata query language.

For more info about metadata access using BitmapDecoder and BitmapEncoder, see How to read image metadata.

Note  You can use the Windows.Storage.FileProperties APIs to get and set basic properties on a Windows.StorageFile without opening a stream. See How to get image properties, for more info.

 

What you need to know

Technologies

Prerequisites

Instructions

Step 1: Get an encoder object

Write the beginning a function that receives a BitmapEncoder object.

function (encoder) {
    

The encoder lets you to access the image metadata. If you don't have a encoder object yet, see How to encode a new image.

Step 2: Create a collection of metadata to set

Use a BitmapPropertySet to store metadata items that you want to set on the encoder. Each metadata item is a key-value pair.

The key is a string that identifies the metadata item to set. BitmapEncoder accepts some Windows properties as well as queries constructed using the WIC metadata query language. For a list of supported Windows properties, see Supported Windows properties. For a summary of supported WIC metadata queries, see WIC native image format metadata queries.

The value is a BitmapTypedValue which lets you to associate the actual metadata value with an explicit data type (Windows.Foundation.PropertyType).

Set the System.Photo.Orientation metadata, which specifies the EXIF orientation, to a value of 1, which specifies a "normal" orientation, and assign it a data type of uint16.

    var propertySet = new Windows.Graphics.Imaging.BitmapPropertySet();
    var orientationValue = new Windows.Graphics.Imaging.BitmapTypedValue(
        1, // Defined as EXIF orientation = "normal"
        Windows.Foundation.PropertyType.uint16
        );

    propertySet.insert("System.Photo.Orientation", orientationValue);     

Step 3: Set the metadata on the encoder

After you are done constructing all of the metadata items, set them on the encoder and continue with the encoding operation.

    encoder.bitmapProperties.setPropertiesAsync(propertySet).done(function () {
        // Continue the encoding operation.
    }, function (error) {
        switch (error.number) {
            case -2003292351: // WINCODEC_ERR_PROPERTYNOTSUPPORTED
                // The file format does not support this property.
                break;
            default:
                throw error;
        }
    });
}    

Note  Each image format supports a different set of metadata items. If you attempt to set a metadata or property item which is not supported by the image format, you will get an error. For example, only JPEG, TIFF and JPEG-XR images support the System.Photo.Orientation property.

 

Remarks

Setting multiple properties works the same as setting a single property, but you specify multiple name-value pairs in a list. The code here sets the Orientation and the CameraModel at the same time.

encoder.savePropertiesAsync(["System.Photo.Orientation": 1],
                                                         "System.Photo.CameraModel": "Camera Model 1"]);

How to encode an image

System.Photo Properties

How to read image metadata

WIC metadata query language

WIC native image format metadata queries

Supported Windows properties