backend.image

image

类：

名称	描述
TemplateNoMatchError	模板未找到异常。
ResultProtocol
TemplateMatchResult
MultipleTemplateMatchResult

函数：

名称	描述
template_match	寻找模板在图像中的位置。
hist_match	对输入图像的矩形部分与模板进行颜色直方图匹配。
find_all_crop	指定一个模板，在输入图像中寻找其出现的所有位置，并裁剪出结果。
find	指定一个模板，在输入图像中寻找其出现的第一个位置。
find_all	指定一个模板，在输入图像中寻找其出现的所有位置。
find_multi	指定多个模板，在输入图像中逐个寻找模板，返回第一个匹配到的结果。
find_all_multi	指定多个模板，在输入图像中逐个寻找模板，返回所有匹配到的结果。
count	指定一个模板，统计其出现的次数。
expect	指定一个模板，寻找其出现的第一个位置。若未找到，则抛出异常。

TemplateNoMatchError

Bases: Exception

模板未找到异常。

ResultProtocol

Bases: Protocol

属性：

名称	类型	描述
rect	Rect	结果区域。左上角坐标和宽高。

rect property

rect: Rect

结果区域。左上角坐标和宽高。

TemplateMatchResult

Bases: NamedTuple

属性：

名称	类型	描述
position	Point	结果位置。左上角坐标。
size	Size	输入模板的大小。宽高。
rect	Rect	结果区域。
right_bottom	Point	结果右下角坐标。

position instance-attribute

position: Point

结果位置。左上角坐标。

size instance-attribute

size: Size

输入模板的大小。宽高。

rect property

rect: Rect

结果区域。

right_bottom property

right_bottom: Point

结果右下角坐标。

MultipleTemplateMatchResult

Bases: NamedTuple

属性：

名称	类型	描述
position	Point	结果位置。左上角坐标。
size	Size	命中模板的大小。宽高。
index	int	命中模板在列表中的索引。
rect	Rect	结果区域。左上角坐标和宽高。
right_bottom	Point	结果右下角坐标。

position instance-attribute

position: Point

结果位置。左上角坐标。

size instance-attribute

size: Size

命中模板的大小。宽高。

index instance-attribute

index: int

命中模板在列表中的索引。

rect property

rect: Rect

结果区域。左上角坐标和宽高。

right_bottom property

right_bottom: Point

结果右下角坐标。

template_match

template_match(template: MatLike | str | Image, image: MatLike | str | Image, mask: MatLike | str | Image | None = None, *, rect: Rect | None = None, transparent: bool = False, threshold: float = 0.8, max_results: int = 5, remove_duplicate: bool = True, colored: bool = False, preprocessors: list[PreprocessorProtocol] | None = None) -> list[TemplateMatchResult]

寻找模板在图像中的位置。

.. note:: mask 和 transparent 参数不能同时使用。 如果使用透明图像，所有透明像素必须为 100% 透明，不能包含半透明像素。

参数：

名称	类型	描述	默认
template	MatLike | str | Image	模板图像，可以是图像路径或 cv2.Mat。	必需
image	MatLike | str | Image	图像，可以是图像路径或 cv2.Mat。	必需
mask	MatLike | str | Image | None	掩码图像，可以是图像路径或 cv2.Mat。	None
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
max_results	int	最大结果数，默认为 1。	5
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
colored	bool	是否匹配颜色，默认为 False。	False
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None

hist_match

hist_match(image: MatLike | str, template: MatLike | str, rect: Rect | None = None, threshold: float = 0.9) -> bool

对输入图像的矩形部分与模板进行颜色直方图匹配。 将图像分为上中下三个区域，分别计算直方图并比较相似度。

https://answers.opencv.org/question/59027/template-matching-using-color/

参数：

名称	类型	描述	默认
image	MatLike | str	输入图像	必需
template	MatLike | str	模板图像	必需
rect	Rect | None	输入图像中待匹配的矩形区域	None
threshold	float	相似度阈值，默认为 0.8	0.9

返回：

类型	描述
bool	是否匹配成功

find_all_crop

find_all_crop(image: MatLike | str | Image, template: MatLike | str | Image, mask: MatLike | str | Image | None = None, transparent: bool = False, threshold: float = 0.8, *, rect: Rect | None = None, colored: bool = False, remove_duplicate: bool = True, preprocessors: list[PreprocessorProtocol] | None = None) -> list[CropResult]

指定一个模板，在输入图像中寻找其出现的所有位置，并裁剪出结果。

参数：

名称	类型	描述	默认
image	MatLike | str | Image	图像，可以是图像路径或 cv2.Mat。	必需
template	MatLike | str | Image	模板图像，可以是图像路径或 cv2.Mat。	必需
mask	MatLike | str | Image | None	掩码图像，可以是图像路径或 cv2.Mat。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
colored	bool	是否匹配颜色，默认为 False。	False
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None

find

find(image: MatLike, template: MatLike | str | Image, mask: MatLike | str | Image | None = None, *, rect: Rect | None = None, transparent: bool = False, threshold: float = 0.8, debug_output: bool = True, colored: bool = False, remove_duplicate: bool = True, preprocessors: list[PreprocessorProtocol] | None = None) -> TemplateMatchResult | None

指定一个模板，在输入图像中寻找其出现的第一个位置。

参数：

名称	类型	描述	默认
image	MatLike	图像，可以是图像路径或 cv2.Mat。	必需
template	MatLike | str | Image	模板图像，可以是图像路径或 cv2.Mat。	必需
mask	MatLike | str | Image | None	掩码图像，可以是图像路径或 cv2.Mat。	None
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
debug_output	bool	是否输出调试信息，默认为 True。	True
colored	bool	是否匹配颜色，默认为 False。	False
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None

find_all

find_all(image: MatLike, template: MatLike | str | Image, mask: MatLike | str | Image | None = None, *, rect: Rect | None = None, transparent: bool = False, threshold: float = 0.8, remove_duplicate: bool = True, colored: bool = False, debug_output: bool = True, preprocessors: list[PreprocessorProtocol] | None = None) -> list[TemplateMatchResult]

指定一个模板，在输入图像中寻找其出现的所有位置。

参数：

名称	类型	描述	默认
image	MatLike	图像，可以是图像路径或 cv2.Mat。	必需
template	MatLike | str | Image	模板图像，可以是图像路径或 cv2.Mat。	必需
mask	MatLike | str | Image | None	掩码图像，可以是图像路径或 cv2.Mat。	None
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
colored	bool	是否匹配颜色，默认为 False。	False
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None

find_multi

find_multi(image: MatLike, templates: Sequence[MatLike | str | Image], masks: Sequence[MatLike | str | Image | None] | None = None, *, rect: Rect | None = None, transparent: bool = False, threshold: float = 0.8, colored: bool = False, remove_duplicate: bool = True, preprocessors: list[PreprocessorProtocol] | None = None) -> MultipleTemplateMatchResult | None

指定多个模板，在输入图像中逐个寻找模板，返回第一个匹配到的结果。

参数：

名称	类型	描述	默认
image	MatLike	图像，可以是图像路径或 cv2.Mat。	必需
templates	Sequence[MatLike | str | Image]	模板图像列表，可以是图像路径或 cv2.Mat。	必需
masks	Sequence[MatLike | str | Image | None] | None	掩码图像列表，可以是图像路径或 cv2.Mat。	None
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
colored	bool	是否匹配颜色，默认为 False。	False
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None

find_all_multi

find_all_multi(image: MatLike, templates: list[MatLike | str | Image], masks: list[MatLike | str | Image | None] | None = None, *, rect: Rect | None = None, transparent: bool = False, threshold: float = 0.8, colored: bool = False, remove_duplicate: bool = True, preprocessors: list[PreprocessorProtocol] | None = None) -> list[MultipleTemplateMatchResult]

指定多个模板，在输入图像中逐个寻找模板，返回所有匹配到的结果。

此函数等价于

result = []
for template in templates:
    result.append(find_all(template, ...))

参数：

名称	类型	描述	默认
image	MatLike	图像，可以是图像路径或 cv2.Mat。	必需
templates	list[MatLike | str | Image]	模板图像列表，可以是图像路径或 cv2.Mat。	必需
masks	list[MatLike | str | Image | None] | None	掩码图像列表，可以是图像路径或 cv2.Mat。	None
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
colored	bool	是否匹配颜色，默认为 False。	False
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None

返回：

类型	描述
list[MultipleTemplateMatchResult]	匹配到的一维结果列表。

count

count(image: MatLike, template: MatLike | str | Image, mask: MatLike | str | Image | None = None, *, rect: Rect | None = None, transparent: bool = False, threshold: float = 0.8, remove_duplicate: bool = True, colored: bool = False, preprocessors: list[PreprocessorProtocol] | None = None) -> int

指定一个模板，统计其出现的次数。

参数：

名称	类型	描述	默认
image	MatLike	图像，可以是图像路径或 cv2.Mat。	必需
template	MatLike | str | Image	模板图像，可以是图像路径或 cv2.Mat。	必需
mask	MatLike | str | Image | None	掩码图像，可以是图像路径或 cv2.Mat。	None
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
colored	bool	是否匹配颜色，默认为 False。	False
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None

expect

expect(image: MatLike, template: MatLike | str | Image, mask: MatLike | str | Image | None = None, *, rect: Rect | None = None, transparent: bool = False, threshold: float = 0.8, colored: bool = False, remove_duplicate: bool = True, preprocessors: list[PreprocessorProtocol] | None = None) -> TemplateMatchResult

指定一个模板，寻找其出现的第一个位置。若未找到，则抛出异常。

参数：

名称	类型	描述	默认
image	MatLike	图像，可以是图像路径或 cv2.Mat。	必需
template	MatLike | str | Image	模板图像，可以是图像路径或 cv2.Mat。	必需
mask	MatLike | str | Image | None	掩码图像，可以是图像路径或 cv2.Mat。	None
rect	Rect | None	如果指定，则只在指定矩形区域内进行匹配。	None
transparent	bool	若为 True，则认为输入模板是透明的，并自动将透明模板转换为 Mask 图像。	False
threshold	float	阈值，默认为 0.8。	0.8
colored	bool	是否匹配颜色，默认为 False。	False
remove_duplicate	bool	是否移除重复结果，默认为 True。	True
preprocessors	list[PreprocessorProtocol] | None	预处理列表，默认为 None。	None