• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (AuxiliaryPicture)
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> - The initial APIs of this interface are supported since API version 13.
12
13The auxiliary picture is generally used to assist the main picture in displaying special information, so that the image includes richer information. The **AuxiliaryPicture** class is used to read or write auxiliary picture data of an image and obtain auxiliary picture information of an image. Before calling any API in AuxiliaryPicture, you must use [createAuxiliaryPicture](arkts-apis-image-f.md#imagecreateauxiliarypicture13) to create a AuxiliaryPicture object.
14
15## Modules to Import
16
17```ts
18import { image } from '@kit.ImageKit';
19```
20
21## writePixelsFromBuffer<sup>13+</sup>
22
23writePixelsFromBuffer(data: ArrayBuffer): Promise\<void>
24
25Reads pixels from an ArrayBuffer and writes the data to this AuxiliaryPicture object. This API uses a promise to return the result.
26
27**System capability**: SystemCapability.Multimedia.Image.Core
28
29**Parameters**
30
31| Name| Type       | Mandatory| Description            |
32| ------ | ----------- | ---- | ---------------- |
33| data   | ArrayBuffer | Yes  | Pixels of the auxiliary picture.|
34
35**Return value**
36
37| Type          | Description                                  |
38| -------------- | -------------------------------------- |
39| Promise\<void> | Promise that returns no value.|
40
41**Error codes**
42
43For details about the error codes, see [Image Error Codes](errorcode-image.md).
44
45| ID| Error Message                                                    |
46| -------- | ------------------------------------------------------------ |
47| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
48
49**Example**
50
51```ts
52import { image } from '@kit.ImageKit';
53
54async function WritePixelsFromBuffer(context: Context) {
55  const resourceMgr = context.resourceManager;
56  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); // Support for HDR images is required.
57  let ops: image.SourceOptions = {
58    sourceDensity: 98,
59  }
60  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
61  let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap();
62  let pictureObj: image.Picture = image.createPicture(commodityPixelMap);
63  let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP);
64  if(auxPictureObj != null) {
65    let auxBuffer: ArrayBuffer = await auxPictureObj.readPixelsToBuffer();
66    await auxPictureObj.writePixelsFromBuffer(auxBuffer);
67    console.info('Write pixels from buffer success.');
68  } else {
69    console.error('AuxPictureObj is null.');
70  }
71}
72```
73
74## readPixelsToBuffer<sup>13+</sup>
75
76readPixelsToBuffer(): Promise\<ArrayBuffer>
77
78Reads pixels of this auxiliary picture and writes the data to an ArrayBuffer. This API uses a promise to return the result.
79
80**System capability**: SystemCapability.Multimedia.Image.Core
81
82**Return value**
83
84| Type                 | Description                             |
85| --------------------- | --------------------------------- |
86| Promise\<ArrayBuffer> | Promise used to return the pixels of the auxiliary picture.|
87
88**Example**
89
90```ts
91import { BusinessError } from '@kit.BasicServicesKit';
92import { image } from '@kit.ImageKit';
93
94async function ReadPixelsToBuffer(context: Context) {
95  const resourceMgr = context.resourceManager;
96  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); // Support for HDR images is required.
97  let ops: image.SourceOptions = {
98    sourceDensity: 98,
99  }
100  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
101  let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap();
102  let pictureObj: image.Picture = image.createPicture(commodityPixelMap);
103  let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP);
104  if(auxPictureObj != null) {
105    await auxPictureObj.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => {
106      console.info('Read pixels to buffer success.' );
107    }).catch((error: BusinessError) => {
108      console.error('Read pixels to buffer failed error.code: ' + JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message));
109    });
110  } else {
111    console.error('AuxPictureObj is null.');
112  }
113}
114```
115
116## getType<sup>13+</sup>
117
118getType(): AuxiliaryPictureType
119
120Obtains the type of this auxiliary picture.
121
122**System capability**: SystemCapability.Multimedia.Image.Core
123
124**Return value**
125
126| Type                                           | Description                        |
127| ----------------------------------------------- | ---------------------------- |
128| [AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13) | Type of the auxiliary picture.|
129
130**Example**
131
132```ts
133import { image } from '@kit.ImageKit';
134
135async function GetAuxiliaryPictureType() {
136  if (auxPictureObj != null) {
137    let type: image.AuxiliaryPictureType = auxPictureObj.getType();
138    console.info('Success get auxiliary picture type ' +  JSON.stringify(type));
139  } else {
140    console.error('Failed get auxiliary picture type ');
141  }
142}
143```
144
145## setMetadata<sup>13+</sup>
146
147setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void>
148
149Sets the metadata for this auxiliary picture.
150
151**System capability**: SystemCapability.Multimedia.Image.Core
152
153**Parameters**
154
155| Name      | Type                           | Mandatory| Description                                |
156| ------------ | ------------------------------- | ---- | ------------------------------------ |
157| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | Yes  | Metadata type, which is used to set the corresponding metadata.|
158| metadata     | [Metadata](arkts-apis-image-Metadata.md)         | Yes  | Metadata object.                        |
159
160**Return value**
161
162| Type          | Description                                  |
163| -------------- | -------------------------------------- |
164| Promise\<void> | Promise that returns no value.|
165
166**Error codes**
167
168For details about the error codes, see [Image Error Codes](errorcode-image.md).
169
170| ID| Error Message                                                    |
171| -------- | ------------------------------------------------------------ |
172| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
173| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
174
175**Example**
176
177```ts
178import { BusinessError } from '@kit.BasicServicesKit';
179import { image } from '@kit.ImageKit';
180
181async function SetAuxPictureObjMetadata(exifContext: Context) {
182  const exifResourceMgr = exifContext.resourceManager;
183  const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg"); // The image contains EXIF metadata.
184  let exifOps: image.SourceOptions = {
185    sourceDensity: 98,
186  }
187  let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps);
188  let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap();
189  let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap);
190  if (exifPictureObj != null) {
191    console.info('Create picture succeeded');
192  } else {
193    console.error('Create picture failed');
194  }
195
196  if (auxPictureObj != null) {
197    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
198    let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType);
199    auxPictureObj.setMetadata(metadataType, exifMetaData).then(() => {
200      console.info('Set metadata success');
201    }).catch((error: BusinessError) => {
202      console.error('Set metadata failed.error.code: ${error.code}, error.message: ${error.message}');
203    });
204  } else {
205    console.error('AuxPictureObjMetaData is null');
206  }
207}
208```
209
210## getMetadata<sup>13+</sup>
211
212getMetadata(metadataType: MetadataType): Promise\<Metadata>
213
214Obtains the metadata of this auxiliary picture.
215
216**System capability**: SystemCapability.Multimedia.Image.Core
217
218**Parameters**
219
220| Name      | Type                           | Mandatory| Description                                  |
221| ------------ | ------------------------------- | ---- | -------------------------------------- |
222| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | Yes  | Metadata type, which is used to obtain metadata of the corresponding type.|
223
224**Return value**
225
226| Type                            | Description            |
227| -------------------------------- | ---------------- |
228| Promise<[Metadata](arkts-apis-image-Metadata.md)> | Metadata object.|
229
230**Error codes**
231
232For details about the error codes, see [Image Error Codes](errorcode-image.md).
233
234| ID| Error Message                                                    |
235| -------- | ------------------------------------------------------------ |
236| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
237| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
238
239**Example**
240
241```ts
242import { image } from '@kit.ImageKit';
243
244async function GetAuxPictureObjMetadata() {
245  if (auxPictureObj != null) {
246    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
247    let auxPictureObjMetaData: image.Metadata | null = await auxPictureObj.getMetadata(metadataType);
248    if (auxPictureObjMetaData != null) {
249      console.info('Get auxpictureobj Metadata success' );
250    } else {
251      console.error('Get auxpictureobj Metadata failed');
252    }
253  } else {
254    console.error('Get auxpictureobj is null.');
255  }
256}
257```
258
259## getAuxiliaryPictureinfo<sup>13+</sup>
260
261getAuxiliaryPictureInfo(): AuxiliaryPictureInfo
262
263Obtains the auxiliary picture information.
264
265**System capability**: SystemCapability.Multimedia.Image.Core
266
267**Return value**
268
269| Type                                           | Description                             |
270| ----------------------------------------------- | --------------------------------- |
271| [AuxiliaryPictureInfo](arkts-apis-image-i.md#auxiliarypictureinfo13) | Promise used to return the auxiliary picture information.|
272
273**Example**
274
275```ts
276import { image } from '@kit.ImageKit';
277
278async function GetAuxiliaryPictureInfo() {
279  if(auxPictureObj != null) {
280    let auxinfo: image.AuxiliaryPictureInfo = auxPictureObj.getAuxiliaryPictureInfo();
281    console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType +
282      ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width +
283      ' rowStride: ' +  auxinfo.rowStride +  ' pixelFormat: ' + auxinfo.pixelFormat +
284      ' colorSpace: ' +  auxinfo.colorSpace);
285  } else {
286    console.error('Get auxiliary picture information failed');
287  }
288}
289```
290
291## setAuxiliaryPictureinfo<sup>13+</sup>
292
293setAuxiliaryPictureInfo(info: AuxiliaryPictureInfo): void
294
295Sets the auxiliary picture information.
296
297**System capability**: SystemCapability.Multimedia.Image.Core
298
299**Parameters**
300
301| Name| Type                                           | Mandatory| Description              |
302| ------ | ----------------------------------------------- | ---- | ------------------ |
303| info   | [AuxiliaryPictureInfo](arkts-apis-image-i.md#auxiliarypictureinfo13) | Yes  | Auxiliary picture information.|
304
305**Error codes**
306
307For details about the error codes, see [Image Error Codes](errorcode-image.md).
308
309| ID| Error Message                                                    |
310| -------- | :----------------------------------------------------------- |
311| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
312
313**Example**
314
315```ts
316import { colorSpaceManager } from '@kit.ArkGraphics2D';
317import { image } from '@kit.ImageKit';
318
319async function SetAuxiliaryPictureInfo() {
320  if(auxPictureObj != null) {
321    let colorSpaceName = colorSpaceManager.ColorSpace.SRGB;
322    let info: image.AuxiliaryPictureInfo = {
323      auxiliaryPictureType: image.AuxiliaryPictureType.GAINMAP,
324      size: {height: 100, width: 200},
325      pixelFormat: image.PixelMapFormat.RGBA_8888,
326      rowStride: 0,
327      colorSpace: colorSpaceManager.create(colorSpaceName),
328    };
329    auxPictureObj.setAuxiliaryPictureInfo(info);
330  }
331}
332```
333
334## release<sup>13+</sup>
335
336release():void
337
338Releases this AuxiliaryPicture object. No value is returned.
339
340**System capability**: SystemCapability.Multimedia.Image.Core
341
342**Example**
343
344```ts
345import { image } from '@kit.ImageKit';
346
347async function Release() {
348  let funcName = "Release";
349  if (auxPictureObj != null) {
350    auxPictureObj.release();
351    if (auxPictureObj.getType() == null) {
352      console.info(funcName, 'Success !');
353    } else {
354      console.error(funcName, 'Failed !');
355    }
356  } else {
357    console.error('PictureObj is null');
358  }
359}
360```
361