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![image_Main_Color.png](figures/image_Main_Color.png)
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![image_Largest_Proportion_Color.png](figures/image_Largest_Proportion_Color.png)
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![image_Largest_Proportion_Color.png](figures/image_Top_Proportion_Colors.png)
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![image_Highest_Saturation_Color.png](figures/image_Highest_Saturation_Color.png)
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![image_Average_Color.png](figures/image_Average_Color.png)
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![image_Add_Blur.png](figures/image_Add_Blur.png)
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![image_Add_Blur_With_TileMode.png](figures/image_Add_Blur_With_TileMode.png)
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![image_Add_Invert.png](figures/image_Add_Invert.png)
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![image_Add_Brightness.png](figures/image_Add_Brightness.png)
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![image_Add_Grayscale.png](figures/image_Add_Grayscale.png)
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