1# @ohos.multimedia.sendableImage (Image Processing Based on Sendable Objects)
2
3The **sendableImage** module provides APIs for image processing based on sendable objects. You can use the APIs to create a **PixelMap** object with specified properties or read pixels of an image (or even in a region of an image).
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import { sendableImage } from '@kit.ImageKit';
13```
14
15## sendableImage.createPixelMap
16
17createPixelMap(colors: ArrayBuffer, options: image.InitializationOptions): Promise\<PixelMap>
18
19Creates a **PixelMap** object with the default BGRA_8888 format and specified pixel properties. This API uses a promise to return the result.
20
21**System capability**: SystemCapability.Multimedia.Image.Core
22
23**Parameters**
24
25| Name | Type                                            | Mandatory| Description                                                            |
26| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- |
27| colors  | ArrayBuffer                                      | Yes  | Color array in BGRA_8888 format.                                       |
28| options | [InitializationOptions](js-apis-image.md#initializationoptions8) | Yes  | Pixel properties, including the alpha type, size, scale mode, pixel format, and editable.|
29
30**Return value**
31
32| Type                            | Description                                                                   |
33| -------------------------------- | ----------------------------------------------------------------------- |
34| Promise\<[PixelMap](#pixelmap)> | Promise used to return the **PixelMap** object.<br>If the size of the created PixelMap exceeds that of the original image, the PixelMap size of the original image is returned.|
35
36**Example**
37
38```ts
39import { image } from '@kit.ImageKit';
40import { BusinessError } from '@kit.BasicServicesKit';
41
42async function Demo() {
43    const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
44    let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
45    sendableImage.createPixelMap(color, opts).then((pixelMap: sendableImage.PixelMap) => {
46        console.info('Succeeded in creating pixelmap.');
47    }).catch((error: BusinessError) => {
48        console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`);
49    })
50}
51```
52
53## sendableImage.createPixelMapFromParcel
54
55createPixelMapFromParcel(sequence: rpc.MessageSequence): PixelMap
56
57Creates a **PixelMap** object from a **MessageSequence** object.
58
59**System capability**: SystemCapability.Multimedia.Image.Core
60
61**Parameters**
62
63| Name                | Type                                                 | Mandatory| Description                                    |
64| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- |
65| sequence               | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | Yes  | **MessageSequence** object that stores the **PixelMap** information.     |
66
67**Return value**
68
69| Type                            | Description                 |
70| -------------------------------- | --------------------- |
71| [PixelMap](#pixelmap) | Returns a **PixelMap** object if the operation is successful; throws an error otherwise.|
72
73**Error codes**
74
75For details about the error codes, see [Image Error Codes](errorcode-image.md).
76
77| ID| Error Message|
78| ------- | --------------------------------------------|
79| 62980096 | If the operation failed|
80| 62980097 | If the ipc error|
81| 62980115 | Invalid input parameter|
82| 62980105 | Failed to get the data|
83| 62980177 | Abnormal API environment|
84| 62980178 | Failed to create the PixelMap|
85| 62980179 | Abnormal buffer size|
86| 62980180 | FD mapping failed|
87| 62980246 | Failed to read the PixelMap|
88
89**Example**
90
91```ts
92import { sendableImage } from '@kit.ImageKit';
93import { image } from '@kit.ImageKit';
94import { rpc } from '@kit.IPCKit';
95import { BusinessError } from '@kit.BasicServicesKit';
96
97class MySequence implements rpc.Parcelable {
98    pixel_map: sendableImage.PixelMap;
99    constructor(conPixelmap: sendableImage.PixelMap) {
100        this.pixel_map = conPixelmap;
101    }
102    marshalling(messageSequence: rpc.MessageSequence) {
103        this.pixel_map.marshalling(messageSequence);
104        return true;
105    }
106    unmarshalling(messageSequence: rpc.MessageSequence) {
107        try {
108            this.pixel_map = sendableImage.createPixelMapFromParcel(messageSequence);
109        } catch(e) {
110            let error = e as BusinessError;
111            console.error(`createPixelMapFromParcel error. code is ${error.code}, message is ${error.message}`);
112            return false;
113        }
114      return true;
115    }
116}
117async function Demo() {
118   const color: ArrayBuffer = new ArrayBuffer(96);
119   let bufferArr: Uint8Array = new Uint8Array(color);
120   for (let i = 0; i < bufferArr.length; i++) {
121      bufferArr[i] = 0x80;
122   }
123   let opts: image.InitializationOptions = {
124      editable: true,
125      pixelFormat: 4,
126      size: { height: 4, width: 6 },
127      alphaType: 3
128   }
129   let pixelMap: image.PixelMap | undefined = undefined;
130   sendableImage.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => {
131      pixelMap = srcPixelMap;
132   })
133   if (pixelMap != undefined) {
134     // Implement serialization.
135     let parcelable: MySequence = new MySequence(pixelMap);
136     let data: rpc.MessageSequence = rpc.MessageSequence.create();
137     data.writeParcelable(parcelable);
138
139     // Implement deserialization to obtain data through the RPC.
140     let ret: MySequence = new MySequence(pixelMap);
141     data.readParcelable(ret);
142
143     // Obtain the PixelMap object.
144     let unmarshPixelmap = ret.pixel_map;
145   }
146}
147```
148
149## sendableImage.createPixelMapFromSurface
150
151createPixelMapFromSurface(surfaceId: string, region: image.Region): Promise\<PixelMap>
152
153Creates a **PixelMap** object from a surface ID.
154
155**System capability**: SystemCapability.Multimedia.Image.Core
156
157**Parameters**
158
159| Name                | Type                | Mandatory| Description                                    |
160| ---------------------- | -------------       | ---- | ---------------------------------------- |
161| surfaceId              | string              | Yes  | Surface ID, which is obtained from [XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md).|
162| region                 | [Region](../apis-image-kit/js-apis-image.md#region8)  | Yes  | Size of the image after cropping.                        |
163
164**Return value**
165| Type                            | Description                 |
166| -------------------------------- | --------------------- |
167| Promise\<[PixelMap](#pixelmap)> | Returns a **PixelMap** object if the operation is successful; throws an error otherwise.|
168
169**Error codes**
170
171For details about the error codes, see [Image Error Codes](errorcode-image.md).
172
173| ID| Error Message|
174| ------- | --------------------------------------------|
175| 62980115 | Invalid input parameter|
176| 62980105 | Failed to get the data|
177| 62980178 | Failed to create the PixelMap|
178
179**Example**
180
181```ts
182import { image } from '@kit.ImageKit';
183import { BusinessError } from '@kit.BasicServicesKit';
184
185async function Demo(surfaceId: string) {
186    let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
187    sendableImage.createPixelMapFromSurface(surfaceId, region).then(() => {
188        console.info('Succeeded in creating pixelmap from Surface');
189    }).catch((error: BusinessError) => {
190        console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`);
191    });
192}
193```
194
195## sendableImage.createPixelMapSync
196
197createPixelMapSync(colors: ArrayBuffer, options: image.InitializationOptions): PixelMap
198
199Creates a **PixelMap** object with the specified pixel properties. This API returns the result synchronously.
200
201**System capability**: SystemCapability.Multimedia.Image.Core
202
203**Parameters**
204
205| Name | Type                                            | Mandatory| Description                                                            |
206| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- |
207| colors  | ArrayBuffer                                      | Yes  | Color array in BGRA_8888 format.                                       |
208| options | [InitializationOptions](js-apis-image.md#initializationoptions8) | Yes  | Pixel properties, including the alpha type, size, scale mode, pixel format, and editable.|
209
210**Return value**
211| Type                            | Description                 |
212| -------------------------------- | --------------------- |
213| [PixelMap](#pixelmap) | Returns a **PixelMap** object if the operation is successful; throws an error otherwise.|
214
215**Error codes**
216
217For details about the error codes, see [Image Error Codes](errorcode-image.md).
218
219| ID| Error Message|
220| ------- | --------------------------------------------|
221|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed|
222
223**Example**
224
225```ts
226import { image } from '@kit.ImageKit';
227import { BusinessError } from '@kit.BasicServicesKit';
228
229async function Demo() {
230    const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
231    let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
232    let pixelMap : sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts);
233    return pixelMap;
234}
235```
236
237## sendableImage.convertFromPixelMap
238
239convertFromPixelMap(pixelMap: image.PixelMap): PixelMap
240
241Creates a **PixelMap** object under **sendableImage** from a **PixelMap** object under **image**. This API returns the result synchronously. The APIs of the **PixelMap** object under **image** cannot be called any more.
242
243**System capability**: SystemCapability.Multimedia.Image.Core
244
245**Parameters**
246
247| Name | Type                                            | Mandatory| Description                                                            |
248| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- |
249| pixelMap | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes  | **PixelMap** object under **image**.|
250
251**Return value**
252| Type                            | Description                 |
253| -------------------------------- | --------------------- |
254| [PixelMap](#pixelmap) | Returns a **PixelMap** object, which is sendable, if the operation is successful; throws an error otherwise.|
255
256**Error codes**
257
258For details about the error codes, see [Image Error Codes](errorcode-image.md).
259
260| ID| Error Message|
261| ------- | --------------------------------------------|
262|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed|
263
264**Example**
265
266```ts
267import { image } from '@kit.ImageKit';
268import { BusinessError } from '@kit.BasicServicesKit';
269
270async function Demo() {
271    const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
272    let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
273    let pixelMap : image.PixelMap = image.createPixelMapSync(color, opts);
274    let sendablePixelMap : sendableImage.PixelMap = sendableImage.convertFromPixelMap(pixelMap);
275    return sendablePixelMap;
276}
277```
278
279## sendableImage.convertToPixelMap
280
281convertToPixelMap(pixelMap: PixelMap): image.PixelMap
282
283Creates a **PixelMap** object under **image** from a **PixelMap** object under **sendableImage**. This API returns the result synchronously. The APIs of the **PixelMap** object under **sendableImage** cannot be called any more.
284
285**System capability**: SystemCapability.Multimedia.Image.Core
286
287**Parameters**
288
289| Name | Type                                            | Mandatory| Description                                                            |
290| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- |
291| pixelMap | [PixelMap](#pixelmap) | Yes  | PixelMap object under **sendableImage**.|
292
293**Return value**
294| Type                            | Description                 |
295| -------------------------------- | --------------------- |
296| [PixelMap](js-apis-image.md#pixelmap7) | Returns a **PixelMap** object, which is not sendable, if the operation is successful; throws an error otherwise.|
297
298**Error codes**
299
300For details about the error codes, see [Image Error Codes](errorcode-image.md).
301
302| ID| Error Message|
303| ------- | --------------------------------------------|
304|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed|
305
306**Example**
307
308```ts
309import { image } from '@kit.ImageKit';
310import { BusinessError } from '@kit.BasicServicesKit';
311
312async function Demo() {
313    const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
314    let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
315    let sendablePixelMap : sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts);
316    let pixelMap : image.PixelMap = sendableImage.convertToPixelMap(sendablePixelMap);
317    return pixelMap;
318}
319```
320
321## PixelMap
322
323Provides APIs to read or write image data and obtain image information. Before calling any API in **PixelMap**, you must use [createPixelMap](#sendableimagecreatepixelmap) to create a **PixelMap** object. Currently, the maximum size of a serialized PixelMap is 128 MB. A larger size will cause a display failure. The size is calculated as follows: Width * Height * Number of bytes occupied by each pixel.
324
325The **PixelMap** object under **sendableImage** supports the **sendable** attribute and sharing of the worker thread. The [Convert](#sendableimageconverttopixelmap) API can be used to convert a **PixelMap** object in **sendableImage** to a **PixelMap** object in **image**, and vise versa. After the conversion, the APIs of the original object cannot be called. Otherwise, error 501 is reported. When processing a **PixelMap** object across threads, you need to consider the multithreaded problem.
326
327Before calling any API in **PixelMap**, you must use [sendableImage.createPixelMap](#sendableimagecreatepixelmap) to create a **PixelMap** object.
328
329### Attributes
330
331**System capability**: SystemCapability.Multimedia.Image.Core
332
333| Name             | Type   | Readable| Writable| Description                      |
334| -----------------| ------- | ---- | ---- | -------------------------- |
335| isEditable        | boolean | Yes  | No  | Whether the pixels of an image are editable.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
336| isStrideAlignment | boolean | Yes  | No  | Whether the image memory is the DMA memory. In the case of DMA, a 256-byte alignment is carried out, which means that a padding area exists at the end of the line.|
337
338### readPixelsToBuffer
339
340readPixelsToBuffer(dst: ArrayBuffer): Promise\<void>
341
342Reads the pixels of this image and writes the data to an ArrayBuffer. This API uses a promise to return the result. If the PixelMap is created in the BGRA_8888 format, the data read is the same as the original data.
343
344**Atomic service API**: This API can be used in atomic services since API version 12.
345
346**System capability**: SystemCapability.Multimedia.Image.Core
347
348**Parameters**
349
350| Name| Type       | Mandatory| Description                                                                                                 |
351| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- |
352| dst    | ArrayBuffer | Yes  | Buffer to which the pixels will be written. The buffer size is obtained by calling [getPixelBytesNumber](#getpixelbytesnumber).|
353
354**Return value**
355
356| Type          | Description                                           |
357| -------------- | ----------------------------------------------- |
358| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.|
359
360**Example**
361
362```ts
363import { BusinessError } from '@kit.BasicServicesKit';
364
365async function Demo() {
366    const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
367    if (pixelMap != undefined) {
368        pixelMap.readPixelsToBuffer(readBuffer).then(() => {
369            console.info('Succeeded in reading image pixel data.'); // Called if the condition is met.
370        }).catch((error: BusinessError) => {
371            console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`); // Called if no condition is met.
372        })
373    }
374}
375```
376
377### readPixelsToBufferSync
378
379readPixelsToBufferSync(dst: ArrayBuffer): void
380
381Reads the pixels of this image and writes the data to an ArrayBuffer. This API returns the result synchronously.
382
383**Atomic service API**: This API can be used in atomic services since API version 12.
384
385**System capability**: SystemCapability.Multimedia.Image.Core
386
387**Parameters**
388
389| Name  | Type                | Mandatory| Description                                                                                                 |
390| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- |
391| dst      | ArrayBuffer          | Yes  | Buffer to which the pixels will be written. The buffer size is obtained by calling [getPixelBytesNumber](#getpixelbytesnumber).|
392
393**Error codes**
394
395For details about the error codes, see [Image Error Codes](errorcode-image.md).
396
397| ID| Error Message|
398| ------- | --------------------------------------------|
399|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
400|  501    | Resource Unavailable |
401
402**Example**
403
404```ts
405import { BusinessError } from '@kit.BasicServicesKit';
406
407async function Demo() {
408    const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
409    if (pixelMap != undefined) {
410        pixelMap.readPixelsToBufferSync(readBuffer);
411    }
412}
413```
414
415### readPixels
416
417readPixels(area: image.PositionArea): Promise\<void>
418
419Reads the pixels in an area. This API uses a promise to return the result.
420
421**Atomic service API**: This API can be used in atomic services since API version 12.
422
423**System capability**: SystemCapability.Multimedia.Image.Core
424
425**Parameters**
426
427| Name| Type                          | Mandatory| Description                    |
428| ------ | ------------------------------ | ---- | ------------------------ |
429| area   | [PositionArea](js-apis-image.md#positionarea7) | Yes  | Area from which the pixels will be read.|
430
431**Return value**
432
433| Type          | Description                                               |
434| :------------- | :-------------------------------------------------- |
435| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.|
436
437**Example**
438
439```ts
440import { image } from '@kit.ImageKit';
441import { BusinessError } from '@kit.BasicServicesKit';
442
443async function Demo() {
444    const area: image.PositionArea = {
445        pixels: new ArrayBuffer(8),
446        offset: 0,
447        stride: 8,
448        region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
449    };
450    if (pixelMap != undefined) {
451        pixelMap.readPixels(area).then(() => {
452            console.info('Succeeded in reading the image data in the area.'); // Called if the condition is met.
453        }).catch((error: BusinessError) => {
454            console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`); // Called if no condition is met.
455        })
456    }
457}
458```
459
460### readPixelsSync
461
462readPixelsSync(area: image.PositionArea): void
463
464Reads the pixels in an area. This API returns the result synchronously.
465
466**Atomic service API**: This API can be used in atomic services since API version 12.
467
468**System capability**: SystemCapability.Multimedia.Image.Core
469
470**Parameters**
471
472| Name| Type                          | Mandatory| Description                    |
473| ------ | ------------------------------ | ---- | ------------------------ |
474| area   | [PositionArea](js-apis-image.md#positionarea7) | Yes  | Area from which the pixels will be read.|
475
476**Error codes**
477
478For details about the error codes, see [Image Error Codes](errorcode-image.md).
479
480| ID| Error Message|
481| ------- | --------------------------------------------|
482|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
483|  501    | Resource Unavailable |
484
485**Example**
486
487```ts
488import { image } from '@kit.ImageKit';
489import { BusinessError } from '@kit.BasicServicesKit';
490
491async function Demo() {
492    const area : image.PositionArea = {
493        pixels: new ArrayBuffer(8),
494        offset: 0,
495        stride: 8,
496        region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
497    };
498    if (pixelMap != undefined) {
499        pixelMap.readPixelsSync(area);
500    }
501}
502```
503
504### writePixels
505
506writePixels(area: image.PositionArea): Promise\<void>
507
508Writes the pixels to an area. This API uses a promise to return the result.
509
510**Atomic service API**: This API can be used in atomic services since API version 12.
511
512**System capability**: SystemCapability.Multimedia.Image.Core
513
514**Parameters**
515
516| Name| Type                          | Mandatory| Description                |
517| ------ | ------------------------------ | ---- | -------------------- |
518| area   | [PositionArea](js-apis-image.md#positionarea7) | Yes  | Area to which the pixels will be written.|
519
520**Return value**
521
522| Type          | Description                                               |
523| :------------- | :-------------------------------------------------- |
524| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.|
525
526**Example**
527
528```ts
529import { image } from '@kit.ImageKit';
530import { BusinessError } from '@kit.BasicServicesKit';
531
532async function Demo() {
533    const area: image.PositionArea = {
534        pixels: new ArrayBuffer(8),
535        offset: 0,
536        stride: 8,
537        region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
538    };
539    let bufferArr: Uint8Array = new Uint8Array(area.pixels);
540    for (let i = 0; i < bufferArr.length; i++) {
541        bufferArr[i] = i + 1;
542    }
543    if (pixelMap != undefined) {
544        pixelMap.writePixels(area).then(() => {
545            console.info('Succeeded to write pixelmap into the specified area.');
546        }).catch((error: BusinessError) => {
547            console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`);
548        })
549    }
550}
551```
552
553### writePixelsSync
554
555writePixelsSync(area: image.PositionArea): void
556
557Writes the pixels to an area. This API returns the result synchronously.
558
559**Atomic service API**: This API can be used in atomic services since API version 12.
560
561**System capability**: SystemCapability.Multimedia.Image.Core
562
563**Parameters**
564
565| Name| Type                          | Mandatory| Description                |
566| ------ | ------------------------------ | ---- | -------------------- |
567| area   | [PositionArea](js-apis-image.md#positionarea7) | Yes  | Area to which the pixels will be written.|
568
569**Error codes**
570
571For details about the error codes, see [Image Error Codes](errorcode-image.md).
572
573| ID| Error Message|
574| ------- | --------------------------------------------|
575|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
576|  501    | Resource Unavailable |
577
578**Example**
579
580```ts
581import { image } from '@kit.ImageKit';
582import { BusinessError } from '@kit.BasicServicesKit';
583
584async function Demo() {
585    const area: image.PositionArea = {
586        pixels: new ArrayBuffer(8),
587        offset: 0,
588        stride: 8,
589        region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
590    };
591    let bufferArr: Uint8Array = new Uint8Array(area.pixels);
592    for (let i = 0; i < bufferArr.length; i++) {
593        bufferArr[i] = i + 1;
594    }
595    if (pixelMap != undefined) {
596        pixelMap.writePixelsSync(area);
597    }
598}
599```
600
601### writeBufferToPixels
602
603writeBufferToPixels(src: ArrayBuffer): Promise\<void>
604
605Reads image data in an ArrayBuffer and writes the data to a **PixelMap** object. This API uses a promise to return the result.
606
607**Atomic service API**: This API can be used in atomic services since API version 12.
608
609**System capability**: SystemCapability.Multimedia.Image.Core
610
611**Parameters**
612
613| Name| Type       | Mandatory| Description          |
614| ------ | ----------- | ---- | -------------- |
615| src    | ArrayBuffer | Yes  | Buffer from which the image data will be read.|
616
617**Return value**
618
619| Type          | Description                                           |
620| -------------- | ----------------------------------------------- |
621| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.|
622
623**Example**
624
625```ts
626import { BusinessError } from '@kit.BasicServicesKit';
627
628async function Demo() {
629    const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
630    let bufferArr: Uint8Array = new Uint8Array(color);
631    for (let i = 0; i < bufferArr.length; i++) {
632        bufferArr[i] = i + 1;
633    }
634    if (pixelMap != undefined) {
635        pixelMap.writeBufferToPixels(color).then(() => {
636            console.info("Succeeded in writing data from a buffer to a PixelMap.");
637        }).catch((error: BusinessError) => {
638            console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`);
639        })
640    }
641}
642```
643
644### writeBufferToPixelsSync
645
646writeBufferToPixelsSync(src: ArrayBuffer): void
647
648Reads image data in an ArrayBuffer and writes the data to a **PixelMap** object. This API returns the result synchronously.
649
650**Atomic service API**: This API can be used in atomic services since API version 12.
651
652**System capability**: SystemCapability.Multimedia.Image.Core
653
654**Parameters**
655
656| Name| Type       | Mandatory| Description          |
657| ------ | ----------- | ---- | -------------- |
658| src    | ArrayBuffer | Yes  | Buffer from which the image data will be read.|
659
660**Error codes**
661
662For details about the error codes, see [Image Error Codes](errorcode-image.md).
663
664| ID| Error Message|
665| ------- | --------------------------------------------|
666|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
667|  501    | Resource Unavailable |
668
669**Example**
670
671```ts
672import { BusinessError } from '@kit.BasicServicesKit';
673
674async function Demo() {
675    const color : ArrayBuffer = new ArrayBuffer(96);  // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
676    let bufferArr : Uint8Array = new Uint8Array(color);
677    for (let i = 0; i < bufferArr.length; i++) {
678        bufferArr[i] = i + 1;
679    }
680    if (pixelMap != undefined) {
681        pixelMap.writeBufferToPixelsSync(color);
682    }
683}
684```
685
686### getImageInfo
687
688getImageInfo(): Promise\<image.ImageInfo>
689
690Obtains the image information. This API uses a promise to return the result.
691
692**Atomic service API**: This API can be used in atomic services since API version 12.
693
694**System capability**: SystemCapability.Multimedia.Image.Core
695
696**Return value**
697
698| Type                             | Description                                                       |
699| --------------------------------- | ----------------------------------------------------------- |
700| Promise\<[ImageInfo](js-apis-image.md#imageinfo)> | Promise used to return the image information. If the operation fails, an error message is returned.|
701
702**Example**
703
704```ts
705import { image } from '@kit.ImageKit';
706import { BusinessError } from '@kit.BasicServicesKit';
707
708async function Demo() {
709    if (pixelMap != undefined) {
710        pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => {
711            if (imageInfo != undefined) {
712                console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height);
713            }
714        }).catch((error: BusinessError) => {
715            console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`);
716        })
717    }
718}
719```
720
721### getImageInfoSync
722
723getImageInfoSync(): image.ImageInfo
724
725Obtains the image information. This API returns the result synchronously.
726
727**Atomic service API**: This API can be used in atomic services since API version 12.
728
729**System capability**: SystemCapability.Multimedia.Image.ImageSource
730
731**Return value**
732
733| Type                             | Description                                                       |
734| --------------------------------- | ----------------------------------------------------------- |
735| [ImageInfo](js-apis-image.md#imageinfo)           | Image information.                                               |
736
737**Error codes**
738
739For details about the error codes, see [Image Error Codes](errorcode-image.md).
740
741| ID| Error Message|
742| ------- | --------------------------------------------|
743|  501    | Resource Unavailable |
744
745**Example**
746
747```ts
748import { image } from '@kit.ImageKit';
749import { BusinessError } from '@kit.BasicServicesKit';
750
751async function Demo() {
752    if (pixelMap != undefined) {
753        let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync();
754    }
755}
756```
757
758### getBytesNumberPerRow
759
760getBytesNumberPerRow(): number
761
762Obtains the number of bytes per row of this image.
763
764**Atomic service API**: This API can be used in atomic services since API version 12.
765
766**System capability**: SystemCapability.Multimedia.Image.Core
767
768**Return value**
769
770| Type  | Description                |
771| ------ | -------------------- |
772| number | Number of bytes per row.|
773
774**Example**
775
776```ts
777let rowCount: number = pixelMap.getBytesNumberPerRow();
778```
779
780### getPixelBytesNumber
781
782getPixelBytesNumber(): number
783
784Obtains the total number of bytes of this image.
785
786**Atomic service API**: This API can be used in atomic services since API version 12.
787
788**System capability**: SystemCapability.Multimedia.Image.Core
789
790**Return value**
791
792| Type  | Description                |
793| ------ | -------------------- |
794| number | Total number of bytes.|
795
796**Example**
797
798```ts
799let pixelBytesNumber: number = pixelMap.getPixelBytesNumber();
800```
801
802### getDensity
803
804getDensity():number
805
806Obtains the density of this image.
807
808**Atomic service API**: This API can be used in atomic services since API version 12.
809
810**System capability**: SystemCapability.Multimedia.Image.Core
811
812**Return value**
813
814| Type  | Description           |
815| ------ | --------------- |
816| number | Density of the image.|
817
818**Example**
819
820```ts
821let getDensity: number = pixelMap.getDensity();
822```
823
824### opacity
825
826opacity(rate: number): Promise\<void>
827
828Sets an opacity rate for this image. This API uses a promise to return the result.
829
830**Atomic service API**: This API can be used in atomic services since API version 12.
831
832**System capability**: SystemCapability.Multimedia.Image.Core
833
834**Parameters**
835
836| Name| Type  | Mandatory| Description                       |
837| ------ | ------ | ---- | --------------------------- |
838| rate   | number | Yes  | Opacity rate.|
839
840**Return value**
841
842| Type          | Description                                           |
843| -------------- | ----------------------------------------------- |
844| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.|
845
846**Example**
847
848```ts
849import { BusinessError } from '@kit.BasicServicesKit';
850
851async function Demo() {
852    let rate: number = 0.5;
853    if (pixelMap != undefined) {
854        pixelMap.opacity(rate).then(() => {
855            console.info('Succeeded in setting opacity.');
856        }).catch((err: BusinessError) => {
857            console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`);
858        })
859    }
860}
861```
862
863### opacitySync
864
865opacitySync(rate: number): void
866
867Sets the opacity rate for this PixelMap and initializes the PixelMap.
868
869**Atomic service API**: This API can be used in atomic services since API version 12.
870
871**System capability**: SystemCapability.Multimedia.Image.Core
872
873**Parameters**
874
875| Name  | Type                | Mandatory| Description                          |
876| -------- | -------------------- | ---- | ------------------------------ |
877| rate     | number               | Yes  | Opacity rate.  |
878
879**Error codes**
880
881For details about the error codes, see [Image Error Codes](errorcode-image.md).
882
883| ID| Error Message|
884| ------- | --------------------------------------------|
885|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
886|  501    | Resource Unavailable |
887
888**Example**
889
890```ts
891import { BusinessError } from '@kit.BasicServicesKit';
892
893async function Demo() {
894    let rate : number = 0.5;
895    if (pixelMap != undefined) {
896        pixelMap.opacitySync(rate);
897    }
898}
899```
900
901### createAlphaPixelmap
902
903createAlphaPixelmap(): Promise\<PixelMap>
904
905Creates a **PixelMap** object that contains only the alpha channel information. This object can be used for the shadow effect. This API uses a promise to return the result.
906
907**Atomic service API**: This API can be used in atomic services since API version 12.
908
909**System capability**: SystemCapability.Multimedia.Image.Core
910
911**Return value**
912
913| Type                            | Description                       |
914| -------------------------------- | --------------------------- |
915| Promise\<[PixelMap](#pixelmap)> | Promise used to return the **PixelMap** object.|
916
917**Example**
918
919```ts
920import { BusinessError } from '@kit.BasicServicesKit';
921
922async function Demo() {
923    if (pixelMap != undefined) {
924        pixelMap.createAlphaPixelmap().then((alphaPixelMap: sendableImage.PixelMap) => {
925            console.info('Succeeded in creating alpha pixelmap.');
926        }).catch((error: BusinessError) => {
927            console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`);
928        })
929    }
930}
931```
932
933### createAlphaPixelmapSync
934
935createAlphaPixelmapSync(): PixelMap
936
937Creates a **PixelMap** object that contains only the alpha channel information. This object can be used for the shadow effect. This API returns the result synchronously.
938
939**Atomic service API**: This API can be used in atomic services since API version 12.
940
941**System capability**: SystemCapability.Multimedia.Image.Core
942
943**Return value**
944
945| Type                            | Description                 |
946| -------------------------------- | --------------------- |
947| [PixelMap](#pixelmap) | Returns a **PixelMap** object if the operation is successful; throws an error otherwise.|
948
949**Error codes**
950
951For details about the error codes, see [Image Error Codes](errorcode-image.md).
952
953| ID| Error Message|
954| ------- | --------------------------------------------|
955|  401    | Parameter error. Possible causes: 1.Parameter verification failed |
956|  501    | Resource Unavailable |
957
958**Example**
959
960```ts
961import { BusinessError } from '@kit.BasicServicesKit';
962
963async function Demo() {
964    let resPixelMap : sendableImage.PixelMap = pixelMap.createAlphaPixelmapSync();
965    return resPixelMap;
966}
967```
968
969### scale
970
971scale(x: number, y: number): Promise\<void>
972
973Scales this image based on a given width and height. This API uses a promise to return the result.
974
975**Atomic service API**: This API can be used in atomic services since API version 12.
976
977**System capability**: SystemCapability.Multimedia.Image.Core
978
979**Parameters**
980
981| Name| Type  | Mandatory| Description                           |
982| ------ | ------ | ---- | ------------------------------- |
983| x      | number | Yes  | Scaling multiple of the width.|
984| y      | number | Yes  | Scaling multiple of the height.|
985
986**Return value**
987
988| Type          | Description                       |
989| -------------- | --------------------------- |
990| Promise\<void> | Promise used to return the result.|
991
992**Example**
993
994```ts
995import { BusinessError } from '@kit.BasicServicesKit';
996
997async function Demo() {
998    let scaleX: number = 2.0;
999    let scaleY: number = 1.0;
1000    if (pixelMap != undefined) {
1001        pixelMap.scale(scaleX, scaleY).then(() => {
1002            console.info('Succeeded in scaling pixelmap.');
1003        }).catch((err: BusinessError) => {
1004            console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`);
1005
1006        })
1007    }
1008}
1009```
1010
1011### scaleSync
1012
1013scaleSync(x: number, y: number): void
1014
1015Scales this image based on a given width and height. This API returns the result synchronously.
1016
1017**Atomic service API**: This API can be used in atomic services since API version 12.
1018
1019**System capability**: SystemCapability.Multimedia.Image.Core
1020
1021**Parameters**
1022
1023| Name| Type  | Mandatory| Description                           |
1024| ------ | ------ | ---- | ------------------------------- |
1025| x      | number | Yes  | Scaling multiple of the width.|
1026| y      | number | Yes  | Scaling multiple of the height.|
1027
1028**Error codes**
1029
1030For details about the error codes, see [Image Error Codes](errorcode-image.md).
1031
1032| ID| Error Message|
1033| ------- | --------------------------------------------|
1034|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
1035|  501    | Resource Unavailable |
1036
1037**Example**
1038
1039```ts
1040import { BusinessError } from '@kit.BasicServicesKit';
1041
1042async function Demo() {
1043    let scaleX: number = 2.0;
1044    let scaleY: number = 1.0;
1045    if (pixelMap != undefined) {
1046        pixelMap.scaleSync(scaleX, scaleY);
1047    }
1048}
1049```
1050
1051### translate
1052
1053translate(x: number, y: number): Promise\<void>
1054
1055Translates this image based on given coordinates. This API uses a promise to return the result.
1056
1057**Atomic service API**: This API can be used in atomic services since API version 12.
1058
1059**System capability**: SystemCapability.Multimedia.Image.Core
1060
1061**Parameters**
1062
1063| Name| Type  | Mandatory| Description       |
1064| ------ | ------ | ---- | ----------- |
1065| x      | number | Yes  | X coordinate to translate.|
1066| y      | number | Yes  | Y coordinate to translate.|
1067
1068**Return value**
1069
1070| Type          | Description                       |
1071| -------------- | --------------------------- |
1072| Promise\<void> | Promise used to return the result.|
1073
1074**Example**
1075
1076```ts
1077import { BusinessError } from '@kit.BasicServicesKit';
1078
1079async function Demo() {
1080    let translateX: number = 50.0;
1081    let translateY: number = 10.0;
1082    if (pixelMap != undefined) {
1083        pixelMap.translate(translateX, translateY).then(() => {
1084            console.info('Succeeded in translating pixelmap.');
1085        }).catch((err: BusinessError) => {
1086            console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`);
1087        })
1088    }
1089}
1090```
1091
1092### translateSync
1093
1094translateSync(x: number, y: number): void
1095
1096Translates this image based on given coordinates. This API returns the result synchronously.
1097
1098**Atomic service API**: This API can be used in atomic services since API version 12.
1099
1100**System capability**: SystemCapability.Multimedia.Image.Core
1101
1102**Parameters**
1103
1104| Name  | Type                | Mandatory| Description                           |
1105| -------- | -------------------- | ---- | ------------------------------- |
1106| x        | number               | Yes  | Scaling multiple of the width.|
1107| y        | number               | Yes  | Scaling multiple of the height.|
1108
1109**Error codes**
1110
1111For details about the error codes, see [Image Error Codes](errorcode-image.md).
1112
1113| ID| Error Message|
1114| ------- | --------------------------------------------|
1115|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
1116|  501    | Resource Unavailable |
1117
1118**Example**
1119
1120```ts
1121import { BusinessError } from '@kit.BasicServicesKit';
1122
1123async function Demo() {
1124    let translateX : number = 50.0;
1125    let translateY : number = 10.0;
1126    if (pixelMap != undefined) {
1127        pixelMap.translateSync(translateX, translateY);
1128    }
1129}
1130```
1131
1132### rotate
1133
1134rotate(angle: number): Promise\<void>
1135
1136Rotates this image based on a given angle. This API uses a promise to return the result.
1137
1138**Atomic service API**: This API can be used in atomic services since API version 12.
1139
1140**System capability**: SystemCapability.Multimedia.Image.Core
1141
1142**Parameters**
1143
1144| Name| Type  | Mandatory| Description                         |
1145| ------ | ------ | ---- | ----------------------------- |
1146| angle  | number | Yes  | Angle to rotate.             |
1147
1148**Return value**
1149
1150| Type          | Description                       |
1151| -------------- | --------------------------- |
1152| Promise\<void> | Promise used to return the result.|
1153
1154**Example**
1155
1156```ts
1157import { BusinessError } from '@kit.BasicServicesKit';
1158
1159async function Demo() {
1160    let angle: number = 90.0;
1161    if (pixelMap != undefined) {
1162        pixelMap.rotate(angle).then(() => {
1163            console.info('Succeeded in rotating pixelmap.');
1164        }).catch((err: BusinessError) => {
1165            console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`);
1166        })
1167    }
1168}
1169```
1170
1171### rotateSync
1172
1173rotateSync(angle: number): void
1174
1175Rotates this image based on a given angle. This API returns the result synchronously.
1176
1177**Atomic service API**: This API can be used in atomic services since API version 12.
1178
1179**System capability**: SystemCapability.Multimedia.Image.Core
1180
1181**Parameters**
1182
1183| Name  | Type                | Mandatory| Description                         |
1184| -------- | -------------------- | ---- | ----------------------------- |
1185| angle    | number               | Yes  | Angle to rotate.             |
1186
1187**Error codes**
1188
1189For details about the error codes, see [Image Error Codes](errorcode-image.md).
1190
1191| ID| Error Message|
1192| ------- | --------------------------------------------|
1193|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
1194|  501    | Resource Unavailable |
1195
1196**Example**
1197
1198```ts
1199import { BusinessError } from '@kit.BasicServicesKit';
1200
1201async function Demo() {
1202    let angle : number = 90.0;
1203    if (pixelMap != undefined) {
1204        pixelMap.rotateSync(angle);
1205    }
1206}
1207```
1208
1209### flip
1210
1211flip(horizontal: boolean, vertical: boolean): Promise\<void>
1212
1213Flips this image horizontally or vertically, or both. This API uses a promise to return the result.
1214
1215**Atomic service API**: This API can be used in atomic services since API version 12.
1216
1217**System capability**: SystemCapability.Multimedia.Image.Core
1218
1219**Parameters**
1220
1221| Name    | Type   | Mandatory| Description     |
1222| ---------- | ------- | ---- | --------- |
1223| horizontal | boolean | Yes  | Whether to flip the image horizontally.|
1224| vertical   | boolean | Yes  | Whether to flip the image vertically.|
1225
1226**Return value**
1227
1228| Type          | Description                       |
1229| -------------- | --------------------------- |
1230| Promise\<void> | Promise used to return the result.|
1231
1232**Example**
1233
1234```ts
1235import { BusinessError } from '@kit.BasicServicesKit';
1236
1237async function Demo() {
1238    let horizontal: boolean = true;
1239    let vertical: boolean = false;
1240    if (pixelMap != undefined) {
1241        pixelMap.flip(horizontal, vertical).then(() => {
1242            console.info('Succeeded in flipping pixelmap.');
1243        }).catch((err: BusinessError) => {
1244            console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`);
1245
1246        })
1247    }
1248}
1249```
1250
1251### flipSync
1252
1253flipSync(horizontal: boolean, vertical: boolean): void
1254
1255Flips this image horizontally or vertically, or both. This API returns the result synchronously.
1256
1257**Atomic service API**: This API can be used in atomic services since API version 12.
1258
1259**System capability**: SystemCapability.Multimedia.Image.Core
1260
1261**Parameters**
1262
1263| Name    | Type                | Mandatory| Description                         |
1264| ---------- | -------------------- | ---- | ----------------------------- |
1265| horizontal | boolean              | Yes  | Whether to flip the image horizontally.                   |
1266| vertical   | boolean              | Yes  | Whether to flip the image vertically.                   |
1267
1268**Error codes**
1269
1270For details about the error codes, see [Image Error Codes](errorcode-image.md).
1271
1272| ID| Error Message|
1273| ------- | --------------------------------------------|
1274|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
1275|  501    | Resource Unavailable |
1276
1277**Example**
1278
1279```ts
1280import { BusinessError } from '@kit.BasicServicesKit';
1281
1282async function Demo() {
1283    let horizontal : boolean = true;
1284    let vertical : boolean = false;
1285    if (pixelMap != undefined) {
1286        pixelMap.flipSync(horizontal, vertical);
1287    }
1288}
1289```
1290
1291### crop
1292
1293crop(region: image.Region): Promise\<void>
1294
1295Crops this image based on a given size. This API uses a promise to return the result.
1296
1297**Atomic service API**: This API can be used in atomic services since API version 12.
1298
1299**System capability**: SystemCapability.Multimedia.Image.Core
1300
1301**Parameters**
1302
1303| Name| Type              | Mandatory| Description       |
1304| ------ | ------------------ | ---- | ----------- |
1305| region | [Region](../apis-image-kit/js-apis-image.md#region8) | Yes  | Size of the image after cropping.|
1306
1307**Return value**
1308
1309| Type          | Description                       |
1310| -------------- | --------------------------- |
1311| Promise\<void> | Promise used to return the result.|
1312
1313**Example**
1314
1315```ts
1316import { image } from '@kit.ImageKit';
1317import { BusinessError } from '@kit.BasicServicesKit';
1318
1319async function Demo() {
1320    let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
1321    if (pixelMap != undefined) {
1322        pixelMap.crop(region).then(() => {
1323            console.info('Succeeded in cropping pixelmap.');
1324        }).catch((err: BusinessError) => {
1325            console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`);
1326
1327        });
1328    }
1329}
1330```
1331
1332### cropSync
1333
1334cropSync(region: image.Region): void
1335
1336Crops this image based on a given size. This API returns the result synchronously.
1337
1338**Atomic service API**: This API can be used in atomic services since API version 12.
1339
1340**System capability**: SystemCapability.Multimedia.Image.Core
1341
1342**Parameters**
1343
1344| Name  | Type                | Mandatory| Description                         |
1345| -------- | -------------------- | ---- | ----------------------------- |
1346| region   | [Region](../apis-image-kit/js-apis-image.md#region8)   | Yes  | Size of the image after cropping.                 |
1347
1348**Error codes**
1349
1350For details about the error codes, see [Image Error Codes](errorcode-image.md).
1351
1352| ID| Error Message|
1353| ------- | --------------------------------------------|
1354|  401    | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
1355|  501    | Resource Unavailable |
1356
1357**Example**
1358
1359```ts
1360import { image } from '@kit.ImageKit';
1361import { BusinessError } from '@kit.BasicServicesKit';
1362
1363async function Demo() {
1364    let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
1365    if (pixelMap != undefined) {
1366        pixelMap.cropSync(region);
1367    }
1368}
1369```
1370
1371### getColorSpace
1372
1373getColorSpace(): colorSpaceManager.ColorSpaceManager
1374
1375Obtains the color space of this image.
1376
1377**System capability**: SystemCapability.Multimedia.Image.Core
1378
1379**Return value**
1380
1381| Type                               | Description            |
1382| ----------------------------------- | ---------------- |
1383| [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | Color space.|
1384
1385**Error codes**
1386
1387For details about the error codes, see [Image Error Codes](errorcode-image.md).
1388
1389| ID| Error Message|
1390| ------- | --------------------------------------------|
1391| 62980101| If the image data abnormal.            |
1392| 62980103| If the image data unsupport.             |
1393| 62980115| If the image parameter invalid.            |
1394
1395**Example**
1396
1397```ts
1398async function Demo() {
1399    if (pixelMap != undefined) {
1400        let csm = pixelMap.getColorSpace();
1401    }
1402}
1403```
1404
1405### setColorSpace
1406
1407setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void
1408
1409Sets the color space for this image.
1410
1411**System capability**: SystemCapability.Multimedia.Image.Core
1412
1413**Parameters**
1414
1415| Name    | Type                               | Mandatory| Description           |
1416| ---------- | ----------------------------------- | ---- | --------------- |
1417| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | Yes  | Color space.|
1418
1419**Error codes**
1420
1421For details about the error codes, see [Image Error Codes](errorcode-image.md).
1422
1423| ID| Error Message|
1424| ------- | --------------------------------------------|
1425| 62980111| If the operation invalid.        |
1426| 62980115| If the image parameter invalid.             |
1427
1428**Example**
1429
1430```ts
1431import { colorSpaceManager } from '@kit.ArkGraphics2D';
1432async function Demo() {
1433    let colorSpaceName = colorSpaceManager.ColorSpace.SRGB;
1434    let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName);
1435    if (pixelMap != undefined) {
1436        pixelMap.setColorSpace(csm);
1437    }
1438}
1439```
1440
1441### applyColorSpace
1442
1443applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise\<void>
1444
1445Performs Color Space Converters (CSC) on the image pixel color based on a given color space. This API uses a promise to return the result.
1446
1447**System capability**: SystemCapability.Multimedia.Image.Core
1448
1449**Parameters**
1450
1451| Name| Type              | Mandatory| Description       |
1452| ------ | ------------------ | ---- | ----------- |
1453| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | Yes  | Target color space. SRGB, DCI_P3, DISPLAY_P3, and ADOBE_RGB_1998 are supported.|
1454
1455**Return value**
1456
1457| Type          | Description                       |
1458| -------------- | --------------------------- |
1459| Promise\<void> | Promise used to return the result.|
1460
1461**Error codes**
1462
1463For details about the error codes, see [Image Error Codes](errorcode-image.md).
1464
1465| ID| Error Message|
1466| ------- | ------------------------------------------|
1467| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed |
1468| 62980104| Failed to initialize the internal object. |
1469| 62980108| Failed to convert the color space.       |
1470| 62980115| Invalid image parameter.            |
1471
1472**Example**
1473
1474```ts
1475import { colorSpaceManager } from '@kit.ArkGraphics2D';
1476import { BusinessError } from '@kit.BasicServicesKit';
1477
1478async function Demo() {
1479    let colorSpaceName = colorSpaceManager.ColorSpace.SRGB;
1480    let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName);
1481    pixelMap.applyColorSpace(targetColorSpace).then(() => {
1482        console.info('Succeeded in applying color space for pixelmap object.');
1483    }).catch((error: BusinessError) => {
1484        console.error(`Failed to apply color space for pixelmap object. code is ${error.code}, message is ${error.message}`);
1485    })
1486}
1487```
1488
1489### marshalling
1490
1491marshalling(sequence: rpc.MessageSequence): void
1492
1493Marshals this **PixelMap** object and writes it to a **MessageSequence** object.
1494
1495**System capability**: SystemCapability.Multimedia.Image.Core
1496
1497**Parameters**
1498
1499| Name                | Type                                                 | Mandatory| Description                                    |
1500| ---------------------- | ------------------------------------------------------ | ---- | ---------------------------------------- |
1501| sequence               | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9)  | Yes  | **MessageSequence** object.                |
1502
1503**Error codes**
1504
1505For details about the error codes, see [Image Error Codes](errorcode-image.md).
1506
1507| ID| Error Message|
1508| ------- | --------------------------------------------|
1509| 62980115 | Invalid image parameter.              |
1510| 62980097 | IPC error.             |
1511
1512**Example**
1513```ts
1514import { sendableImage } from '@kit.ImageKit';
1515import { image } from '@kit.ImageKit';
1516import { rpc } from '@kit.IPCKit';
1517
1518class MySequence implements rpc.Parcelable {
1519    pixel_map: sendableImage.PixelMap;
1520    constructor(conPixelMap : sendableImage.PixelMap) {
1521        this.pixel_map = conPixelMap;
1522    }
1523    marshalling(messageSequence : rpc.MessageSequence) {
1524        this.pixel_map.marshalling(messageSequence);
1525        console.info('marshalling');
1526        return true;
1527    }
1528    unmarshalling(messageSequence : rpc.MessageSequence) {
1529      sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: sendableImage.PixelMap) => {
1530        pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: sendableImage.PixelMap) => {
1531          this.pixel_map = pixelMap;
1532          pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => {
1533            console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width);
1534          })
1535        })
1536      });
1537      return true;
1538    }
1539}
1540async function Demo() {
1541   const color: ArrayBuffer = new ArrayBuffer(96);
1542   let bufferArr: Uint8Array = new Uint8Array(color);
1543   for (let i = 0; i < bufferArr.length; i++) {
1544      bufferArr[i] = 0x80;
1545   }
1546   let opts: image.InitializationOptions = {
1547      editable: true,
1548      pixelFormat: 4,
1549      size: { height: 4, width: 6 },
1550      alphaType: 3
1551   }
1552   let pixelMap: sendableImage.PixelMap | undefined = undefined;
1553   sendableImage.createPixelMap(color, opts).then((srcPixelMap: sendableImage.PixelMap) => {
1554      pixelMap = srcPixelMap;
1555   })
1556   if (pixelMap != undefined) {
1557    // Implement serialization.
1558     let parcelable: MySequence = new MySequence(pixelMap);
1559     let data: rpc.MessageSequence = rpc.MessageSequence.create();
1560     data.writeParcelable(parcelable);
1561
1562    // Implement deserialization to obtain data through the RPC.
1563     let ret: MySequence = new MySequence(pixelMap);
1564     data.readParcelable(ret);
1565   }
1566}
1567```
1568
1569### unmarshalling
1570
1571unmarshalling(sequence: rpc.MessageSequence): Promise\<PixelMap>
1572
1573Unmarshals a **MessageSequence** object to obtain a **PixelMap** object.
1574To create a **PixelMap** object in synchronous mode, use [createPixelMapFromParcel](#sendableimagecreatepixelmapfromparcel).
1575
1576**System capability**: SystemCapability.Multimedia.Image.Core
1577
1578**Parameters**
1579
1580| Name                | Type                                                 | Mandatory| Description                                    |
1581| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- |
1582| sequence               | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | Yes  | **MessageSequence** object that stores the **PixelMap** information.     |
1583
1584**Return value**
1585
1586| Type                            | Description                 |
1587| -------------------------------- | --------------------- |
1588| Promise\<[PixelMap](#pixelmap)> | Promise used to return the result. If the operation fails, an error message is returned.|
1589
1590**Error codes**
1591
1592For details about the error codes, see [Image Error Codes](errorcode-image.md).
1593
1594| ID| Error Message|
1595| ------- | --------------------------------------------|
1596| 62980115 | Invalid image parameter.              |
1597| 62980097 | IPC error.              |
1598| 62980096 | The operation failed.         |
1599
1600**Example**
1601
1602```ts
1603import { sendableImage } from '@kit.ImageKit';
1604import { image } from '@kit.ImageKit';
1605import { rpc } from '@kit.IPCKit';
1606
1607class MySequence implements rpc.Parcelable {
1608    pixel_map: sendableImage.PixelMap;
1609    constructor(conPixelMap: sendableImage.PixelMap) {
1610        this.pixel_map = conPixelMap;
1611    }
1612    marshalling(messageSequence: rpc.MessageSequence) {
1613        this.pixel_map.marshalling(messageSequence);
1614        console.info('marshalling');
1615        return true;
1616    }
1617    unmarshalling(messageSequence: rpc.MessageSequence) {
1618      sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : sendableImage.PixelMap) => {
1619        pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : sendableImage.PixelMap) => {
1620          this.pixel_map = pixelMap;
1621          pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => {
1622            console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width);
1623          })
1624        })
1625      });
1626      return true;
1627    }
1628}
1629async function Demo() {
1630   const color: ArrayBuffer = new ArrayBuffer(96);
1631   let bufferArr: Uint8Array = new Uint8Array(color);
1632   for (let i = 0; i < bufferArr.length; i++) {
1633      bufferArr[i] = 0x80;
1634   }
1635   let opts: image.InitializationOptions = {
1636      editable: true,
1637      pixelFormat: 4,
1638      size: { height: 4, width: 6 },
1639      alphaType: 3
1640   }
1641   let pixelMap: sendableImage.PixelMap | undefined = undefined;
1642   sendableImage.createPixelMap(color, opts).then((srcPixelMap : sendableImage.PixelMap) => {
1643      pixelMap = srcPixelMap;
1644   })
1645   if (pixelMap != undefined) {
1646    // Implement serialization.
1647     let parcelable: MySequence = new MySequence(pixelMap);
1648     let data : rpc.MessageSequence = rpc.MessageSequence.create();
1649     data.writeParcelable(parcelable);
1650
1651    // Implement deserialization to obtain data through the RPC.
1652     let ret : MySequence = new MySequence(pixelMap);
1653     data.readParcelable(ret);
1654   }
1655}
1656```
1657
1658### release
1659
1660release():Promise\<void>
1661
1662Releases this **PixelMap** object. This API uses a promise to return the result.
1663
1664**Atomic service API**: This API can be used in atomic services since API version 12.
1665
1666**System capability**: SystemCapability.Multimedia.Image.Core
1667
1668**Return value**
1669
1670| Type          | Description                           |
1671| -------------- | ------------------------------- |
1672| Promise\<void> | Promise used to return the result.|
1673
1674**Example**
1675
1676```ts
1677import { BusinessError } from '@kit.BasicServicesKit';
1678
1679async function Demo() {
1680    if (pixelMap != undefined) {
1681        pixelMap.release().then(() => {
1682            console.info('Succeeded in releasing pixelmap object.');
1683        }).catch((error: BusinessError) => {
1684            console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`);
1685        })
1686    }
1687}
1688```
1689
1690## Size
1691
1692Describes the size of an image.
1693It inherits from [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable).
1694
1695**Widget capability**: This API can be used in ArkTS widgets since API version 12.
1696
1697**Atomic service API**: This API can be used in atomic services since API version 12.
1698
1699**System capability**: SystemCapability.Multimedia.Image.Core
1700
1701| Name  | Type  | Read Only| Optional| Description          |
1702| ------ | ------ | ---- | ---- | -------------- |
1703| height | number | No  | No  | Height of the output image, in px.|
1704| width  | number | No  | No  | Width of the output image, in px.|
1705
1706## Region
1707
1708Describes the region information.
1709It inherits from [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable).
1710
1711**Widget capability**: This API can be used in ArkTS widgets since API version 12.
1712
1713**Atomic service API**: This API can be used in atomic services since API version 12.
1714
1715**System capability**: SystemCapability.Multimedia.Image.Core
1716
1717| Name| Type         | Read Only| Optional| Description        |
1718| ---- | ------------- | ---- | ---- | ------------ |
1719| size | [Size](#size) | No  | No  | Region size.  |
1720| x    | number        | No  | No  | X coordinate.|
1721| y    | number        | No  | No  | Y coordinate.|
1722
1723## sendableImage.createImageSource
1724
1725createImageSource(uri: string): ImageSource
1726
1727Creates an **ImageSource** instance based on a given URI.
1728
1729
1730**Atomic service API**: This API can be used in atomic services since API version 12.
1731
1732**System capability**: SystemCapability.Multimedia.Image.ImageSource
1733
1734**Parameters**
1735
1736| Name| Type  | Mandatory| Description                              |
1737| ------ | ------ | ---- | ---------------------------------- |
1738| uri    | string | Yes  | Image path. Currently, only the application sandbox path is supported.<br>The following formats are supported: .jpg, .png, .gif, .bmp, .webp, .dng [SVG](./js-apis-image.md#svg), and ico.|
1739
1740**Return value**
1741
1742| Type                       | Description                                        |
1743| --------------------------- | -------------------------------------------- |
1744| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
1745
1746**Example**
1747
1748```ts
1749const context: Context = getContext(this);
1750const path: string = context.cacheDir + "/test.jpg";
1751const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(path);
1752```
1753
1754## sendableImage.createImageSource
1755
1756createImageSource(fd: number): ImageSource
1757
1758Creates an **ImageSource** instance based on a given file descriptor.
1759
1760**Atomic service API**: This API can be used in atomic services since API version 12.
1761
1762**System capability**: SystemCapability.Multimedia.Image.ImageSource
1763
1764**Parameters**
1765
1766| Name| Type  | Mandatory| Description         |
1767| ------ | ------ | ---- | ------------- |
1768| fd     | number | Yes  | File descriptor.|
1769
1770**Return value**
1771
1772| Type                       | Description                                        |
1773| --------------------------- | -------------------------------------------- |
1774| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
1775
1776**Example**
1777
1778```ts
1779import { fileIo as fs } from '@kit.CoreFileKit';
1780
1781const context: Context = getContext(this);
1782const path: string = context.cacheDir + "/test.jpg";
1783let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
1784const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(file.fd);
1785```
1786
1787## sendableImage.createImageSource
1788
1789createImageSource(buf: ArrayBuffer): ImageSource
1790
1791Creates an **ImageSource** instance based on buffers.
1792
1793**Widget capability**: This API can be used in ArkTS widgets since API version 12.
1794
1795**Atomic service API**: This API can be used in atomic services since API version 12.
1796
1797**System capability**: SystemCapability.Multimedia.Image.ImageSource
1798
1799**Parameters**
1800
1801| Name| Type       | Mandatory| Description            |
1802| ------ | ----------- | ---- | ---------------- |
1803| buf    | ArrayBuffer | Yes  | Array of image buffers.|
1804
1805**Return value**
1806
1807| Type                       | Description                                        |
1808| --------------------------- | -------------------------------------------- |
1809| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
1810
1811
1812**Example**
1813
1814```ts
1815const buf: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4.
1816const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(buf);
1817```
1818
1819## sendableImage.createImageReceiver
1820
1821createImageReceiver(size: image.Size, format: image.ImageFormat, capacity: number): ImageReceiver
1822
1823Creates an **ImageReceiver** instance based on the specified image size, format, and capacity.
1824
1825**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
1826
1827**Parameters**
1828
1829| Name  | Type  | Mandatory| Description                  |
1830| -------- | ------ | ---- | ---------------------- |
1831| size    | [image.Size](./js-apis-image.md#size)  | Yes  | Default size of the image.      |
1832| format   | [image.ImageFormat](./js-apis-image.md#imageformat9) | Yes  | Image format, which is a constant of **image.ImageFormat**. (Currently, only **ImageFormat:JPEG** is supported.)            |
1833| capacity | number | Yes  | Maximum number of images that can be accessed at the same time.|
1834
1835**Return value**
1836
1837| Type                            | Description                                   |
1838| -------------------------------- | --------------------------------------- |
1839| [ImageReceiver](#imagereceiver) | Returns an **ImageReceiver** instance if the operation is successful.|
1840
1841**Error codes**
1842
1843For details about the error codes, see [Image Error Codes](errorcode-image.md).
1844
1845| ID| Error Message|
1846| ------- | --------------------------------------------|
1847| 401| Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;   |
1848
1849**Example**
1850
1851```ts
1852import { image } from '@kit.ImageKit';
1853
1854let size: image.Size = {
1855    height: 8192,
1856    width: 8
1857}
1858let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
1859```
1860
1861## ImageSource
1862
1863Provides APIs to obtain image information. Before calling any API in **ImageSource**, you must use [createImageSource](#sendableimagecreateimagesource) to create an **ImageSource** instance.
1864
1865
1866### createPixelMap
1867
1868createPixelMap(options?: image.DecodingOptions): Promise\<PixelMap>
1869
1870Creates a **PixelMap** object based on image decoding parameters. This API uses a promise to return the result.
1871
1872**Widget capability**: This API can be used in ArkTS widgets since API version 12.
1873
1874**Atomic service API**: This API can be used in atomic services since API version 12.
1875
1876**System capability**: SystemCapability.Multimedia.Image.ImageSource
1877
1878**Parameters**
1879
1880| Name | Type                                | Mandatory| Description      |
1881| ------- | ------------------------------------ | ---- | ---------- |
1882| options | [image.DecodingOptions](./js-apis-image.md#decodingoptions7) | No  | Image decoding parameters.|
1883
1884**Return value**
1885
1886| Type                            | Description                 |
1887| -------------------------------- | --------------------- |
1888| Promise\<[PixelMap]> | Promise used to return the **PixelMap** object.|
1889
1890**Example**
1891
1892```ts
1893import { BusinessError } from '@kit.BasicServicesKit';
1894
1895const context: Context = getContext(this);
1896const path: string = context.cacheDir + "/test.jpg";
1897const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(path);
1898sendableImageSourceApi.createPixelMap().then((pixelMap: sendableImage.PixelMap) => {
1899    console.info('Succeeded in creating pixelMap object through image decoding parameters.');
1900}).catch((error: BusinessError) => {
1901    console.error(`Failed to create pixelMap object through image decoding parameters. code ${error.code}, message is ${error.message}`);
1902})
1903```
1904
1905### release
1906
1907release(): Promise\<void>
1908
1909Releases this **ImageSource** instance. This API uses a promise to return the result.
1910The thread that runs **release** is insecure.
1911
1912**System capability**: SystemCapability.Multimedia.Image.ImageSource
1913
1914**Return value**
1915
1916| Type          | Description                       |
1917| -------------- | --------------------------- |
1918| Promise\<void> | Promise used to return the result.|
1919
1920**Example**
1921
1922```ts
1923import { BusinessError } from '@kit.BasicServicesKit';
1924
1925const context: Context = getContext(this);
1926const path: string = context.cacheDir + "/test.jpg";
1927const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(path);
1928sendableImageSourceApi.release().then(() => {
1929    console.info('Succeeded in releasing the image source instance.');
1930}).catch((error: BusinessError) => {
1931    console.error(`Failed to release the image source instance. code ${error.code}, message is ${error.message}`);
1932})
1933```
1934
1935## Image
1936
1937Provides APIs for basic image operations, including obtaining image information and reading and writing image data. An **Image** instance is returned when [readNextImage](#readnextimage) and [readLatestImage](#readlatestimage) are called.
1938This class inherits from [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable).
1939
1940### Attributes
1941
1942**System capability**: SystemCapability.Multimedia.Image.Core
1943
1944| Name    | Type              | Read Only| Optional| Description                                              |
1945| -------- | ------------------ | ---- | ---- | -------------------------------------------------- |
1946| clipRect | [Region](#region) | No  | No  | Image area to be cropped.                                |
1947| size     | [Size](#size)      | Yes  | No  | Image size. If the **image** object stores the camera preview stream data (YUV image data), the width and height in **size** obtained correspond to those of the YUV image. If the **image** object stores the camera photo stream data (JPEG image data, which is already encoded), the width in **size** obtained is the JPEG data size, and the height is 1. The type of data stored in the **image** object depends on whether the application passes the surface ID in the receiver to a **previewOutput** or **captureOutput** object of the camera. For details about the best practices of camera preview and photo capture, see [Dual-Channel Preview (ArkTS)](../../media/camera/camera-dual-channel-preview.md) and [Photo Capture Sample (ArkTS)](../../media/camera/camera-shooting-case.md).                                        |
1948| format   | number             | Yes  | No  | Image format. For details, see [OH_NativeBuffer_Format](../apis-arkgraphics2d/_o_h___native_buffer.md#oh_nativebuffer_format).|
1949| timestamp<sup>12+</sup> | number         | Yes     | No  | Image timestamp. Timestamps, measured in nanoseconds, are usually monotonically increasing. The specific meaning and baseline of these timestamps are determined by the image producer, which is the camera in the camera preview and photo scenarios. As a result, images from different producers may carry timestamps with distinct meanings and baselines, making direct comparison between them infeasible. To obtain the generation time of a photo, you can use [getImageProperty](js-apis-image.md#getimageproperty11) to read the related EXIF information.|
1950
1951### getComponent
1952
1953getComponent(componentType: image.ComponentType): Promise\<image.Component>
1954
1955Obtains the component buffer from the **Image** instance based on the color component type. This API uses a promise to return the result.
1956The thread that runs **getComponent** is insecure.
1957
1958**System capability**: SystemCapability.Multimedia.Image.Core
1959
1960**Parameters**
1961
1962| Name       | Type                            | Mandatory| Description            |
1963| ------------- | -------------------------------- | ---- | ---------------- |
1964| componentType | [image.ComponentType](./js-apis-image.md#componenttype9) | Yes  | Color component type of the image.|
1965
1966**Return value**
1967
1968| Type                             | Description                             |
1969| --------------------------------- | --------------------------------- |
1970| Promise<[image.Component](./js-apis-image.md#component9)> | Promise used to return the component buffer.|
1971
1972**Example**
1973
1974```ts
1975import { BusinessError } from '@kit.BasicServicesKit';
1976import { image } from '@kit.ImageKit';
1977
1978async function Demo() {
1979  let size: image.Size = {
1980    height: 8192,
1981    width: 8
1982  }
1983  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
1984  let img = await receiver.readNextImage();
1985  img.getComponent(4).then((component: image.Component) => {
1986    console.info('getComponent succeeded.');
1987  }).catch((error: BusinessError) => {
1988    console.error(`getComponent failed code ${error.code}, message is ${error.message}`);
1989  })
1990}
1991```
1992
1993### release
1994
1995release(): Promise\<void>
1996
1997Releases this **Image** instance. This API uses a promise to return the result.
1998
1999The corresponding resources must be released before another image arrives. The thread that runs **release** is insecure.
2000
2001
2002**System capability**: SystemCapability.Multimedia.Image.Core
2003
2004**Return value**
2005
2006| Type          | Description                 |
2007| -------------- | --------------------- |
2008| Promise\<void> | Promise used to return the result.|
2009
2010**Example**
2011
2012```ts
2013import { BusinessError } from '@kit.BasicServicesKit';
2014import { image } from '@kit.ImageKit';
2015
2016async function Demo() {
2017  let size: image.Size = {
2018    height: 8192,
2019    width: 8
2020  }
2021  let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
2022  let img = await receiver.readNextImage();
2023  img.release().then(() => {
2024    console.info('release succeeded.');
2025  }).catch((error: BusinessError) => {
2026    console.error(`release failed. code ${error.code}, message is ${error.message}`);
2027  })
2028}
2029```
2030
2031## ImageReceiver
2032
2033You can use the **ImageReceiver** class to obtain the surface ID of a component, read the latest image or the next image, and release **ImageReceiver** instances.
2034
2035Before calling any APIs in **ImageReceiver**, you must create an **ImageReceiver** instance.
2036
2037### Attributes
2038
2039**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
2040
2041| Name    | Type                        | Read Only| Optional| Description              |
2042| -------- | ---------------------------- | ---- | ---- | ------------------ |
2043| size     | [image.Size](./js-apis-image.md#size)                | Yes  | No  | Image size.        |
2044| capacity | number                       | Yes  | No  | Maximum number of images that can be accessed at the same time.|
2045| format   | [image.ImageFormat](./js-apis-image.md#imageformat9) | Yes  | No  | Image format.        |
2046
2047### getReceivingSurfaceId
2048
2049getReceivingSurfaceId(): Promise\<string>
2050
2051Obtains a surface ID for the camera or other components. This API uses a promise to return the result.
2052
2053**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
2054
2055**Return value**
2056
2057| Type            | Description                |
2058| ---------------- | -------------------- |
2059| Promise\<string> | Promise used to return the surface ID.|
2060
2061**Example**
2062
2063```ts
2064import { BusinessError } from '@kit.BasicServicesKit';
2065import { image } from '@kit.ImageKit';
2066
2067let size: image.Size = {
2068    height: 8192,
2069    width: 8
2070}
2071let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
2072receiver.getReceivingSurfaceId().then((id: string) => {
2073    console.info('Succeeded in getting the ReceivingSurfaceId.');
2074}).catch((error: BusinessError) => {
2075    console.error(`Failed to get the ReceivingSurfaceId.code ${error.code}, message is ${error.message}`);
2076})
2077```
2078
2079### readLatestImage
2080
2081readLatestImage(): Promise\<Image>
2082
2083Reads the latest image from the **ImageReceiver** instance. This API uses a promise to return the result.
2084
2085This API can be called to receive data only after the [on](#on) callback is triggered. When the [Image](#image) object returned by this API is no longer needed, call [release](#release-2) to release the object. New data can be received only after the release.
2086
2087**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
2088
2089**Return value**
2090
2091| Type                     | Description              |
2092| ------------------------- | ------------------ |
2093| Promise<[Image](#image)> | Promise used to return the latest image.|
2094
2095**Example**
2096
2097```ts
2098import { BusinessError } from '@kit.BasicServicesKit';
2099import { image } from '@kit.ImageKit';
2100
2101let size: image.Size = {
2102    height: 8192,
2103    width: 8
2104}
2105let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
2106receiver.readLatestImage().then((img: image.Image) => {
2107    console.info('readLatestImage succeeded.');
2108}).catch((error: BusinessError) => {
2109    console.error(`readLatestImage failed. code ${error.code}, message is ${error.message}`);
2110})
2111```
2112
2113### readNextImage
2114
2115readNextImage(): Promise\<Image>
2116
2117Reads the next image from the **ImageReceiver** instance. This API uses a promise to return the result.
2118
2119This API can be called to receive data only after the [on](#on) callback is triggered. When the [Image](#image) object returned by this API is no longer needed, call [release](#release-2) to release the object. New data can be received only after the release.
2120
2121**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
2122
2123**Return value**
2124
2125| Type                     | Description                |
2126| ------------------------- | -------------------- |
2127| Promise<[Image](#image)> | Promise used to return the next image.|
2128
2129**Example**
2130
2131```ts
2132import { BusinessError } from '@kit.BasicServicesKit';
2133import { image } from '@kit.ImageKit';
2134
2135let size: image.Size = {
2136    height: 8192,
2137    width: 8
2138}
2139let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
2140receiver.readNextImage().then((img: image.Image) => {
2141    console.info('readNextImage succeeded.');
2142}).catch((error: BusinessError) => {
2143    console.error(`readNextImage failed. code ${error.code}, message is ${error.message}`);
2144})
2145```
2146
2147### on
2148
2149on(type: 'imageArrival', callback: AsyncCallback\<void>): void
2150
2151Listens for image arrival events.
2152
2153**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
2154
2155**Parameters**
2156
2157| Name  | Type                | Mandatory| Description                                                  |
2158| -------- | -------------------- | ---- | ------------------------------------------------------ |
2159| type     | string               | Yes  | Type of event to listen for. The value is fixed at **'imageArrival'**, which is triggered when an image is received.|
2160| callback | AsyncCallback\<void> | Yes  | Callback invoked for the event.                                      |
2161
2162**Example**
2163
2164```ts
2165import { BusinessError } from '@kit.BasicServicesKit';
2166import { image } from '@kit.ImageKit';
2167
2168let size: image.Size = {
2169    height: 8192,
2170    width: 8
2171}
2172let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
2173receiver.on('imageArrival', () => {
2174    // image arrival, do something.
2175})
2176```
2177
2178### release
2179
2180release(): Promise\<void>
2181
2182Releases this **ImageReceiver** instance. This API uses a promise to return the result.
2183The thread that runs **release** is insecure.
2184
2185**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
2186
2187**Return value**
2188
2189| Type          | Description              |
2190| -------------- | ------------------ |
2191| Promise\<void> | Promise used to return the result.|
2192
2193**Example**
2194
2195```ts
2196import { BusinessError } from '@kit.BasicServicesKit';
2197import { image } from '@kit.ImageKit';
2198
2199let size: image.Size = {
2200    height: 8192,
2201    width: 8
2202}
2203let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8);
2204receiver.release().then(() => {
2205    console.info('release succeeded.');
2206}).catch((error: BusinessError) => {
2207    console.error(`release failed. code ${error.code}, message is ${error.message}`);
2208})
2209```
2210