backend.color

color

函数：

名称	描述
hsv_web2cv	将 HSV 颜色从 Web 格式转换为 OpenCV 格式。
hsv_cv2web	将 HSV 颜色从 OpenCV 格式转换为 Web 格式。
rgb_to_hsv	将 RGB 颜色转换为 HSV 颜色。
hsv_to_rgb	将 HSV 颜色转换为 RGB 颜色。
in_range	判断颜色是否在范围内。
find	在图像中查找指定颜色的点。
color_distance_map	计算图像中每个像素点到目标颜色的HSL距离，并返回归一化后的距离矩阵。
find_all	在图像中查找所有符合指定颜色的点。
dominant_color	提取图像的主色调。

属性：

名称	类型	描述
RgbColor		颜色。三元组 (r, g, b) 或十六进制颜色字符串 #RRGGBB
HsvColor		HSV颜色。三元组 (h, s, v)。

RgbColor module-attribute

RgbColor = RgbColorTuple | RgbColorStr

颜色。三元组 (r, g, b) 或十六进制颜色字符串 #RRGGBB

HsvColor module-attribute

HsvColor = tuple[int, int, int]

HSV颜色。三元组 (h, s, v)。

hsv_web2cv

hsv_web2cv(h: int, s: int, v: int) -> HsvColor

将 HSV 颜色从 Web 格式转换为 OpenCV 格式。

参数：

名称	类型	描述	默认
h	int	色相，范围 [0, 360]	必需
s	int	饱和度，范围 [0, 100]	必需
v	int	亮度，范围 [0, 100]	必需

返回：

类型	描述
HsvColor	OpenCV 格式 HSV 颜色。三元组 (h, s, v)，范围分别为 (0-180, 0-255, 0-255)。

hsv_cv2web

hsv_cv2web(h: int, s: int, v: int) -> HsvColor

将 HSV 颜色从 OpenCV 格式转换为 Web 格式。

参数：

名称	类型	描述	默认
h	int	色相，范围 [0, 180]	必需
s	int	饱和度，范围 [0, 255]	必需
v	int	亮度，范围 [0, 255]	必需

返回：

类型	描述
HsvColor	Web 格式 HSV 颜色。三元组 (h, s, v)，范围分别为 (0-360, 0-100, 0-100)。

rgb_to_hsv

rgb_to_hsv(c: RgbColor) -> HsvColor

将 RGB 颜色转换为 HSV 颜色。

参数：

名称	类型	描述	默认
c	RgbColor	RGB 颜色。十六进制颜色字符串 #RRGGBB 或整数三元组 (r, g, b)。	必需

返回：

类型	描述
HsvColor	Web 格式 HSV 颜色。三元组 (h, s, v)，范围分别为 (0-360, 0-100, 0-100)。

hsv_to_rgb

hsv_to_rgb(c: HsvColor) -> RgbColor

将 HSV 颜色转换为 RGB 颜色。

参数：

名称	类型	描述	默认
c	HsvColor	Web 格式 HSV 颜色。三元组 (h, s, v)，范围分别为 (0-360, 0-100, 0-100)。	必需

返回：

类型	描述
RgbColor	RGB 颜色。整数三元组 (r, g, b)。

in_range

in_range(color: RgbColor, range: tuple[HsvColor, HsvColor]) -> bool

判断颜色是否在范围内。

参数：

名称	类型	描述	默认
color	RgbColor	RGB 颜色。	必需
range	tuple[HsvColor, HsvColor]	Web HSV 颜色范围。	必需

find

find(image: MatLike | str, color: RgbColor, *, rect: Rect | None = None, threshold: float = 0.95, method: Literal['rgb_dist'] = 'rgb_dist') -> tuple[int, int] | None

在图像中查找指定颜色的点。

参数：

名称	类型	描述	默认
image	MatLike | str	图像。可以是 MatLike 或图像文件路径。 注意如果参数为 MatLike，则颜色格式必须为 BGR，而不是 RGB。	必需
color	RgbColor	颜色。可以是整数三元组 (r, g, b) 或十六进制颜色字符串 #RRGGBB。	必需
rect	Rect | None	查找范围。如果为 None，则在整个图像中查找。	None
threshold	float	阈值，越大表示越相似，1 表示完全相似。默认为 0.95。	0.95
method	Literal['rgb_dist']	比较算法。默认为 'rgb_dist'，且目前也只有这个方法。 比较算法 rgb_dist: 计算图片中每个点的颜色到目标颜色的欧氏距离，并以 442 为最大值归一化到 0-1 之间。	'rgb_dist'

color_distance_map

color_distance_map(image: MatLike | str, color: RgbColor, *, rect: RectTuple | None = None) -> np.ndarray

计算图像中每个像素点到目标颜色的HSL距离，并返回归一化后的距离矩阵。

参数：

名称	类型	描述	默认
image	MatLike | str	图像。可以是 MatLike 或图像文件路径。	必需
color	RgbColor	目标颜色。可以是整数三元组 (r, g, b) 或十六进制颜色字符串 #RRGGBB。	必需
rect	RectTuple | None	计算范围。如果为 None，则在整个图像中计算。	None

返回：

类型	描述
ndarray	归一化后的距离矩阵，范围 [0, 1]，0 表示完全匹配，1 表示完全不匹配。

find_all

find_all(image: MatLike | str, color: RgbColor, *, rect: Rect | None = None, threshold: float = 0.95, method: Literal['rgb_dist'] = 'rgb_dist', filter_method: Literal['point', 'contour'] = 'contour', max_results: int | None = None) -> list[FindColorPointResult]

在图像中查找所有符合指定颜色的点。

参数：

名称	类型	描述	默认
image	MatLike | str	图像。可以是 MatLike 或图像文件路径。 注意如果参数为 MatLike，则颜色格式必须为 BGR，而不是 RGB。	必需
color	RgbColor	颜色。可以是整数三元组 (r, g, b) 或十六进制颜色字符串 #RRGGBB。	必需
rect	Rect | None	查找范围。如果为 None，则在整个图像中查找。	None
threshold	float	阈值，越大表示越相似，1 表示完全相似。默认为 0.95。	0.95
method	Literal['rgb_dist']	比较算法。默认为 'rgb_dist'，且目前也只有这个方法。	'rgb_dist'
filter_method	Literal['point', 'contour']	查找方法。 point：按点查找结果 contour：按轮廓查找结果。也就是如果很多个符合要求的点连在一起，会被当做一个整体返回。	'contour'
max_results	int | None	最大返回结果数量。如果为 None，则返回所有结果。	None

返回：

类型	描述
list[FindColorPointResult]	结果列表。

dominant_color

dominant_color(image: MatLike | str, count: int = 1, *, rect: Rect | None = None) -> list[RgbColorStr]

提取图像的主色调。

参数：

名称	类型	描述	默认
image	MatLike | str	图像。可以是 MatLike 或图像文件路径。 如果是 MatLike，则颜色格式必须为 BGR。	必需
count	int	提取的颜色数量。默认为 1。	1
rect	Rect | None	提取范围。如果为 None，则在整个图像中提取。	None