• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (Picture)
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一些包含特殊信息的图片可以解码为多图对象，多图对象一般包含主图、辅助图和元数据。其中主图包含图像的大部分信息，主要用于显示图像内容；辅助图用于存储与主图相关但不同的数据，展示图像更丰富的信息；元数据一般用来存储关于图像文件的信息。多图对象类用于读取或写入多图对象。在调用Picture的方法前，需要先通过[createPicture](arkts-apis-image-f.md#imagecreatepicture13)创建一个Picture实例。
15
16## 导入模块
17
18```ts
19import { image } from '@kit.ImageKit';
20```
21
22## getMainPixelmap<sup>13+</sup>
23
24getMainPixelmap(): PixelMap
25
26获取主图的pixelmap。
27
28**系统能力：** SystemCapability.Multimedia.Image.Core
29
30**返回值：**
31
32| 类型                | 说明                   |
33| ------------------- | ---------------------- |
34| [PixelMap](arkts-apis-image-PixelMap.md) | 同步返回PixelMap对象。 |
35
36**示例：**
37
38```ts
39import { BusinessError } from '@kit.BasicServicesKit';
40
41async function GetMainPixelmap(pictureObj : image.Picture) {
42  let funcName = "getMainPixelmap";
43  if (pictureObj != null) {
44    let mainPixelmap: image.PixelMap = pictureObj.getMainPixelmap();
45    if (mainPixelmap != null) {
46      mainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => {
47        if (imageInfo != null) {
48          console.info('GetMainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width);
49        }
50      }).catch((error: BusinessError) => {
51        console.error(funcName, `Failed error.code: ${error.code} ,error.message: ${error.message}`);
52      });
53    }
54  } else {
55    console.error('PictureObj is null');
56  }
57}
58```
59
60## getHdrComposedPixelmap<sup>13+</sup>
61
62getHdrComposedPixelmap(): Promise\<PixelMap>
63
64合成hdr图并获取hdr图的pixelmap，使用Promise形式返回结果。
65
66**系统能力：** SystemCapability.Multimedia.Image.Core
67
68**返回值：**
69
70| 类型                          | 说明                        |
71| ----------------------------- | --------------------------- |
72| Promise\<[PixelMap](arkts-apis-image-PixelMap.md)> | Promise对象，返回PixelMap。 |
73
74**错误码：**
75
76以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
77
78| 错误码ID | 错误信息               |
79| -------- | ---------------------- |
80| 7600901  | Inner unknown error. Please check the logs for detailed information. |
81| 7600201  | Unsupported operation. e.g.,1. The picture does not has a gainmap. 2. MainPixelMap's allocator type is not DMA. |
82
83**示例：**
84
85```ts
86import { BusinessError } from '@kit.BasicServicesKit';
87
88async function GetHdrComposedPixelmap(pictureObj : image.Picture) {
89  let funcName = "getHdrComposedPixelmap";
90  if (pictureObj != null) { // 图片包含Hdr图。
91    let hdrComposedPixelmap: image.PixelMap = await pictureObj.getHdrComposedPixelmap();
92    if (hdrComposedPixelmap != null) {
93      hdrComposedPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => {
94        if (imageInfo != null) {
95          console.info(`GetHdrComposedPixelmap information height:${imageInfo.size.height} width:${imageInfo.size.width}`);
96        }
97      }).catch((error: BusinessError) => {
98        console.error(funcName, `Failed error.code: ${error.code} ,error.message: ${error.message}`);
99      });
100    }
101  } else {
102    console.error('PictureObj is null');
103  }
104}
105```
106
107## getGainmapPixelmap<sup>13+</sup>
108
109getGainmapPixelmap(): PixelMap | null
110
111获取增益图的pixelmap。
112
113**系统能力：** SystemCapability.Multimedia.Image.Core
114
115**返回值：**
116
117| 类型                      | 说明                                   |
118| ------------------------- | -------------------------------------- |
119| [PixelMap](arkts-apis-image-PixelMap.md) \| null | 返回Pixelmap对象，如果没有则返回null。 |
120
121**示例：**
122
123```ts
124import { BusinessError } from '@kit.BasicServicesKit';
125
126async function GetGainmapPixelmap(pictureObj : image.Picture) {
127  let funcName = "getGainmapPixelmap";
128  if (pictureObj != null) { // 图片包含增益图。
129    let gainPixelmap: image.PixelMap | null = pictureObj.getGainmapPixelmap();
130    if (gainPixelmap != null) {
131      gainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => {
132        if (imageInfo != null) {
133          console.info(`GetGainmapPixelmap information height:${imageInfo.size.height} width:${imageInfo.size.width}`);
134        } else {
135          console.error('GainPixelmap is null');
136        }
137      }).catch((error: BusinessError) => {
138        console.error(funcName, `Failed error.code: ${error.code} ,error.message: ${error.message}`);
139      });
140    } else {
141      console.info('GainPixelmap is null');
142    }
143  } else {
144    console.error('PictureObj is null');
145  }
146}
147```
148
149## setAuxiliaryPicture<sup>13+</sup>
150
151setAuxiliaryPicture(type: AuxiliaryPictureType, auxiliaryPicture: AuxiliaryPicture): void
152
153设置辅助图。
154
155**系统能力：** SystemCapability.Multimedia.Image.Core
156
157**参数：**
158
159| 参数名           | 类型                 | 必填 | 说明         |
160| ---------------- | -------------------- | ---- | ------------ |
161| type             | [AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13) | 是   | 辅助图类型。 |
162| auxiliaryPicture | [AuxiliaryPicture](arkts-apis-image-AuxiliaryPicture.md)     | 是   | 辅助图对象。 |
163
164**错误码：**
165
166以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
167
168| 错误码ID | 错误信息                                                     |
169| -------- | ------------------------------------------------------------ |
170| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
171
172**示例：**
173
174```ts
175async function SetAuxiliaryPicture(context: Context) {
176  const resourceMgr = context.resourceManager;
177  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg");// 需要支持hdr的图片。
178  let ops: image.SourceOptions = {
179    sourceDensity: 98,
180  }
181  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
182  let pixelMap: image.PixelMap = await imageSource.createPixelMap();
183  let pictureObj: image.Picture = image.createPicture(pixelMap);
184  if (pictureObj != null) {
185    console.info('Create picture succeeded');
186  } else {
187    console.error('Create picture failed');
188  }
189
190  if (pictureObj != null) {
191    let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP;
192    let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(type);
193    if (auxPictureObj != null) {
194      pictureObj.setAuxiliaryPicture(type, auxPictureObj);
195    }
196  }
197}
198```
199
200## getAuxiliaryPicture<sup>13+</sup>
201
202getAuxiliaryPicture(type: AuxiliaryPictureType): AuxiliaryPicture | null
203
204根据类型获取辅助图。
205
206**系统能力：** SystemCapability.Multimedia.Image.Core
207
208**参数：**
209
210| 参数名 | 类型                 | 必填 | 说明         |
211| ------ | -------------------- | ---- | ------------ |
212| type   | [AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13) | 是   | 辅助图类型。 |
213
214**返回值：**
215
216| 类型                   | 说明                                           |
217| ---------------------- | ---------------------------------------------- |
218| [AuxiliaryPicture](arkts-apis-image-AuxiliaryPicture.md) \| null | 返回AuxiliaryPicture对象，如果没有则返回null。 |
219
220**错误码：**
221
222以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
223
224| 错误码ID | 错误信息                                                     |
225| -------- | ------------------------------------------------------------ |
226| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
227
228**示例：**
229
230```ts
231async function GetAuxiliaryPicture(pictureObj : image.Picture) {
232  if (pictureObj != null) {
233    let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP;
234    let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(type);
235  }
236}
237```
238
239## setMetadata<sup>13+</sup>
240
241setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void>
242
243设置主图的元数据。
244
245**系统能力：** SystemCapability.Multimedia.Image.Core
246
247**参数：**
248
249| 参数名       | 类型         | 必填 | 说明         |
250| ------------ | ------------ | ---- | ------------ |
251| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | 是   | 元数据类型。 |
252| metadata     | [Metadata](arkts-apis-image-Metadata.md)     | 是   | 元数据对象。 |
253
254**返回值：**
255
256| 类型           | 说明                                   |
257| -------------- | -------------------------------------- |
258| Promise\<void> | Promise对象。无返回结果的Promise对象。 |
259
260**错误码：**
261
262以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
263
264| 错误码ID | 错误信息                                                     |
265| -------- | ------------------------------------------------------------ |
266| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
267| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
268
269**示例：**
270
271```ts
272import { BusinessError } from '@kit.BasicServicesKit';
273
274async function SetPictureObjMetadata(exifContext: Context) {
275  const exifResourceMgr = exifContext.resourceManager;
276  const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg");// 含有exif metadata的图片。
277  let exifOps: image.SourceOptions = {
278    sourceDensity: 98,
279  }
280  let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps);
281  let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap();
282  let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap);
283  if (exifPictureObj != null) {
284    console.info('Create picture succeeded');
285  } else {
286    console.error('Create picture failed');
287  }
288
289  if (exifPictureObj != null) {
290    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
291    let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType);
292    exifPictureObj.setMetadata(metadataType, exifMetaData).then(() => {
293      console.info('Set metadata success');
294    }).catch((error: BusinessError) => {
295      console.error('Failed to set metadata. error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message));
296    });
297  } else {
298    console.error('exifPictureOb is null');
299  }
300}
301```
302
303## getMetadata<sup>13+</sup>
304
305getMetadata(metadataType: MetadataType): Promise\<Metadata>
306
307获取主图的元数据。
308
309**系统能力：** SystemCapability.Multimedia.Image.Core
310
311**参数：**
312
313| 参数名       | 类型         | 必填 | 说明         |
314| ------------ | ------------ | ---- | ------------ |
315| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | 是   | 元数据类型。 |
316
317**返回值：**
318
319| 类型               | 说明                      |
320| ------------------ | ------------------------- |
321| Promise\<[Metadata](arkts-apis-image-Metadata.md)> | Promise对象。返回元数据。 |
322
323**错误码：**
324
325以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
326
327| 错误码ID | 错误信息                                                     |
328| -------- | ------------------------------------------------------------ |
329| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
330| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
331
332**示例：**
333
334```ts
335async function GetPictureObjMetadataProperties(pictureObj : image.Picture) {
336  if (pictureObj != null) {
337    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
338    let pictureObjMetaData: image.Metadata = await pictureObj.getMetadata(metadataType);
339    if (pictureObjMetaData != null) {
340      console.info('get picture metadata success');
341    } else {
342      console.error('get picture metadata is failed');
343    }
344  } else {
345    console.error(" pictureObj is null");
346  }
347}
348```
349
350## marshalling<sup>13+</sup>
351
352marshalling(sequence: rpc.MessageSequence): void
353
354将picture序列化后写入MessageSequence。
355
356**系统能力：** SystemCapability.Multimedia.Image.Core
357
358**参数：**
359
360| 参数名   | 类型                                                                | 必填 | 说明                      |
361| -------- | ------------------------------------------------------------------- | ---- | ------------------------- |
362| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是   | 新创建的MessageSequence。 |
363
364**错误码：**
365
366以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。
367
368| 错误码ID | 错误信息                                                     |
369| -------- | ------------------------------------------------------------ |
370| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
371| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory.                                                   |
372
373**示例：**
374
375```ts
376import { BusinessError } from '@kit.BasicServicesKit';
377import { rpc } from '@kit.IPCKit';
378
379class MySequence implements rpc.Parcelable {
380  picture: image.Picture | null = null;
381  constructor(conPicture: image.Picture) {
382    this.picture = conPicture;
383  }
384  marshalling(messageSequence: rpc.MessageSequence) {
385    if(this.picture != null) {
386      this.picture.marshalling(messageSequence);
387      console.info('Marshalling success !');
388      return true;
389    } else {
390      console.error('Marshalling failed !');
391      return false;
392    }
393  }
394  unmarshalling(messageSequence : rpc.MessageSequence) {
395    this.picture = image.createPictureFromParcel(messageSequence);
396    this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => {
397      console.info(`Unmarshalling to get mainPixelmap information height:${imageInfo.size.height} width:${imageInfo.size.width}`);
398    }).catch((error: BusinessError) => {
399      console.error(`Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}`);
400    });
401    return true;
402  }
403}
404
405async function Marshalling_UnMarshalling(pictureObj : image.Picture) {
406  if (pictureObj != null) {
407    let parcelable: MySequence = new MySequence(pictureObj);
408    let data: rpc.MessageSequence = rpc.MessageSequence.create();
409    // 序列化。
410    data.writeParcelable(parcelable);
411    let ret: MySequence = new MySequence(pictureObj);
412    // 反序列化。
413    data.readParcelable(ret);
414  } else {
415    console.error('PictureObj is null');
416  }
417}
418```
419
420## release<sup>13+</sup>
421
422release(): void
423
424释放picture对象。
425
426**系统能力：** SystemCapability.Multimedia.Image.Core
427
428**示例：**
429
430```ts
431async function Release(pictureObj : image.Picture) {
432  let funcName = "Release";
433  if (pictureObj != null) {
434    pictureObj.release();
435    if (pictureObj.getMainPixelmap() == null) {
436      console.info(funcName, 'Success !');
437    } else {
438      console.error(funcName, 'Failed !');
439    }
440  } else {
441    console.error('PictureObj is null');
442  }
443}
444```
445