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```js 18import effectKit from '@ohos.effectKit'; 19``` 20 21## effectKit.createEffect 22createEffect(source: image.PixelMap): Filter 23 24Creates a **Filter** instance based on the pixel map. 25 26**System capability**: SystemCapability.Multimedia.Image.Core 27 28**Parameters** 29 30| Name | Type | Mandatory| Description | 31| ------- | ----------------- | ---- | -------- | 32| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module. | 33 34**Return value** 35 36| Type | Description | 37| -------------------------------- | -------------- | 38| [Filter](#filter) | Head node of the filter linked list without any effect. If the operation fails, **null** is returned.| 39 40**Example** 41 42```js 43import image from "@ohos.multimedia.image"; 44 45const color = new ArrayBuffer(96); 46let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 47image.createPixelMap(color, opts).then((pixelMap) => { 48 let headFilter = effectKit.createEffect(pixelMap); 49}) 50``` 51 52## effectKit.createColorPicker 53 54createColorPicker(source: image.PixelMap): Promise\<ColorPicker> 55 56Creates a **ColorPicker** instance based on the pixel map. This API uses a promise to return the result. 57 58**System capability**: SystemCapability.Multimedia.Image.Core 59 60**Parameters** 61 62| Name | Type | Mandatory| Description | 63| -------- | ----------- | ---- | -------------------------- | 64| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module.| 65 66**Return value** 67 68| Type | Description | 69| ---------------------- | -------------- | 70| Promise\<[ColorPicker](#colorpicker)> | Promise used to return the **ColorPicker** instance created.| 71 72**Example** 73 74```js 75import image from "@ohos.multimedia.image"; 76 77const color = new ArrayBuffer(96); 78let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 79image.createPixelMap(color, opts).then((pixelMap) => { 80 effectKit.createColorPicker(pixelMap).then(colorPicker => { 81 console.info("color picker=" + colorPicker); 82 }).catch(ex => console.error(".error=" + ex.toString())) 83}) 84``` 85 86## effectKit.createColorPicker 87 88createColorPicker(source: image.PixelMap, callback: AsyncCallback\<ColorPicker>): void 89 90Creates a **ColorPicker** instance based on the pixel map. This API uses an asynchronous callback to return the result. 91 92**System capability**: SystemCapability.Multimedia.Image.Core 93 94**Parameters** 95 96| Name | Type | Mandatory| Description | 97| -------- | ------------------ | ---- | -------------------------- | 98| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes |**PixelMap** instance created by the image module. | 99| callback | AsyncCallback\<[ColorPicker](#colorpicker)> | Yes | Callback used to return the **ColorPicker** instance created.| 100 101**Example** 102 103```js 104import image from "@ohos.multimedia.image"; 105 106const color = new ArrayBuffer(96); 107let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 108image.createPixelMap(color, opts).then((pixelMap) => { 109 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 110 if (error) { 111 console.log('Failed to create color picker.'); 112 } else { 113 console.log('Succeeded in creating color picker.'); 114 } 115 }) 116}) 117``` 118 119## Color 120 121A class that stores the color picked. 122 123**System capability**: SystemCapability.Multimedia.Image.Core 124 125| Name | Type | Readable| Writable| Description | 126| ------ | ----- | ---- | ---- | ---------------- | 127| red | number | Yes | No | Value of the red component. | 128| green | number | Yes | No | Value of the green component. | 129| blue | number | Yes | No | Value of the blue component. | 130| alpha | number | Yes | No | Value of the alpha component. | 131 132## ColorPicker 133 134A class used to obtain the main color of an image from its data. Before calling any method of **ColorPicker**, use [createColorPicker](#effectkitcreatecolorpicker) to create a **ColorPicker** instance. 135 136### getMainColor 137 138getMainColor(): Promise\<Color> 139 140Obtains the main color of the image and writes the result to a **[Color](#color)** instance. This API uses a promise to return the result. 141 142**System capability**: SystemCapability.Multimedia.Image.Core 143 144**Return value** 145 146| Type | Description | 147| :------------- | :---------------------------------------------- | 148| Promise\<[Color](#color)> | Promise used to return the color value of the main color. If the operation fails, an error message is returned.| 149 150**Example** 151 152```js 153colorPicker.getMainColor().then(color => { 154 console.log('Succeeded in getting main color.'); 155 console.info(`color[ARGB]=${color.alpha},${color.red},${color.green},${color.blue}`); 156}).catch(error => { 157 console.log('Failed to get main color.'); 158}) 159``` 160 161### getMainColorSync 162 163getMainColorSync(): Color 164 165Obtains the main color of the image and writes the result to a **[Color](#color)** instance. This API returns the result in synchronous mode. 166 167**System capability**: SystemCapability.Multimedia.Image.Core 168 169**Return value** 170 171| Type | Description | 172| :------- | :----------------------------------- | 173| [Color](#color) | Color value of the main color. If the operation fails, **null** is returned.| 174 175**Example** 176 177```js 178let color = colorPicker.getMainColorSync(); 179console.log('get main color =' + color); 180``` 181 182 183## Filter 184 185A class used to add a specified effect to an image. Before calling any method of **Filter**, use [createEffect](#effectkitcreateeffect) to create a **Filter** instance. 186 187### blur 188 189blur(radius: number): Filter 190 191Adds the blur effect to the filter linked list, and returns the head node of the linked list. 192 193**System capability**: SystemCapability.Multimedia.Image.Core 194 195**Parameters** 196 197| Name| Type | Mandatory| Description | 198| ------ | ----------- | ---- | ------------------------------------------------------------ | 199| radius | number | Yes | Blur radius, in pixels. The blur effect is proportional to the configured value. A larger value indicates a more obvious effect.| 200 201**Return value** 202 203| Type | Description | 204| :------------- | :---------------------------------------------- | 205| [Filter](#filter) | Final image effect.| 206 207**Example** 208 209```js 210import image from "@ohos.multimedia.image"; 211 212const color = new ArrayBuffer(96); 213let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }; 214image.createPixelMap(color, opts).then((pixelMap) => { 215 let radius = 5; 216 let headFilter = effectKit.createEffect(pixelMap); 217 if (headFilter != null) { 218 headFilter.blur(radius); 219 } 220}) 221``` 222 223 224### brightness 225 226brightness(bright: number): Filter 227 228Adds the brightness effect to the filter linked list, and returns the head node of the linked list. 229 230**System capability**: SystemCapability.Multimedia.Image.Core 231 232**Parameters** 233 234| Name| Type | Mandatory| Description | 235| ------ | ----------- | ---- | ------------------------------------------------------------ | 236| bright | number | Yes | Brightness value, ranging from 0 to 1. When the value is **0**, the image brightness remains unchanged.| 237 238**Return value** 239 240| Type | Description | 241| :------------- | :---------------------------------------------- | 242| [Filter](#filter) | Final image effect.| 243 244**Example** 245 246```js 247import image from "@ohos.multimedia.image"; 248 249const color = new ArrayBuffer(96); 250let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }; 251image.createPixelMap(color, opts).then((pixelMap) => { 252 let bright = 0.5; 253 let headFilter = effectKit.createEffect(pixelMap); 254 if (headFilter != null) { 255 headFilter.brightness(bright); 256 } 257}) 258``` 259 260 261### grayscale 262 263grayscale(): Filter 264 265Adds the grayscale effect to the filter linked list, and returns the head node of the linked list. 266 267**System capability**: SystemCapability.Multimedia.Image.Core 268 269**Return value** 270 271| Type | Description | 272| :------------- | :---------------------------------------------- | 273| [Filter](#filter) | Final image effect.| 274 275**Example** 276 277```js 278import image from "@ohos.multimedia.image"; 279 280const color = new ArrayBuffer(96); 281let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }; 282image.createPixelMap(color, opts).then((pixelMap) => { 283 let headFilter = effectKit.createEffect(pixelMap); 284 if (headFilter != null) { 285 headFilter.grayscale(); 286 } 287}) 288``` 289 290 291### getPixelMap 292 293getPixelMap(): [image.PixelMap](js-apis-image.md#pixelmap7) 294 295Obtains **image.PixelMap** of the source image to which the filter linked list is added. 296 297**System capability**: SystemCapability.Multimedia.Image.Core 298 299**Return value** 300 301| Type | Description | 302| :------------- | :---------------------------------------------- | 303| [image.PixelMap](js-apis-image.md#pixelmap7) | **image.PixelMap** of the source image.| 304 305**Example** 306 307```js 308import image from "@ohos.multimedia.image"; 309 310const color = new ArrayBuffer(96); 311let opts = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }; 312image.createPixelMap(color, opts).then((pixelMap) => { 313 let pixel = effectKit.createEffect(pixelMap).grayscale().getPixelMap(); 314}) 315``` 316
