openharmony 鸿蒙 arkts-apis-image-AuxiliaryPicture

2026-08-25 浏览 (1)

Interface (AuxiliaryPicture)

The AuxiliaryPicture class is used to read or write auxiliary picture data of an image and obtain auxiliary picture information of an image. The supported types of auxiliary pictures can be found in AuxiliaryPictureType.

Before calling any API in AuxiliaryPicture, you must create an AuxiliaryPicture instance using image.createAuxiliaryPicture or getAuxiliaryPicture in Picture.

Images occupy a large amount of memory. When you finish using an AuxiliaryPicture instance, call release to free the memory promptly. Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

NOTE

  • 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.
  • The initial APIs of this interface are supported since API version 13.

Modules to Import

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

writePixelsFromBuffer13+

writePixelsFromBuffer(data: ArrayBuffer): Promise<void>

Reads pixels from an ArrayBuffer and writes the data to this AuxiliaryPicture object. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

NameTypeMandatoryDescription
dataArrayBufferYesPixels of the auxiliary picture.

Return value

TypeDescription
Promise<void>Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.

Example

async function WritePixelsFromBuffer(context: Context) {
  const resourceMgr = context.resourceManager;
  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); // An HDR-compatible image is required.
  let ops: image.SourceOptions = {
    sourceDensity: 98,
  }
  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
  let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap();
  let pictureObj: image.Picture = image.createPicture(commodityPixelMap);
  let auxPictureObj: image.AuxiliaryPicture|null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP);
  if(auxPictureObj != null) {
    let auxBuffer: ArrayBuffer = await auxPictureObj.readPixelsToBuffer();
    await auxPictureObj.writePixelsFromBuffer(auxBuffer);
    console.info('Write pixels from buffer success.');
  } else {
    console.error('AuxPictureObj is null.');
  }
}

readPixelsToBuffer13+

readPixelsToBuffer(): Promise<ArrayBuffer>

Reads pixels of this auxiliary picture and writes the data to an ArrayBuffer. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Return value

TypeDescription
Promise<ArrayBuffer>Promise used to return the pixels of the auxiliary picture.

Example

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

async function ReadPixelsToBuffer(context: Context) {
  const resourceMgr = context.resourceManager;
  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); // An HDR-compatible image is required.
  let ops: image.SourceOptions = {
    sourceDensity: 98,
  }
  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
  let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap();
  let pictureObj: image.Picture = image.createPicture(commodityPixelMap);
  let auxPictureObj: image.AuxiliaryPicture|null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP);
  if(auxPictureObj != null) {
    await auxPictureObj.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => {
      console.info('Read pixels to buffer success.' );
    }).catch((error: BusinessError) => {
      console.error(`Read pixels to buffer failed error.code: ${error.code}, error.message: ${error.message}`);
    });
  } else {
    console.error('AuxPictureObj is null.');
  }
}

getType13+

getType(): AuxiliaryPictureType

Obtains the type of this auxiliary picture.

System capability: SystemCapability.Multimedia.Image.Core

Return value

TypeDescription
AuxiliaryPictureTypeType of the auxiliary picture.

Example

async function GetAuxiliaryPictureType(auxPictureObj : image.AuxiliaryPicture) {
  if (auxPictureObj != null) {
    let type: image.AuxiliaryPictureType = auxPictureObj.getType();
    console.info('Success get auxiliary picture type ' +  JSON.stringify(type));
  } else {
    console.error('Failed get auxiliary picture type ');
  }
}

setMetadata13+

setMetadata(metadataType: MetadataType, metadata: Metadata): Promise<void>

Sets the metadata for this auxiliary picture. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

NameTypeMandatoryDescription
metadataTypeMetadataTypeYesMetadata type, which is used to set the corresponding metadata.
metadataMetadataYesMetadata object.

Return value

TypeDescription
Promise<void>Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

IDError Message
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
7600202Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type.

Example

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

async function SetAuxPictureObjMetadata(exifContext: Context, auxPictureObj: image.AuxiliaryPicture) {
  const exifResourceMgr = exifContext.resourceManager;
  const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg"); // An image containing Exif metadata is required.
  let exifOps: image.SourceOptions = {
    sourceDensity: 98,
  }
  let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps);
  let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap();
  let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap);
  if (exifPictureObj != null) {
    console.info('Create picture succeeded');
  } else {
    console.error('Create picture failed');
  }

  if (auxPictureObj != null) {
    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
    let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType);
    auxPictureObj.setMetadata(metadataType, exifMetaData).then(() => {
      console.info('Set metadata success');
    }).catch((error: BusinessError) => {
      console.error(`Set metadata failed.error.code: ${error.code}, error.message: ${error.message}`);
    });
  } else {
    console.error('AuxPictureObjMetaData is null');
  }
}

getMetadata13+

getMetadata(metadataType: MetadataType): Promise<Metadata>

Obtains the metadata of this auxiliary picture. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

NameTypeMandatoryDescription
metadataTypeMetadataTypeYesMetadata type, which is used to obtain metadata of the corresponding type.

Return value

TypeDescription
Promise<Metadata>Promise that returns the metadata.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

IDError Message
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
7600202Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type.

Example

async function GetAuxPictureObjMetadata(auxPictureObj: image.AuxiliaryPicture) {
  if (auxPictureObj != null) {
    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
    let auxPictureObjMetaData: image.Metadata|null = await auxPictureObj.getMetadata(metadataType);
    if (auxPictureObjMetaData != null) {
      console.info('Get AuxPictureObj Metadata success' );
    } else {
      console.error('Get AuxPictureObj Metadata failed');
    }
  } else {
    console.error('Get AuxPictureObj is null.');
  }
}

getAuxiliaryPictureInfo13+

getAuxiliaryPictureInfo(): AuxiliaryPictureInfo

Obtains the auxiliary picture information.

System capability: SystemCapability.Multimedia.Image.Core

Return value

TypeDescription
AuxiliaryPictureInfoAuxiliary picture information.

Example

async function GetAuxiliaryPictureInfo(auxPictureObj: image.AuxiliaryPicture) {
  if(auxPictureObj != null) {
    let auxinfo: image.AuxiliaryPictureInfo = auxPictureObj.getAuxiliaryPictureInfo();
    console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType +
      ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width +
      ' rowStride: ' +  auxinfo.rowStride +  ' pixelFormat: ' + auxinfo.pixelFormat +
      ' colorSpace: ' +  auxinfo.colorSpace);
  } else {
    console.error('Get auxiliary picture information failed');
  }
}

setAuxiliaryPictureInfo13+

setAuxiliaryPictureInfo(info: AuxiliaryPictureInfo): void

Sets the auxiliary picture information.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

NameTypeMandatoryDescription
infoAuxiliaryPictureInfoYesAuxiliary picture information.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.

Example

import { colorSpaceManager } from '@kit.ArkGraphics2D';

async function SetAuxiliaryPictureInfo(auxPictureObj: image.AuxiliaryPicture) {
  if(auxPictureObj != null) {
    let colorSpaceName = colorSpaceManager.ColorSpace.SRGB;
    let info: image.AuxiliaryPictureInfo = {
      auxiliaryPictureType: image.AuxiliaryPictureType.GAINMAP,
      size: {height: 100, width: 200},
      pixelFormat: image.PixelMapFormat.RGBA_8888,
      rowStride: 0,
      colorSpace: colorSpaceManager.create(colorSpaceName),
    };
    auxPictureObj.setAuxiliaryPictureInfo(info);
  }
}

release13+

release():void

Releases this AuxiliaryPicture object. No value is returned.

Images occupy a large amount of memory. When you finish using an AuxiliaryPicture instance, call this API to free the memory promptly.

Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

System capability: SystemCapability.Multimedia.Image.Core

Example

async function Release(auxPictureObj: image.AuxiliaryPicture) {
  let funcName = "Release";
  if (auxPictureObj != null) {
    auxPictureObj.release();
    if (auxPictureObj.getType() == null) {
      console.info(funcName, 'Success !');
    } else {
      console.error(funcName, 'Failed !');
    }
  } else {
    console.error('PictureObj is null');
  }
}

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-image-nativemodule-oh-pixelmap-hdrmetadatavalue

openharmony 鸿蒙 capi-image-imagepacker-opts-

openharmony 鸿蒙 capi-image-nativemodule-image-region

openharmony 鸿蒙 capi-image-imagepacker-native-

openharmony 鸿蒙 capi-image-imagenative-

openharmony 鸿蒙 capi-image-processing-h

openharmony 鸿蒙 capi-image-ohosimagesourcesupportedformat

openharmony 鸿蒙 capi-image-nativemodule-image-size

openharmony 鸿蒙 capi-image-mdk-h

openharmony 鸿蒙 capi-image-ohosimagesourcedelaytimelist

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/urgW6SuJ