1# Using PixelMap for PixelMap Operations
2
3To process a certain area in an image, you can perform PixelMap operations, which are usually used to beautify the image.
4
5As shown in the figure below, the pixel data of a rectangle in an image is read, modified, and then written back to the corresponding area of the original image.
6
7**Figure 1** PixelMap operation
8
9![PixelMap operation](figures/bitmap-operation.png)
10
11## How to Develop
12
13Read [Image](../../reference/apis-image-kit/js-apis-image.md#pixelmap7) for APIs related to PixelMap operations.
14
151. Complete [image decoding](image-decoding.md) and obtain a **PixelMap** object.
16
172. Obtain information from the **PixelMap** object.
18
19   ```ts
20   import { image } from '@kit.ImageKit';
21   // Obtain the total number of bytes of this PixelMap object.
22   let pixelBytesNumber : number = pixelMap.getPixelBytesNumber();
23   // Obtain the number of bytes per row of this PixelMap object.
24   let rowBytes : number = pixelMap.getBytesNumberPerRow();
25   // Obtain the pixel density of this PixelMap object. Pixel density refers to the number of pixels per inch of an image. A larger value of the pixel density indicates a finer image.
26   let density : number = pixelMap.getDensity();
27   ```
28
293. Read and modify the pixel data of the target area, and write the modified data back to the original image.
30   > **NOTE**
31   >
32   > To prevent issues with the PixelMap due to inconsistent pixel formats, you are advised to use **readPixelsToBuffer** with **writeBufferToPixels** and **readPixels** with **writePixels** in corresponding pairs.
33
34   ```ts
35   import { BusinessError } from '@kit.BasicServicesKit';
36   // Scenario 1: Read and modify data of the entire image.
37   // Read the pixel data of the PixelMap based on the PixelMap's pixel format and write the data to the buffer.
38   const buffer = new ArrayBuffer(pixelBytesNumber);
39   pixelMap.readPixelsToBuffer(buffer).then(() => {
40     console.info('Succeeded in reading image pixel data.');
41   }).catch((error : BusinessError) => {
42     console.error('Failed to read image pixel data. The error is: ' + error);
43   })
44   // Read the pixel data in the buffer based on the PixelMap's pixel format and write the data to the PixelMap.
45   pixelMap.writeBufferToPixels(buffer).then(() => {
46     console.info('Succeeded in writing image pixel data.');
47   }).catch((error : BusinessError) => {
48     console.error('Failed to write image pixel data. The error is: ' + error);
49   })
50
51   // Scenario 2: Read and modify image data in a specified area.
52   // Read the pixel data in the area specified by PositionArea.region in the PixelMap in the BGRA_8888 format and write the data to the PositionArea.pixels buffer.
53   const area : image.PositionArea = {
54     pixels: new ArrayBuffer(8),
55     offset: 0,
56     stride: 8,
57     region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
58   }
59   pixelMap.readPixels(area).then(() => {
60     console.info('Succeeded in reading the image data in the area.');
61   }).catch((error : BusinessError) => {
62     console.error('Failed to read the image data in the area. The error is: ' + error);
63   })
64   // Read the pixel data in the PositionArea.pixels buffer in the BGRA_8888 format and write the data to the area specified by PositionArea.region in the PixelMap.
65   pixelMap.writePixels(area).then(() => {
66     console.info('Succeeded in writing the image data in the area.');
67   }).catch((error : BusinessError) => {
68     console.error('Failed to write the image data in the area. The error is: ' + error);
69   })
70   ```
71
72## Development Example: Cloning (Deep Copying) a PixelMap
73
741. Complete [image decoding](image-decoding.md) and obtain a **PixelMap** object.
75
762. Clone (deep copy) this **PixelMap** object to obtain a new PixelMap.
77   > **NOTE**
78   >
79   > When creating a PixelMap, you must set **srcPixelFormat** to the pixel format of the original PixelMap. Otherwise, the new PixelMap is abnormal.
80
81     ```ts
82      /**
83       * Clone (deep copy) a PixelMap.
84       *
85       * @param pixelMap - PixelMap to clone.
86       * @param desiredPixelFormat - Pixel format of the new PixelMap. If this parameter is not specified, the pixel format of the current PixelMap is used.
87       * @return Returns a new PixelMap.
88       **/
89      clonePixelMap(pixelMap: PixelMap, desiredPixelFormat?: image.PixelMapFormat): PixelMap {
90        // Obtain the image information of the current PixelMap.
91        const imageInfo = pixelMap.getImageInfoSync();
92        // Read the pixel data of the PixelMap and write the data to a buffer array based on the PixelMap's pixel format.
93        const buffer = new ArrayBuffer(pixelMap.getPixelBytesNumber());
94        pixelMap.readPixelsToBufferSync(buffer);
95        // Generate initialization options based on the image information of the current PixelMap.
96        const options: image.InitializationOptions = {
97          // Pixel format of the current PixelMap.
98          srcPixelFormat: imageInfo.pixelFormat,
99          // Pixel format of the new PixelMap.
100          pixelFormat: desiredPixelFormat ?? imageInfo.pixelFormat,
101          // Size of the current PixelMap.
102          size: imageInfo.size
103        };
104        // Generate a new PixelMap based on the initialization options and buffer array.
105        return image.createPixelMapSync(buffer, options);
106      }
107     ```
108
109<!--RP1-->
110<!--RP1End-->
111