# Image Processing
The **Image** module provides APIs for image processing. You can use the APIs to create a **PixelMap** object with specified properties or read image pixel data (even in an area).
> **NOTE**
>
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```js
import image from '@ohos.multimedia.image';
```
## image.createPixelMap8+
createPixelMap(colors: ArrayBuffer, options: InitializationOptions): Promise\
Creates a **PixelMap** object with the default BGRA_8888 format and pixel properties specified. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- |
| colors | ArrayBuffer | Yes | Color array in BGRA_8888 format. |
| options | [InitializationOptions](#initializationoptions8) | Yes | Pixel properties, including the alpha type, size, scale mode, pixel format, and editable.|
**Return value**
| Type | Description |
| -------------------------------- | ----------------------------------------------------------------------- |
| Promise\<[PixelMap](#pixelmap7)> | Promise used to return the **PixelMap** object.
If the size of the created pixel map exceeds that of the original image, the pixel map size of the original image is returned.|
**Example**
```js
const color = new ArrayBuffer(96);
let bufferArr = new Uint8Array(color);
let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts)
.then((pixelmap) => {
})
```
## image.createPixelMap8+
createPixelMap(colors: ArrayBuffer, options: InitializationOptions, callback: AsyncCallback\): void
Creates a **PixelMap** object with the default BGRA_8888 format and pixel properties specified. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------ | ---- | -------------------------- |
| colors | ArrayBuffer | Yes | Color array in BGRA_8888 format. |
| options | [InitializationOptions](#initializationoptions8) | Yes | Pixel properties. |
| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | Yes | Callback used to return the **PixelMap** object.|
**Example**
```js
const color = new ArrayBuffer(96);
let bufferArr = new Uint8Array(color);
let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts, (error, pixelmap) => {
if(error) {
console.log('Failed to create pixelmap.');
} else {
console.log('Succeeded in creating pixelmap.');
}
})
```
## PixelMap7+
Provides APIs to read or write image pixel map data and obtain image pixel map information. Before calling any API in **PixelMap**, you must use **createPixelMap** to create a **PixelMap** object.
### Attributes
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Type | Readable| Writable| Description |
| ---------- | ------- | ---- | ---- | -------------------------- |
| isEditable | boolean | Yes | No | Whether the image pixel map is editable.|
### readPixelsToBuffer7+
readPixelsToBuffer(dst: ArrayBuffer): Promise\
Reads data of this pixel map and writes the data to an **ArrayBuffer**. This API uses a promise to return the result. If this pixel map is created in the BGRA_8888 format, the data read is the same as the original data.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- |
| dst | ArrayBuffer | Yes | Buffer to which the image pixel map data will be written. The buffer size is obtained by calling **getPixelBytesNumber**.|
**Return value**
| Type | Description |
| -------------- | ----------------------------------------------- |
| Promise\ | Promise used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
const readBuffer = new ArrayBuffer(96);
pixelmap.readPixelsToBuffer(readBuffer).then(() => {
console.log('Succeeded in reading image pixel data.'); // Called if the condition is met.
}).catch(error => {
('Failed to read image pixel data.'); // Called if no condition is met.
})
```
### readPixelsToBuffer7+
readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback\): void
Reads data of this pixel map and writes the data to an **ArrayBuffer**. This API uses an asynchronous callback to return the result. If this pixel map is created in the BGRA_8888 format, the data read is the same as the original data.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- |
| dst | ArrayBuffer | Yes | Buffer to which the image pixel map data will be written. The buffer size is obtained by calling **getPixelBytesNumber**.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned. |
**Example**
```js
const readBuffer = new ArrayBuffer(96);
pixelmap.readPixelsToBuffer(readBuffer, (err, res) => {
if(err) {
console.log('Failed to read image pixel data.'); // Called if no condition is met.
} else {
console.log('Succeeded in reading image pixel data.'); // Called if the condition is met.
}
})
```
### readPixels7+
readPixels(area: PositionArea): Promise\
Reads image pixel map data in an area. This API uses a promise to return the data read.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------ | ---- | ------------------------ |
| area | [PositionArea](#positionarea7) | Yes | Area from which the image pixel map data will be read.|
**Return value**
| Type | Description |
| :------------- | :-------------------------------------------------- |
| Promise\ | Promise used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
const area = {
pixels: new ArrayBuffer(8),
offset: 0,
stride: 8,
region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
}
pixelmap.readPixels(area).then(() => {
console.log('Succeeded in reading the image data in the area.'); // Called if the condition is met.
}).catch(error => {
console.log('Failed to read the image data in the area.'); // Called if no condition is met.
})
```
### readPixels7+
readPixels(area: PositionArea, callback: AsyncCallback\): void
Reads image pixel map data in an area. This API uses an asynchronous callback to return the data read.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | ------------------------------ |
| area | [PositionArea](#positionarea7) | Yes | Area from which the image pixel map data will be read. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
const color = new ArrayBuffer(96);
let bufferArr = new Uint8Array(color);
let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts, (err, pixelmap) => {
if(pixelmap == undefined){
console.info('createPixelMap failed.');
} else {
const area = { pixels: new ArrayBuffer(8),
offset: 0,
stride: 8,
region: { size: { height: 1, width: 2 }, x: 0, y: 0 }};
pixelmap.readPixels(area, () => {
console.info('readPixels success');
})
}
})
```
### writePixels7+
writePixels(area: PositionArea): Promise\
Writes image pixel map data to an area. This API uses a promise to return the operation result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------ | ---- | -------------------- |
| area | [PositionArea](#positionarea7) | Yes | Area to which the image pixel map data will be written.|
**Return value**
| Type | Description |
| :------------- | :-------------------------------------------------- |
| Promise\ | Promise used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
const color = new ArrayBuffer(96);
let bufferArr = new Uint8Array(color);
let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts)
.then( pixelmap => {
if (pixelmap == undefined) {
console.info('createPixelMap failed.');
}
const area = { pixels: new ArrayBuffer(8),
offset: 0,
stride: 8,
region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
}
let bufferArr = new Uint8Array(area.pixels);
for (var i = 0; i < bufferArr.length; i++) {
bufferArr[i] = i + 1;
}
pixelmap.writePixels(area).then(() => {
const readArea = { pixels: new ArrayBuffer(8),
offset: 0,
stride: 8,
// region.size.width + x < opts.width, region.size.height + y < opts.height
region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
}
})
}).catch(error => {
console.log('error: ' + error);
})
```
### writePixels7+
writePixels(area: PositionArea, callback: AsyncCallback\): void
Writes image pixel map data to an area. This API uses an asynchronous callback to return the operation result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------------ | ---- | ------------------------------ |
| area | [PositionArea](#positionarea7) | Yes | Area to which the image pixel map data will be written. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
const area = new ArrayBuffer(400);
pixelmap.writePixels(area, (error) => {
if (error != undefined) {
console.info('Failed to write pixelmap into the specified area.');
} else {
const readArea = {
pixels: new ArrayBuffer(20),
offset: 0,
stride: 8,
region: { size: { height: 1, width: 2 }, x: 0, y: 0 },
}
}
})
```
### writeBufferToPixels7+
writeBufferToPixels(src: ArrayBuffer): Promise\
Reads image data in an **ArrayBuffer** and writes the data to a **PixelMap** object. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------- | ---- | -------------- |
| src | ArrayBuffer | Yes | Buffer from which the image data will be read.|
**Return value**
| Type | Description |
| -------------- | ----------------------------------------------- |
| Promise\ | Promise used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
const color = new ArrayBuffer(96);
const pixelMap = new ArrayBuffer(400);
let bufferArr = new Uint8Array(color);
pixelMap.writeBufferToPixels(color).then(() => {
console.log("Succeeded in writing data from a buffer to a PixelMap.");
}).catch((err) => {
console.error("Failed to write data from a buffer to a PixelMap.");
})
```
### writeBufferToPixels7+
writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback\): void
Reads image data in an **ArrayBuffer** and writes the data to a **PixelMap** object. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------ |
| src | ArrayBuffer | Yes | Buffer from which the image data will be read. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
const color = new ArrayBuffer(96);
const pixelMap = new ArrayBuffer(400);
let bufferArr = new Uint8Array(color);
pixelMap.writeBufferToPixels(color, function(err) {
if (err) {
console.error("Failed to write data from a buffer to a PixelMap.");
return;
} else {
console.log("Succeeded in writing data from a buffer to a PixelMap.");
}
});
```
### getImageInfo7+
getImageInfo(): Promise\
Obtains pixel map information of this image. This API uses a promise to return the information.
**System capability**: SystemCapability.Multimedia.Image.Core
**Return value**
| Type | Description |
| --------------------------------- | ----------------------------------------------------------- |
| Promise\<[ImageInfo](#imageinfo)> | Promise used to return the pixel map information. If the operation fails, an error message is returned.|
**Example**
```js
const pixelMap = new ArrayBuffer(400);
pixelMap.getImageInfo().then(function(info) {
console.log("Succeeded in obtaining the image pixel map information.");
}).catch((err) => {
console.error("Failed to obtain the image pixel map information.");
});
```
### getImageInfo7+
getImageInfo(callback: AsyncCallback\): void
Obtains pixel map information of this image. This API uses an asynchronous callback to return the information.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback\<[ImageInfo](#imageinfo)> | Yes | Callback used to return the pixel map information. If the operation fails, an error message is returned.|
**Example**
```js
pixelmap.getImageInfo((imageInfo) => {
console.log("Succeeded in obtaining the image pixel map information.");
})
```
### getBytesNumberPerRow7+
getBytesNumberPerRow(): number
Obtains the number of bytes per row of this image pixel map.
**System capability**: SystemCapability.Multimedia.Image.Core
**Return value**
| Type | Description |
| ------ | -------------------- |
| number | Number of bytes per row.|
**Example**
```js
const color = new ArrayBuffer(96);
let bufferArr = new Uint8Array(color);
let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts, (err,pixelmap) => {
let rowCount = pixelmap.getBytesNumberPerRow();
})
```
### getPixelBytesNumber7+
getPixelBytesNumber(): number
Obtains the total number of bytes of this image pixel map.
**System capability**: SystemCapability.Multimedia.Image.Core
**Return value**
| Type | Description |
| ------ | -------------------- |
| number | Total number of bytes.|
**Example**
```js
let pixelBytesNumber = pixelmap.getPixelBytesNumber();
```
### getDensity9+
getDensity():number
Obtains the density of this image pixel map.
**System capability**: SystemCapability.Multimedia.Image.Core
**Return value**
| Type | Description |
| ------ | --------------- |
| number | Density of the image pixel map.|
**Example**
```js
let getDensity = pixelmap.getDensity();
```
### opacity9+
opacity(rate: number, callback: AsyncCallback\): void
Sets an opacity rate for this image pixel map. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------ |
| rate | number | Yes | Opacity rate to set. The value ranges from 0 to 1. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
async function () {
await pixelMap.opacity(0.5);
}
```
### opacity9+
opacity(rate: number): Promise\
Sets an opacity rate for this image pixel map. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | --------------------------- |
| rate | number | Yes | Opacity rate to set. The value ranges from 0 to 1.|
**Return value**
| Type | Description |
| -------------- | ----------------------------------------------- |
| Promise\ | Promise used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
async function () {
await pixelMap.opacity(0.5);
}
```
### createAlphaPixelmap9+
createAlphaPixelmap(): Promise\
Creates 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.
**System capability**: SystemCapability.Multimedia.Image.Core
**Return value**
| Type | Description |
| -------------------------------- | --------------------------- |
| Promise\<[PixelMap](#pixelmap7)> | Promise used to return the **PixelMap** object.|
**Example**
```js
pixelMap.createAlphaPixelmap(async (err, alphaPixelMap) => {
if (alphaPixelMap == undefined) {
console.info('Failed to obtain new pixel map.');
} else {
console.info('Succeed in obtaining new pixel map.');
}
})
```
### createAlphaPixelmap9+
createAlphaPixelmap(callback: AsyncCallback\): void
Creates a **PixelMap** object that contains only the alpha channel information. This object can be used for the shadow effect. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------ |
| callback | AsyncCallback\ | Yes | Callback used to return the **PixelMap** object.|
**Example**
```js
let pixelMap = await imageSource.createPixelMap();
if (pixelMap != undefined) {
pixelMap.createAlphaPixelmap(async (err, alphaPixelMap) => {
console.info('Failed to obtain new pixel map.');
})
} else {
console.info('Succeed in obtaining new pixel map.');
}
```
### scale9+
scale(x: number, y: number, callback: AsyncCallback\): void
Scales this image based on the input width and height. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------- |
| x | number | Yes | Scaling ratio of the width.|
| y | number | Yes | Scaling ratio of the height.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned. |
**Example**
```js
async function () {
await pixelMap.scale(2.0, 1.0);
}
```
### scale9+
scale(x: number, y: number): Promise\
Scales this image based on the input width and height. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------- |
| x | number | Yes | Scaling ratio of the width.|
| y | number | Yes | Scaling ratio of the height.|
**Return value**
| Type | Description |
| -------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
async function () {
await pixelMap.scale(2.0, 1.0);
}
```
### translate9+
translate(x: number, y: number, callback: AsyncCallback\): void
Translates this image based on the input coordinates. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ----------------------------- |
| x | number | Yes | X coordinate to translate. |
| y | number | Yes | Y coordinate to translate. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
async function () {
await pixelMap.translate(3.0, 1.0);
}
```
### translate9+
translate(x: number, y: number): Promise\
Translates this image based on the input coordinates. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ----------- |
| x | number | Yes | X coordinate to translate.|
| y | number | Yes | Y coordinate to translate.|
**Return value**
| Type | Description |
| -------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
async function () {
await pixelMap.translate(3.0, 1.0);
}
```
### rotate9+
rotate(angle: number, callback: AsyncCallback\): void
Rotates this image based on the input angle. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ----------------------------- |
| angle | number | Yes | Angle to rotate. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
async function () {
await pixelMap.rotate(90.0);
}
```
### rotate9+
rotate(angle: number): Promise\
Rotates this image based on the input angle. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ----------------------------- |
| angle | number | Yes | Angle to rotate. |
**Return value**
| Type | Description |
| -------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
async function () {
await pixelMap.rotate(90.0);
}
```
### flip9+
flip(horizontal: boolean, vertical: boolean, callback: AsyncCallback\): void
Flips this image horizontally or vertically, or both. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | -------------------- | ---- | ----------------------------- |
| horizontal | boolean | Yes | Whether to flip the image horizontally. |
| vertical | boolean | Yes | Whether to flip the image vertically. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
async function () {
await pixelMap.flip(false, true);
}
```
### flip9+
flip(horizontal: boolean, vertical: boolean): Promise\
Flips this image horizontally or vertically, or both. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------- | ---- | --------- |
| horizontal | boolean | Yes | Whether to flip the image horizontally.|
| vertical | boolean | Yes | Whether to flip the image vertically.|
**Return value**
| Type | Description |
| -------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
async function () {
await pixelMap.flip(false, true);
}
```
### crop9+
crop(region: Region, callback: AsyncCallback\): void
Crops this image based on the input size. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ----------------------------- |
| region | [Region](#region7) | Yes | Size of the image after cropping. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation fails, an error message is returned.|
**Example**
```js
async function () {
await pixelMap.crop({ x: 0, y: 0, size: { height: 100, width: 100 } });
}
```
### crop9+
crop(region: Region): Promise\
Crops this image based on the input size. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------ | ---- | ----------- |
| region | [Region](#region7) | Yes | Size of the image after cropping.|
**Return value**
| Type | Description |
| -------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
async function () {
await pixelMap.crop({ x: 0, y: 0, size: { height: 100, width: 100 } });
}
```
### release7+
release():Promise\
Releases this **PixelMap** object. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Return value**
| Type | Description |
| -------------- | ------------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
const color = new ArrayBuffer(96);
let bufferArr = new Uint8Array(color);
let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts, (pixelmap) => {
pixelmap.release().then(() => {
console.log('Succeeded in releasing pixelmap object.');
}).catch(error => {
console.log('Failed to release pixelmap object.');
})
})
```
### release7+
release(callback: AsyncCallback\): void
Releases this **PixelMap** object. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------ |
| callback | AsyncCallback\ | Yes | Callback used to return the result.|
**Example**
```js
const color = new ArrayBuffer(96);
let bufferArr = new Uint8Array(color);
let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts, (pixelmap) => {
pixelmap.release().then(() => {
console.log('Succeeded in releasing pixelmap object.');
})
})
```
## image.createImageSource
createImageSource(uri: string): ImageSource
Creates an **ImageSource** instance based on the URI.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ---------------------------------- |
| uri | string | Yes | Image path. Currently, only the application sandbox path is supported.
Currently, the following raw formats are supported: .jpg, .png, .gif, .bmp, and .webp.|
**Return value**
| Type | Description |
| --------------------------- | -------------------------------------------- |
| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
**Example**
```js
let path = this.context.getApplicationContext().fileDirs + "test.jpg";
const imageSourceApi = image.createImageSource(path);
```
## image.createImageSource9+
createImageSource(uri: string, options: SourceOptions): ImageSource
Creates an **ImageSource** instance based on the URI.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------- | ---- | ----------------------------------- |
| uri | string | Yes | Image path. Currently, only the application sandbox path is supported.
Currently, the following raw formats are supported: .jpg, .png, .gif, .bmp, and .webp.|
| options | [SourceOptions](#sourceoptions9) | Yes | Image properties, including the image index and default property value.|
**Return value**
| Type | Description |
| --------------------------- | -------------------------------------------- |
| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
**Example**
```js
const imageSourceApi = image.createImageSource('/sdcard/test.jpg');
```
## image.createImageSource7+
createImageSource(fd: number): ImageSource
Creates an **ImageSource** instance based on the file descriptor.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------- |
| fd | number | Yes | File descriptor.|
**Return value**
| Type | Description |
| --------------------------- | -------------------------------------------- |
| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
**Example**
```js
const imageSourceApi = image.createImageSource(0);
```
## image.createImageSource9+
createImageSource(fd: number, options: SourceOptions): ImageSource
Creates an **ImageSource** instance based on the file descriptor.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------- | ---- | ----------------------------------- |
| fd | number | Yes | File descriptor. |
| options | [SourceOptions](#sourceoptions9) | Yes | Image properties, including the image index and default property value.|
**Return value**
| Type | Description |
| --------------------------- | -------------------------------------------- |
| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
**Example**
```js
const imageSourceApi = image.createImageSource(fd);
```
## image.createImageSource9+
createImageSource(buf: ArrayBuffer): ImageSource
Creates an **ImageSource** instance based on the buffers.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------- | ---- | ---------------- |
| buf | ArrayBuffer | Yes | Array of image buffers.|
**Example**
```js
const buf = new ArrayBuffer(96);
const imageSourceApi = image.createImageSource(buf);
```
## image.createImageSource9+
createImageSource(buf: ArrayBuffer, options: SourceOptions): ImageSource
Creates an **ImageSource** instance based on the buffers.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | -------------------------------- | ---- | ------------------------------------ |
| buf | ArrayBuffer | Yes | Array of image buffers. |
| options | [SourceOptions](#sourceoptions9) | Yes | Image properties, including the image index and default property value.|
**Return value**
| Type | Description |
| --------------------------- | -------------------------------------------- |
| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.|
**Example**
```js
const data = new ArrayBuffer(112);
const imageSourceApi = image.createImageSource(data);
```
## image.CreateIncrementalSource9+
CreateIncrementalSource(buf: ArrayBuffer): ImageSource
Creates an **ImageSource** instance in incremental mode based on the buffers.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------| ---- | ----------|
| buf | ArrayBuffer | Yes | Incremental data.|
**Return value**
| Type | Description |
| --------------------------- | --------------------------------- |
| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns undefined otherwise.|
**Example**
```js
const buf = new ArrayBuffer(96);
const imageSourceApi = image.CreateIncrementalSource(buf);
```
## image.CreateIncrementalSource9+
CreateIncrementalSource(buf: ArrayBuffer, options?: SourceOptions): ImageSource
Creates an **ImageSource** instance in incremental mode based on the buffers.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------- | ---- | ------------------------------------ |
| buf | ArrayBuffer | Yes | Incremental data. |
| options | [SourceOptions](#sourceoptions9) | No | Image properties, including the image index and default property value.|
**Return value**
| Type | Description |
| --------------------------- | --------------------------------- |
| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns undefined otherwise.|
**Example**
```js
const buf = new ArrayBuffer(96);
const imageSourceApi = image.CreateIncrementalSource(buf);
```
## ImageSource
Provides APIs to obtain image information. Before calling any API in **ImageSource**, you must use **createImageSource** to create an **ImageSource** instance.
### Attributes
**System capability**: SystemCapability.Multimedia.Image.ImageSource
| Name | Type | Readable| Writable| Description |
| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ |
| supportedFormats | Array\ | Yes | No | Supported image formats, including png, jpeg, wbmp, bmp, gif, webp, and heif.|
### getImageInfo
getImageInfo(index: number, callback: AsyncCallback\): void
Obtains information about an image with the specified index. This API uses an asynchronous callback to return the information.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | ---------------------------------------- |
| index | number | Yes | Index of the image. |
| callback | AsyncCallback<[ImageInfo](#imageinfo)> | Yes | Callback used to return the image information.|
**Example**
```js
imageSourceApi.getImageInfo(0,(error, imageInfo) => {
if(error) {
console.log('getImageInfo failed.');
} else {
console.log('getImageInfo succeeded.');
}
})
```
### getImageInfo
getImageInfo(callback: AsyncCallback\): void
Obtains information about this image. This API uses an asynchronous callback to return the information.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | ---------------------------------------- |
| callback | AsyncCallback<[ImageInfo](#imageinfo)> | Yes | Callback used to return the image information.|
**Example**
```js
imageSourceApi.getImageInfo(imageInfo => {
console.log('Succeeded in obtaining the image information.');
})
```
### getImageInfo
getImageInfo(index?: number): Promise\
Obtains information about an image with the specified index. This API uses a promise to return the image information.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ----- | ------ | ---- | ------------------------------------- |
| index | number | No | Index of the image. If this parameter is not set, the default value **0** is used.|
**Return value**
| Type | Description |
| -------------------------------- | ---------------------- |
| Promise<[ImageInfo](#imageinfo)> | Promise used to return the image information.|
**Example**
```js
imageSourceApi.getImageInfo(0)
.then(imageInfo => {
console.log('Succeeded in obtaining the image information.');
}).catch(error => {
console.log('Failed to obtain the image information.');
})
```
### getImageProperty7+
getImageProperty(key:string, options?: GetImagePropertyOptions): Promise\
Obtains the value of a property with the specified index in this image. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ---------------------------------------------------- | ---- | ------------------------------------ |
| key | string | Yes | Name of the property. |
| options | [GetImagePropertyOptions](#getimagepropertyoptions7) | No | Image properties, including the image index and default property value.|
**Return value**
| Type | Description |
| ---------------- | ----------------------------------------------------------------- |
| Promise\ | Promise used to return the property value. If the operation fails, the default value is returned.|
**Example**
```js
imageSourceApi.getImageProperty("BitsPerSample")
.then(data => {
console.log('Succeeded in getting the value of the specified attribute key of the image.');
})
```
### getImageProperty7+
getImageProperty(key:string, callback: AsyncCallback\): void
Obtains the value of a property with the specified index in this image. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| key | string | Yes | Name of the property. |
| callback | AsyncCallback\ | Yes | Callback used to return the property value. If the operation fails, the default value is returned.|
**Example**
```js
imageSourceApi.getImageProperty("BitsPerSample",(error,data) => {
if(error) {
console.log('Failed to get the value of the specified attribute key of the image.');
} else {
console.log('Succeeded in getting the value of the specified attribute key of the image.');
}
})
```
### getImageProperty7+
getImageProperty(key:string, options: GetImagePropertyOptions, callback: AsyncCallback\): void
Obtains the value of a property in this image. This API uses an asynchronous callback to return the property value in a string.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------- |
| key | string | Yes | Name of the property. |
| options | [GetImagePropertyOptions](#getimagepropertyoptions7) | Yes | Image properties, including the image index and default property value. |
| callback | AsyncCallback\ | Yes | Callback used to return the property value. If the operation fails, the default value is returned.|
**Example**
```js
const property = new ArrayBuffer(400);
imageSourceApi.getImageProperty("BitsPerSample",property,(error,data) => {
if(error) {
console.log('Failed to get the value of the specified attribute key of the image.');
} else {
console.log('Succeeded in getting the value of the specified attribute key of the image.');
}
})
```
### modifyImageProperty9+
modifyImageProperty(key: string, value: string): Promise\
Modifies the value of a property in this image. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ------------ |
| key | string | Yes | Name of the property.|
| value | string | Yes | New value of the property. |
**Return value**
| Type | Description |
| -------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
imageSourceApi.modifyImageProperty("ImageWidth", "120")
.then(() => {
const w = imageSourceApi.getImageProperty("ImageWidth")
console.info('w', w);
})
```
### modifyImageProperty9+
modifyImageProperty(key: string, value: string, callback: AsyncCallback\): void
Modifies the value of a property in this image. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------- | ---- | ------------------------------ |
| key | string | Yes | Name of the property. |
| value | string | Yes | New value of the property. |
| callback | AsyncCallback\ | Yes | Callback used to return the result.|
**Example**
```js
imageSourceApi.modifyImageProperty("ImageWidth", "120",() => {})
```
### updateData9+
updateData(buf: ArrayBuffer, isFinished: boolean, value: number, length: number): Promise\
Updates incremental data. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------- | ---- | ------------ |
| buf | ArrayBuffer | Yes | Incremental data. |
| isFinished | boolean | Yes | Whether the update is complete.|
| value | number | No | Offset for data reading. |
| length | number | No | Array length. |
**Return value**
| Type | Description |
| -------------- | -------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
const array = new ArrayBuffer(100);
imageSourceIncrementalSApi.updateData(array, false, 0, 10).then(data => {
console.info('Succeeded in updating data.');
})
```
### updateData9+
updateData(buf: ArrayBuffer, isFinished: boolean, value: number, length: number, callback: AsyncCallback\): void
Updates incremental data. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------- | ---- | -------------------- |
| buf | ArrayBuffer | Yes | Incremental data. |
| isFinished | boolean | Yes | Whether the update is complete. |
| value | number | No | Offset for data reading. |
| length | number | No | Array length. |
| callback | AsyncCallback\ | Yes | Callback used to return the result.|
**Example**
```js
const array = new ArrayBuffer(100);
imageSourceIncrementalSApi.updateData(array, false, 0, 10,(error,data )=> {
if(data !== undefined){
console.info('Succeeded in updating data.');
}
})
```
### createPixelMap7+
createPixelMap(options?: DecodingOptions): Promise\
Creates a **PixelMap** object based on image decoding parameters. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------ | ---- | ---------- |
| options | [DecodingOptions](#decodingoptions7) | No | Image decoding parameters.|
**Return value**
| Type | Description |
| -------------------------------- | --------------------- |
| Promise\<[PixelMap](#pixelmap7)> | Promise used to return the **PixelMap** object.|
**Example**
```js
imageSourceApi.createPixelMap().then(pixelmap => {
console.log('Succeeded in creating pixelmap object through image decoding parameters.');
}).catch(error => {
console.log('Failed to create pixelmap object through image decoding parameters.');
})
```
### createPixelMap7+
createPixelMap(callback: AsyncCallback\): void
Creates a **PixelMap** object based on the default parameters. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | -------------------------- |
| callback | AsyncCallback<[PixelMap](#pixelmap7)> | Yes | Callback used to return the **PixelMap** object.|
**Example**
```js
imageSourceApi.createPixelMap((err, pixelmap) => {
console.info('Succeeded in creating pixelmap object.');
})
```
### createPixelMap7+
createPixelMap(options: DecodingOptions, callback: AsyncCallback\): void
Creates a **PixelMap** object based on image decoding parameters. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | -------------------------- |
| options | [DecodingOptions](#decodingoptions7) | Yes | Image decoding parameters. |
| callback | AsyncCallback<[PixelMap](#pixelmap7)> | Yes | Callback used to return the **PixelMap** object.|
**Example**
```js
const decodingOptions = new ArrayBuffer(400);
imageSourceApi.createPixelMap(decodingOptions, pixelmap => {
console.log('Succeeded in creating pixelmap object.');
})
```
### release
release(callback: AsyncCallback\): void
Releases this **ImageSource** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------- |
| callback | AsyncCallback\ | Yes | Callback invoked for instance release. If the operation fails, an error message is returned.|
**Example**
```js
imageSourceApi.release(() => {
console.log('release succeeded.');
})
```
### release
release(): Promise\
Releases this **ImageSource** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
**Return value**
| Type | Description |
| -------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
imageSourceApi.release().then(()=>{
console.log('Succeeded in releasing the image source instance.');
}).catch(error => {
console.log('Failed to release the image source instance.');
})
```
## image.createImagePacker
createImagePacker(): ImagePacker
Creates an **ImagePacker** instance.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
**Return value**
| Type | Description |
| --------------------------- | --------------------- |
| [ImagePacker](#imagepacker) | **ImagePacker** instance created.|
**Example**
```js
const imagePackerApi = image.createImagePacker();
```
## ImagePacker
Provide APIs to pack images. Before calling any API in **ImagePacker**, you must use **createImagePacker** to create an **ImagePacker** instance.
### Attributes
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
| Name | Type | Readable| Writable| Description |
| ---------------- | -------------- | ---- | ---- | -------------------------- |
| supportedFormats | Array\ | Yes | No | Supported image format, which can be jpeg.|
### packing
packing(source: ImageSource, option: PackingOption, callback: AsyncCallback\): void
Packs an image. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------- | ---- | ---------------------------------- |
| source | [ImageSource](#imagesource) | Yes | Image to pack. |
| option | [PackingOption](#packingoption) | Yes | Option for image packing. |
| callback | AsyncCallback\ | Yes | Callback used to return the packed data.|
**Example**
```js
let packOpts = { format:"image/jpeg", quality:98 };
const imageSourceApi = new ArrayBuffer(400);
imagePackerApi.packing(imageSourceApi, packOpts, data => {})
```
### packing
packing(source: ImageSource, option: PackingOption): Promise\
Packs an image. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------- | ---- | -------------- |
| source | [ImageSource](#imagesource) | Yes | Image to pack.|
| option | [PackingOption](#packingoption) | Yes | Option for image packing.|
**Return value**
| Type | Description |
| ---------------------------- | --------------------------------------------- |
| Promise\ | Promise used to return the packed data.|
**Example**
```js
let packOpts = { format:"image/jpeg", quality:98 }
const imageSourceApi = new ArrayBuffer(400);
imagePackerApi.packing(imageSourceApi, packOpts)
.then( data => {
console.log('packing succeeded.');
}).catch(error => {
console.log('packing failed.');
})
```
### packing8+
packing(source: PixelMap, option: PackingOption, callback: AsyncCallback\): void
Packs an image. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ---------------------------------- |
| source | [PixelMap](#pixelmap) | Yes | **PixelMap** object to pack. |
| option | [PackingOption](#packingoption) | Yes | Option for image packing. |
| callback | AsyncCallback\ | Yes | Callback used to return the packed data.|
**Example**
```js
let packOpts = { format:"image/jpeg", quality:98 }
const pixelMapApi = new ArrayBuffer(400);
imagePackerApi.packing(pixelMapApi, packOpts, data => {
console.log('Succeeded in packing the image.');
})
```
### packing8+
packing(source: PixelMap, option: PackingOption): Promise\
Packs an image. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------- | ---- | ------------------ |
| source | [PixelMap](#pixelmap) | Yes | **PixelMap** object to pack.|
| option | [PackingOption](#packingoption) | Yes | Option for image packing. |
**Return value**
| Type | Description |
| --------------------- | -------------------------------------------- |
| Promise\ | Promise used to return the packed data.|
**Example**
```js
let packOpts = { format:"image/jpeg", quality:98 }
const pixelMapApi = new ArrayBuffer(400);
imagePackerApi.packing(pixelMapApi, packOpts)
.then( data => {
console.log('Succeeded in packing the image.');
}).catch(error => {
console.log('Failed to pack the image..');
})
```
### release
release(callback: AsyncCallback\): void
Releases this **ImagePacker** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------ |
| callback | AsyncCallback\ | Yes | Callback invoked for instance release. If the operation fails, an error message is returned.|
**Example**
```js
imagePackerApi.release(()=>{
console.log('Succeeded in releasing image packaging.');
})
```
### release
release(): Promise\
Releases this **ImagePacker** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
**Return value**
| Type | Description |
| -------------- | ------------------------------------------------------ |
| Promise\ | Promise used to return the instance release result. If the operation fails, an error message is returned.|
**Example**
```js
imagePackerApi.release().then(()=>{
console.log('Succeeded in releasing image packaging.');
}).catch((error)=>{
console.log('Failed to release image packaging.');
})
```
## image.createImageReceiver9+
createImageReceiver(width: number, height: number, format: number, capacity: number): ImageReceiver
Create an **ImageReceiver** instance by specifying the image width, height, format, and capacity.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ---------------------- |
| width | number | Yes | Default image width. |
| height | number | Yes | Default image height. |
| format | number | Yes | Image format. |
| capacity | number | Yes | Maximum number of images that can be accessed at the same time.|
**Return value**
| Type | Description |
| -------------------------------- | --------------------------------------- |
| [ImageReceiver](#imagereceiver9) | Returns an **ImageReceiver** instance if the operation is successful.|
**Example**
```js
var receiver = image.createImageReceiver(8192, 8, 4, 8);
```
## ImageReceiver9+
Provides APIs to obtain the surface ID of a component, read the latest image, read the next image, and release the **ImageReceiver** instance.
Before calling any APIs in **ImageReceiver**, you must create an **ImageReceiver** instance.
### Attributes
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
| Name | Type | Readable| Writable| Description |
| -------- | ---------------------------- | ---- | ---- | ------------------ |
| size | [Size](#size) | Yes | No | Image size. |
| capacity | number | Yes | No | Maximum number of images that can be accessed at the same time.|
| format | [ImageFormat](#imageformat9) | Yes | No | Image format. |
### getReceivingSurfaceId9+
getReceivingSurfaceId(callback: AsyncCallback\): void
Obtains a surface ID for the camera or other components. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | -------------------------- |
| callback | AsyncCallback\ | Yes | Callback used to return the surface ID.|
**Example**
```js
receiver.getReceivingSurfaceId((err, id) => {
if(err) {
console.log('getReceivingSurfaceId failed.');
} else {
console.log('getReceivingSurfaceId succeeded.');
}
});
```
### getReceivingSurfaceId9+
getReceivingSurfaceId(): Promise\
Obtains a surface ID for the camera or other components. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Return value**
| Type | Description |
| ---------------- | -------------------- |
| Promise\ | Promise used to return the surface ID.|
**Example**
```js
receiver.getReceivingSurfaceId().then( id => {
console.log('getReceivingSurfaceId succeeded.');
}).catch(error => {
console.log('getReceivingSurfaceId failed.');
})
```
### readLatestImage9+
readLatestImage(callback: AsyncCallback\): void
Reads the latest image from the **ImageReceiver** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | ------------------------ |
| callback | AsyncCallback<[Image](#image9)> | Yes | Callback used to return the latest image.|
**Example**
```js
receiver.readLatestImage((err, img) => {
if(err) {
console.log('readLatestImage failed.');
} else {
console.log('readLatestImage succeeded.');
}
});
```
### readLatestImage9+
readLatestImage(): Promise\
Reads the latest image from the **ImageReceiver** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Return value**
| Type | Description |
| ------------------------- | ------------------ |
| Promise<[Image](#image9)> | Promise used to return the latest image.|
**Example**
```js
receiver.readLatestImage().then(img => {
console.log('readLatestImage succeeded.');
}).catch(error => {
console.log('readLatestImage failed.');
})
```
### readNextImage9+
readNextImage(callback: AsyncCallback\): void
Reads the next image from the **ImageReceiver** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------- | ---- | -------------------------- |
| callback | AsyncCallback<[Image](#image9)> | Yes | Callback used to return the next image.|
**Example**
```js
receiver.readNextImage((err, img) => {
if(err) {
console.log('readNextImage failed.');
} else {
console.log('readNextImage succeeded.');
}
});
```
### readNextImage9+
readNextImage(): Promise\
Reads the next image from the **ImageReceiver** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Return value**
| Type | Description |
| ------------------------- | -------------------- |
| Promise<[Image](#image9)> | Promise used to return the next image.|
**Example**
```js
receiver.readNextImage().then(img => {
console.log('readNextImage succeeded.');
}).catch(error => {
console.log('readNextImage failed.');
})
```
### on('imageArrival')9+
on(type: 'imageArrival', callback: AsyncCallback\): void
Listens for image arrival events.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------ |
| type | string | Yes | Type of event to listen for. The value is fixed at **imageArrival**, which is triggered when an image is received.|
| callback | AsyncCallback\ | Yes | Callback invoked for the event. |
**Example**
```js
receiver.on('imageArrival', () => {})
```
### release9+
release(callback: AsyncCallback\): void
Releases this **ImageReceiver** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------ |
| callback | AsyncCallback\ | Yes | Callback used to return the result.|
**Example**
```js
receiver.release(() => {})
```
### release9+
release(): Promise\
Releases this **ImageReceiver** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
**Return value**
| Type | Description |
| -------------- | ------------------ |
| Promise\ | Promise used to return the result.|
**Example**
```js
receiver.release().then(() => {
console.log('release succeeded.');
}).catch(error => {
console.log('release failed.');
})
```
## Image9+
Provides APIs for basic image operations, including obtaining image information and reading and writing image data. An **Image** instance is returned when [readNextImage](#readnextimage9) and [readLatestImage](#readlatestimage9) are called.
### Attributes
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Type | Readable| Writable| Description |
| -------- | ------------------ | ---- | ---- | -------------------------------------------------- |
| clipRect | [Region](#region7) | Yes | Yes | Image area to be cropped. |
| size | [Size](#size) | Yes | No | Image size. |
| format | number | Yes | No | Image format. For details, see [PixelMapFormat](#pixelmapformat7).|
### getComponent9+
getComponent(componentType: ComponentType, callback: AsyncCallback\): void
Obtains the component buffer from the **Image** instance based on the color component type. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------- | --------------------------------------- | ---- | -------------------- |
| componentType | [ComponentType](#componenttype9) | Yes | Color component type of the image. |
| callback | AsyncCallback<[Component](#component9)> | Yes | Callback used to return the component buffer.|
**Example**
```js
img.getComponent(4, (err, component) => {
if(err) {
console.log('getComponent failed.');
} else {
console.log('getComponent succeeded.');
}
})
```
### getComponent9+
getComponent(componentType: ComponentType): Promise\
Obtains the component buffer from the **Image** instance based on the color component type. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------- | -------------------------------- | ---- | ---------------- |
| componentType | [ComponentType](#componenttype9) | Yes | Color component type of the image.|
**Return value**
| Type | Description |
| --------------------------------- | --------------------------------- |
| Promise<[Component](#component9)> | Promise used to return the component buffer.|
**Example**
```js
img.getComponent(4).then(component => { })
```
### release9+
release(callback: AsyncCallback\): void
Releases this **Image** instance. This API uses an asynchronous callback to return the result.
The corresponding resources must be released before another image arrives.
**System capability**: SystemCapability.Multimedia.Image.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | -------------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result.|
**Example**
```js
img.release(() =>{
console.log('release succeeded.');
})
```
### release9+
release(): Promise\
Releases this **Image** instance. This API uses a promise to return the result.
The corresponding resources must be released before another image arrives.
**System capability**: SystemCapability.Multimedia.Image.Core
**Return value**
| Type | Description |
| -------------- | --------------------- |
| Promise\ | Promise used to return the result.|
**Example**
```js
img.release().then(() =>{
console.log('release succeeded.');
}).catch(error => {
console.log('release failed.');
})
```
## PositionArea7+
Describes area information in an image.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Type | Readable| Writable| Description |
| ------ | ------------------ | ---- | ---- | ------------------------------------------------------------ |
| pixels | ArrayBuffer | Yes | No | Pixels of the image. |
| offset | number | Yes | No | Offset for data reading. |
| stride | number | Yes | No | Number of bytes from one row of pixels in memory to the next row of pixels in memory. The value of **stride** must be greater than or equal to the value of **region.size.width** multiplied by 4. |
| region | [Region](#region7) | Yes | No | Region to read or write. The width of the region to write plus the X coordinate cannot be greater than the width of the original image. The height of the region to write plus the Y coordinate cannot be greater than the height of the original image.|
## ImageInfo
Describes image information.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name| Type | Readable| Writable| Description |
| ---- | ------------- | ---- | ---- | ---------- |
| size | [Size](#size) | Yes | Yes | Image size.|
## Size
Describes the size of an image.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Type | Readable| Writable| Description |
| ------ | ------ | ---- | ---- | -------------- |
| height | number | Yes | Yes | Image height.|
| width | number | Yes | Yes | Image width.|
## PixelMapFormat7+
Enumerates the pixel formats of images.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Default Value| Description |
| ---------------------- | ------ | ----------------- |
| UNKNOWN | 0 | Unknown format. |
| RGB_565 | 2 | RGB_565. |
| RGBA_8888 | 3 | RGBA_8888.|
| BGRA_88889+ | 4 | BGRA_8888.|
## AlphaType9+
Enumerates the alpha types of images.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Default Value| Description |
| -------- | ------ | ----------------------- |
| UNKNOWN | 0 | Unknown alpha type. |
| OPAQUE | 1 | There is no alpha or the image is opaque.|
| PREMUL | 2 | Premultiplied alpha. |
| UNPREMUL | 3 | Unpremultiplied alpha, that is, straight alpha. |
## ScaleMode9+
Enumerates the scale modes of images.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Default Value| Description |
| --------------- | ------ | -------------------------------------------------- |
| CENTER_CROP | 1 | Scales the image so that it fills the requested bounds of the target and crops the extra.|
| FIT_TARGET_SIZE | 0 | Reduces the image size to the dimensions of the target. |
## SourceOptions9+
Defines image source initialization options.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Type | Readable| Writable| Description |
| ----------------- | ---------------------------------- | ---- | ---- | ------------------ |
| sourceDensity | number | Yes | Yes | Density of the image source.|
| sourcePixelFormat | [PixelMapFormat](#pixelmapformat7) | Yes | Yes | Pixel format of the image source. |
| sourceSize | [Size](#size) | Yes | Yes | Pixel size of the image source. |
## InitializationOptions8+
Defines pixel map initialization options.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Type | Readable| Writable| Description |
| ------------------------ | ---------------------------------- | ---- | ---- | -------------- |
| alphaType9+ | [AlphaType](#alphatype9) | Yes | Yes | Alpha type. |
| editable | boolean | Yes | Yes | Whether the image is editable. |
| pixelFormat | [PixelMapFormat](#pixelmapformat7) | Yes | Yes | Pixel map format. |
| scaleMode9+ | [ScaleMode](#scalemode9) | Yes | Yes | Scale mode. |
| size | [Size](#size) | Yes | Yes | Image size.|
## DecodingOptions7+
Defines image decoding options.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
| Name | Type | Readable| Writable| Description |
| ------------------ | ---------------------------------- | ---- | ---- | ---------------- |
| sampleSize | number | Yes | Yes | Thumbnail sampling size.|
| rotate | number | Yes | Yes | Rotation angle. |
| editable | boolean | Yes | Yes | Whether the image is editable. |
| desiredSize | [Size](#size) | Yes | Yes | Expected output size. |
| desiredRegion | [Region](#region7) | Yes | Yes | Region to decode. |
| desiredPixelFormat | [PixelMapFormat](#pixelmapformat7) | Yes | Yes | Pixel map format for decoding.|
| index | number | Yes | Yes | Index of the image to decode. |
## Region7+
Describes region information.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name| Type | Readable| Writable| Description |
| ---- | ------------- | ---- | ---- | ------------ |
| size | [Size](#size) | Yes | Yes | Region size. |
| x | number | Yes | Yes | X coordinate of the region.|
| y | number | Yes | Yes | Y coordinate of the region.|
## PackingOption
Defines the option for image packing.
**System capability**: SystemCapability.Multimedia.Image.ImagePacker
| Name | Type | Readable| Writable| Description |
| ------- | ------ | ---- | ---- | --------------------------------------------------- |
| format | string | Yes | Yes | Format of the packed image.
Currently, the following raw formats are supported: .jpg, .png, .gif, .bmp, and .webp. |
| quality | number | Yes | Yes | Quality of the output image during JPEG encoding. The value ranges from 1 to 100.|
## GetImagePropertyOptions7+
Describes image properties.
**System capability**: SystemCapability.Multimedia.Image.ImageSource
| Name | Type | Readable| Writable| Description |
| ------------ | ------ | ---- | ---- | ------------ |
| index | number | Yes | Yes | Index of an image. |
| defaultValue | string | Yes | Yes | Default property value.|
## PropertyKey7+
Describes the exchangeable image file format (EXIF) information of an image.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Default Value | Description |
| ----------------- | ----------------------- | ------------------------ |
| BITS_PER_SAMPLE | "BitsPerSample" | Number of bits per pixel. |
| ORIENTATION | "Orientation" | Image orientation. |
| IMAGE_LENGTH | "ImageLength" | Image length. |
| IMAGE_WIDTH | "ImageWidth" | Image width. |
| GPS_LATITUDE | "GPSLatitude" | Image latitude. |
| GPS_LONGITUDE | "GPSLongitude" | Image longitude. |
| GPS_LATITUDE_REF | "GPSLatitudeRef" | Latitude reference, for example, N or S. |
| GPS_LONGITUDE_REF | "GPSLongitudeRef" | Longitude reference, for example, W or E. |
## ImageFormat9+
Enumerates the image formats.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Default Value| Description |
| ------------ | ------ | -------------------- |
| YCBCR_422_SP | 1000 | YCBCR422 semi-planar format.|
| JPEG | 2000 | JPEG encoding format. |
## ComponentType9+
Enumerates the color component types of images.
**System capability**: SystemCapability.Multimedia.Image.ImageReceiver
| Name | Default Value| Description |
| ----- | ------ | ----------- |
| YUV_Y | 1 | Luminance component. |
| YUV_U | 2 | Chrominance component. |
| YUV_V | 3 | Chrominance component. |
| JPEG | 4 | JPEG type.|
## Component9+
Describes the color components of an image.
**System capability**: SystemCapability.Multimedia.Image.Core
| Name | Type | Readable| Writable| Description |
| ------------- | -------------------------------- | ---- | ---- | ------------ |
| componentType | [ComponentType](#componenttype9) | Yes | No | Color component type. |
| rowStride | number | Yes | No | Row stride. |
| pixelStride | number | Yes | No | Pixel stride. |
| byteBuffer | ArrayBuffer | Yes | No | Component buffer.|
## ResponseCode
Enumerates the response codes returned upon build errors.
| Name | Value | Description |
| ----------------------------------- | -------- | --------------------------------------------------- |
| ERR_MEDIA_INVALID_VALUE | -1 | Invalid value. |
| SUCCESS | 0 | Operation successful. |
| ERROR | 62980096 | Operation failed. |
| ERR_IPC | 62980097 | IPC error. |
| ERR_SHAMEM_NOT_EXIST | 62980098 | The shared memory does not exist. |
| ERR_SHAMEM_DATA_ABNORMAL | 62980099 | The shared memory is abnormal. |
| ERR_IMAGE_DECODE_ABNORMAL | 62980100 | An error occurs during image decoding. |
| ERR_IMAGE_DATA_ABNORMAL | 62980101 | The input image data is incorrect. |
| ERR_IMAGE_MALLOC_ABNORMAL | 62980102 | An error occurs during image memory allocation. |
| ERR_IMAGE_DATA_UNSUPPORT | 62980103 | Unsupported image type. |
| ERR_IMAGE_INIT_ABNORMAL | 62980104 | An error occurs during image initialization. |
| ERR_IMAGE_GET_DATA_ABNORMAL | 62980105 | An error occurs during image data retrieval. |
| ERR_IMAGE_TOO_LARGE | 62980106 | The image data is too large. |
| ERR_IMAGE_TRANSFORM | 62980107 | An error occurs during image transformation. |
| ERR_IMAGE_COLOR_CONVERT | 62980108 | An error occurs during image color conversion. |
| ERR_IMAGE_CROP | 62980109 | An error occurs during image cropping. |
| ERR_IMAGE_SOURCE_DATA | 62980110 | The image source data is incorrect. |
| ERR_IMAGE_SOURCE_DATA_INCOMPLETE | 62980111 | The image source data is incomplete. |
| ERR_IMAGE_MISMATCHED_FORMAT | 62980112 | The image formats do not match. |
| ERR_IMAGE_UNKNOWN_FORMAT | 62980113 | Unknown image format. |
| ERR_IMAGE_SOURCE_UNRESOLVED | 62980114 | The image source is not parsed. |
| ERR_IMAGE_INVALID_PARAMETER | 62980115 | Invalid image parameter. |
| ERR_IMAGE_DECODE_FAILED | 62980116 | Decoding failed. |
| ERR_IMAGE_PLUGIN_REGISTER_FAILED | 62980117 | Failed to register the plug-in. |
| ERR_IMAGE_PLUGIN_CREATE_FAILED | 62980118 | Failed to create the plug-in. |
| ERR_IMAGE_ENCODE_FAILED | 62980119 | Failed to encode the image. |
| ERR_IMAGE_ADD_PIXEL_MAP_FAILED | 62980120 | Failed to add the image pixel map. |
| ERR_IMAGE_HW_DECODE_UNSUPPORT | 62980121 | Unsupported image hardware decoding. |
| ERR_IMAGE_DECODE_HEAD_ABNORMAL | 62980122 | The image decoding header is incorrect. |
| ERR_IMAGE_DECODE_EXIF_UNSUPPORT | 62980123 | EXIF decoding is not supported. |
| ERR_IMAGE_PROPERTY_NOT_EXIST | 62980124 | The image property does not exist. The error codes for the image start from 150.|
| ERR_IMAGE_READ_PIXELMAP_FAILED | 62980246 | Failed to read the pixel map. |
| ERR_IMAGE_WRITE_PIXELMAP_FAILED | 62980247 | Failed to write the pixel map. |
| ERR_IMAGE_PIXELMAP_NOT_ALLOW_MODIFY | 62980248 | Modification to the pixel map is not allowed. |
| ERR_IMAGE_CONFIG_FAILED | 62980259 | The configuration is incorrect. |