1# Using ImageSource to Decode Pictures
2
3Image decoding refers to the process of decoding an archived image in a supported format (JPEG and HEIF currently) into a [picture](image-overview.md).
4
5## How to Develop
6
7Read [Image](../../reference/apis-image-kit/js-apis-image.md#imagesource) for APIs related to image decoding.
8
91. Import the image module.
10
11   ```ts
12   import { image } from '@kit.ImageKit';
13   ```
14
152. Obtain an image.
16   - Method 1: Obtain the sandbox path. For details about how to obtain the sandbox path, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths). For details about the application sandbox and how to push files to the application sandbox directory, see [File Management](../../file-management/app-sandbox-directory.md).
17
18      ```ts
19      const context : Context = getContext(this);
20      const filePath : string = context.cacheDir + '/test.jpg';
21      ```
22
23   - Method 2: Obtain the file descriptor of the image through the sandbox path. For details, see [file.fs API Reference](../../reference/apis-core-file-kit/js-apis-file-fs.md).
24      To use this method, you must import the \@kit.CoreFileKit module first.
25
26      ```ts
27      import { fileIo } from '@kit.CoreFileKit';
28      ```
29
30      Then call **fileIo.openSync()** to obtain the file descriptor.
31
32      ```ts
33      const context = getContext(this);
34      const filePath = context.cacheDir + '/test.jpg';
35      const file : fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE);
36      const fd : number = file?.fd;
37      ```
38
39   - Method 3: Obtain the array buffer of the resource file through the resource manager. For details, see [ResourceManager API Reference](../../reference/apis-localization-kit/js-apis-resource-manager.md#getrawfilecontent9-1).
40
41      ```ts
42      const context : Context = getContext(this);
43      // Obtain a resource manager.
44      const resourceMgr : resourceManager.ResourceManager = context.resourceManager;
45      ```
46
47      The method of obtaining the resource manager varies according to the application model. After obtaining the resource manager, call **resourceMgr.getRawFileContent()** to obtain the array buffer of the resource file.
48
49      ```ts
50      resourceMgr.getRawFileContent('test.jpg').then((fileData : Uint8Array) => {
51         console.log("Succeeded in getting RawFileContent")
52         // Obtain the array buffer of the image.
53         const buffer = fileData.buffer.slice(0);
54      }).catch((err : BusinessError) => {
55         console.error("Failed to get RawFileContent")
56      });
57
58      ```
59
60   - Method 4: Obtain the raw file descriptor of the resource file through the resource manager. For details, see [ResourceManager API Reference](../../reference/apis-localization-kit/js-apis-resource-manager.md#getrawfd9-1).
61
62      ```ts
63      const context : Context = getContext(this);
64      // Obtain a resource manager.
65      const resourceMgr : resourceManager.ResourceManager = context.resourceManager;
66      ```
67
68      The method of obtaining the resource manager varies according to the application model. After obtaining the resource manager, call **resourceMgr.getRawFd()** to obtain the raw file descriptor of the resource file.
69
70      ```ts
71
72      resourceMgr.getRawFd('test.jpg').then((rawFileDescriptor : resourceManager.RawFileDescriptor) => {
73         console.log("Succeeded in getting RawFileDescriptor")
74      }).catch((err : BusinessError) => {
75         console.error("Failed to get RawFileDescriptor")
76      });
77      ```
78
793. Create an **ImageSource** instance.
80
81   - Method 1: Create an **ImageSource** instance using the sandbox path. The sandbox path can be obtained by using method 1 in step 2.
82
83      ```ts
84      // path indicates the obtained sandbox path.
85      const imageSource : image.ImageSource = image.createImageSource(filePath);
86      ```
87
88   - Method 2: Create an **ImageSource** instance using the file descriptor. The file descriptor can be obtained by using method 2 in step 2.
89
90      ```ts
91      // fd is the obtained file descriptor.
92      const imageSource : image.ImageSource = image.createImageSource(fd);
93      ```
94
95   - Method 3: Create an **ImageSource** instance using an array buffer. The array buffer can be obtained by using method 3 in step 2.
96
97      ```ts
98      const imageSource : image.ImageSource = image.createImageSource(buffer);
99      ```
100
101   - Method 4: Create an **ImageSource** instance using the raw file descriptor of the resource file. The raw file descriptor can be obtained by using method 4 in step 2.
102
103      ```ts
104      const imageSource : image.ImageSource = image.createImageSource(rawFileDescriptor);
105      ```
106
1074. Set **DecodingOptions** and decode the image to obtain a picture.
108
109   Set the expected format for decoding.
110      ```ts
111      import { BusinessError } from '@kit.BasicServicesKit';
112      import image from '@kit.ImageKit';
113      let img = await getContext(this).resourceManager.getMediaContent($r('app.media.picture'));
114      let imageSource:image.ImageSource = image.createImageSource(img.buffer.slice(0));
115      let options: image.DecodingOptionsForPicture = {
116         desiredAuxiliaryPictures: [image.AuxiliaryPictureType.GAINMAP] // GAINMAP indicates the type of the auxiliary picture to be decoded.
117      };
118      // Create a Picture instance.
119      imageSource.createPicture(options).then((picture: image.Picture) => {
120         console.log("Create picture succeeded.")
121      }).catch((err: BusinessError) => {
122         console.error("Create picture failed.")
123      });
124      ```
125
1265. Manipulate the picture, for example, obtaining an auxiliary picture. For details about how to manipulate a picture and auxiliary picture, see [Image API](../../reference/apis-image-kit/js-apis-image.md#picture13).
127
128   ```ts
129   // Obtain an auxiliary picture.
130   let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP;
131   let auxPicture: image.AuxiliaryPicture | null = picture.getAuxiliaryPicture(type);
132   // Obtain the information of the auxiliary picture.
133   let auxinfo: image.AuxiliaryPictureInfo = auxPicture.getAuxiliaryPictureInfo();
134   console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType +
135      ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width +
136      ' rowStride: ' +  auxinfo.rowStride +  ' pixelFormat: ' + auxinfo.pixelFormat +
137      ' colorSpace: ' +  auxinfo.colorSpace);
138   // Read data of the auxiliary picture and write the data to an ArrayBuffer.
139   auxPicture.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => {
140      console.info('Read pixels to buffer success.');
141   }).catch((error: BusinessError) => {
142      console.error('Read pixels to buffer failed error.code: ' + JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message));
143   });
144   auxPicture.release();
145   ```
146
1476. Release the **Picture** instance.
148
149   ```ts
150   picture.release();
151   ```
152
153## Sample Code - Decoding an Image in Resource Files
154
1551. Obtain a resource manager.
156
157   ```ts
158   const context : Context = getContext(this);
159   // Obtain a resource manager.
160   const resourceMgr : resourceManager.ResourceManager = context.resourceManager;
161   ```
162
1632. Create an **ImageSource** instance.
164   - Create an **ImageSource** instance by using the array buffer of **test.jpg** in the **rawfile** folder.
165
166     ```ts
167      resourceMgr.getRawFileContent('test.jpg').then((fileData : Uint8Array) => {
168         console.log("Succeeded in getting RawFileContent")
169         // Obtain the array buffer of the image.
170         const buffer = fileData.buffer.slice(0);
171         const imageSource : image.ImageSource = image.createImageSource(buffer);
172      }).catch((err : BusinessError) => {
173         console.error("Failed to get RawFileContent")
174      });
175     ```
176
177   - Create an **ImageSource** instance by using the raw file descriptor of **test.jpg** in the **rawfile** folder.
178
179     ```ts
180      resourceMgr.getRawFd('test.jpg').then((rawFileDescriptor : resourceManager.RawFileDescriptor) => {
181         console.log("Succeeded in getting RawFd")
182         const imageSource : image.ImageSource = image.createImageSource(rawFileDescriptor);
183      }).catch((err : BusinessError) => {
184         console.error("Failed to get RawFd")
185      });
186     ```
187
1883. Create a **Picture** instance.
189
190   ```ts
191   let options: image.DecodingOptionsForPicture = {
192      desiredAuxiliaryPictures: [image.AuxiliaryPictureType.GAINMAP] // GAINMAP indicates the type of the auxiliary picture to be decoded.
193   };
194   imageSource.createPicture(options).then((picture: image.Picture) => {
195      console.log("Create picture succeeded.")
196   }).catch((err : BusinessError) => {
197      console.error("Create picture failed.")
198   });
199   ```
200
2014. Manipulate the picture, for example, obtaining an auxiliary picture. For details about how to manipulate a picture and auxiliary picture, see [Image API](../../reference/apis-image-kit/js-apis-image.md#picture13).
202
203   ```ts
204   // Obtain an auxiliary picture.
205   let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP;
206   let auxPicture: image.AuxiliaryPicture | null = picture.getAuxiliaryPicture(type);
207   // Obtain the information of the auxiliary picture.
208   let auxinfo: image.AuxiliaryPictureInfo = auxPicture.getAuxiliaryPictureInfo();
209   console.info('GetAuxiliaryPictureInfo Type: ' + auxinfo.auxiliaryPictureType +
210      ' height: ' + auxinfo.size.height + ' width: ' + auxinfo.size.width +
211      ' rowStride: ' +  auxinfo.rowStride +  ' pixelFormat: ' + auxinfo.pixelFormat +
212      ' colorSpace: ' +  auxinfo.colorSpace);
213   // Read data of the auxiliary picture and write the data to an ArrayBuffer.
214   auxPicture.readPixelsToBuffer().then((pixelsBuffer: ArrayBuffer) => {
215      console.info('Read pixels to buffer success.');
216   }).catch((error: BusinessError) => {
217      console.error('Read pixels to buffer failed error.code: ' + JSON.stringify(error.code) + ' ,error.message:' + JSON.stringify(error.message));
218   });
219   auxPicture.release();
220   ```
221
2225. Release the **Picture** instance.
223
224   ```ts
225   picture.release();
226   ```
227