• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (AuxiliaryPicture)
2<!--Kit: Image Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @aulight02-->
5<!--Designer: @liyang_bryan-->
6<!--Tester: @xchaosioda-->
7<!--Adviser: @zengyawen-->
8
9> **说明：**
10>
11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
12> - 本Interface首批接口从API version 13开始支持。
13
14辅助图一般用于辅助主图进行特殊信息的展示，使图像包含更丰富的信息。辅助图图像类，用于读取或写入图像的辅助图数据以及获取图像的辅助图信息。在调用AuxiliaryPicture的方法前，需要先通过[createAuxiliaryPicture](arkts-apis-image-f.md#imagecreateauxiliarypicture13)创建一个AuxiliaryPicture实例。
15
16## 导入模块
17
18```ts
19import { image } from '@kit.ImageKit';
20```
21
22## writePixelsFromBuffer<sup>13+</sup>
23
24writePixelsFromBuffer(data: ArrayBuffer): Promise\<void>
25
26读取ArrayBuffer中的辅助图片数据，并将数据写入AuxiliaryPicture对象，使用Promise形式返回。
27
28**系统能力：** SystemCapability.Multimedia.Image.Core
29
30**参数：**
31
32| 参数名 | 类型        | 必填 | 说明             |
33| ------ | ----------- | ---- | ---------------- |
34| data   | ArrayBuffer | 是   | 辅助图像素数据。 |
35
36**返回值：**
37
38| 类型           | 说明                                   |
39| -------------- | -------------------------------------- |
40| Promise\<void> | Promise对象。无返回结果的Promise对象。 |
41
42**错误码：**
43
44以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
45
46| 错误码ID | 错误信息                                                     |
47| -------- | ------------------------------------------------------------ |
48| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
49
50**示例:**
51
52```ts
53async function WritePixelsFromBuffer(context: Context) {
54  const resourceMgr = context.resourceManager;
55  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); // 需要支持hdr的图片。
56  let ops: image.SourceOptions = {
57    sourceDensity: 98,
58  }
59  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
60  let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap();
61  let pictureObj: image.Picture = image.createPicture(commodityPixelMap);
62  let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP);
63  if(auxPictureObj != null) {
64    let auxBuffer: ArrayBuffer = await auxPictureObj.readPixelsToBuffer();
65    await auxPictureObj.writePixelsFromBuffer(auxBuffer);
66    console.info('Write pixels from buffer success.');
67  } else {
68    console.error('AuxPictureObj is null.');
69  }
70}
71```
72
73## readPixelsToBuffer<sup>13+</sup>
74
75readPixelsToBuffer(): Promise\<ArrayBuffer>
76
77读取图像像素映射数据并将数据写入ArrayBuffer，使用Promise形式返回。
78
79**系统能力：** SystemCapability.Multimedia.Image.Core
80
81**返回值：**
82
83| 类型                  | 说明                              |
84| --------------------- | --------------------------------- |
85| Promise\<ArrayBuffer> | Promise对象。返回辅助图像素数据。 |
86
87**示例：**
88
89```ts
90import { BusinessError } from '@kit.BasicServicesKit';
91
92async function ReadPixelsToBuffer(context: Context) {
93  const resourceMgr = context.resourceManager;
94  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); // 需要支持hdr的图片。
95  let ops: image.SourceOptions = {
96    sourceDensity: 98,
97  }
98  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
99  let commodityPixelMap: image.PixelMap = await imageSource.createPixelMap();
100  let pictureObj: image.Picture = image.createPicture(commodityPixelMap);
101  let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(image.AuxiliaryPictureType.GAINMAP);
102  if(auxPictureObj != null) {
103    await auxPictureObj.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => {
104      console.info('Read pixels to buffer success.' );
105    }).catch((error: BusinessError) => {
106      console.error(`Read pixels to buffer failed error.code: ${error.code}, error.message: ${error.message}`);
107    });
108  } else {
109    console.error('AuxPictureObj is null.');
110  }
111}
112```
113
114## getType<sup>13+</sup>
115
116getType(): AuxiliaryPictureType
117
118获取辅助图的类型。
119
120**系统能力：** SystemCapability.Multimedia.Image.Core
121
122**返回值：**
123
124| 类型                                            | 说明                         |
125| ----------------------------------------------- | ---------------------------- |
126| [AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13) | 操作成功，返回辅助图的类型。 |
127
128**示例：**
129
130```ts
131async function GetAuxiliaryPictureType(auxPictureObj : image.AuxiliaryPicture) {
132  if (auxPictureObj != null) {
133    let type: image.AuxiliaryPictureType = auxPictureObj.getType();
134    console.info('Success get auxiliary picture type ' +  JSON.stringify(type));
135  } else {
136    console.error('Failed get auxiliary picture type ');
137  }
138}
139```
140
141## setMetadata<sup>13+</sup>
142
143setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void>
144
145设置辅助图元数据。
146
147**系统能力：** SystemCapability.Multimedia.Image.Core
148
149**参数：**
150
151| 参数名       | 类型                            | 必填 | 说明                                 |
152| ------------ | ------------------------------- | ---- | ------------------------------------ |
153| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | 是   | 元数据的类型，用于设置对应的元数据。 |
154| metadata     | [Metadata](arkts-apis-image-Metadata.md)         | 是   | 元数据对象。                         |
155
156**返回值：**
157
158| 类型           | 说明                                   |
159| -------------- | -------------------------------------- |
160| Promise\<void> | Promise对象，无返回结果的Promise对象。 |
161
162**错误码：**
163
164以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
165
166| 错误码ID | 错误信息                                                     |
167| -------- | ------------------------------------------------------------ |
168| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
169| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
170
171**示例：**
172
173```ts
174import { BusinessError } from '@kit.BasicServicesKit';
175
176async function SetAuxPictureObjMetadata(exifContext: Context, auxPictureObj: image.AuxiliaryPicture) {
177  const exifResourceMgr = exifContext.resourceManager;
178  const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");// 图片包含exif metadata。
179  let exifOps: image.SourceOptions = {
180    sourceDensity: 98,
181  }
182  let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps);
183  let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap();
184  let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap);
185  if (exifPictureObj != null) {
186    console.info('Create picture succeeded');
187  } else {
188    console.error('Create picture failed');
189  }
190
191  if (auxPictureObj != null) {
192    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
193    let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType);
194    auxPictureObj.setMetadata(metadataType, exifMetaData).then(() => {
195      console.info('Set metadata success');
196    }).catch((error: BusinessError) => {
197      console.error(`Set metadata failed.error.code: ${error.code}, error.message: ${error.message}`);
198    });
199  } else {
200    console.error('AuxPictureObjMetaData is null');
201  }
202}
203```
204
205## getMetadata<sup>13+</sup>
206
207getMetadata(metadataType: MetadataType): Promise\<Metadata>
208
209从辅助图中获取元数据。
210
211**系统能力：** SystemCapability.Multimedia.Image.Core
212
213**参数：**
214
215| 参数名       | 类型                            | 必填 | 说明                                   |
216| ------------ | ------------------------------- | ---- | -------------------------------------- |
217| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | 是   | 元数据类型，用于获取对应类型的元数据。 |
218
219**返回值：**
220
221| 类型                             | 说明             |
222| -------------------------------- | ---------------- |
223| Promise<[Metadata](arkts-apis-image-Metadata.md)> | 返回元数据对象。 |
224
225**错误码：**
226
227以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
228
229| 错误码ID | 错误信息                                                     |
230| -------- | ------------------------------------------------------------ |
231| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
232| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
233
234**示例：**
235
236```ts
237async function GetAuxPictureObjMetadata(auxPictureObj: image.AuxiliaryPicture) {
238  if (auxPictureObj != null) {
239    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
240    let auxPictureObjMetaData: image.Metadata | null = await auxPictureObj.getMetadata(metadataType);
241    if (auxPictureObjMetaData != null) {
242      console.info('Get AuxPictureObj Metadata success' );
243    } else {
244      console.error('Get AuxPictureObj Metadata failed');
245    }
246  } else {
247    console.error('Get AuxPictureObj is null.');
248  }
249}
250```
251
252## getAuxiliaryPictureinfo<sup>13+</sup>
253
254getAuxiliaryPictureInfo(): AuxiliaryPictureInfo
255
256获取有关此辅助图的图像信息。
257
258**系统能力：** SystemCapability.Multimedia.Image.Core
259
260**返回值：**
261
262| 类型                                            | 说明                              |
263| ----------------------------------------------- | --------------------------------- |
264| [AuxiliaryPictureInfo](arkts-apis-image-i.md#auxiliarypictureinfo13) | Promise对象，返回辅助图图像信息。 |
265
266**示例：**
267
268```ts
269async function GetAuxiliaryPictureInfo(auxPictureObj: image.AuxiliaryPicture) {
270  if(auxPictureObj != null) {
271    let auxinfo: image.AuxiliaryPictureInfo = auxPictureObj.getAuxiliaryPictureInfo();
272    console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType +
273      ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width +
274      ' rowStride: ' +  auxinfo.rowStride +  ' pixelFormat: ' + auxinfo.pixelFormat +
275      ' colorSpace: ' +  auxinfo.colorSpace);
276  } else {
277    console.error('Get auxiliary picture information failed');
278  }
279}
280```
281
282## setAuxiliaryPictureinfo<sup>13+</sup>
283
284setAuxiliaryPictureInfo(info: AuxiliaryPictureInfo): void
285
286设置辅助图的图像信息。
287
288**系统能力：** SystemCapability.Multimedia.Image.Core
289
290**参数：**
291
292| 参数名 | 类型                                            | 必填 | 说明               |
293| ------ | ----------------------------------------------- | ---- | ------------------ |
294| info   | [AuxiliaryPictureInfo](arkts-apis-image-i.md#auxiliarypictureinfo13) | 是   | 辅助图的图像信息。 |
295
296**错误码：**
297
298以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
299
300| 错误码ID | 错误信息                                                     |
301| -------- | :----------------------------------------------------------- |
302| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
303
304**示例：**
305
306```ts
307import { colorSpaceManager } from '@kit.ArkGraphics2D';
308
309async function SetAuxiliaryPictureInfo(auxPictureObj: image.AuxiliaryPicture) {
310  if(auxPictureObj != null) {
311    let colorSpaceName = colorSpaceManager.ColorSpace.SRGB;
312    let info: image.AuxiliaryPictureInfo = {
313      auxiliaryPictureType: image.AuxiliaryPictureType.GAINMAP,
314      size: {height: 100, width: 200},
315      pixelFormat: image.PixelMapFormat.RGBA_8888,
316      rowStride: 0,
317      colorSpace: colorSpaceManager.create(colorSpaceName),
318    };
319    auxPictureObj.setAuxiliaryPictureInfo(info);
320  }
321}
322```
323
324## release<sup>13+</sup>
325
326release():void
327
328释放辅助图对象，无返回值。
329
330**系统能力：** SystemCapability.Multimedia.Image.Core
331
332**示例：**
333
334```ts
335async function Release(auxPictureObj: image.AuxiliaryPicture) {
336  let funcName = "Release";
337  if (auxPictureObj != null) {
338    auxPictureObj.release();
339    if (auxPictureObj.getType() == null) {
340      console.info(funcName, 'Success !');
341    } else {
342      console.error(funcName, 'Failed !');
343    }
344  } else {
345    console.error('PictureObj is null');
346  }
347}
348```
349