@ohos.multimedia.image (图片处理)(系统接口)

本模块提供图片处理效果，包括通过属性创建PixelMap、读取图像像素数据、读取区域内的图片数据等。

说明：

本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.multimedia.image (图片处理)。

导入模块

import { image } from '@kit.ImageKit';

GainmapParams

Gainmap（增益图）参数设置选项。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.Core

名称	类型	只读	可选	说明
isFullSizeGainmap	boolean	否	否	返回Picture中的Gainmap（增益图）是否使用全尺寸图。 true表示使用全尺寸图，宽高和主图一致；false表示不使用全尺寸图，宽高均为主图的一半。默认值为false。

DecodingOptions⁷⁺

图像解码设置选项。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.ImageSource

名称	类型	只读	可选	说明
resolutionQuality¹²⁺	ResolutionQuality	否	是	画质效果等级。

ResolutionQuality¹²⁺

枚举，画质效果等级类型。

系统能力： SystemCapability.Multimedia.Image.Core

名称	值	说明
LOW	1	低画质效果，解码耗时短。此接口为系统接口。
MEDIUM	2	中等画质效果，解码耗时中等。此接口为系统接口。
HIGH	3	最高等级画质效果，解码耗时长。此接口为系统接口。

PropertyKey⁷⁺

枚举，Exif（Exchangeable image file format）图像信息。

格式示例中的key为：image.PropertyKey.XXX（XXX为枚举的名称，如：image.PropertyKey.XTSTYLE_TEMPLATE_NAME）。
格式示例仅用于说明修改传值和读取结果的格式。具体接口使用方法请参考：modifyImageProperty（修改单个Exif字段）、modifyImageProperties（修改多个Exif字段）、getImageProperty（读取单个Exif字段）、getImageProperties（读取多个Exif字段）。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.Core

名称	值	说明
XTSTYLE_TEMPLATE_NAME	'HwMnoteXtStyleTemplateName'	个性色卡模板名称。起始版本： 26.0.0
XTSTYLE_CUSTOM_LIGHT_AND_SHADOW	'HwMnoteXtStyleCustomLightAndShadow'	个性色卡自定义光影。起始版本： 26.0.0
XTSTYLE_CUSTOM_SATURATION	'HwMnoteXtStyleCustomSaturation'	个性色卡自定义饱和度。起始版本： 26.0.0
XTSTYLE_CUSTOM_HUE	'HwMnoteXtStyleCustomHue'	个性色卡自定义色调。起始版本： 26.0.0
XTSTYLE_EXPOSURE_PARAM	'HwMnoteXtStyleExposureParam'	个性色卡曝光参数。起始版本： 26.0.0

image.createPictureByHdrAndSdrPixelMap²⁰⁺

createPictureByHdrAndSdrPixelMap(hdrPixelMap: PixelMap, sdrPixelMap: PixelMap): Promise<Picture>

根据HDR PixelMap和SDR PixelMap创建Picture对象。系统将使用HDR和SDR PixelMap生成一个增益图（gainmap），返回的Picture对象将包含SDR PixelMap和生成的gainmap PixelMap，像素格式为RGBA8888。使用Promise异步回调。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名	类型	必填	说明
hdrPixelMap	PixelMap	是	HDR PixelMap，位深16bit或10bit，像素格式为FP16/RGBA1010102/YCBCR_P010，色彩空间是BT2020_HLG。
sdrPixelMap	PixelMap	是	SDR PixelMap，位深8bit，像素格式为RGBA8888/NV21，色彩空间是P3。

返回值：

类型	说明
Promise<Picture>	返回Picture包含sdr和gainmap，像素格式为RGBA8888。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID	错误信息
7600201	Unsupported operation. HdrPixelMap's PixelMapFormat is not RGBA_F16\RGBA_1010102\YCBCR_P010, or its color space is not BT2020_HLG. Or sdrPixelMap's PixelMapFormat is not RGBA_8888\NV21\NV12, or its color space is not P3.

示例：

import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function CreatePictureTest(context: Context) {
  const resourceMgr = context.resourceManager;
  const rawFile = await resourceMgr.getRawFileContent("test.jpg"); // SDR
  let imageSource: image.ImageSource = image.createImageSource(rawFile);
  let options1: image.DecodingOptions = {
    desiredDynamicRange : image.DecodingDynamicRange.SDR,
  }
  let options2: image.DecodingOptions = {
    desiredDynamicRange : image.DecodingDynamicRange.HDR, // 通过AIHDR将SDR解码为HDR。
  }
  let sdrPixelMap = await imageSource.createPixelMap(options1);
  let hdrPixelMap = await imageSource.createPixelMap(options2);

  // 获取计算生成的gainmap并编码。
  let picture: image.Picture = await image.createPictureByHdrAndSdrPixelMap(hdrPixelMap, sdrPixelMap);
  if (picture != null) {
    console.info('Create picture succeeded');
  } else {
    console.error('Create picture failed');
  }
  const imagePackerObj = image.createImagePacker();
  let packOpts : image.PackingOption = { format : "image/jpeg", quality: 98};
  packOpts.desiredDynamicRange = image.PackingDynamicRange.AUTO;
  const path: string = context.filesDir + "/hdr-test.jpg";
  let file = fileIo.openSync(path, fileIo.OpenMode.CREATE | fileIo.OpenMode.READ_WRITE);
  imagePackerObj.packToFile(picture, file.fd, packOpts).then(() => {
  }).catch((error : BusinessError) => {
    console.error('Failed to pack the image. And the error is: ' + error);
  })
}

image.createPictureByHdrAndSdrPixelMap

createPictureByHdrAndSdrPixelMap(hdrPixelMap: PixelMap, sdrPixelMap: PixelMap, params: GainmapParams): Promise<Picture>

根据HDR PixelMap和SDR PixelMap创建Picture对象。系统将使用HDR和SDR PixelMap生成一个Gainmap（增益图），返回的Picture对象将包含SDR PixelMap和生成的Gainmap PixelMap，像素格式为RGBA8888。Gainmap PixelMap的尺寸可以通过设置params进行选择。使用Promise异步回调。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名	类型	必填	说明
hdrPixelMap	PixelMap	是	HDR PixelMap，位深16bit或10bit，像素格式为RGBA_F16/RGBA_1010102/YCBCR_P010，色彩空间是BT2020_HLG。
sdrPixelMap	PixelMap	是	SDR PixelMap，位深8bit，像素格式为RGBA_8888/NV21，色彩空间是P3。
params	GainmapParams	是	Gainmap Params，增益图参数设置选项，决定是否使用全尺寸增益图。

返回值：

类型	说明
Promise<Picture>	Promise对象，返回Picture包含SDR和Gainmap，像素格式为RGBA_8888。

错误码：

以下错误码的详细介绍请参见Image错误码和通用错误码。

错误码ID	错误信息
7600201	Unsupported operation. HdrPixelMap's PixelMapFormat is not RGBA_F16\RGBA_1010102\YCBCR_P010, or its color space is not BT2020_HLG. Or sdrPixelMap's PixelMapFormat is not RGBA_8888\NV21\NV12, or its color space is not P3.
202	Non-system applications are not allowed to use system APIs.

示例：

import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

async function CreatePictureTest(context: Context) {
  const resourceMgr = context.resourceManager;
  const rawFile = await resourceMgr.getRawFileContent("test.jpg"); // 获取SDR图片。
  let imageSource: image.ImageSource = image.createImageSource(rawFile);
  let decodingOptionsForSDR: image.DecodingOptions = {
    desiredDynamicRange : image.DecodingDynamicRange.SDR,
  }
  let decodingOptionsForHDR: image.DecodingOptions = {
    desiredDynamicRange : image.DecodingDynamicRange.HDR, // 通过AIHDR将SDR解码为HDR。
  }
  let sdrPixelMap = await imageSource.createPixelMap(decodingOptionsForSDR);
  let hdrPixelMap = await imageSource.createPixelMap(decodingOptionsForHDR);
  let params : image.GainmapParams = {
    isFullSizeGainmap: true
  }

  // 获取计算生成的gainmap并编码。
  let picture: image.Picture = await image.createPictureByHdrAndSdrPixelMap(hdrPixelMap, sdrPixelMap, params);
  if (picture != null) {
    console.info('Succeeded in creating picture');
  } else {
    console.error('Create picture failed');
  }
  const imagePackerObj = image.createImagePacker();
  let packOpts : image.PackingOption = { format : "image/jpeg", quality: 98};
  packOpts.desiredDynamicRange = image.PackingDynamicRange.AUTO;
  const path: string = context.filesDir + "/hdr-test.jpg";
  let file = fileIo.openSync(path, fileIo.OpenMode.CREATE | fileIo.OpenMode.READ_WRITE);
  imagePackerObj.packToFile(picture, file.fd, packOpts).then(() => {
  }).catch((error : BusinessError) => {
    console.error('Failed to pack the image. And the error is: ' + error);
  })
}

HdrDecomposeOptions

HDR PixelMap分解为Picture的配置选项，分解后的Picture包含一张SDR主图和一张增益图（GainMap）。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.Core

名称	类型	只读	可选	说明
isFullSizeGainmap	boolean	否	是	是否生成全尺寸增益图。 true表示生成全尺寸增益图，增益图尺寸和主图一致；false表示不生成全尺寸增益图，增益图尺寸是主图的一半。默认值为false。
desiredPixelFormat	PixelMapFormat	否	是	分解后SDR PixelMap和增益图的像素格式。支持RGBA_8888、NV12、NV21。默认值为RGBA_8888。

image.decomposeToPicture

decomposeToPicture(hdrPixelMap : PixelMap, options?: HdrDecomposeOptions): Promise<Picture | undefined>

将HDR PixelMap分解为包含SDR PixelMap和增益图（gainmap）的Picture对象。使用Promise异步回调。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.Core

参数：

参数名	类型	必填	说明
hdrPixelMap	PixelMap	是	HDR PixelMap，像素格式需为RGBA_F16、RGBA_1010102、YCBCR_P010或YCRCB_P010。
options	HdrDecomposeOptions	否	HDR分解配置选项，包含增益图尺寸和像素格式设置。

返回值：

类型	说明
Promise<Picture \| undefined>	Promise对象。返回包含SDR PixelMap和增益图的Picture对象。

错误码：

以下错误码的详细介绍请参见通用错误码和Image错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.
7600201	Unsupported operation. hdrPixelMap's PixelMapFormat is not RGBA_F16\RGBA_1010102\YCBCR_P010\YCRCB_P010.
7600206	Invalid parameter. Possible cause: hdrPixelMap is empty.
7600208	HDR image decomposition failed. Possible causes: 1. Decomposition processing is not supported. 2. Processing error occurs.
7600301	Alloc memory failed.

示例：

import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function DecomposeToPictureTest(context: Context) {
  const resourceMgr = context.resourceManager;
  const rawFile = await resourceMgr.getRawFileContent("test.jpg");
  let imageSource: image.ImageSource = image.createImageSource(rawFile);
  let decodingOptions: image.DecodingOptions = {
    desiredDynamicRange: image.DecodingDynamicRange.HDR,
  };
  let hdrPixelMap = await imageSource.createPixelMap(decodingOptions);
  // 指定gainmap为全尺寸，像素格式为NV12。
  let options: image.HdrDecomposeOptions = {
    isFullSizeGainmap: true,
    desiredPixelFormat: image.PixelMapFormat.NV12,
  };
  let picture: image.Picture | undefined = await image.decomposeToPicture(hdrPixelMap, options);
  if (picture != undefined) {
    console.info('Decompose to picture with options successfully');
  } else {
    console.error('Decompose to picture with options failed');
  }
}

ImageSource

ImageSource类，用于获取图片相关信息。

在调用ImageSource的方法前，需要先通过image.createImageSource构建一个ImageSource实例。

ImageSource的所有方法均不支持并发调用。

由于图片占用内存较大，所以当ImageSource实例使用完成后，应主动调用release方法及时释放内存。释放时应确保该实例的所有异步方法均执行完成，且后续不再使用该实例。

createWideGamutSdrPixelMap²⁰⁺

createWideGamutSdrPixelMap(): Promise<PixelMap>

创建SDR的PixelMap对象。当图片为带有3通道GainMap的HDR图片时，会将其基础图扩展为BT.2020色域的SDR图。使用Promise异步回调。

说明：

对SDR图片源，按图片自带的色彩空间解码，输出SDR图。

对带有单通道GainMap的HDR图片源，解码其基础图（SDR图），忽略GainMap。

对带有3通道GainMap的HDR图片源，解码其基础图（SDR图），并将输出SDR图的色域扩展为ColorSpace.DISPLAY_BT2020_SRGB。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.ImageSource

返回值：

类型	说明
Promise<PixelMap>	Promise对象，返回PixelMap。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID	错误信息
7700101	Bad source.
7700102	Unsupported MIME type.
7700103	Image too large.
7700301	Decoding failed.

示例：

async function CreateWideGamutSdrPixelMap(context: Context) {
  // 此处'sdr.jpg'仅作示例，请开发者自行替换。
  let filePath: string = context.filesDir + "/sdr.jpg";
  let sdrImageSource = image.createImageSource(filePath);
  let pixelmap = sdrImageSource.createWideGamutSdrPixelMap();
  if (pixelmap != undefined) {
    console.info('Succeeded in creating sdr pixelMap object.');
  } else {
    console.error('Failed to create pixelMap.');
  }

  // 此处'singleChannelGainmapFilePath.jpg'仅作示例，请开发者自行替换。
  let singleChannelGainmapFilePath: string = context.filesDir + "/singleChannelGainmapFilePath.jpg";
  let singleChannelGainmapImageSource = image.createImageSource(singleChannelGainmapFilePath);
  let singleChannelGainmapPixelmap = singleChannelGainmapImageSource.createWideGamutSdrPixelMap();
  if (singleChannelGainmapPixelmap != undefined) {
    console.info('Succeeded in creating sdr pixelMap object by using singleChannelGainmapImageSource.');
  } else {
    console.error('Failed to create pixelMap.');
  }
  // 此处'threeChannelGainmapFilePath.jpg'仅作示例，请开发者自行替换。
  let threeChannelGainmapFilePath: string = context.filesDir + "/threeChannelGainmapFilePath.jpg";
  let threeChannelGainmapImageSource = image.createImageSource(threeChannelGainmapFilePath);
  let threeChannelGainmapPixelmap = threeChannelGainmapImageSource.createWideGamutSdrPixelMap();
  if (threeChannelGainmapPixelmap != undefined) {
    console.info('Succeeded in creating sdr pixelMap using DISPLAY_BT2020_SRGB.');
  } else {
    console.error('Failed to create pixelMap.');
  }
}

isJpegProgressive²²⁺

isJpegProgressive(): Promise<boolean>

判断Jpeg图片是否是渐进式图片。使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.ImageSource

返回值：

类型	说明
Promise<boolean>	Promise对象。返回true表示Jpeg图片是渐进式；返回false表示Jpeg图片不是渐进式。

错误码：

以下错误码的详细介绍请参见Image错误码。

错误码ID	错误信息
7600201	Bad source.
7600202	Unsupported MIME type.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

async function IsJpegProgressive(imageSource : image.ImageSource) {
  imageSource.isJpegProgressive()
    .then((isProgressive: boolean) => {
      console.info("isJpegProgressive: " + isProgressive);
    }).catch((error: BusinessError) => {
      console.error(`Failed to obtain the jpeg image isprogressive error.code is ${error.code}, message is ${error.message}`);
    })
}

modifyImageAllProperties²⁴⁺

modifyImageAllProperties(records: Record<string, string|null>): Promise<void>

批量修改图片属性。使用Promise异步回调。

Exif属性中除"JPEGInterchangeFormat"/"JPEGInterchangeFormatLength"/"GIFLoopCount"字段外，其他均支持修改。

说明：

调用该接口修改属性会改变属性字节长度，建议通过传入文件描述符来创建image.createImageSource实例或通过传入的uri创建image.createImageSource实例。

支持修改JPEG、PNG、HEIF和WEBP文件类型的图片属性，图片需要包含Exif信息。

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Multimedia.Image.ImageSource

参数：

参数名	类型	必填	说明
records	Record<string, string \| null>	是	包含图片属性名和属性值的键值对集合。

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见通用错误码和Image错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.
7700102	Unsupported MIME type.
7700202	Unsupported metadata. For example, the property key is not supported, or the property value is invalid.
7700304	Failed to write image properties to the file.

示例：

async function ModifyImageAllProperties(imageSource: image.ImageSource) {
  try {
    let record: Record<string, string | null> = {
      "HwMnotePhysicalAperture": "13",
    }
    await imageSource.modifyImageAllProperties(record);
  } catch (err) {
    console.error('[modifyImageAllProperties]', `modify image property failed.err: ${err.code}, errorMessage: ${err.message}`);
  }
}

@ohos.multimedia.image (图片处理)(系统接口)

导入模块

GainmapParams

DecodingOptions7+

ResolutionQuality12+

PropertyKey7+

image.createPictureByHdrAndSdrPixelMap20+

image.createPictureByHdrAndSdrPixelMap

HdrDecomposeOptions

image.decomposeToPicture

ImageSource

createWideGamutSdrPixelMap20+

isJpegProgressive22+

modifyImageAllProperties24+

DecodingOptions⁷⁺

ResolutionQuality¹²⁺

PropertyKey⁷⁺

image.createPictureByHdrAndSdrPixelMap²⁰⁺

createWideGamutSdrPixelMap²⁰⁺

isJpegProgressive²²⁺

modifyImageAllProperties²⁴⁺