1# @ohos.effectKit (图像效果) 2 3图像效果提供处理图像的一些基础能力，包括对当前图像的亮度调节、模糊化、灰度调节、智能取色等。 4 5该模块提供以下图像效果相关的常用功能： 6 7- [Filter](#filter)：效果类，用于添加指定效果到图像源。 8- [Color](#color)：颜色类，用于保存取色的结果。 9- [ColorPicker](#colorpicker)：智能取色器。 10 11> **说明：** 12> 13> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import effectKit from '@ohos.effectKit'; 19``` 20 21## effectKit.createEffect 22createEffect(source: image.PixelMap): Filter 23 24通过传入的PixelMap创建Filter实例。 25 26**系统能力：** SystemCapability.Multimedia.Image.Core 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| ------- | ----------------- | ---- | -------- | 32| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 33 34**返回值：** 35 36| 类型 | 说明 | 37| -------------------------------- | -------------- | 38| [Filter](#filter) | 返回不带任何效果的Filter链表的头节点，失败时返回null。 | 39 40**示例：** 41 42```ts 43import image from "@ohos.multimedia.image"; 44import effectKit from "@ohos.effectKit"; 45 46const color = new ArrayBuffer(96); 47let opts : image.InitializationOptions = { 48 editable: true, 49 pixelFormat: 3, 50 size: { 51 height: 4, 52 width: 6 53 } 54} 55image.createPixelMap(color, opts).then((pixelMap) => { 56 let headFilter = effectKit.createEffect(pixelMap); 57}) 58``` 59 60## effectKit.createColorPicker 61 62createColorPicker(source: image.PixelMap): Promise\<ColorPicker> 63 64通过传入的PixelMap创建ColorPicker实例，使用Promise异步回调。 65 66**系统能力：** SystemCapability.Multimedia.Image.Core 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| -------- | ----------- | ---- | -------------------------- | 72| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 73 74**返回值：** 75 76| 类型 | 说明 | 77| ---------------------- | -------------- | 78| Promise\<[ColorPicker](#colorpicker)> | Promise对象。返回创建的ColorPicker实例。 | 79 80**示例：** 81 82```ts 83import image from "@ohos.multimedia.image"; 84import effectKit from "@ohos.effectKit"; 85import { BusinessError } from "@ohos.base"; 86 87const color = new ArrayBuffer(96); 88let opts : image.InitializationOptions = { 89 editable: true, 90 pixelFormat: 3, 91 size: { 92 height: 4, 93 width: 6 94 } 95} 96 97image.createPixelMap(color, opts).then((pixelMap) => { 98 effectKit.createColorPicker(pixelMap).then(colorPicker => { 99 console.info("color picker=" + colorPicker); 100 }).catch( (reason : BusinessError) => { 101 console.error("error=" + reason.message); 102 }) 103}) 104``` 105 106## effectKit.createColorPicker<sup>10+</sup> 107 108createColorPicker(source: image.PixelMap, region: Array\<number>): Promise\<ColorPicker> 109 110通过传入的PixelMap创建选定取色区域的ColorPicker实例，使用Promise异步回调。 111 112**系统能力：** SystemCapability.Multimedia.Image.Core 113 114**参数：** 115 116| 参数名 | 类型 | 必填 | 说明 | 117| -------- | ----------- | ---- | -------------------------- | 118| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 119| region | Array\<number> | 是 | 指定图片的取色区域。<br>数组元素个数为4，取值范围为[0, 1]，数组元素分别表示图片区域的左、上、右、下位置，图片最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。数组第三个元素需大于第一个元素，第四个元素需大于第二个元素。| 120 121**返回值：** 122 123| 类型 | 说明 | 124| ---------------------- | -------------- | 125| Promise\<[ColorPicker](#colorpicker)> | Promise对象。返回创建的ColorPicker实例。 | 126 127**示例：** 128 129```ts 130import image from "@ohos.multimedia.image"; 131import effectKit from "@ohos.effectKit"; 132import { BusinessError } from "@ohos.base"; 133 134const color = new ArrayBuffer(96); 135let opts : image.InitializationOptions = { 136 editable: true, 137 pixelFormat: 3, 138 size: { 139 height: 4, 140 width: 6 141 } 142} 143 144image.createPixelMap(color, opts).then((pixelMap) => { 145 effectKit.createColorPicker(pixelMap, [0, 0, 1, 1]).then(colorPicker => { 146 console.info("color picker=" + colorPicker); 147 }).catch( (reason : BusinessError) => { 148 console.error("error=" + reason.message); 149 }) 150}) 151``` 152 153## effectKit.createColorPicker 154 155createColorPicker(source: image.PixelMap, callback: AsyncCallback\<ColorPicker>): void 156 157通过传入的PixelMap创建ColorPicker实例，使用callback异步回调。 158 159**系统能力：** SystemCapability.Multimedia.Image.Core 160 161**参数：** 162 163| 参数名 | 类型 | 必填 | 说明 | 164| -------- | ------------------ | ---- | -------------------------- | 165| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 |image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 166| callback | AsyncCallback\<[ColorPicker](#colorpicker)> | 是 | 回调函数。返回创建的ColorPicker实例。 | 167 168**示例：** 169 170```ts 171import image from "@ohos.multimedia.image"; 172import effectKit from "@ohos.effectKit"; 173 174const color = new ArrayBuffer(96); 175let opts : image.InitializationOptions = { 176 editable: true, 177 pixelFormat: 3, 178 size: { 179 height: 4, 180 width: 6 181 } 182} 183image.createPixelMap(color, opts).then((pixelMap) => { 184 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 185 if (error) { 186 console.error('Failed to create color picker.'); 187 } else { 188 console.info('Succeeded in creating color picker.'); 189 } 190 }) 191}) 192``` 193 194## effectKit.createColorPicker<sup>10+</sup> 195 196createColorPicker(source: image.PixelMap, region:Array\<number>, callback: AsyncCallback\<ColorPicker>): void 197 198通过传入的PixelMap创建选定取色区域的ColorPicker实例，使用callback异步回调。 199 200**系统能力：** SystemCapability.Multimedia.Image.Core 201 202**参数：** 203 204| 参数名 | 类型 | 必填 | 说明 | 205| -------- | ------------------ | ---- | -------------------------- | 206| source | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 |image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image-overview.md)。 | 207| region | Array\<number> | 是 | 指定图片的取色区域。<br>数组元素个数为4，取值范围为[0, 1]，数组元素分别表示图片区域的左、上、右、下位置，图片最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。数组第三个元素需大于第一个元素，第四个元素需大于第二个元素。| 208| callback | AsyncCallback\<[ColorPicker](#colorpicker)> | 是 | 回调函数。返回创建的ColorPicker实例。 | 209 210**示例：** 211 212```ts 213import image from "@ohos.multimedia.image"; 214import effectKit from "@ohos.effectKit"; 215 216const color = new ArrayBuffer(96); 217let opts : image.InitializationOptions = { 218 editable: true, 219 pixelFormat: 3, 220 size: { 221 height: 4, 222 width: 6 223 } 224} 225image.createPixelMap(color, opts).then((pixelMap) => { 226 effectKit.createColorPicker(pixelMap, [0, 0, 1, 1], (error, colorPicker) => { 227 if (error) { 228 console.error('Failed to create color picker.'); 229 } else { 230 console.info('Succeeded in creating color picker.'); 231 } 232 }) 233}) 234``` 235 236## Color 237 238颜色类，用于保存取色的结果。 239 240**系统能力：** SystemCapability.Multimedia.Image.Core 241 242| 名称 | 类型 | 可读 | 可写 | 说明 | 243| ------ | ----- | ---- | ---- | ---------------- | 244| red | number | 是 | 否 | 红色分量值，取值范围[0x0, 0xFF]。 | 245| green | number | 是 | 否 | 绿色分量值，取值范围[0x0, 0xFF]。 | 246| blue | number | 是 | 否 | 蓝色分量值，取值范围[0x0, 0xFF]。 | 247| alpha | number | 是 | 否 | 透明通道分量值，取值范围[0x0, 0xFF]。 | 248 249## ColorPicker 250 251取色类，用于从一张图像数据中获取它的主要颜色。在调用ColorPicker的方法前，需要先通过[createColorPicker](#effectkitcreatecolorpicker)创建一个ColorPicker实例。 252 253### getMainColor 254 255getMainColor(): Promise\<Color> 256 257读取图像主色的颜色值，结果写入[Color](#color)里，使用Promise异步回调。 258 259**系统能力：** SystemCapability.Multimedia.Image.Core 260 261**返回值：** 262 263| 类型 | 说明 | 264| :------------- | :---------------------------------------------- | 265| Promise\<[Color](#color)> | Promise对象。返回图像主色对应的颜色值，失败时返回错误信息。 | 266 267**示例：** 268 269```ts 270import image from "@ohos.multimedia.image"; 271import effectKit from "@ohos.effectKit"; 272 273export function test06(): void { 274 const color = new ArrayBuffer(96); 275 let opts: image.InitializationOptions = { 276 editable: true, 277 pixelFormat: 3, 278 size: { 279 height: 4, 280 width: 6 281 } 282 } 283 image.createPixelMap(color, opts).then((pixelMap) => { 284 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 285 if (error) { 286 console.error('Failed to create color picker.'); 287 } else { 288 console.info('Succeeded in creating color picker.'); 289 colorPicker.getMainColor().then(color => { 290 console.info('Succeeded in getting main color.'); 291 console.info(`color[ARGB]=${color.alpha},${color.red},${color.green},${color.blue}`); 292 }) 293 } 294 }) 295 }) 296} 297``` 298 299### getMainColorSync 300 301getMainColorSync(): Color 302 303读取图像主色的颜色值，结果写入[Color](#color)里，使用同步方式返回。 304 305**系统能力：** SystemCapability.Multimedia.Image.Core 306 307**返回值：** 308 309| 类型 | 说明 | 310| :------- | :----------------------------------- | 311| [Color](#color) | Color实例，即图像主色对应的颜色值，失败时返回null。 | 312 313**示例：** 314 315```ts 316import image from "@ohos.multimedia.image"; 317import effectKit from "@ohos.effectKit"; 318 319const color = new ArrayBuffer(96); 320let opts : image.InitializationOptions = { 321 editable: true, 322 pixelFormat: 3, 323 size: { 324 height: 4, 325 width: 6 326 } 327} 328image.createPixelMap(color, opts).then((pixelMap) => { 329 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 330 if (error) { 331 console.error('Failed to create color picker.'); 332 } else { 333 console.info('Succeeded in creating color picker.'); 334 let color = colorPicker.getMainColorSync(); 335 console.info('get main color =' + color); 336 } 337 }) 338}) 339``` 340 341 342### getLargestProportionColor<sup>10+</sup> 343 344getLargestProportionColor(): Color 345 346读取图像占比最多的颜色值，结果写入[Color](#color)里，使用同步方式返回。 347 348**系统能力：** SystemCapability.Multimedia.Image.Core 349 350**返回值：** 351 352| 类型 | 说明 | 353| :------------- | :---------------------------------------------- | 354| [Color](#color) | Color实例，即图像占比最多的颜色值，失败时返回null。 | 355 356**示例：** 357 358```ts 359import image from "@ohos.multimedia.image"; 360import effectKit from "@ohos.effectKit"; 361 362const color = new ArrayBuffer(96); 363let opts : image.InitializationOptions = { 364 editable: true, 365 pixelFormat: 3, 366 size: { 367 height: 4, 368 width: 6 369 } 370} 371image.createPixelMap(color, opts).then((pixelMap) => { 372 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 373 if (error) { 374 console.error('Failed to create color picker.'); 375 } else { 376 console.info('Succeeded in creating color picker.'); 377 let color = colorPicker.getLargestProportionColor(); 378 console.info('get largest proportion color =' + color); 379 } 380 }) 381}) 382``` 383 384 385### getHighestSaturationColor<sup>10+</sup> 386 387getHighestSaturationColor(): Color 388 389读取图像饱和度最高的颜色值，结果写入[Color](#color)里，使用同步方式返回。 390 391**系统能力：** SystemCapability.Multimedia.Image.Core 392 393**返回值：** 394 395| 类型 | 说明 | 396| :------------- | :---------------------------------------------- | 397| [Color](#color) | Color实例，即图像饱和度最高的颜色值，失败时返回null。 | 398 399**示例：** 400 401```ts 402import image from "@ohos.multimedia.image"; 403import effectKit from "@ohos.effectKit"; 404 405const color = new ArrayBuffer(96); 406let opts: image.InitializationOptions = { 407 editable: true, 408 pixelFormat: 3, 409 size: { 410 height: 4, 411 width: 6 412 } 413} 414image.createPixelMap(color, opts).then((pixelMap) => { 415 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 416 if (error) { 417 console.error('Failed to create color picker.'); 418 } else { 419 console.info('Succeeded in creating color picker.'); 420 let color = colorPicker.getHighestSaturationColor(); 421 console.info('get highest saturation color =' + color); 422 } 423 }) 424}) 425``` 426 427 428### getAverageColor<sup>10+</sup> 429 430getAverageColor(): Color 431 432读取图像平均的颜色值，结果写入[Color](#color)里，使用同步方式返回。 433 434**系统能力：** SystemCapability.Multimedia.Image.Core 435 436**返回值：** 437 438| 类型 | 说明 | 439| :------------- | :---------------------------------------------- | 440| [Color](#color) | Color实例，即图像平均的颜色值，失败时返回null。 | 441 442**示例：** 443 444```ts 445import image from "@ohos.multimedia.image"; 446import effectKit from "@ohos.effectKit"; 447 448const color = new ArrayBuffer(96); 449let opts: image.InitializationOptions = { 450 editable: true, 451 pixelFormat: 3, 452 size: { 453 height: 4, 454 width: 6 455 } 456} 457image.createPixelMap(color, opts).then((pixelMap) => { 458 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 459 if (error) { 460 console.error('Failed to create color picker.'); 461 } else { 462 console.info('Succeeded in creating color picker.'); 463 let color = colorPicker.getAverageColor(); 464 console.info('get average color =' + color); 465 } 466 }) 467}) 468``` 469 470 471### isBlackOrWhiteOrGrayColor<sup>10+</sup> 472 473isBlackOrWhiteOrGrayColor(color: number): boolean 474 475判断图像是否为黑白灰颜色，返回true或false。 476 477**系统能力：** SystemCapability.Multimedia.Image.Core 478 479**参数：** 480 481| 参数名 | 类型 | 必填 | 说明 | 482| -------- | ----------- | ---- | -------------------------- | 483| color| number | 是 | 需要判断是否黑白灰色的颜色值，取值范围[0x0, 0xFFFFFFFF]。 | 484 485**返回值：** 486 487| 类型 | 说明 | 488| :------------- | :---------------------------------------------- | 489| boolean | 如果此图像为黑白灰颜色，则返回true；否则返回false。 | 490 491**示例：** 492 493```ts 494import image from "@ohos.multimedia.image"; 495import effectKit from "@ohos.effectKit"; 496 497const color = new ArrayBuffer(96); 498let opts: image.InitializationOptions = { 499 editable: true, 500 pixelFormat: 3, 501 size: { 502 height: 4, 503 width: 6 504 } 505} 506image.createPixelMap(color, opts).then((pixelMap) => { 507 effectKit.createColorPicker(pixelMap, (error, colorPicker) => { 508 if (error) { 509 console.error('Failed to create color picker.'); 510 } else { 511 console.info('Succeeded in creating color picker.'); 512 let bJudge = colorPicker.isBlackOrWhiteOrGrayColor(0xFFFFFFFF); 513 console.info('is black or white or gray color[bool](white) =' + bJudge); 514 } 515 }) 516}) 517``` 518 519## Filter 520 521图像效果类，用于将指定的效果添加到输入图像中。在调用Filter的方法前，需要先通过[createEffect](#effectkitcreateeffect)创建一个Filter实例。 522 523### blur 524 525blur(radius: number): Filter 526 527将模糊效果添加到效果链表中，结果返回效果链表的头节点。 528 529**系统能力：** SystemCapability.Multimedia.Image.Core 530 531**参数：** 532 533| 参数名 | 类型 | 必填 | 说明 | 534| ------ | ----------- | ---- | ------------------------------------------------------------ | 535| radius | number | 是 | 模糊半径，单位是像素。模糊效果与所设置的值成正比，值越大效果越明显。 | 536 537**返回值：** 538 539| 类型 | 说明 | 540| :------------- | :---------------------------------------------- | 541| [Filter](#filter) | 返回已添加的图像效果。 | 542 543**示例：** 544 545```ts 546import image from "@ohos.multimedia.image"; 547import effectKit from "@ohos.effectKit"; 548 549const color = new ArrayBuffer(96); 550let opts : image.InitializationOptions = { 551 editable: true, 552 pixelFormat: 3, 553 size: { 554 height: 4, 555 width: 6 556 } 557}; 558image.createPixelMap(color, opts).then((pixelMap) => { 559 let radius = 5; 560 let headFilter = effectKit.createEffect(pixelMap); 561 if (headFilter != null) { 562 headFilter.blur(radius); 563 } 564}) 565``` 566 567 568### brightness 569 570brightness(bright: number): Filter 571 572将高亮效果添加到效果链表中，结果返回效果链表的头节点。 573 574**系统能力：** SystemCapability.Multimedia.Image.Core 575 576**参数：** 577 578| 参数名 | 类型 | 必填 | 说明 | 579| ------ | ----------- | ---- | ------------------------------------------------------------ | 580| bright | number | 是 | 高亮程度，取值范围在0-1之间，取值为0时图像保持不变。 | 581 582**返回值：** 583 584| 类型 | 说明 | 585| :------------- | :---------------------------------------------- | 586| [Filter](#filter) | 返回已添加的图像效果。 | 587 588**示例：** 589 590```ts 591import image from "@ohos.multimedia.image"; 592import effectKit from "@ohos.effectKit"; 593 594const color = new ArrayBuffer(96); 595let opts : image.InitializationOptions = { 596 editable: true, 597 pixelFormat: 3, 598 size: { 599 height: 4, 600 width: 6 601 } 602}; 603image.createPixelMap(color, opts).then((pixelMap) => { 604 let bright = 0.5; 605 let headFilter = effectKit.createEffect(pixelMap); 606 if (headFilter != null) { 607 headFilter.brightness(bright); 608 } 609}) 610``` 611 612 613### grayscale 614 615grayscale(): Filter 616 617将灰度效果添加到效果链表中，结果返回效果链表的头节点。 618 619**系统能力：** SystemCapability.Multimedia.Image.Core 620 621**返回值：** 622 623| 类型 | 说明 | 624| :------------- | :---------------------------------------------- | 625| [Filter](#filter) | 返回已添加的图像效果。 | 626 627**示例：** 628 629```ts 630import image from "@ohos.multimedia.image"; 631import effectKit from "@ohos.effectKit"; 632 633const color = new ArrayBuffer(96); 634let opts : image.InitializationOptions = { 635 editable: true, 636 pixelFormat: 3, 637 size: { 638 height: 4, 639 width: 6 640 } 641}; 642image.createPixelMap(color, opts).then((pixelMap) => { 643 let headFilter = effectKit.createEffect(pixelMap); 644 if (headFilter != null) { 645 headFilter.grayscale(); 646 } 647}) 648``` 649 650 651### getPixelMap 652 653getPixelMap(): [image.PixelMap](js-apis-image.md#pixelmap7) 654 655获取已添加链表效果的源图像的image.PixelMap。 656 657**系统能力：** SystemCapability.Multimedia.Image.Core 658 659**返回值：** 660 661| 类型 | 说明 | 662| :------------- | :---------------------------------------------- | 663| [image.PixelMap](js-apis-image.md#pixelmap7) | 已添加效果的源图像的image.PixelMap。 | 664 665**示例：** 666 667```ts 668import image from "@ohos.multimedia.image"; 669import effectKit from "@ohos.effectKit"; 670 671const color = new ArrayBuffer(96); 672let opts : image.InitializationOptions = { 673 editable: true, 674 pixelFormat: 3, 675 size: { 676 height: 4, 677 width: 6 678 } 679}; 680image.createPixelMap(color, opts).then((pixelMap) => { 681 let pixel = effectKit.createEffect(pixelMap).grayscale().getPixelMap(); 682 console.info('getPixelBytesNumber = ', pixel.getPixelBytesNumber()); 683}) 684``` 685 686
