目录

Using ImageSource to Obtain Specific Metadata

Starting from API version 23, you can use ImageSource to obtain specific metadata from various image formats, including GIF, HEIFS, DNG, WebP, PNG, JFIF, TIFF, and AVIS.

The following table lists the starting API version supported by each format.

Supported Metadata Categories

Metadata Category MetadataType Return Field Starting API Version Typical Information
GIF GIF_METADATA GifMetadata 26.0.0 Frame delay time, loop count, canvas size, etc.
HEIFS HEIFS_METADATA HeifsMetadata 23 Canvas height, canvas width, unclamped delay time, etc.
DNG DNG_METADATA DngMetadata 24 DNG version, camera model, CFA parameters, black/white levels, color correction matrix, etc.
WebP WEBP_METADATA WebPMetadata 24 Canvas size, frame delay time, loop count, etc.
PNG PNG_METADATA PngMetadata 26.0.0 Pixel density, description, copyright, etc.
JFIF JFIF_METADATA JfifMetadata 26.0.0 Pixel density, progressive encoding, etc.
TIFF TIFF_METADATA TiffMetadata 26.0.0 Resolution, chromaticity coordinates, compression method, etc.
AVIS AVIS_METADATA AvisMetadata 26.0.0 Frame delay time, etc.

HeifsMetadata is available since API version 23, and three properties (heifsCanvasWidth, heifsCanvasHeight, and heifsUnclampedDelayTime) are newly added in API version 26.0.0.

Available APIs

API Description
readImageMetadata

Reads the metadata of an image source, using propertyKeys to specify the metadata fields.

Supported since API version 23.
readImageMetadataByType

Reads the metadata of an image source, using metadataTypes to specify the metadata types.

Supported since API version 24.

How to Develop

For details about the APIs for obtaining image-specific metadata, see ImageSource and Metadata.

  1. Import the Image module globally, and import the corresponding Kit modules as needed.

    // Import the related modules.
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import { fileIo } from '@kit.CoreFileKit';
import { resourceManager } from '@kit.LocalizationKit';

  2. Create an ImageSource instance by referring to Using ImageSource for Image Decoding.

  3. Read specific metadata.

    Use the readImageMetadata API to read specific metadata of the corresponding format by specifying property keys (propertyKeys). The following example reads the frame delay time in GIF metadata:

    async readImageMetadata(imageSource: image.ImageSource | undefined) : Promise<image.ImageMetadata | undefined> {
  if (imageSource == undefined) {
    console.error('imageSource is undefined.');
    return undefined;
  }
  try {
    let properties: string[] = [image.GifPropertyKey.GIF_DELAY_TIME];
    let index: number = 0;
    let imageMetadata: image.ImageMetadata = await imageSource.readImageMetadata(properties, index);
    if (imageMetadata.gifMetadata != undefined) {
      console.info(`GIF_DELAY_TIME: ${JSON.stringify(imageMetadata.gifMetadata?.delayTime)}`);
    }
    return imageMetadata
  } catch (error) {
    console.error(`ReadImageMetadata failed, error.code: ${error.code},
               error.message: ${error.message}`)
    return undefined;
  }
}

    Use the readImageMetadataByType API to read specific metadata of the corresponding format by specifying a MetadataType enum value. The following example reads GIF metadata:

    async readImageMetadataByType(imageSource: image.ImageSource | undefined) : Promise<image.ImageMetadata | undefined> {
  if (imageSource == undefined) {
    console.error('imageSource is undefined.');
    return undefined;
  }
  try {
    let types: image.MetadataType[] = [image.MetadataType.GIF_METADATA];
    let index: number = 0;
    let imageMetadata: image.ImageMetadata = await imageSource.readImageMetadataByType(types, index);
    if (imageMetadata.gifMetadata != undefined) {
      console.info(`GIF_DELAY_TIME: ${JSON.stringify(imageMetadata.gifMetadata?.delayTime)}`);
    }
    return imageMetadata;
  } catch (error) {
    console.error(`ReadImageMetadataByType failed, error.code: ${error.code},
               error.message: ${error.message}`)
    return undefined;
  }
}

  4. Release the imageSource.

    After confirming that the asynchronous method of imageSource has completed execution and the variable is no longer in use, you can manually call the following method to release it as needed.

    async release() {
  try {
    await this.pixelMap?.release();
  } catch (error) {
    console.error(`Failed to release PixelMap: ${error}.`);
  } finally {
    this.pixelMap = undefined;
  }

  try {
    await this.imageSource?.release();
  } catch (error) {
    console.error(`Failed to release ImageSource: ${error}.`);
  } finally {
    this.imageSource = undefined;
  }
}

Precautions