• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (Picture)
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
13An image that contains special information can be decoded into a picture object, which generally contains the main picture, auxiliary picture, and metadata. The main picture contains most information about the image and is mainly used to render the image. The auxiliary picture is used to store data related to but different from the main picture, revealing more comprehensive details. The metadata is generally used to store information about the image file. The picture object class is used to read or write picture objects. Before calling any API in Picture, you must use [createPicture](arkts-apis-image-f.md#imagecreatepicture13) to create a Picture object.
14
15## Modules to Import
16
17```ts
18import { image } from '@kit.ImageKit';
19```
20
21## getMainPixelmap<sup>13+</sup>
22
23getMainPixelmap(): PixelMap
24
25Obtains the PixelMap object of the main picture. This API returns the result synchronously.
26
27**System capability**: SystemCapability.Multimedia.Image.Core
28
29**Return value**
30
31| Type               | Description                  |
32| ------------------- | ---------------------- |
33| [PixelMap](arkts-apis-image-PixelMap.md) | PixelMap object.|
34
35**Example**
36
37```ts
38import { BusinessError } from '@kit.BasicServicesKit';
39import { image } from '@kit.ImageKit';
40
41async function GetMainPixelmap() {
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
64Generates a High Dynamic Range (HDR) image and obtains its PixelMap object. This API uses a promise to return the result.
65
66**System capability**: SystemCapability.Multimedia.Image.Core
67
68**Return value**
69
70| Type                         | Description                       |
71| ----------------------------- | --------------------------- |
72| Promise\<[PixelMap](arkts-apis-image-PixelMap.md)> | Promise used to return the PixelMap object.|
73
74**Error codes**
75
76For details about the error codes, see [Image Error Codes](errorcode-image.md).
77
78| ID| Error Message              |
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**Example**
84
85```ts
86import { BusinessError } from '@kit.BasicServicesKit';
87import { image } from '@kit.ImageKit';
88
89async function GetHdrComposedPixelmap() {
90  let funcName = "getHdrComposedPixelmap";
91  if (pictureObj != null) { // An HDR image is contained.
92    let hdrComposedPixelmap: image.PixelMap = await pictureObj.getHdrComposedPixelmap();
93    if (hdrComposedPixelmap != null) {
94      hdrComposedPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => {
95        if (imageInfo != null) {
96          console.info('GetHdrComposedPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width);
97        }
98      }).catch((error: BusinessError) => {
99        console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}');
100      });
101    }
102  } else {
103    console.error('PictureObj is null');
104  }
105}
106```
107
108## getGainmapPixelmap<sup>13+</sup>
109
110getGainmapPixelmap(): PixelMap | null
111
112Obtains the PixelMap object of the gain map.
113
114**System capability**: SystemCapability.Multimedia.Image.Core
115
116**Return value**
117
118| Type                     | Description                                  |
119| ------------------------- | -------------------------------------- |
120| [PixelMap](arkts-apis-image-PixelMap.md) \| null | PixelMap object obtained. If there is no PixelMap object, null is returned.|
121
122**Example**
123
124```ts
125import { BusinessError } from '@kit.BasicServicesKit';
126import { image } from '@kit.ImageKit';
127
128async function GetGainmapPixelmap() {
129  let funcName = "getGainmapPixelmap";
130  if (pictureObj != null) { // A gain map is contained.
131    let gainPixelmap: image.PixelMap | null = pictureObj.getGainmapPixelmap();
132    if (gainPixelmap != null) {
133      gainPixelmap.getImageInfo().then((imageInfo: image.ImageInfo) => {
134        if (imageInfo != null) {
135          console.info('GetGainmapPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width);
136        } else {
137          console.error('GainPixelmap is null');
138        }
139      }).catch((error: BusinessError) => {
140        console.error(funcName, 'Failed error.code: ${error.code} ,error.message: ${error.message}');
141      });
142    } else {
143      console.info('GainPixelmap is null');
144    }
145  } else {
146    console.error('PictureObj is null');
147  }
148}
149```
150
151## setAuxiliaryPicture<sup>13+</sup>
152
153setAuxiliaryPicture(type: AuxiliaryPictureType, auxiliaryPicture: AuxiliaryPicture): void
154
155Sets an auxiliary picture.
156
157**System capability**: SystemCapability.Multimedia.Image.Core
158
159**Parameters**
160
161| Name          | Type                | Mandatory| Description        |
162| ---------------- | -------------------- | ---- | ------------ |
163| type             | [AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13) | Yes  | Type of the auxiliary picture.|
164| auxiliaryPicture | [AuxiliaryPicture](arkts-apis-image-AuxiliaryPicture.md)     | Yes  | AuxiliaryPicture object.|
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
174**Example**
175
176```ts
177import { image } from '@kit.ImageKit';
178
179async function SetAuxiliaryPicture(context: Context) {
180  const resourceMgr = context.resourceManager;
181  const rawFile = await resourceMgr.getRawFileContent("hdr.jpg"); // Support for HDR images is required.
182  let ops: image.SourceOptions = {
183    sourceDensity: 98,
184  }
185  let imageSource: image.ImageSource = image.createImageSource(rawFile.buffer as ArrayBuffer, ops);
186  let pixelMap: image.PixelMap = await imageSource.createPixelMap();
187  let auxPicture: image.Picture = image.createPicture(pixelMap);
188  if (auxPicture != null) {
189    console.info('Create picture succeeded');
190  } else {
191    console.error('Create picture failed');
192  }
193
194  if (pictureObj != null) {
195    let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP;
196    let auxPictureObj: image.AuxiliaryPicture | null = await auxPicture.getAuxiliaryPicture(type);
197    if (auxPictureObj != null) {
198      pictureObj.setAuxiliaryPicture(type, auxPictureObj);
199    }
200  }
201}
202```
203
204## getAuxiliaryPicture<sup>13+</sup>
205
206getAuxiliaryPicture(type: AuxiliaryPictureType): AuxiliaryPicture | null
207
208Obtains an auxiliary picture by type.
209
210**System capability**: SystemCapability.Multimedia.Image.Core
211
212**Parameters**
213
214| Name| Type                | Mandatory| Description        |
215| ------ | -------------------- | ---- | ------------ |
216| type   | [AuxiliaryPictureType](arkts-apis-image-e.md#auxiliarypicturetype13) | Yes  | Type of the auxiliary picture.|
217
218**Return value**
219
220| Type                  | Description                                          |
221| ---------------------- | ---------------------------------------------- |
222| [AuxiliaryPicture](arkts-apis-image-AuxiliaryPicture.md) \| null | AuxiliaryPicture object. If there is no AuxiliaryPicture object, null is returned.|
223
224**Error codes**
225
226For details about the error codes, see [Image Error Codes](errorcode-image.md).
227
228| ID| Error Message                                                    |
229| -------- | ------------------------------------------------------------ |
230| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
231
232**Example**
233
234```ts
235import { image } from '@kit.ImageKit';
236
237async function GetAuxiliaryPicture() {
238  if (pictureObj != null) {
239    let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP;
240    let auxPictureObj: image.AuxiliaryPicture | null = pictureObj.getAuxiliaryPicture(type);
241  }
242}
243```
244
245## setMetadata<sup>13+</sup>
246
247setMetadata(metadataType: MetadataType, metadata: Metadata): Promise\<void>
248
249Sets the metadata for this Picture object.
250
251**System capability**: SystemCapability.Multimedia.Image.Core
252
253**Parameters**
254
255| Name      | Type        | Mandatory| Description        |
256| ------------ | ------------ | ---- | ------------ |
257| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | Yes  | Metadata type.|
258| metadata     | [Metadata](arkts-apis-image-Metadata.md)     | Yes  | Metadata object.|
259
260**Return value**
261
262| Type          | Description                                  |
263| -------------- | -------------------------------------- |
264| Promise\<void> | Promise that returns no value.|
265
266**Error codes**
267
268For details about the error codes, see [Image Error Codes](errorcode-image.md).
269
270| ID| Error Message                                                    |
271| -------- | ------------------------------------------------------------ |
272| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
273| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
274
275**Example**
276
277```ts
278import { BusinessError } from '@kit.BasicServicesKit';
279import { image } from '@kit.ImageKit';
280
281async function SetPictureObjMetadata(exifContext: Context) {
282  const exifResourceMgr = exifContext.resourceManager;
283  const exifRawFile = await exifResourceMgr.getRawFileContent("exif.jpg"); // The image contains EXIF metadata.
284  let exifOps: image.SourceOptions = {
285    sourceDensity: 98,
286  }
287  let exifImageSource: image.ImageSource = image.createImageSource(exifRawFile.buffer as ArrayBuffer, exifOps);
288  let exifCommodityPixelMap: image.PixelMap = await exifImageSource.createPixelMap();
289  let exifPictureObj: image.Picture = image.createPicture(exifCommodityPixelMap);
290  if (exifPictureObj != null) {
291    console.info('Create picture succeeded');
292  } else {
293    console.error('Create picture failed');
294  }
295
296  if (pictureObj != null) {
297    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
298    let exifMetaData: image.Metadata = await exifPictureObj.getMetadata(metadataType);
299    pictureObj.setMetadata(metadataType, exifMetaData).then(() => {
300      console.info('Set metadata success');
301    }).catch((error: BusinessError) => {
302      console.error('Failed to set metadata. error.code: ' +JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message));
303    });
304  } else {
305    console.error('PictureObj is null');
306  }
307}
308```
309
310## getMetadata<sup>13+</sup>
311
312getMetadata(metadataType: MetadataType): Promise\<Metadata>
313
314Obtains the metadata of this Picture object.
315
316**System capability**: SystemCapability.Multimedia.Image.Core
317
318**Parameters**
319
320| Name      | Type        | Mandatory| Description        |
321| ------------ | ------------ | ---- | ------------ |
322| metadataType | [MetadataType](arkts-apis-image-e.md#metadatatype13) | Yes  | Metadata type.|
323
324**Return value**
325
326| Type              | Description                     |
327| ------------------ | ------------------------- |
328| Promise\<[Metadata](arkts-apis-image-Metadata.md)> | Promise used to return the metadata.|
329
330**Error codes**
331
332For details about the error codes, see [Image Error Codes](errorcode-image.md).
333
334| ID| Error Message                                                    |
335| -------- | ------------------------------------------------------------ |
336| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
337| 7600202  | Unsupported metadata. Possible causes: 1. Unsupported metadata type. 2. The metadata type does not match the auxiliary picture type. |
338
339**Example**
340
341```ts
342import { image } from '@kit.ImageKit';
343
344async function GetPictureObjMetadataProperties() {
345  if (pictureObj != null) {
346    let metadataType: image.MetadataType = image.MetadataType.EXIF_METADATA;
347    let pictureObjMetaData: image.Metadata = await pictureObj.getMetadata(metadataType);
348    if (pictureObjMetaData != null) {
349      console.info('get picture metadata success');
350    } else {
351      console.error('get picture metadata is failed');
352    }
353  } else {
354    console.error(" pictureObj is null");
355  }
356}
357```
358
359## marshalling<sup>13+</sup>
360
361marshalling(sequence: rpc.MessageSequence): void
362
363Marshals this Picture object and writes it to a MessageSequence object.
364
365**System capability**: SystemCapability.Multimedia.Image.Core
366
367**Parameters**
368
369| Name  | Type                                                               | Mandatory| Description                     |
370| -------- | ------------------------------------------------------------------- | ---- | ------------------------- |
371| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | Yes  | MessageSequence object.|
372
373**Error codes**
374
375For details about the error codes, see [Image Error Codes](errorcode-image.md).
376
377| ID| Error Message                                                    |
378| -------- | ------------------------------------------------------------ |
379| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
380| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory.                                                   |
381
382**Example**
383
384```ts
385import { BusinessError } from '@kit.BasicServicesKit';
386import { image } from '@kit.ImageKit';
387import { rpc } from '@kit.IPCKit';
388
389class MySequence implements rpc.Parcelable {
390  picture: image.Picture | null = null;
391  constructor(conPicture: image.Picture) {
392    this.picture = conPicture;
393  }
394  marshalling(messageSequence: rpc.MessageSequence) {
395    if(this.picture != null) {
396      this.picture.marshalling(messageSequence);
397      console.info('Marshalling success !');
398      return true;
399    } else {
400      console.error('Marshalling failed !');
401      return false;
402    }
403  }
404  unmarshalling(messageSequence : rpc.MessageSequence) {
405    this.picture = image.createPictureFromParcel(messageSequence);
406    this.picture.getMainPixelmap().getImageInfo().then((imageInfo : image.ImageInfo) => {
407      console.info('Unmarshalling to get mainPixelmap information height:' + imageInfo.size.height + ' width:' + imageInfo.size.width);
408    }).catch((error: BusinessError) => {
409      console.error('Unmarshalling failed error.code: ${error.code} ,error.message: ${error.message}');
410    });
411    return true;
412  }
413}
414
415async function Marshalling_UnMarshalling() {
416  if (pictureObj != null) {
417    let parcelable: MySequence = new MySequence(pictureObj);
418    let data: rpc.MessageSequence = rpc.MessageSequence.create();
419    // marshalling.
420    data.writeParcelable(parcelable);
421    let ret: MySequence = new MySequence(pictureObj);
422    // unmarshalling.
423    data.readParcelable(ret);
424  } else {
425    console.error('PictureObj is null');
426  }
427}
428```
429
430## release<sup>13+</sup>
431
432release(): void
433
434Releases this Picture object.
435
436**System capability**: SystemCapability.Multimedia.Image.Core
437
438**Example**
439
440```ts
441import { image } from '@kit.ImageKit';
442
443async function Release() {
444  let funcName = "Release";
445  if (pictureObj != null) {
446    pictureObj.release();
447    if (pictureObj.getMainPixelmap() == null) {
448      console.info(funcName, 'Success !');
449    } else {
450      console.error(funcName, 'Failed !');
451    }
452  } else {
453    console.error('PictureObj is null');
454  }
455}
456```
457