1# Interfaces (Others) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--SE: @liyang_bryan--> 6<!--TSE: @xchaosioda--> 7 8> **NOTE** 9> 10> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 11 12## PositionArea<sup>7+</sup> 13 14Describes area information in an image. 15 16**Widget capability**: This API can be used in ArkTS widgets since API version 12. 17 18**Atomic service API**: This API can be used in atomic services since API version 11. 19 20**System capability**: SystemCapability.Multimedia.Image.Core 21 22| Name | Type | Read Only| Optional| Description | 23| ------ | ------------------ | ---| -----|------------------------------------------------------- | 24| pixels | ArrayBuffer | No| No | Pixels of the image. Only pixel data in BGRA_8888 format is supported.| 25| offset | number | No| No | Offset for data reading, in bytes. | 26| stride | number | No| No | Number of bytes from one row of pixels in memory to the next row of pixels in memory. The value of **stride** must be greater than or equal to the value of **region.size.width** multiplied by 4. | 27| region | [Region](#region8) | No| No |Region to read or write. The width of the region to write plus the X coordinate cannot be greater than the width of the original image. The height of the region to write plus the Y coordinate cannot be greater than the height of the original image.| 28 29## ImageInfo 30 31Describes image information. 32 33**System capability**: SystemCapability.Multimedia.Image.Core 34 35| Name| Type | Read Only| Optional| Description | 36| ---- | ------------- | --- |-----|---------- | 37| size<sup>6+</sup> | [Size](#size) | No| No |Image size.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 38| density<sup>9+</sup> | number | No | No|Pixel density, in ppi.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 39| stride<sup>11+</sup> | number | No | No | Number of bytes from one row of pixels in memory to the next row of pixels in memory.stride >= region.size.width*4 <br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 40| pixelFormat<sup>12+</sup> | [PixelMapFormat](arkts-apis-image-e.md#pixelmapformat7) | No | No| Pixel format.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 41| alphaType<sup>12+</sup> | [AlphaType](arkts-apis-image-e.md#alphatype9) | No | No |Alpha type.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 42| mimeType<sup>12+</sup> | string | No | No |Actual image format (MIME type). | 43| isHdr<sup>12+</sup> | boolean | No | No | Whether the image is an HDR image. The value **true** means an HDR image, and **false** means an SDR image. For [ImageSource](arkts-apis-image-ImageSource.md), this parameter specifies whether the source image is in HDR format. For [PixelMap](arkts-apis-image-PixelMap.md), this parameter specifies whether the decoded PixelMap is in HDR format.| 44 45## Size 46 47Describes the size of an image. 48 49**Widget capability**: This API can be used in ArkTS widgets since API version 12. 50 51**Atomic service API**: This API can be used in atomic services since API version 11. 52 53**System capability**: SystemCapability.Multimedia.Image.Core 54 55| Name | Type | Read Only| Optional |Description | 56| ------ | ------ | -- |-----| -------------- | 57| height | number | No | No |Image height, in px.| 58| width | number | No | No| Image width, in px.| 59 60## AuxiliaryPictureInfo<sup>13+</sup> 61 62Describes the auxiliary picture information. 63 64**System capability**: SystemCapability.Multimedia.Image.Core 65 66| Name | Type | Read Only| Optional| Description | 67| ------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 68| auxiliaryPictureType | [AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13) | No | No | Auxiliary picture type. | 69| size | [Size](#size) | No | No | Image size.| 70| rowStride | number | No | No | Row stride. | 71| pixelFormat | [PixelMapFormat](arkts-apis-image-e.md#pixelmapformat7) | No | No | Pixel format.| 72| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | No | No | Color space. | 73 74## SourceOptions<sup>9+</sup> 75 76Defines image source initialization options. 77 78**Widget capability**: This API can be used in ArkTS widgets since API version 12. 79 80**Atomic service API**: This API can be used in atomic services since API version 11. 81 82**System capability**: SystemCapability.Multimedia.Image.Core 83 84| Name | Type | Read Only| Optional| Description | 85| ----------------- | ---------------------------------- | ---- | ---- | ------------------ | 86| sourceDensity | number | No | No | Pixel density of the image resource, in ppi.<br>If **desiredSize** is not set in [DecodingOptions](#decodingoptions7) and **SourceOptions.sourceDensity** and **DecodingOptions.fitDensity** are not 0, the PixelMap output after decoding will be scaled.<br>The formula for calculating the width after scaling is as follows (the same applies to the height): (width * fitDensity + (sourceDensity >> 1)) / sourceDensity.| 87| sourcePixelFormat | [PixelMapFormat](arkts-apis-image-e.md#pixelmapformat7) | No | Yes | Image pixel format. The default value is **UNKNOWN**. | 88| sourceSize | [Size](#size) | No | Yes | Image pixel size. The default value is null. | 89 90## InitializationOptions<sup>8+</sup> 91 92Defines PixelMap initialization options. 93 94**System capability**: SystemCapability.Multimedia.Image.Core 95 96| Name | Type | Read Only|Optional| Description | 97| ------------------------ | ---------------------------------- | ----| -----| -------------- | 98| alphaType<sup>9+</sup> | [AlphaType](arkts-apis-image-e.md#alphatype9) | No | Yes| Alpha type. The default value is **IMAGE_ALPHA_TYPE_PREMUL**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 99| editable | boolean | No | Yes| Whether the image is editable. The value **true** means that the image is editable, and **false** means the opposite. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 100| srcPixelFormat<sup>12+</sup> | [PixelMapFormat](arkts-apis-image-e.md#pixelmapformat7) | No| Yes| Pixel format of the passed-in buffer data. The default value is **BGRA_8888**.| 101| pixelFormat | [PixelMapFormat](arkts-apis-image-e.md#pixelmapformat7) | No| Yes| Pixel format of the generated PixelMap. The default value is **RGBA_8888**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 102| scaleMode<sup>9+</sup> | [ScaleMode](arkts-apis-image-e.md#scalemode9) | No | Yes| Scale mode. The default value is **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 103| size | [Size](#size) | No | No|Image size.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 104 105## DecodingOptions<sup>7+</sup> 106 107Describes the image decoding options. 108 109**System capability**: SystemCapability.Multimedia.Image.ImageSource 110 111| Name | Type | Read Only| Optional| Description | 112| ------------------ | ---------------------------------- | ---- | ---- | ---------------- | 113| sampleSize | number | No | Yes | Sampling size of the thumbnail. The default value is **1**. Currently, the value can only be **1**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 114| rotate | number | No | Yes | Rotation angle. The default value is **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 115| editable | boolean | No | Yes | Whether the image is editable. The value **true** means that the image is editable, and **false** means the opposite. The default value is **false**. If this option is set to **false**, the image cannot be edited again, and operations such as writing pixels will fail.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 116| desiredSize | [Size](#size) | No | Yes | Expected output size. The value must be a positive integer and defaults to the original image size. If the output size is different from the original size, the output is stretched or scaled to the specified size.<br>Note: If both **desiredSize** and **desiredRegion** are passed to the decoding API, you must also include **cropAndScaleStrategy** to determine whether to crop or scale first. **CROP_FIRST** is recommended.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 117| desiredRegion | [Region](#region8) | No | Yes | Rectangle specified by **Region** in the decoded image. When the original image is large and only a specific part of the image is required, you can set this parameter to improve performance. The default value is the original image size.<br>Note: If both **desiredSize** and **desiredRegion** are passed to the decoding API, you must also include **cropAndScaleStrategy** to determine whether to crop or scale first. **CROP_FIRST** is recommended.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 118| desiredPixelFormat | [PixelMapFormat](arkts-apis-image-e.md#pixelmapformat7) | No | Yes | Pixel format for decoding. The default value is **RGBA_8888**. Only RGBA_8888, BGRA_8888, and RGB_565 are supported. RGB_565 is not supported for images with alpha channels, such as PNG, GIF, ICO, and WEBP.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12.| 119| index | number | No | Yes | Index of the image to decode. The default value is **0**, indicating the first image. If this parameter is set to N, the (N+1)th image is used. For single-frame images, the value is always **0**. For multi-frame images such as animations, the value ranges from 0 to (Number of frames – 1).<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 120| fitDensity<sup>9+</sup> | number | No | Yes | Pixel density, in ppi. The default value is **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 12. | 121| desiredColorSpace<sup>11+</sup> | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | No | Yes | Target color space. The default value is **UNKNOWN**.| 122| desiredDynamicRange<sup>12+</sup> | [DecodingDynamicRange](arkts-apis-image-e.md#decodingdynamicrange12) | No | Yes | Desired dynamic range. The default value is **SDR**.<br>This property cannot be set for an image source created using [CreateIncrementalSource](arkts-apis-image-f.md#imagecreateincrementalsource9). By default, the image source is decoded as SDR content.<br>If the platform does not support HDR, the setting is invalid and the content is decoded as SDR content by default.| 123| cropAndScaleStrategy<sup>18+</sup> | [CropAndScaleStrategy](arkts-apis-image-e.md#cropandscalestrategy18) | No | Yes | If **desiredRegion** and **desiredSize** are both specified, the order of cropping and scaling is determined.<br>Only **SCALE_FIRST** and **CROP_FIRST** are supported.| 124 125## DecodingOptionsForPicture<sup>13+</sup> 126 127Describes the image decoding options. 128 129**System capability**: SystemCapability.Multimedia.Image.ImageSource 130 131| Name | Type | Read Only| Optional| Description | 132| ------------------------ | ------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | 133| desiredAuxiliaryPictures | Array\<[AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13)> | No | No | Auxiliary picture type. By default, all auxiliary picture types are decoded.| 134 135## Region<sup>8+</sup> 136 137Describes the region information. 138 139**Widget capability**: This API can be used in ArkTS widgets since API version 12. 140 141**Atomic service API**: This API can be used in atomic services since API version 11. 142 143**System capability**: SystemCapability.Multimedia.Image.Core 144 145| Name| Type | Read Only| Optional| Description | 146| ---- | ------------- | ---- | ---- | ------------ | 147| size<sup>7+</sup> | [Size](#size) | No | No | Region size. | 148| x<sup>7+</sup> | number | No | No | X coordinate of the upper left corner of the region, in px.| 149| y<sup>7+</sup> | number | No | No | Y coordinate of the upper left corner of the region, in px.| 150 151## PackingOption 152 153Describes the options for image encoding. 154 155**System capability**: SystemCapability.Multimedia.Image.ImagePacker 156 157| Name | Type | Read Only| Optional| Description | 158| ------- | ------ | ---- | ---- | --------------------------------------------------- | 159| format | string | No | No | Format of the packed image.<br>Currently, only the following formats are supported: image/jpeg, image/webp, image/png, image/heic (or image/heif)<sup>12+</sup>, image/sdr_astc_4x4<sup>18+</sup>, image/sdr_sut_superfast_4x4<sup>18+</sup> (depending on the hardware), and image/hdr_astc_4x4<sup>20+</sup>.<br>**NOTE**: The JPEG format does not support the alpha channel. If the JPEG format with the alpha channel is used for data encoding, the transparent color turns black.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 160| quality | number | No | No | Quality of the output image set. This parameter takes effect only for JPEG and HEIF images. The value range is [0, 100]. The value **0** means the lowest quality, and **100** means the highest quality. The higher the quality, the larger the space occupied by the generated image. WebP and PNG images are lossless.<br>In the case of sdr_astc_4x4 encoding, the parameter can be set to **92** and **85**.<br>In the case of sut encoding, the parameter can be set to **92**.<br>(Available since API version 20) In the case of hdr_astc_4x4 encoding, the parameter can be set to **85**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 161| bufferSize<sup>9+</sup> | number | No | Yes | Size of the buffer for receiving the encoded data, in bytes. If this parameter is not set, the default value 25 MB is used. If the size of an image exceeds 25 MB, you must specify the size. The value of **bufferSize** must be greater than the size of the encoded image. The use of [packToFile](arkts-apis-image-ImagePacker.md#packtofile11) is not restricted by this parameter.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 162| desiredDynamicRange<sup>12+</sup> | [PackingDynamicRange](arkts-apis-image-e.md#packingdynamicrange12) | No | Yes | Desired dynamic range. The default value is **SDR**.| 163| needsPackProperties<sup>12+</sup> | boolean | No | Yes | Whether to encode image property information, for example, EXIF. The value **true** means to encode image property information, and **false** means the opposite. The default value is **false**.| 164 165## PackingOptionsForSequence<sup>18+</sup> 166 167Defines the options for encoding animated images. 168 169**System capability**: SystemCapability.Multimedia.Image.ImagePacker 170 171| Name | Type | Read Only| Optional| Description | 172| ------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 173| frameCount | number | No | No | Number of frames specified in GIF encoding. | 174| delayTimeList | Array\<number> | No | No | Delay time of each frame in GIF encoding. The value must be greater than 0.<br>The unit is 10 milliseconds. For example, if this parameter is set to 10, the actual delay per frame is 100 ms.<br>If the array length is less than **frameCount**, the last value in the array will be used for the remaining frames.| 175| disposalTypes | Array\<number> | No | Yes | Array that defines how each image frame transitions. If the array length is less than **frameCount**, the last value in the array will be used for the remaining frames. The values can be:<br>- **0**: No operation is required.<br>- **1**: Keeps the image unchanged.<br>- **2**: Restores the background color.<br>- **3**: Restores to the previous state.| 176| loopCount | number | No | Yes | Number of times that the output image in GIF encoding loops. The value range is [0, 65535].<br>The value **0** means an infinite loop. If this field is not carried, loop playback is not performed.| 177 178## ImagePropertyOptions<sup>11+</sup> 179 180Describes the image properties. 181 182**System capability**: SystemCapability.Multimedia.Image.ImageSource 183 184| Name | Type | Read Only| Optional| Description | 185| ------------ | ------ | ---- | ---- | ------------ | 186| index | number | No | Yes | Index of the image. The default value is **0**. | 187| defaultValue | string | No | Yes | Default property value. The default value is null.| 188 189## Component<sup>9+</sup> 190 191Describes the color components of an image. 192 193**System capability**: SystemCapability.Multimedia.Image.Core 194 195| Name | Type | Read Only| Optional| Description | 196| ------------- | -------------------------------- | ---- | ---- | ------------ | 197| componentType | [ComponentType](arkts-apis-image-e.md#componenttype9) | Yes | No | Color component type. | 198| rowStride | number | Yes | No | Row stride. The camera preview stream data needs to be read by stride. For details, see [Solution to Screen Artifacts During Camera Preview](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-deal-stride-solution). | 199| pixelStride | number | Yes | No | Pixel stride. | 200| byteBuffer | ArrayBuffer | Yes | No | Component buffer.| 201 202## HdrStaticMetadata<sup>12+</sup> 203 204Describes the static metadata keys, that is, the values available for **HDR_STATIC_METADATA** in [HdrMetadataKey](arkts-apis-image-e.md#hdrmetadatakey12). 205 206**System capability**: SystemCapability.Multimedia.Image.Core 207 208| Name | Type | Read Only| Optional| Description | 209| ------------- | ----------| -- | -- | ------------ | 210| displayPrimariesX | Array\<number> | No| No| X coordinate of the three primary colors of the display device after normalization. The array length is 3. The unit is 0.00002. The value range is [0.0, 1.0]. | 211| displayPrimariesY | Array\<number> | No| No| Y coordinate of the three primary colors of the display device after normalization. The array length is 3. The unit is 0.00002. The value range is [0.0, 1.0]. | 212| whitePointX | number | No| No| X coordinate of the white point after normalization. The unit is 0.00002. The value range is [0.0, 1.0]. | 213| whitePointY | number | No| No| Y coordinate of the white point after normalization. The unit is 0.00002. The value range is [0.0, 1.0]. | 214| maxLuminance | number | No| No| Maximum luminance of the main monitor. The unit is 1, and the maximum value is 65535. | 215| minLuminance | number | No| No| Minimum luminance of the main monitor. The unit is 0.0001, and the maximum value is 6.55535. | 216| maxContentLightLevel | number | No| No| Maximum luminance of the displayed content. The unit is 1, and the maximum value is 65535. | 217| maxFrameAverageLightLevel | number | No| No| Maximum average luminance of the displayed content. The unit is 1, and the maximum value is 65535.| 218 219## GainmapChannel<sup>12+</sup> 220 221Describes the data content of a single channel of the gain map. For details, see ISO 21496-1. 222 223**System capability**: SystemCapability.Multimedia.Image.Core 224 225| Name | Type | Read Only| Optional| Description | 226| ------------- | ----------| -- | -- | ------------ | 227| gainmapMax | number | No| No| Maximum value of the gain map. For details, see ISO 21496-1. | 228| gainmapMin | number | No| No| Minimum value of the gain map. For details, see ISO 21496-1. | 229| gamma | number | No| No| Gamma. For details, see ISO 21496-1. | 230| baseOffset | number | No| No| Offset of the base graphic. For details, see ISO 21496-1. | 231| alternateOffset | number | No| No| Offset of the alternative graphic that can be extracted. For details, see ISO 21496-1. | 232 233## HdrGainmapMetadata<sup>12+</sup> 234 235Describes the metadata keys used by a gain map, that is, the values available for **HDR_GAINMAP_METADATA** in [HdrMetadataKey](arkts-apis-image-e.md#hdrmetadatakey12). For details, see ISO 21496-1. 236 237**System capability**: SystemCapability.Multimedia.Image.Core 238 239| Name | Type | Read Only| Optional| Description | 240| ------------- | ----------| -- | -- | ------------ | 241| writerVersion | number | No| No| Version used by the metadata editor. | 242| miniVersion | number | No| No| Minimum version that needs to be understood for metadata parsing. | 243| gainmapChannelCount | number | No| No| Number of color channels of the gain map. When the value is 3, the metadata values of the RGB channels are different. When the value is 1, the metadata values of the RGB channels are the same. For details, see ISO 21496-1. | 244| useBaseColorFlag | boolean | No| No| Whether to use the color space of the base graphic. For details, see ISO 21496-1. The value **true** means to use the color space of the base graphic, and **false** means the opposite. | 245| baseHeadroom | number | No| No| Headroom of the base graphic, which means the additional brightness that can be added to the base graphic. For details, see ISO 21496-1. | 246| alternateHeadroom | number | No| No| Headroom of the alternate graphic. For details, see ISO 21496-1. | 247| channels | Array<[GainmapChannel](#gainmapchannel12)> | No| No| Number of channels. The length is 3. For details, see ISO 21496-1.| 248 249## GetImagePropertyOptions<sup>(deprecated)</sup> 250 251Describes the image properties. 252 253> **NOTE** 254> 255> This API is deprecated since API version 11. You are advised to use [ImagePropertyOptions](#imagepropertyoptions11). 256 257**System capability**: SystemCapability.Multimedia.Image.ImageSource 258 259| Name | Type | Read Only| Optional| Description | 260| ------------ | ------ | ---- | ---- | ------------ | 261| index | number | No | Yes | Index of the image. The default value is **0**. | 262| defaultValue | string | No | Yes | Default property value. The default value is null.| 263