1# @ohos.effectKit (Image Effects) 2 3The **EffectKit** module provides basic image processing capabilities, including brightness adjustment, blurring, grayscale adjustment, and color picker. 4 5This module provides the following classes: 6 7- [Filter](#filter): a class that adds a specified effect to the image source. 8- [Color](#color): a class used to store the color picked. 9- [ColorPicker](#colorpicker): a smart color picker. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15## Modules to Import 16 17```ts 18import { effectKit } from "@kit.ArkGraphics2D"; 19``` 20 21## effectKit.createEffect 22createEffect(source: image.PixelMap): Filter 23 24Creates a **Filter** instance based on a pixel map. 25 26**Widget capability**: This API can be used in ArkTS widgets since API version 12. 27 28**Atomic service API**: This API can be used in atomic services since API version 12. 29 30**System capability**: SystemCapability.Multimedia.Image.Core 31 32**Parameters** 33 34| Name | Type | Mandatory| Description | 35| ------- | ----------------- | ---- | -------- | 36| source | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image/image-overview.md). | 37 38**Return value** 39 40| Type | Description | 41| -------------------------------- | -------------- | 42| [Filter](#filter) | Head node of the filter linked list without any effect. If the operation fails, **null** is returned.| 43 44**Example** 45 46```ts 47import { image } from "@kit.ImageKit"; 48import { effectKit } from "@kit.ArkGraphics2D"; 49 50const color = new ArrayBuffer(96); 51let opts : image.InitializationOptions = { 52 editable: true, 53 pixelFormat: 3, 54 size: { 55 height: 4, 56 width: 6 57 } 58} 59image.createPixelMap(color, opts).then((pixelMap) => { 60 let headFilter = effectKit.createEffect(pixelMap); 61}) 62``` 63 64## effectKit.createColorPicker 65 66createColorPicker(source: image.PixelMap): Promise\<ColorPicker> 67 68Creates a **ColorPicker** instance based on a pixel map. This API uses a promise to return the result. 69 70**Widget capability**: This API can be used in ArkTS widgets since API version 12. 71 72**Atomic service API**: This API can be used in atomic services since API version 12. 73 74**System capability**: SystemCapability.Multimedia.Image.Core 75 76**Parameters** 77 78| Name | Type | Mandatory| Description | 79| -------- | ----------- | ---- | -------------------------- | 80| source | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image/image-overview.md).| 81 82**Return value** 83 84| Type | Description | 85| ---------------------- | -------------- | 86| Promise\<[ColorPicker](#colorpicker)> | Promise used to return the **ColorPicker** instance created.| 87 88**Error codes** 89 90For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 91 92| ID| Error Message | 93| -------- | ------------------------------ | 94| 401 | Input parameter error. | 95 96**Example** 97 98```ts 99import { image } from "@kit.ImageKit"; 100import { effectKit } from "@kit.ArkGraphics2D"; 101import { BusinessError } from "@kit.BasicServicesKit"; 102 103const color = new ArrayBuffer(96); 104let opts : image.InitializationOptions = { 105 editable: true, 106 pixelFormat: 3, 107 size: { 108 height: 4, 109 width: 6 110 } 111} 112 113image.createPixelMap(color, opts).then((pixelMap) => { 114 effectKit.createColorPicker(pixelMap).then(colorPicker => { 115 console.info("color picker=" + colorPicker); 116 }).catch( (reason : BusinessError) => { 117 console.error("error=" + reason.message); 118 }) 119}) 120``` 121 122## effectKit.createColorPicker<sup>10+</sup> 123 124createColorPicker(source: image.PixelMap, region: Array\<number>): Promise\<ColorPicker> 125 126Creates a **ColorPicker** instance for the selected region based on a pixel map. This API uses a promise to return the result. 127 128**Widget capability**: This API can be used in ArkTS widgets since API version 12. 129 130**Atomic service API**: This API can be used in atomic services since API version 12. 131 132**System capability**: SystemCapability.Multimedia.Image.Core 133 134**Parameters** 135 136| Name | Type | Mandatory| Description | 137| -------- | ----------- | ---- | -------------------------- | 138| source | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image/image-overview.md).| 139| region | Array\<number> | Yes | Region of the image from which the color is picked.<br>The array consists of four elements, representing the left, top, right, and bottom positions of the image, respectively. The value of each element must be in the range [0, 1]. The leftmost and topmost positions of the image correspond to 0, and the rightmost and bottom positions correspond to 1. In the array, the third element must be greater than the first element, and the fourth element must be greater than the second element.| 140 141**Return value** 142 143| Type | Description | 144| ---------------------- | -------------- | 145| Promise\<[ColorPicker](#colorpicker)> | Promise used to return the **ColorPicker** instance created.| 146 147**Error codes** 148 149For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 150 151| ID| Error Message | 152| -------- | ------------------------------ | 153| 401 | Input parameter error. | 154 155**Example** 156 157```ts 158import { image } from "@kit.ImageKit"; 159import { effectKit } from "@kit.ArkGraphics2D"; 160import { BusinessError } from "@kit.BasicServicesKit"; 161 162const color = new ArrayBuffer(96); 163let opts : image.InitializationOptions = { 164 editable: true, 165 pixelFormat: 3, 166 size: { 167 height: 4, 168 width: 6 169 } 170} 171 172image.createPixelMap(color, opts).then((pixelMap) => { 173 effectKit.createColorPicker(pixelMap, [0, 0, 1, 1]).then(colorPicker => { 174 console.info("color picker=" + colorPicker); 175 }).catch( (reason : BusinessError) => { 176 console.error("error=" + reason.message); 177 }) 178}) 179``` 180 181## effectKit.createColorPicker 182 183createColorPicker(source: image.PixelMap, callback: AsyncCallback\<ColorPicker>): void 184 185Creates a **ColorPicker** instance based on a pixel map. This API uses an asynchronous callback to return the result. 186 187**Widget capability**: This API can be used in ArkTS widgets since API version 12. 188 189**Atomic service API**: This API can be used in atomic services since API version 12. 190 191**System capability**: SystemCapability.Multimedia.Image.Core 192 193**Parameters** 194 195| Name | Type | Mandatory| Description | 196| -------- | ------------------ | ---- | -------------------------- | 197| source | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes |**PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image/image-overview.md). | 198| callback | AsyncCallback\<[ColorPicker](#colorpicker)> | Yes | Callback used to return the **ColorPicker** instance created.| 199 200**Error codes** 201 202For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 203 204| ID| Error Message | 205| -------- | ------------------------------ | 206| 401 | Input parameter error. | 207 208**Example** 209 210```ts 211import { image } from "@kit.ImageKit"; 212import { effectKit } from "@kit.ArkGraphics2D"; 213 214const color = new ArrayBuffer(96); 215let opts : image.InitializationOptions = { 216 editable: true, 217 pixelFormat: 3, 218 size: { 219 height: 4, 220 width: 6 221 } 222} 223image.createPixelMap(color, opts).then((pixelMap) => { 224 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 225 if (error) { 226 console.error('Failed to create color picker.'); 227 } else { 228 console.info('Succeeded in creating color picker.'); 229 } 230 }) 231}) 232``` 233 234## effectKit.createColorPicker<sup>10+</sup> 235 236createColorPicker(source: image.PixelMap, region:Array\<number>, callback: AsyncCallback\<ColorPicker>): void 237 238Creates a **ColorPicker** instance for the selected region based on a pixel map. This API uses an asynchronous callback to return the result. 239 240**Widget capability**: This API can be used in ArkTS widgets since API version 12. 241 242**Atomic service API**: This API can be used in atomic services since API version 12. 243 244**System capability**: SystemCapability.Multimedia.Image.Core 245 246**Parameters** 247 248| Name | Type | Mandatory| Description | 249| -------- | ------------------ | ---- | -------------------------- | 250| source | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes |**PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image/image-overview.md). | 251| region | Array\<number> | Yes | Region of the image from which the color is picked.<br>The array consists of four elements, representing the left, top, right, and bottom positions of the image, respectively. The value of each element must be in the range [0, 1]. The leftmost and topmost positions of the image correspond to 0, and the rightmost and bottom positions correspond to 1. In the array, the third element must be greater than the first element, and the fourth element must be greater than the second element.| 252| callback | AsyncCallback\<[ColorPicker](#colorpicker)> | Yes | Callback used to return the **ColorPicker** instance created.| 253 254**Error codes** 255 256For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 257 258| ID| Error Message | 259| -------- | ------------------------------ | 260| 401 | Input parameter error. | 261 262**Example** 263 264```ts 265import { image } from "@kit.ImageKit"; 266import { effectKit } from "@kit.ArkGraphics2D"; 267 268const color = new ArrayBuffer(96); 269let opts : image.InitializationOptions = { 270 editable: true, 271 pixelFormat: 3, 272 size: { 273 height: 4, 274 width: 6 275 } 276} 277image.createPixelMap(color, opts).then((pixelMap) => { 278 effectKit.createColorPicker(pixelMap, [0, 0, 1, 1], (error, colorPicker) => { 279 if (error) { 280 console.error('Failed to create color picker.'); 281 } else { 282 console.info('Succeeded in creating color picker.'); 283 } 284 }) 285}) 286``` 287 288## Color 289 290A class that stores the color picked. 291 292**Widget capability**: This API can be used in ArkTS widgets since API version 12. 293 294**Atomic service API**: This API can be used in atomic services since API version 12. 295 296**System capability**: SystemCapability.Multimedia.Image.Core 297 298| Name | Type | Readable| Writable| Description | 299| ------ | ----- | ---- | ---- | ---------------- | 300| red | number | Yes | No | Value of the red component. The value range is [0x0, 0xFF]. | 301| green | number | Yes | No | Value of the green component. The value range is [0x0, 0xFF]. | 302| blue | number | Yes | No | Value of the blue component. The value range is [0x0, 0xFF]. | 303| alpha | number | Yes | No | Value of the alpha component. The value range is [0x0, 0xFF]. | 304 305## TileMode<sup>14+</sup> 306 307Enumerates the tile modes of the shader effect. 308 309**System capability**: SystemCapability.Multimedia.Image.Core 310 311| Name | Value | Description | 312| ---------------------- | ---- | ------------------------------ | 313| CLAMP | 0 | Replicates the edge color if the shader effect draws outside of its original boundary.| 314| REPEAT | 1 | Repeats the shader effect in both horizontal and vertical directions.| 315| MIRROR | 2 | Repeats the shader effect in both horizontal and vertical directions, alternating mirror images.| 316| DECAL | 3 | Renders the shader effect only within the original boundary.| 317 318## ColorPicker 319 320A class used to obtain the color from an image. Before calling any method of **ColorPicker**, use [createColorPicker](#effectkitcreatecolorpicker) to create a **ColorPicker** instance. 321 322### getMainColor 323 324getMainColor(): Promise\<Color> 325 326Obtains the main color from the image and writes the result to a [Color](#color) instance. This API uses a promise to return the result. 327 328**Widget capability**: This API can be used in ArkTS widgets since API version 12. 329 330**Atomic service API**: This API can be used in atomic services since API version 12. 331 332**System capability**: SystemCapability.Multimedia.Image.Core 333 334**Return value** 335 336| Type | Description | 337| :------------- | :---------------------------------------------- | 338| Promise\<[Color](#color)> | Promise used to return the color value of the main color. If the operation fails, an error message is returned.| 339 340**Example** 341 342```ts 343import { image } from "@kit.ImageKit"; 344import { effectKit } from "@kit.ArkGraphics2D"; 345 346const color = new ArrayBuffer(96); 347let opts: image.InitializationOptions = { 348 editable: true, 349 pixelFormat: 3, 350 size: { 351 height: 4, 352 width: 6 353 } 354} 355image.createPixelMap(color, opts).then((pixelMap) => { 356 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 357 if (error) { 358 console.error('Failed to create color picker.'); 359 } else { 360 console.info('Succeeded in creating color picker.'); 361 colorPicker.getMainColor().then(color => { 362 console.info('Succeeded in getting main color.'); 363 console.info(`color[ARGB]=${color.alpha},${color.red},${color.green},${color.blue}`); 364 }) 365 } 366 }) 367}) 368``` 369 370### getMainColorSync 371 372getMainColorSync(): Color 373 374Obtains the main color from the image and writes the result to a [Color](#color) instance. This API returns the result synchronously. 375 376**Widget capability**: This API can be used in ArkTS widgets since API version 12. 377 378**Atomic service API**: This API can be used in atomic services since API version 12. 379 380**System capability**: SystemCapability.Multimedia.Image.Core 381 382**Return value** 383 384| Type | Description | 385| :------- | :----------------------------------- | 386| [Color](#color) | Color value of the main color. If the operation fails, **null** is returned.| 387 388**Example** 389 390```ts 391import { image } from "@kit.ImageKit"; 392import { effectKit } from "@kit.ArkGraphics2D"; 393 394const color = new ArrayBuffer(96); 395let opts : image.InitializationOptions = { 396 editable: true, 397 pixelFormat: 3, 398 size: { 399 height: 4, 400 width: 6 401 } 402} 403image.createPixelMap(color, opts).then((pixelMap) => { 404 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 405 if (error) { 406 console.error('Failed to create color picker.'); 407 } else { 408 console.info('Succeeded in creating color picker.'); 409 let color = colorPicker.getMainColorSync(); 410 console.info('get main color =' + color); 411 } 412 }) 413}) 414``` 415 416 417### getLargestProportionColor<sup>10+</sup> 418 419getLargestProportionColor(): Color 420 421Obtains the color with the largest proportion from the image and writes the result to a [Color](#color) instance. This API returns the result synchronously. 422 423**Widget capability**: This API can be used in ArkTS widgets since API version 12. 424 425**Atomic service API**: This API can be used in atomic services since API version 12. 426 427**System capability**: SystemCapability.Multimedia.Image.Core 428 429**Return value** 430 431| Type | Description | 432| :------------- | :---------------------------------------------- | 433| [Color](#color) | Color value of the color with the largest proportion. If the operation fails, **null** is returned.| 434 435**Example** 436 437```ts 438import { image } from "@kit.ImageKit"; 439import { effectKit } from "@kit.ArkGraphics2D"; 440 441const color = new ArrayBuffer(96); 442let opts : image.InitializationOptions = { 443 editable: true, 444 pixelFormat: 3, 445 size: { 446 height: 4, 447 width: 6 448 } 449} 450image.createPixelMap(color, opts).then((pixelMap) => { 451 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 452 if (error) { 453 console.error('Failed to create color picker.'); 454 } else { 455 console.info('Succeeded in creating color picker.'); 456 let color = colorPicker.getLargestProportionColor(); 457 console.info('get largest proportion color =' + color); 458 } 459 }) 460}) 461``` 462 463 464### getTopProportionColors<sup>12+</sup> 465 466getTopProportionColors(colorCount: number): Array<Color | null> 467 468Obtains a given number of colors with the top proportions in the image. This API returns the result synchronously. 469 470**Widget capability**: This API can be used in ArkTS widgets since API version 12. 471 472**Atomic service API**: This API can be used in atomic services since API version 12. 473 474**System capability**: SystemCapability.Multimedia.Image.Core 475 476**Parameters** 477| Name | Type | Mandatory| Description | 478| ---------- | ------ | ---- | ------------------------------------------- | 479| colorCount | number | Yes | Number of colors to obtain. The value range is [1, 10]. If a non-integer is passed in, the value will be rounded down. | 480 481**Return value** 482 483| Type | Description | 484| :--------------------------------------- | :---------------------------------------------- | 485| Array<[Color](#color) \| null> | Array of colors, sorted by proportion.<br>- If the number of colors obtained is less than the value of **colorCount**, the array size is the actual number obtained.<br>- If the color fails to be obtained, an empty array is returned.<br>- If the value of **colorCount** is less than 1, **[null]** is returned.<br>- If the value of **colorCount** is greater than 10, an array holding the first 10 colors with the top proportions is returned.| 486 487**Example** 488 489```js 490import { image } from "@kit.ImageKit"; 491import { effectKit } from "@kit.ArkGraphics2D"; 492 493const color = new ArrayBuffer(96); 494let opts : image.InitializationOptions = { 495 editable: true, 496 pixelFormat: 3, 497 size: { 498 height: 4, 499 width: 6 500 } 501} 502image.createPixelMap(color, opts).then((pixelMap) => { 503 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 504 if (error) { 505 console.error('Failed to create color picker.'); 506 } else { 507 console.info('Succeeded in creating color picker.'); 508 let colors = colorPicker.getTopProportionColors(2); 509 for(let index = 0; index < colors.length; index++) { 510 if (colors[index]) { 511 console.info('get top proportion colors: index ' + index + ', color ' + colors[index]); 512 } 513 } 514 } 515 }) 516}) 517``` 518 519 520### getHighestSaturationColor<sup>10+</sup> 521 522getHighestSaturationColor(): Color 523 524Obtains the color with the highest saturation from the image and writes the result to a [Color](#color) instance. This API returns the result synchronously. 525 526**Widget capability**: This API can be used in ArkTS widgets since API version 12. 527 528**Atomic service API**: This API can be used in atomic services since API version 12. 529 530**System capability**: SystemCapability.Multimedia.Image.Core 531 532**Return value** 533 534| Type | Description | 535| :------------- | :---------------------------------------------- | 536| [Color](#color) | Color value of the color with the highest saturation. If the operation fails, **null** is returned.| 537 538**Example** 539 540```ts 541import { image } from "@kit.ImageKit"; 542import { effectKit } from "@kit.ArkGraphics2D"; 543 544const color = new ArrayBuffer(96); 545let opts: image.InitializationOptions = { 546 editable: true, 547 pixelFormat: 3, 548 size: { 549 height: 4, 550 width: 6 551 } 552} 553image.createPixelMap(color, opts).then((pixelMap) => { 554 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 555 if (error) { 556 console.error('Failed to create color picker.'); 557 } else { 558 console.info('Succeeded in creating color picker.'); 559 let color = colorPicker.getHighestSaturationColor(); 560 console.info('get highest saturation color =' + color); 561 } 562 }) 563}) 564``` 565 566 567### getAverageColor<sup>10+</sup> 568 569getAverageColor(): Color 570 571Obtains the average color from the image and writes the result to a [Color](#color) instance. This API returns the result synchronously. 572 573**Widget capability**: This API can be used in ArkTS widgets since API version 12. 574 575**Atomic service API**: This API can be used in atomic services since API version 12. 576 577**System capability**: SystemCapability.Multimedia.Image.Core 578 579**Return value** 580 581| Type | Description | 582| :------------- | :---------------------------------------------- | 583| [Color](#color) | Average color value. If the operation fails, **null** is returned.| 584 585**Example** 586 587```ts 588import { image } from "@kit.ImageKit"; 589import { effectKit } from "@kit.ArkGraphics2D"; 590 591const color = new ArrayBuffer(96); 592let opts: image.InitializationOptions = { 593 editable: true, 594 pixelFormat: 3, 595 size: { 596 height: 4, 597 width: 6 598 } 599} 600image.createPixelMap(color, opts).then((pixelMap) => { 601 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 602 if (error) { 603 console.error('Failed to create color picker.'); 604 } else { 605 console.info('Succeeded in creating color picker.'); 606 let color = colorPicker.getAverageColor(); 607 console.info('get average color =' + color); 608 } 609 }) 610}) 611``` 612 613 614### isBlackOrWhiteOrGrayColor<sup>10+</sup> 615 616isBlackOrWhiteOrGrayColor(color: number): boolean 617 618Checks whether a color is black, white, and gray. 619 620**Widget capability**: This API can be used in ArkTS widgets since API version 12. 621 622**Atomic service API**: This API can be used in atomic services since API version 12. 623 624**System capability**: SystemCapability.Multimedia.Image.Core 625 626**Parameters** 627 628| Name | Type | Mandatory| Description | 629| -------- | ----------- | ---- | -------------------------- | 630| color| number | Yes | Color to check. The value range is [0x0, 0xFFFFFFFF].| 631 632**Return value** 633 634| Type | Description | 635| :------------- | :---------------------------------------------- | 636| boolean | Returns **true** if the image is black, white, and gray; returns **false** otherwise.| 637 638**Example** 639 640```ts 641import { image } from "@kit.ImageKit"; 642import { effectKit } from "@kit.ArkGraphics2D"; 643 644const color = new ArrayBuffer(96); 645let opts: image.InitializationOptions = { 646 editable: true, 647 pixelFormat: 3, 648 size: { 649 height: 4, 650 width: 6 651 } 652} 653image.createPixelMap(color, opts).then((pixelMap) => { 654 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 655 if (error) { 656 console.error('Failed to create color picker.'); 657 } else { 658 console.info('Succeeded in creating color picker.'); 659 let bJudge = colorPicker.isBlackOrWhiteOrGrayColor(0xFFFFFFFF); 660 console.info('is black or white or gray color[bool](white) =' + bJudge); 661 } 662 }) 663}) 664``` 665 666## Filter 667 668A class used to add a specified effect to an image. Before calling any method of **Filter**, use [createEffect](#effectkitcreateeffect) to create a **Filter** instance. 669 670### blur 671 672blur(radius: number): Filter 673 674Adds the blur effect to the filter linked list, and returns the head node of the linked list. 675 676> **NOTE** 677> 678> This API provides the blur effect for static images. To provide the real-time blur effect for components, use [dynamic blur](../../ui/arkts-blur-effect.md). 679 680**Widget capability**: This API can be used in ArkTS widgets since API version 12. 681 682**Atomic service API**: This API can be used in atomic services since API version 12. 683 684**System capability**: SystemCapability.Multimedia.Image.Core 685 686**Parameters** 687 688| Name| Type | Mandatory| Description | 689| ------ | ----------- | ---- | ------------------------------------------------------------ | 690| radius | number | Yes | Blur radius, in pixels. The blur effect is proportional to the configured value. A larger value indicates a more obvious effect.| 691 692**Return value** 693 694| Type | Description | 695| :------------- | :---------------------------------------------- | 696| [Filter](#filter) | Final image effect.| 697 698**Example** 699 700```ts 701import { image } from "@kit.ImageKit"; 702import { effectKit } from "@kit.ArkGraphics2D"; 703 704const color = new ArrayBuffer(96); 705let opts : image.InitializationOptions = { 706 editable: true, 707 pixelFormat: 3, 708 size: { 709 height: 4, 710 width: 6 711 } 712}; 713image.createPixelMap(color, opts).then((pixelMap) => { 714 let radius = 5; 715 let headFilter = effectKit.createEffect(pixelMap); 716 if (headFilter != null) { 717 headFilter.blur(radius); 718 } 719}) 720``` 721 722 723### blur<sup>14+</sup> 724 725blur(radius: number, tileMode: TileMode): Filter 726 727Adds the blur effect to the filter linked list, and returns the head node of the linked list. 728 729> **NOTE** 730> 731> This API provides the blur effect for static images. To provide the real-time blur effect for components, use [dynamic blur](../../ui/arkts-blur-effect.md). 732 733**System capability**: SystemCapability.Multimedia.Image.Core 734 735**Parameters** 736 737| Name| Type | Mandatory| Description | 738| ------ | ----------- | ---- | ------------------------------------------------------------ | 739| radius | number | Yes | Blur radius, in pixels. The blur effect is proportional to the configured value. A larger value indicates a more obvious effect.| 740| tileMode | [TileMode](#tilemode14) | Yes | Tile mode of the shader effect. The blur effect of image edges is affected. Currently, only CPU rendering is supported. Therefore, the tile mode supports only DECAL.| 741 742**Return value** 743 744| Type | Description | 745| :------------- | :---------------------------------------------- | 746| [Filter](#filter) | Final image effect.| 747 748**Example** 749 750```ts 751import { image } from "@kit.ImageKit"; 752import { effectKit } from "@kit.ArkGraphics2D"; 753 754const color = new ArrayBuffer(96); 755let opts : image.InitializationOptions = { 756 editable: true, 757 pixelFormat: 3, 758 size: { 759 height: 4, 760 width: 6 761 } 762}; 763image.createPixelMap(color, opts).then((pixelMap) => { 764 let radius = 30; 765 let headFilter = effectKit.createEffect(pixelMap); 766 if (headFilter != null) { 767 headFilter.blur(radius, effectKit.TileMode.DECAL); 768 } 769}) 770``` 771 772 773### invert<sup>12+</sup> 774 775invert(): Filter 776 777Adds the inversion effect to the filter linked list, and returns the head node of the linked list. 778 779**System capability**: SystemCapability.Multimedia.Image.Core 780 781**Return value** 782 783| Type | Description | 784| :------------- | :---------------------------------------------- | 785| [Filter](#filter) | Final image effect.| 786 787**Example** 788 789```ts 790import { image } from "@kit.ImageKit"; 791import { effectKit } from "@kit.ArkGraphics2D"; 792 793const color = new ArrayBuffer(96); 794let opts : image.InitializationOptions = { 795 editable: true, 796 pixelFormat: 3, 797 size: { 798 height: 4, 799 width: 6 800 } 801}; 802image.createPixelMap(color, opts).then((pixelMap) => { 803 let headFilter = effectKit.createEffect(pixelMap); 804 if (headFilter != null) { 805 headFilter.invert(); 806 } 807}) 808``` 809 810 811### setColorMatrix<sup>12+</sup> 812 813setColorMatrix(colorMatrix: Array\<number>): Filter 814 815Adds a custom effect to the filter linked list, and returns the head node of the linked list. 816 817**System capability**: SystemCapability.Multimedia.Image.Core 818 819**Parameters** 820 821| Name| Type | Mandatory| Description | 822| ------ | ----------- | ---- | ------------------------------------------------------------ | 823| colorMatrix | Array\<number> | Yes | Custom color matrix.<br>A 5 x 4 matrix can be created. The value range of the matrix element is [0, 1], where **0** indicates that the color channel is not involved in the calculation, and **1** indicates that the color channel is involved in the calculation and retains the original weight.| 824 825**Return value** 826 827| Type | Description | 828| :------------- | :---------------------------------------------- | 829| [Filter](#filter) | Final image effect.| 830 831**Error codes** 832 833For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 834 835| ID| Error Message | 836| -------- | ------------------------------ | 837| 401 | Input parameter error. | 838 839**Example** 840 841```ts 842import { image } from "@kit.ImageKit"; 843import { effectKit } from "@kit.ArkGraphics2D"; 844 845const color = new ArrayBuffer(96); 846let opts : image.InitializationOptions = { 847 editable: true, 848 pixelFormat: 3, 849 size: { 850 height: 4, 851 width: 6 852 } 853}; 854image.createPixelMap(color, opts).then((pixelMap) => { 855 let colorMatrix:Array<number> = [ 856 0.2126,0.7152,0.0722,0,0, 857 0.2126,0.7152,0.0722,0,0, 858 0.2126,0.7152,0.0722,0,0, 859 0,0,0,1,0 860 ]; 861 let headFilter = effectKit.createEffect(pixelMap); 862 if (headFilter != null) { 863 headFilter.setColorMatrix(colorMatrix); 864 } 865}) 866``` 867 868### brightness 869 870brightness(bright: number): Filter 871 872Adds the brightness effect to the filter linked list, and returns the head node of the linked list. 873 874**Widget capability**: This API can be used in ArkTS widgets since API version 12. 875 876**Atomic service API**: This API can be used in atomic services since API version 12. 877 878**System capability**: SystemCapability.Multimedia.Image.Core 879 880**Parameters** 881 882| Name| Type | Mandatory| Description | 883| ------ | ----------- | ---- | ------------------------------------------------------------ | 884| bright | number | Yes | Brightness value, ranging from 0 to 1. When the value is **0**, the image brightness remains unchanged.| 885 886**Return value** 887 888| Type | Description | 889| :------------- | :---------------------------------------------- | 890| [Filter](#filter) | Final image effect.| 891 892**Example** 893 894```ts 895import { image } from "@kit.ImageKit"; 896import { effectKit } from "@kit.ArkGraphics2D"; 897 898const color = new ArrayBuffer(96); 899let opts : image.InitializationOptions = { 900 editable: true, 901 pixelFormat: 3, 902 size: { 903 height: 4, 904 width: 6 905 } 906}; 907image.createPixelMap(color, opts).then((pixelMap) => { 908 let bright = 0.5; 909 let headFilter = effectKit.createEffect(pixelMap); 910 if (headFilter != null) { 911 headFilter.brightness(bright); 912 } 913}) 914``` 915 916 917### grayscale 918 919grayscale(): Filter 920 921Adds the grayscale effect to the filter linked list, and returns the head node of the linked list. 922 923**Widget capability**: This API can be used in ArkTS widgets since API version 12. 924 925**Atomic service API**: This API can be used in atomic services since API version 12. 926 927**System capability**: SystemCapability.Multimedia.Image.Core 928 929**Return value** 930 931| Type | Description | 932| :------------- | :---------------------------------------------- | 933| [Filter](#filter) | Final image effect.| 934 935**Example** 936 937```ts 938import { image } from "@kit.ImageKit"; 939import { effectKit } from "@kit.ArkGraphics2D"; 940 941const color = new ArrayBuffer(96); 942let opts : image.InitializationOptions = { 943 editable: true, 944 pixelFormat: 3, 945 size: { 946 height: 4, 947 width: 6 948 } 949}; 950image.createPixelMap(color, opts).then((pixelMap) => { 951 let headFilter = effectKit.createEffect(pixelMap); 952 if (headFilter != null) { 953 headFilter.grayscale(); 954 } 955}) 956``` 957 958 959### getEffectPixelMap<sup>11+</sup> 960 961getEffectPixelMap(): Promise<image.PixelMap> 962 963Obtains **image.PixelMap** of the source image to which the filter linked list is added. This API uses a promise to return the result. 964 965**Widget capability**: This API can be used in ArkTS widgets since API version 12. 966 967**Atomic service API**: This API can be used in atomic services since API version 12. 968 969**System capability**: SystemCapability.Multimedia.Image.Core 970 971**Return value** 972 973| Type | Description | 974| ---------------------- | -------------- | 975| Promise\<image.PixelMap> | Promise used to return **image.PixelMap** of the source image.| 976 977 978**Example** 979 980```ts 981import { image } from "@kit.ImageKit"; 982import { effectKit } from "@kit.ArkGraphics2D"; 983 984const color = new ArrayBuffer(96); 985let opts : image.InitializationOptions = { 986 editable: true, 987 pixelFormat: 3, 988 size: { 989 height: 4, 990 width: 6 991 } 992}; 993image.createPixelMap(color, opts).then((pixelMap) => { 994 effectKit.createEffect(pixelMap).grayscale().getEffectPixelMap().then(data => { 995 console.info('getPixelBytesNumber = ', data.getPixelBytesNumber()); 996 }) 997}) 998``` 999 1000### getPixelMap<sup>(deprecated)</sup> 1001 1002getPixelMap(): image.PixelMap 1003 1004Obtains **image.PixelMap** of the source image to which the filter linked list is added. 1005 1006> **NOTE** 1007> 1008> This API is supported since API version 9 and deprecated since API version 11. You are advised to use [getEffectPixelMap](#geteffectpixelmap11) instead. 1009 1010**System capability**: SystemCapability.Multimedia.Image.Core 1011 1012**Return value** 1013 1014| Type | Description | 1015| :------------- | :---------------------------------------------- | 1016| [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | **image.PixelMap** of the source image.| 1017 1018**Example** 1019 1020```ts 1021import { image } from "@kit.ImageKit"; 1022import { effectKit } from "@kit.ArkGraphics2D"; 1023 1024const color = new ArrayBuffer(96); 1025let opts : image.InitializationOptions = { 1026 editable: true, 1027 pixelFormat: 3, 1028 size: { 1029 height: 4, 1030 width: 6 1031 } 1032}; 1033image.createPixelMap(color, opts).then((pixelMap) => { 1034 let pixel = effectKit.createEffect(pixelMap).grayscale().getPixelMap(); 1035 console.info('getPixelBytesNumber = ', pixel.getPixelBytesNumber()); 1036}) 1037``` 1038