1# Image Processing 2 3The **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). 4 5> **NOTE** 6> 7> 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. 8 9## Modules to Import 10 11```js 12import image from '@ohos.multimedia.image'; 13``` 14 15## image.createPixelMap<sup>8+</sup> 16 17createPixelMap(colors: ArrayBuffer, options: InitializationOptions): Promise\<PixelMap> 18 19Creates a **PixelMap** object. 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](#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](#pixelmap7)> | Promise used to return the **PixelMap** object.| 35 36**Example** 37 38```js 39const color = new ArrayBuffer(96); 40let bufferArr = new Uint8Array(color); 41let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 42image.createPixelMap(color, opts) 43 .then((pixelmap) => { 44 }) 45``` 46 47## image.createPixelMap<sup>8+</sup> 48 49createPixelMap(colors: ArrayBuffer, options: InitializationOptions, callback: AsyncCallback\<PixelMap>): void 50 51Creates a **PixelMap** object. This API uses an asynchronous callback to return the result. 52 53**System capability**: SystemCapability.Multimedia.Image.Core 54 55**Parameters** 56 57| Name | Type | Mandatory| Description | 58| -------- | ------------------------------------------------ | ---- | -------------------------- | 59| colors | ArrayBuffer | Yes | Color array in BGRA_8888 format. | 60| options | [InitializationOptions](#initializationoptions8) | Yes | Pixel properties. | 61| callback | AsyncCallback\<[PixelMap](#pixelmap7)> | Yes | Callback used to return the **PixelMap** object.| 62 63**Example** 64 65```js 66const color = new ArrayBuffer(96); 67let bufferArr = new Uint8Array(color); 68let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 69image.createPixelMap(color, opts, (pixelmap) => { 70 }) 71``` 72 73## PixelMap<sup>7+</sup> 74 75Provides 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. 76 77 ### Attributes 78 79**System capability**: SystemCapability.Multimedia.Image.Core 80 81| Name | Type | Readable| Writable| Description | 82| ---------- | ------- | ---- | ---- | -------------------------- | 83| isEditable | boolean | Yes | No | Whether the image pixel map is editable.| 84 85### readPixelsToBuffer<sup>7+</sup> 86 87readPixelsToBuffer(dst: ArrayBuffer): Promise\<void> 88 89Reads image pixel map data and writes the data to an **ArrayBuffer**. This API uses a promise to return the result. 90 91**System capability**: SystemCapability.Multimedia.Image.Core 92 93**Parameters** 94 95| Name| Type | Mandatory| Description | 96| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- | 97| dst | ArrayBuffer | Yes | Buffer to which the image pixel map data will be written. The buffer size is obtained by calling **getPixelBytesNumber**.| 98 99**Return value** 100 101| Type | Description | 102| -------------- | ----------------------------------------------- | 103| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 104 105**Example** 106 107```js 108const readBuffer = new ArrayBuffer(400); 109pixelmap.readPixelsToBuffer(readBuffer).then(() => { 110 console.log('Succeeded in reading image pixel data.'); // Called if the condition is met. 111}).catch(error => { 112 console.log('Failed to read image pixel data.'); // Called if no condition is met. 113}) 114``` 115 116### readPixelsToBuffer<sup>7+</sup> 117 118readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback\<void>): void 119 120Reads image pixel map data and writes the data to an **ArrayBuffer**. This API uses an asynchronous callback to return the result. 121 122**System capability**: SystemCapability.Multimedia.Image.Core 123 124**Parameters** 125 126| Name | Type | Mandatory| Description | 127| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 128| dst | ArrayBuffer | Yes | Buffer to which the image pixel map data will be written. The buffer size is obtained by calling **getPixelBytesNumber**.| 129| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation fails, an error message is returned. | 130 131**Example** 132 133```js 134const readBuffer = new ArrayBuffer(400); 135pixelmap.readPixelsToBuffer(readBuffer, (err, res) => { 136 if(err) { 137 console.log('Failed to read image pixel data.'); // Called if no condition is met. 138 } else { 139 console.log('Succeeded in reading image pixel data.'); // Called if the condition is met. 140 } 141}) 142``` 143 144### readPixels<sup>7+</sup> 145 146readPixels(area: PositionArea): Promise\<void> 147 148Reads image pixel map data in an area. This API uses a promise to return the data read. 149 150**System capability**: SystemCapability.Multimedia.Image.Core 151 152**Parameters** 153 154| Name| Type | Mandatory| Description | 155| ------ | ------------------------------ | ---- | ------------------------ | 156| area | [PositionArea](#positionarea7) | Yes | Area from which the image pixel map data will be read.| 157 158**Return value** 159 160| Type | Description | 161| :------------- | :-------------------------------------------------- | 162| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 163 164**Example** 165 166```js 167const area = new ArrayBuffer(400); 168pixelmap.readPixels(area).then(() => { 169 console.log('Succeeded in reading the image data in the area.'); // Called if the condition is met. 170}).catch(error => { 171 console.log('Failed to read the image data in the area.'); // Called if no condition is met. 172}) 173``` 174 175### readPixels<sup>7+</sup> 176 177readPixels(area: PositionArea, callback: AsyncCallback\<void>): void 178 179Reads image pixel map data in an area. This API uses an asynchronous callback to return the data read. 180 181**System capability**: SystemCapability.Multimedia.Image.Core 182 183**Parameters** 184 185| Name | Type | Mandatory| Description | 186| -------- | ------------------------------ | ---- | ------------------------------ | 187| area | [PositionArea](#positionarea7) | Yes | Area from which the image pixel map data will be read. | 188| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation fails, an error message is returned.| 189 190**Example** 191 192```js 193const color = new ArrayBuffer(96); 194let bufferArr = new Uint8Array(color); 195let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 196image.createPixelMap(color, opts, (err, pixelmap) => { 197 if(pixelmap == undefined){ 198 console.info('createPixelMap failed.'); 199 } else { 200 const area = { pixels: new ArrayBuffer(8), 201 offset: 0, 202 stride: 8, 203 region: { size: { height: 1, width: 2 }, x: 0, y: 0 }}; 204 pixelmap.readPixels(area, () => { 205 console.info('readPixels success'); 206 }) 207 } 208}) 209``` 210 211### writePixels<sup>7+</sup> 212 213writePixels(area: PositionArea): Promise\<void> 214 215Writes image pixel map data to an area. This API uses a promise to return the operation result. 216 217**System capability**: SystemCapability.Multimedia.Image.Core 218 219**Parameters** 220 221| Name| Type | Mandatory| Description | 222| ------ | ------------------------------ | ---- | -------------------- | 223| area | [PositionArea](#positionarea7) | Yes | Area to which the image pixel map data will be written.| 224 225**Return value** 226 227| Type | Description | 228| :------------- | :-------------------------------------------------- | 229| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 230 231**Example** 232 233```js 234const color = new ArrayBuffer(96); 235let bufferArr = new Uint8Array(color); 236let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 237image.createPixelMap(color, opts) 238 .then( pixelmap => { 239 if (pixelmap == undefined) { 240 console.info('createPixelMap failed.'); 241 } 242 const area = { pixels: new ArrayBuffer(8), 243 offset: 0, 244 stride: 8, 245 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 246 } 247 let bufferArr = new Uint8Array(area.pixels); 248 for (var i = 0; i < bufferArr.length; i++) { 249 bufferArr[i] = i + 1; 250 } 251 252 pixelmap.writePixels(area).then(() => { 253 const readArea = { pixels: new ArrayBuffer(8), 254 offset: 0, 255 stride: 8, 256 // region.size.width + x < opts.width, region.size.height + y < opts.height 257 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 258 } 259 }) 260 }).catch(error => { 261 console.log('error: ' + error); 262 }) 263``` 264 265### writePixels<sup>7+</sup> 266 267writePixels(area: PositionArea, callback: AsyncCallback\<void>): void 268 269Writes image pixel map data to an area. This API uses an asynchronous callback to return the operation result. 270 271**System capability**: SystemCapability.Multimedia.Image.Core 272 273**Parameters** 274 275| Name | Type | Mandatory| Description | 276| --------- | ------------------------------ | ---- | ------------------------------ | 277| area | [PositionArea](#positionarea7) | Yes | Area to which the image pixel map data will be written. | 278| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation fails, an error message is returned.| 279 280**Example** 281 282```js 283const area = new ArrayBuffer(400); 284pixelmap.writePixels(area, (error) => { 285 if (error!=undefined) { 286 console.info('Failed to write pixelmap into the specified area.'); 287 } else { 288 const readArea = { 289 pixels: new ArrayBuffer(20), 290 offset: 0, 291 stride: 8, 292 region: { size: { height: 1, width: 2 }, x: 0, y: 0 }, 293 } 294 } 295}) 296``` 297 298### writeBufferToPixels<sup>7+</sup> 299 300writeBufferToPixels(src: ArrayBuffer): Promise\<void> 301 302Reads image data in an **ArrayBuffer** and writes the data to a **PixelMap** object. This API uses a promise to return the result. 303 304**System capability**: SystemCapability.Multimedia.Image.Core 305 306**Parameters** 307 308| Name| Type | Mandatory| Description | 309| ------ | ----------- | ---- | -------------- | 310| src | ArrayBuffer | Yes | Buffer from which the image data will be read.| 311 312**Return value** 313 314| Type | Description | 315| -------------- | ----------------------------------------------- | 316| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 317 318**Example** 319 320```js 321const color = new ArrayBuffer(96); 322const pixelMap = new ArrayBuffer(400); 323let bufferArr = new Uint8Array(color); 324pixelMap.writeBufferToPixels(color).then(() => { 325 console.log("Succeeded in writing data from a buffer to a PixelMap."); 326}).catch((err) => { 327 console.error("Failed to write data from a buffer to a PixelMap."); 328}) 329``` 330 331### writeBufferToPixels<sup>7+</sup> 332 333writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback\<void>): void 334 335Reads image data in an **ArrayBuffer** and writes the data to a **PixelMap** object. This API uses an asynchronous callback to return the result. 336 337**System capability**: SystemCapability.Multimedia.Image.Core 338 339**Parameters** 340 341| Name | Type | Mandatory| Description | 342| -------- | -------------------- | ---- | ------------------------------ | 343| src | ArrayBuffer | Yes | Buffer from which the image data will be read. | 344| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation fails, an error message is returned.| 345 346**Example** 347 348```js 349const color = new ArrayBuffer(96);\ 350const pixelMap = new ArrayBuffer(400); 351let bufferArr = new Uint8Array(color); 352pixelMap.writeBufferToPixels(color, function(err) { 353 if (err) { 354 console.error("Failed to write data from a buffer to a PixelMap."); 355 return; 356 } else { 357 console.log("Succeeded in writing data from a buffer to a PixelMap."); 358 } 359}); 360``` 361 362### getImageInfo<sup>7+</sup> 363 364getImageInfo(): Promise\<ImageInfo> 365 366Obtains pixel map information of this image. This API uses a promise to return the information. 367 368**System capability**: SystemCapability.Multimedia.Image.Core 369 370**Return value** 371 372| Type | Description | 373| --------------------------------- | ----------------------------------------------------------- | 374| Promise\<[ImageInfo](#imageinfo)> | Promise used to return the pixel map information. If the operation fails, an error message is returned.| 375 376**Example** 377 378```js 379const pixelMap = new ArrayBuffer(400); 380pixelMap.getImageInfo().then(function(info) { 381 console.log("Succeeded in obtaining the image pixel map information."); 382}).catch((err) => { 383 console.error("Failed to obtain the image pixel map information."); 384}); 385``` 386 387### getImageInfo<sup>7+</sup> 388 389getImageInfo(callback: AsyncCallback\<ImageInfo>): void 390 391Obtains pixel map information of this image. This API uses an asynchronous callback to return the information. 392 393**System capability**: SystemCapability.Multimedia.Image.Core 394 395**Parameters** 396 397| Name | Type | Mandatory| Description | 398| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 399| callback | AsyncCallback\<[ImageInfo](#imageinfo)> | Yes | Callback used to return the pixel map information. If the operation fails, an error message is returned.| 400 401**Example** 402 403```js 404pixelmap.getImageInfo((imageInfo) => { 405 console.log("Succeeded in obtaining the image pixel map information."); 406}) 407``` 408 409### getBytesNumberPerRow<sup>7+</sup> 410 411getBytesNumberPerRow(): number 412 413Obtains the number of bytes per row of this image pixel map. 414 415**System capability**: SystemCapability.Multimedia.Image.Core 416 417**Return value** 418 419| Type | Description | 420| ------ | -------------------- | 421| number | Number of bytes per row.| 422 423**Example** 424 425```js 426const color = new ArrayBuffer(96); 427let bufferArr = new Uint8Array(color); 428let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 429image.createPixelMap(color, opts, (err,pixelmap) => { 430 let rowCount = pixelmap.getBytesNumberPerRow(); 431}) 432``` 433 434### getPixelBytesNumber<sup>7+</sup> 435 436getPixelBytesNumber(): number 437 438Obtains the total number of bytes of this image pixel map. 439 440**System capability**: SystemCapability.Multimedia.Image.Core 441 442**Return value** 443 444| Type | Description | 445| ------ | -------------------- | 446| number | Total number of bytes.| 447 448**Example** 449 450```js 451let pixelBytesNumber = pixelmap.getPixelBytesNumber(); 452``` 453 454### release<sup>7+</sup> 455 456release():Promise\<void> 457 458Releases this **PixelMap** object. This API uses a promise to return the result. 459 460**System capability**: SystemCapability.Multimedia.Image.Core 461 462**Return value** 463 464| Type | Description | 465| -------------- | ------------------------------- | 466| Promise\<void> | Promise used to return the result.| 467 468**Example** 469 470```js 471const color = new ArrayBuffer(96); 472let bufferArr = new Uint8Array(color); 473let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 474image.createPixelMap(color, opts, (pixelmap) => { 475 pixelmap.release().then(() => { 476 console.log('Succeeded in releasing pixelmap object.'); 477 }).catch(error => { 478 console.log('Failed to release pixelmap object.'); 479 }) 480}) 481``` 482 483### release<sup>7+</sup> 484 485release(callback: AsyncCallback\<void>): void 486 487Releases this **PixelMap** object. This API uses an asynchronous callback to return the result. 488 489**System capability**: SystemCapability.Multimedia.Image.Core 490 491**Parameters** 492 493| Name | Type | Mandatory| Description | 494| -------- | -------------------- | ---- | ------------------ | 495| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 496 497**Example** 498 499```js 500const color = new ArrayBuffer(96); 501let bufferArr = new Uint8Array(color); 502let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 503image.createPixelMap(color, opts, (pixelmap) => { 504 pixelmap.release().then(() => { 505 console.log('Succeeded in releasing pixelmap object.'); 506 }).catch(error => { 507 console.log('Failed to release pixelmap object.'); 508 }) 509}) 510``` 511 512## image.createImageSource 513 514createImageSource(uri: string): ImageSource 515 516Creates an **ImageSource** instance based on the URI. 517 518**System capability**: SystemCapability.Multimedia.Image.ImageSource 519 520**Parameters** 521 522| Name| Type | Mandatory| Description | 523| ------ | ------ | ---- | ---------------------------------- | 524| uri | string | Yes | Image path. Currently, only the application sandbox path is supported.| 525 526**Return value** 527 528| Type | Description | 529| --------------------------- | -------------------------------------------- | 530| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.| 531 532**Example** 533 534```js 535let path = this.context.getApplicationContext().fileDirs + "test.jpg"; 536const imageSourceApi = image.createImageSource(path); 537``` 538 539## image.createImageSource<sup>7+</sup> 540 541createImageSource(fd: number): ImageSource 542 543Creates an **ImageSource** instance based on the file descriptor. 544 545**System capability**: SystemCapability.Multimedia.Image.ImageSource 546 547**Parameters** 548 549| Name| Type | Mandatory| Description | 550| ------ | ------ | ---- | ------------- | 551| fd | number | Yes | File descriptor.| 552 553**Return value** 554 555| Type | Description | 556| --------------------------- | -------------------------------------------- | 557| [ImageSource](#imagesource) | Returns the **ImageSource** instance if the operation is successful; returns **undefined** otherwise.| 558 559**Example** 560 561```js 562const imageSourceApi = image.createImageSource(0) 563``` 564 565## ImageSource 566 567Provides APIs to obtain image information. Before calling any API in **ImageSource**, you must use **createImageSource** to create an **ImageSource** instance. 568 569### Attributes 570 571**System capability**: SystemCapability.Multimedia.Image.ImageSource 572 573| Name | Type | Readable| Writable| Description | 574| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | 575| supportedFormats | Array\<string> | Yes | No | Supported image formats, including png, jpeg, wbmp, bmp, gif, webp, and heif.| 576 577### getImageInfo 578 579getImageInfo(index: number, callback: AsyncCallback\<ImageInfo>): void 580 581Obtains information about an image with the specified index. This API uses an asynchronous callback to return the information. 582 583**System capability**: SystemCapability.Multimedia.Image.ImageSource 584 585**Parameters** 586 587| Name | Type | Mandatory| Description | 588| -------- | -------------------------------------- | ---- | ---------------------------------------- | 589| index | number | Yes | Index of the image. | 590| callback | AsyncCallback<[ImageInfo](#imageinfo)> | Yes | Callback used to return the image information.| 591 592**Example** 593 594```js 595imageSourceApi.getImageInfo(0,(error, imageInfo) => { 596 if(error) { 597 console.log('getImageInfo failed.'); 598 } else { 599 console.log('getImageInfo succeeded.'); 600 } 601}) 602``` 603 604### getImageInfo 605 606getImageInfo(callback: AsyncCallback\<ImageInfo>): void 607 608Obtains information about this image. This API uses an asynchronous callback to return the information. 609 610**System capability**: SystemCapability.Multimedia.Image.ImageSource 611 612**Parameters** 613 614| Name | Type | Mandatory| Description | 615| -------- | -------------------------------------- | ---- | ---------------------------------------- | 616| callback | AsyncCallback<[ImageInfo](#imageinfo)> | Yes | Callback used to return the image information.| 617 618**Example** 619 620```js 621imageSourceApi.getImageInfo(imageInfo => { 622 console.log('Succeeded in obtaining the image information.'); 623}) 624``` 625 626### getImageInfo 627 628getImageInfo(index?: number): Promise\<ImageInfo> 629 630Obtains information about an image with the specified index. This API uses a promise to return the image information. 631 632**System capability**: SystemCapability.Multimedia.Image.ImageSource 633 634**Parameters** 635 636| Name | Type | Mandatory| Description | 637| ----- | ------ | ---- | ------------------------------------- | 638| index | number | No | Index of the image. If this parameter is not set, the default value **0** is used.| 639 640**Return value** 641 642| Type | Description | 643| -------------------------------- | ---------------------- | 644| Promise<[ImageInfo](#imageinfo)> | Promise used to return the image information.| 645 646**Example** 647 648```js 649imageSourceApi.getImageInfo(0) 650 .then(imageInfo => { 651 console.log('Succeeded in obtaining the image information.'); 652 }).catch(error => { 653 console.log('Failed to obtain the image information.'); 654 }) 655``` 656 657### getImageProperty<sup>7+</sup> 658 659getImageProperty(key:string, options?: GetImagePropertyOptions): Promise\<string> 660 661Obtains the value of a property with the specified index in this image. This API uses a promise to return the result. 662 663**System capability**: SystemCapability.Multimedia.Image.ImageSource 664 665 **Parameters** 666 667| Name | Type | Mandatory| Description | 668| ------- | ---------------------------------------------------- | ---- | ------------------------------------ | 669| key | string | Yes | Name of the property. | 670| options | [GetImagePropertyOptions](#getimagepropertyoptions7) | No | Image properties, including the image index and default property value.| 671 672**Return value** 673 674| Type | Description | 675| ---------------- | ----------------------------------------------------------------- | 676| Promise\<string> | Promise used to return the property value. If the operation fails, the default value is returned.| 677 678**Example** 679 680```js 681imageSourceApi.getImageProperty("BitsPerSample") 682 .then(data => { 683 console.log('Succeeded in getting the value of the specified attribute key of the image.'); 684 }) 685``` 686 687### getImageProperty<sup>7+</sup> 688 689getImageProperty(key:string, callback: AsyncCallback\<string>): void 690 691Obtains the value of a property with the specified index in this image. This API uses an asynchronous callback to return the result. 692 693**System capability**: SystemCapability.Multimedia.Image.ImageSource 694 695 **Parameters** 696 697| Name | Type | Mandatory| Description | 698| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 699| key | string | Yes | Name of the property. | 700| callback | AsyncCallback\<string> | Yes | Callback used to return the property value. If the operation fails, the default value is returned.| 701 702**Example** 703 704```js 705imageSourceApi.getImageProperty("BitsPerSample",(error,data) => { 706 if(error) { 707 console.log('Failed to get the value of the specified attribute key of the image.'); 708 } else { 709 console.log('Succeeded in getting the value of the specified attribute key of the image.'); 710 } 711}) 712``` 713 714### getImageProperty<sup>7+</sup> 715 716getImageProperty(key:string, options: GetImagePropertyOptions, callback: AsyncCallback\<string>): void 717 718Obtains the value of a property in this image. This API uses an asynchronous callback to return the property value in a string. 719 720**System capability**: SystemCapability.Multimedia.Image.ImageSource 721 722**Parameters** 723 724| Name | Type | Mandatory| Description | 725| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------- | 726| key | string | Yes | Name of the property. | 727| options | [GetImagePropertyOptions](#getimagepropertyoptions7) | Yes | Image properties, including the image index and default property value. | 728| callback | AsyncCallback\<string> | Yes | Callback used to return the property value. If the operation fails, the default value is returned.| 729 730**Example** 731 732```js 733const property = new ArrayBuffer(400); 734imageSourceApi.getImageProperty("BitsPerSample",property,(error,data) => { 735 if(error) { 736 console.log('Failed to get the value of the specified attribute key of the image.'); 737 } else { 738 console.log('Succeeded in getting the value of the specified attribute key of the image.'); 739 } 740}) 741``` 742 743### createPixelMap<sup>7+</sup> 744 745createPixelMap(options?: DecodingOptions): Promise\<PixelMap> 746 747Creates a **PixelMap** object based on image decoding parameters. This API uses a promise to return the result. 748 749**System capability**: SystemCapability.Multimedia.Image.ImageSource 750 751**Parameters** 752 753| Name | Type | Mandatory| Description | 754| ------- | ------------------------------------ | ---- | ---------- | 755| options | [DecodingOptions](#decodingoptions7) | No | Image decoding parameters.| 756 757**Return value** 758 759| Type | Description | 760| -------------------------------- | --------------------- | 761| Promise\<[PixelMap](#pixelmap7)> | Promise used to return the **PixelMap** object.| 762 763**Example** 764 765```js 766imageSourceApi.createPixelMap().then(pixelmap => { 767 console.log('Succeeded in creating pixelmap object through image decoding parameters.'); 768}).catch(error => { 769 console.log('Failed to create pixelmap object through image decoding parameters.'); 770}) 771``` 772 773### createPixelMap<sup>7+</sup> 774 775createPixelMap(callback: AsyncCallback\<PixelMap>): void 776 777Creates a **PixelMap** object based on the default parameters. This API uses an asynchronous callback to return the result. 778 779**System capability**: SystemCapability.Multimedia.Image.ImageSource 780 781**Parameters** 782 783| Name | Type | Mandatory| Description | 784| -------- | ------------------------------------- | ---- | -------------------------- | 785| callback | AsyncCallback<[PixelMap](#pixelmap7)> | Yes | Callback used to return the **PixelMap** object.| 786 787**Example** 788 789```js 790imageSourceApi.createPixelMap(pixelmap => { 791 console.log('Succeeded in creating pixelmap object.'); 792}).catch(error => { 793 console.log('Failed to create pixelmap object.'); 794}) 795``` 796 797### createPixelMap<sup>7+</sup> 798 799createPixelMap(options: DecodingOptions, callback: AsyncCallback\<PixelMap>): void 800 801Creates a **PixelMap** object based on image decoding parameters. This API uses an asynchronous callback to return the result. 802 803**System capability**: SystemCapability.Multimedia.Image.ImageSource 804 805**Parameters** 806 807| Name | Type | Mandatory| Description | 808| -------- | ------------------------------------- | ---- | -------------------------- | 809| options | [DecodingOptions](#decodingoptions7) | Yes | Image decoding parameters. | 810| callback | AsyncCallback<[PixelMap](#pixelmap7)> | Yes | Callback used to return the **PixelMap** object.| 811 812**Example** 813 814```js 815const decodingOptions = new ArrayBuffer(400); 816imageSourceApi.createPixelMap(decodingOptions, pixelmap => { 817 console.log('Succeeded in creating pixelmap object.'); 818}) 819``` 820 821### release 822 823release(callback: AsyncCallback\<void>): void 824 825Releases this **ImageSource** instance. This API uses an asynchronous callback to return the result. 826 827**System capability**: SystemCapability.Multimedia.Image.ImageSource 828 829**Parameters** 830 831| Name | Type | Mandatory| Description | 832| -------- | -------------------- | ---- | ---------------------------------- | 833| callback | AsyncCallback\<void> | Yes | Callback invoked for instance release. If the operation fails, an error message is returned.| 834 835**Example** 836 837```js 838imageSourceApi.release(() => { 839 console.log('release succeeded.'); 840}) 841``` 842 843### release 844 845release(): Promise\<void> 846 847Releases this **ImageSource** instance. This API uses a promise to return the result. 848 849**System capability**: SystemCapability.Multimedia.Image.ImageSource 850 851**Return value** 852 853| Type | Description | 854| -------------- | --------------------------- | 855| Promise\<void> | Promise used to return the result.| 856 857**Example** 858 859```js 860imageSourceApi.release().then(()=>{ 861 console.log('Succeeded in releasing the image source instance.'); 862}).catch(error => { 863 console.log('Failed to release the image source instance.'); 864}) 865``` 866 867## image.createImagePacker 868 869createImagePacker(): ImagePacker 870 871Creates an **ImagePacker** instance. 872 873**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 874 875**Return value** 876 877| Type | Description | 878| --------------------------- | --------------------- | 879| [ImagePacker](#imagepacker) | **ImagePacker** instance created.| 880 881**Example** 882 883```js 884const imagePackerApi = image.createImagePacker(); 885``` 886 887## ImagePacker 888 889Provide APIs to pack images. Before calling any API in **ImagePacker**, you must use **createImagePacker** to create an **ImagePacker** instance. 890 891### Attributes 892 893**System capability**: SystemCapability.Multimedia.Image.ImagePacker 894 895| Name | Type | Readable| Writable| Description | 896| ---------------- | -------------- | ---- | ---- | -------------------------- | 897| supportedFormats | Array\<string> | Yes | No | Supported image format, which can be jpeg.| 898 899### packing 900 901packing(source: ImageSource, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 902 903Packs an image. This API uses an asynchronous callback to return the result. 904 905**System capability**: SystemCapability.Multimedia.Image.ImagePacker 906 907**Parameters** 908 909| Name | Type | Mandatory| Description | 910| -------- | ---------------------------------- | ---- | ---------------------------------- | 911| source | [ImageSource](#imagesource) | Yes | Image to pack. | 912| option | [PackingOption](#packingoption) | Yes | Option for image packing. | 913| callback | AsyncCallback\<ArrayBuffer> | Yes | Callback used to return the packed data.| 914 915**Example** 916 917```js 918let packOpts = { format:"image/jpeg", quality:98 }; 919const imageSourceApi = new ArrayBuffer(400); 920imagePackerApi.packing(imageSourceApi, packOpts, data => {}) 921``` 922 923### packing 924 925packing(source: ImageSource, option: PackingOption): Promise\<ArrayBuffer> 926 927Packs an image. This API uses a promise to return the result. 928 929**System capability**: SystemCapability.Multimedia.Image.ImagePacker 930 931**Parameters** 932 933| Name| Type | Mandatory| Description | 934| ------ | ------------------------------- | ---- | -------------- | 935| source | [ImageSource](#imagesource) | Yes | Image to pack.| 936| option | [PackingOption](#packingoption) | Yes | Option for image packing.| 937 938**Return value** 939 940| Type | Description | 941| ---------------------------- | --------------------------------------------- | 942| Promise\<ArrayBuffer> | Promise used to return the packed data.| 943 944**Example** 945 946```js 947let packOpts = { format:"image/jpeg", quality:98 } 948const imageSourceApi = new ArrayBuffer(400); 949imagePackerApi.packing(imageSourceApi, packOpts) 950 .then( data => { 951 console.log('packing succeeded.'); 952 }).catch(error => { 953 console.log('packing failed.'); 954 }) 955``` 956 957### packing<sup>8+</sup> 958 959packing(source: PixelMap, option: PackingOption, callback: AsyncCallback\<ArrayBuffer>): void 960 961Packs an image. This API uses an asynchronous callback to return the result. 962 963**System capability**: SystemCapability.Multimedia.Image.ImagePacker 964 965**Parameters** 966 967| Name | Type | Mandatory| Description | 968| -------- | ------------------------------- | ---- | ---------------------------------- | 969| source | [PixelMap](#pixelmap) | Yes | **PixelMap** object to pack. | 970| option | [PackingOption](#packingoption) | Yes | Option for image packing. | 971| callback | AsyncCallback\<ArrayBuffer> | Yes | Callback used to return the packed data.| 972 973**Example** 974 975```js 976let packOpts = { format:"image/jpeg", quality:98 } 977const pixelMapApi = new ArrayBuffer(400); 978imagePackerApi.packing(pixelMapApi, packOpts, data => { 979 console.log('Succeeded in packing the image.'); 980}).catch(error => { 981 console.log('Failed to pack the image.'); 982}) 983``` 984 985### packing<sup>8+</sup> 986 987packing(source: PixelMap, option: PackingOption): Promise\<ArrayBuffer> 988 989Packs an image. This API uses a promise to return the result. 990 991**System capability**: SystemCapability.Multimedia.Image.ImagePacker 992 993**Parameters** 994 995| Name| Type | Mandatory| Description | 996| ------ | ------------------------------- | ---- | ------------------ | 997| source | [PixelMap](#pixelmap) | Yes | **PixelMap** object to pack.| 998| option | [PackingOption](#packingoption) | Yes | Option for image packing. | 999 1000**Return value** 1001 1002| Type | Description | 1003| --------------------- | -------------------------------------------- | 1004| Promise\<ArrayBuffer> | Promise used to return the packed data.| 1005 1006**Example** 1007 1008```js 1009let packOpts = { format:"image/jpeg", quality:98 } 1010const pixelMapApi = new ArrayBuffer(400); 1011imagePackerApi.packing(pixelMapApi, packOpts) 1012 .then( data => { 1013 console.log('Succeeded in packing the image.'); 1014 }).catch(error => { 1015 console.log('Failed to pack the image.'); 1016 }) 1017``` 1018 1019### release 1020 1021release(callback: AsyncCallback\<void>): void 1022 1023Releases this **ImagePacker** instance. This API uses an asynchronous callback to return the result. 1024 1025**System capability**: SystemCapability.Multimedia.Image.ImagePacker 1026 1027**Parameters** 1028 1029| Name | Type | Mandatory| Description | 1030| -------- | -------------------- | ---- | ------------------------------ | 1031| callback | AsyncCallback\<void> | Yes | Callback invoked for instance release. If the operation fails, an error message is returned.| 1032 1033**Example** 1034 1035```js 1036imagePackerApi.release(()=>{ 1037 console.log('Succeeded in releasing image packaging.'); 1038}) 1039``` 1040 1041### release 1042 1043release(): Promise\<void> 1044 1045Releases this **ImagePacker** instance. This API uses a promise to return the result. 1046 1047**System capability**: SystemCapability.Multimedia.Image.ImagePacker 1048 1049**Return value** 1050 1051| Type | Description | 1052| -------------- | ------------------------------------------------------ | 1053| Promise\<void> | Promise used to return the instance release result. If the operation fails, an error message is returned.| 1054 1055**Example** 1056 1057```js 1058imagePackerApi.release().then(()=>{ 1059 console.log('Succeeded in releasing image packaging.'); 1060}).catch((error)=>{ 1061 console.log('Failed to release image packaging.'); 1062}) 1063``` 1064 1065 1066## PositionArea<sup>7+</sup> 1067 1068Describes area information in an image. 1069 1070**System capability**: SystemCapability.Multimedia.Image.Core 1071 1072| Name | Type | Readable| Writable| Description | 1073| ------ | ------------------ | ---- | ---- | ------------------------------------------------------------ | 1074| pixels | ArrayBuffer | Yes | No | Pixels of the image. | 1075| offset | number | Yes | No | Offset for data reading. | 1076| 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. | 1077| 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.| 1078 1079## ImageInfo 1080 1081Describes image information. 1082 1083**System capability**: SystemCapability.Multimedia.Image.Core 1084 1085| Name| Type | Readable| Writable| Description | 1086| ---- | ------------- | ---- | ---- | ---------- | 1087| size | [Size](#size) | Yes | Yes | Image size.| 1088 1089## Size 1090 1091Describes the size of an image. 1092 1093**System capability**: SystemCapability.Multimedia.Image.Core 1094 1095| Name | Type | Readable| Writable| Description | 1096| ------ | ------ | ---- | ---- | -------------- | 1097| height | number | Yes | Yes | Image height.| 1098| width | number | Yes | Yes | Image width.| 1099 1100## PixelMapFormat<sup>7+</sup> 1101 1102Enumerates the pixel formats of images. 1103 1104**System capability**: SystemCapability.Multimedia.Image.Core 1105 1106| Name | Default Value| Description | 1107| ---------------------- | ------ | ----------------- | 1108| UNKNOWN | 0 | Unknown format. | 1109| RGBA_8888 | 3 | RGBA_8888.| 1110| RGB_565 | 2 | RGB_565. | 1111 1112 1113 1114## InitializationOptions<sup>8+</sup> 1115 1116Defines pixel map initialization options. 1117 1118**System capability**: SystemCapability.Multimedia.Image.Core 1119 1120| Name | Type | Readable| Writable| Description | 1121| ------------------------ | ---------------------------------- | ---- | ---- | -------------- | 1122| editable | boolean | Yes | Yes | Whether the image is editable. | 1123| pixelFormat | [PixelMapFormat](#pixelmapformat7) | Yes | Yes | Pixel map format. | 1124| size | [Size](#size) | Yes | Yes | Image size.| 1125 1126## DecodingOptions<sup>7+</sup> 1127 1128Defines image decoding options. 1129 1130**System capability**: SystemCapability.Multimedia.Image.ImageSource 1131 1132| Name | Type | Readable| Writable| Description | 1133| ------------------ | ---------------------------------- | ---- | ---- | ---------------- | 1134| sampleSize | number | Yes | Yes | Thumbnail sampling size.| 1135| rotate | number | Yes | Yes | Rotation angle. | 1136| editable | boolean | Yes | Yes | Whether the image is editable. | 1137| desiredSize | [Size](#size) | Yes | Yes | Expected output size. | 1138| desiredRegion | [Region](#region7) | Yes | Yes | Region to decode. | 1139| desiredPixelFormat | [PixelMapFormat](#pixelmapformat7) | Yes | Yes | Pixel map format for decoding.| 1140| index | number | Yes | Yes | Index of the image to decode. | 1141 1142## Region<sup>7+</sup> 1143 1144Describes region information. 1145 1146**System capability**: SystemCapability.Multimedia.Image.Core 1147 1148| Name| Type | Readable| Writable| Description | 1149| ---- | ------------- | ---- | ---- | ------------ | 1150| size | [Size](#size) | Yes | Yes | Region size. | 1151| x | number | Yes | Yes | X coordinate of the region.| 1152| y | number | Yes | Yes | Y coordinate of the region.| 1153 1154## PackingOption 1155 1156Defines the option for image packing. 1157 1158**System capability**: SystemCapability.Multimedia.Image.ImagePacker 1159 1160| Name | Type | Readable| Writable| Description | 1161| ------- | ------ | ---- | ---- | --------------------------------------------------- | 1162| format | string | Yes | Yes | Format of the packed image. | 1163| quality | number | Yes | Yes | Quality of the output image during JPEG encoding. The value ranges from 1 to 100.| 1164 1165## GetImagePropertyOptions<sup>7+</sup> 1166 1167Describes image properties. 1168 1169**System capability**: SystemCapability.Multimedia.Image.ImageSource 1170 1171| Name | Type | Readable| Writable| Description | 1172| ------------ | ------ | ---- | ---- | ------------ | 1173| index | number | Yes | Yes | Index of an image. | 1174| defaultValue | string | Yes | Yes | Default property value.| 1175 1176## PropertyKey<sup>7+</sup> 1177 1178Describes the exchangeable image file format (EXIF) information of an image. 1179 1180**System capability**: SystemCapability.Multimedia.Image.Core 1181 1182| Name | Default Value | Description | 1183| ----------------- | ----------------------- | ------------------------ | 1184| BITS_PER_SAMPLE | "BitsPerSample" | Number of bits per pixel. | 1185| ORIENTATION | "Orientation" | Image orientation. | 1186| IMAGE_LENGTH | "ImageLength" | Image length. | 1187| IMAGE_WIDTH | "ImageWidth" | Image width. | 1188| GPS_LATITUDE | "GPSLatitude" | Image latitude. | 1189| GPS_LONGITUDE | "GPSLongitude" | Image longitude. | 1190| GPS_LATITUDE_REF | "GPSLatitudeRef" | Latitude reference, for example, N or S. | 1191| GPS_LONGITUDE_REF | "GPSLongitudeRef" | Longitude reference, for example, W or E. | 1192 1193 1194## ResponseCode 1195 1196Enumerates the response codes returned upon build errors. 1197 1198| Name | Value | Description | 1199| ----------------------------------- | -------- | --------------------------------------------------- | 1200| ERR_MEDIA_INVALID_VALUE | -1 | Invalid value. | 1201| SUCCESS | 0 | Operation successful. | 1202| ERROR | 62980096 | Operation failed. | 1203| ERR_IPC | 62980097 | IPC error. | 1204| ERR_SHAMEM_NOT_EXIST | 62980098 | The shared memory does not exist. | 1205| ERR_SHAMEM_DATA_ABNORMAL | 62980099 | The shared memory is abnormal. | 1206| ERR_IMAGE_DECODE_ABNORMAL | 62980100 | An error occurs during image decoding. | 1207| ERR_IMAGE_DATA_ABNORMAL | 62980101 | The input image data is incorrect. | 1208| ERR_IMAGE_MALLOC_ABNORMAL | 62980102 | An error occurs during image memory allocation. | 1209| ERR_IMAGE_DATA_UNSUPPORT | 62980103 | Unsupported image type. | 1210| ERR_IMAGE_INIT_ABNORMAL | 62980104 | An error occurs during image initialization. | 1211| ERR_IMAGE_GET_DATA_ABNORMAL | 62980105 | An error occurs during image data retrieval. | 1212| ERR_IMAGE_TOO_LARGE | 62980106 | The image data is too large. | 1213| ERR_IMAGE_TRANSFORM | 62980107 | An error occurs during image transformation. | 1214| ERR_IMAGE_COLOR_CONVERT | 62980108 | An error occurs during image color conversion. | 1215| ERR_IMAGE_CROP | 62980109 | An error occurs during image cropping. | 1216| ERR_IMAGE_SOURCE_DATA | 62980110 | The image source data is incorrect. | 1217| ERR_IMAGE_SOURCE_DATA_INCOMPLETE | 62980111 | The image source data is incomplete. | 1218| ERR_IMAGE_MISMATCHED_FORMAT | 62980112 | The image formats do not match. | 1219| ERR_IMAGE_UNKNOWN_FORMAT | 62980113 | Unknown image format. | 1220| ERR_IMAGE_SOURCE_UNRESOLVED | 62980114 | The image source is not parsed. | 1221| ERR_IMAGE_INVALID_PARAMETER | 62980115 | Invalid image parameter. | 1222| ERR_IMAGE_DECODE_FAILED | 62980116 | Decoding failed. | 1223| ERR_IMAGE_PLUGIN_REGISTER_FAILED | 62980117 | Failed to register the plug-in. | 1224| ERR_IMAGE_PLUGIN_CREATE_FAILED | 62980118 | Failed to create the plug-in. | 1225| ERR_IMAGE_ENCODE_FAILED | 62980119 | Failed to encode the image. | 1226| ERR_IMAGE_ADD_PIXEL_MAP_FAILED | 62980120 | Failed to add the image pixel map. | 1227| ERR_IMAGE_HW_DECODE_UNSUPPORT | 62980121 | Unsupported image hardware decoding. | 1228| ERR_IMAGE_DECODE_HEAD_ABNORMAL | 62980122 | The image decoding header is incorrect. | 1229| ERR_IMAGE_DECODE_EXIF_UNSUPPORT | 62980123 | EXIF decoding is not supported. | 1230| ERR_IMAGE_PROPERTY_NOT_EXIST | 62980124 | The image property does not exist. The error codes for the image start from 150.| 1231| ERR_IMAGE_READ_PIXELMAP_FAILED | 62980246 | Failed to read the pixel map. | 1232| ERR_IMAGE_WRITE_PIXELMAP_FAILED | 62980247 | Failed to write the pixel map. | 1233| ERR_IMAGE_PIXELMAP_NOT_ALLOW_MODIFY | 62980248 | Modification to the pixel map is not allowed. | 1234| ERR_IMAGE_CONFIG_FAILED | 62980259 | The configuration is incorrect. | 1235
