@ohos.effectKit (图像效果)(系统接口)

图像效果模块提供了处理图像的基础能力，包括亮度调节、模糊化、灰度调节和智能取色等。effectKit用于离线处理图像（如pixelmap、png、jpeg）以获得视觉效果，而uiEffect则实时接入渲染服务，针对屏幕帧缓存进行处理以获得动态视觉效果。

该模块提供以下图像效果相关的常用功能：

• ColorPicker：智能取色器。

说明：

• 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
• 页面仅包含本模块的系统接口，其他公开接口参见ohos.effectKit (图像效果)。

导入模块

import { effectKit } from "@kit.ArkGraphics2D";

PictureComplexityDegree²²⁺

图片内容复杂度的枚举。

系统能力： SystemCapability.Multimedia.Image.Core

系统接口： 此接口为系统接口。

名称	值	说明
UNKNOWN_COMPLEXITY_DEGREE_PICTURE	0	默认值，图片内容复杂度未知。
PURE_PICTURE	1	图片内容复杂度为纯净。
MODERATE_COMPLEXITY_PICTURE	2	图片内容复杂度为一般。
VERY_FLOWERY_PICTURE	3	图片内容复杂度为复杂。

PictureShadeDegree²²⁺

图片颜色深浅度的枚举。

系统能力： SystemCapability.Multimedia.Image.Core

系统接口： 此接口为系统接口。

名称	值	说明
UNKNOWN_SHADE_DEGREE_PICTURE	0	默认值，图片颜色深浅度未知。
EXTREMELY_LIGHT_PICTURE	1	图片颜色深浅度为极浅。
VERY_LIGHT_PICTURE	2	图片颜色深浅度为较浅。
LIGHT_PICTURE	3	图片颜色深浅度为略浅。
MODERATE_SHADE_PICTURE	4	图片颜色深浅度为一般。
DARK_PICTURE	5	图片颜色深浅度为较深。
EXTREMELY_DARK_PICTURE	6	图片颜色深浅度为极深。

ColorPicker

取色类，用于从一张图像数据中获取它的主要颜色。在调用ColorPicker的方法前，需要先通过createColorPicker创建一个ColorPicker实例。

getTopProportionColorsAndPercentage²²⁺

getTopProportionColorsAndPercentage(colorCount: number): Map<Color | null, number | null>

读取图像占比靠前的颜色值以及对应比例，个数由colorCount指定，结果写入Color与其对应比例的字典中，使用同步方式返回。

卡片能力： 从API version 22开始，该接口支持在ArkTS卡片中使用。

系统能力： SystemCapability.Multimedia.Image.Core

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
colorCount	number	是	需要取主色的个数，取值范围为[1, 10]，向下取整。

返回值：

类型	说明
Map<Color | null, number | null>	图像占比前colorCount的颜色值与对应比例的字典，比例的取值范围为(0,1]。 - 当实际读取的特征色个数小于colorCount时，字典大小为实际特征色个数。 - 取色失败或取色个数小于1返回Map()。 - 取色个数大于10视为取前10个。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { image } from "@kit.ImageKit";
import { effectKit } from "@kit.ArkGraphics2D";

const color = new ArrayBuffer(96);
let opts: image.InitializationOptions = {
  editable: true,
  pixelFormat: 3,
  size: {
    height: 4,
    width: 6
  }
}
image.createPixelMap(color, opts).then((pixelMap) => {
  effectKit.createColorPicker(pixelMap, (error, colorPicker) => {
    if (error) {
      console.error('Failed to create color picker.');
    } else {
      console.info('Succeeded in creating color picker.');
      let colors: Map<effectKit.Color | null, number | null> = colorPicker.getTopProportionColorsAndPercentage(2);
      colors.forEach((value: number | null, key: effectKit.Color | null) => {
        console.info('get top proportion colors and percentages: color ' + key + ', percentage ' + value);
      })
    }
  })
})

getShadeDegree²²⁺

getShadeDegree(): PictureShadeDegree

获取图像颜色深浅度。

卡片能力： 从API version 22开始，该接口支持在ArkTS卡片中使用。

系统能力： SystemCapability.Multimedia.Image.Core

系统接口： 此接口为系统接口。

返回值：

类型	说明
PictureShadeDegree	图像颜色深浅度。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { image } from "@kit.ImageKit";
import { effectKit } from "@kit.ArkGraphics2D";

const color = new ArrayBuffer(96);
let opts: image.InitializationOptions = {
  editable: true,
  pixelFormat: 3,
  size: {
    height: 4,
    width: 6
  }
}
image.createPixelMap(color, opts).then((pixelMap) => {
  effectKit.createColorPicker(pixelMap, (error, colorPicker) => {
    if (error) {
      console.error('Failed to create color picker.');
    } else {
      console.info('Succeeded in creating color picker.');
      let shadeDegree: effectKit.PictureShadeDegree = colorPicker.getShadeDegree();
      console.info('The shade degree of the image is ' + shadeDegree);
    }
  })
})

getComplexityDegree²²⁺

getComplexityDegree(): PictureComplexityDegree

获取图像内容复杂度。

卡片能力： 从API version 22开始，该接口支持在ArkTS卡片中使用。

系统能力： SystemCapability.Multimedia.Image.Core

系统接口： 此接口为系统接口。

返回值：

类型	说明
PictureComplexityDegree	图像内容复杂度。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { image } from "@kit.ImageKit";
import { effectKit } from "@kit.ArkGraphics2D";

const color = new ArrayBuffer(96);
let opts: image.InitializationOptions = {
  editable: true,
  pixelFormat: 3,
  size: {
    height: 4,
    width: 6
  }
}
image.createPixelMap(color, opts).then((pixelMap) => {
  effectKit.createColorPicker(pixelMap, (error, colorPicker) => {
    if (error) {
      console.error('Failed to create color picker.');
    } else {
      console.info('Succeeded in creating color picker.');
      let complexityDegree: effectKit.PictureComplexityDegree = colorPicker.getComplexityDegree();
      console.info('The complexity degree of the image is ' + complexityDegree);
    }
  })
})

getAlphaZeroTransparentProportion²³⁺

getAlphaZeroTransparentProportion(): number

获取图像中完全透明的像素占比。

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

系统能力： SystemCapability.Multimedia.Image.Core

系统接口： 此接口为系统接口。

返回值：

类型	说明
number	完全透明的像素占比，比例的取值范围为(0,1]。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { image } from "@kit.ImageKit";
import { effectKit } from "@kit.ArkGraphics2D";

const color = new ArrayBuffer(96);
let opts: image.InitializationOptions = {
  editable: true,
  pixelFormat: 3,
  size: {
    height: 4,
    width: 6
  }
}
image.createPixelMap(color, opts).then((pixelMap) => {
  effectKit.createColorPicker(pixelMap, (error, colorPicker) => {
    if (error) {
      console.error('Failed to create color picker.');
    } else {
      console.info('Succeeded in creating color picker.');
        let percentage: number = colorPicker.getAlphaZeroTransparentProportion();
      console.info('Get proportion of fully transparent pixels: ' + percentage);
    }
  })
})