util

util

类：

名称	描述
AdaptiveWait	自适应延时。延迟时间会随着时间逐渐增加，直到达到最大延迟时间。
Throttler	限流器，在循环中用于限制某操作的频率。
Profiler	性能分析器。对 cProfile 的简单封装。

函数：

名称	描述
is_windows	检查当前是否为 Windows 系统
is_linux	检查当前是否为 Linux 系统
is_macos	检查当前是否为 macOS 系统
require_windows	要求必须在 Windows 系统上运行，否则抛出 NotImplementedError
windows_only	装饰器：在 Windows 以外平台调用时抛出 NotImplementedError。
crop	按比例裁剪图像。
cropped	Hook 设备截图与点击操作，将截图裁剪为指定区域，并调整点击坐标。
until	等待条件成立，如果条件不成立，则返回 False 或抛出异常。
measure_time	测量函数执行时间的装饰器
cv2_imread	对 cv2.imread 的简单封装。
cv2_imwrite	对 cv2.imwrite 的简单封装。

AdaptiveWait

自适应延时。延迟时间会随着时间逐渐增加，直到达到最大延迟时间。

Throttler

限流器，在循环中用于限制某操作的频率。

示例代码：

while True:
    device.screenshot()
    if throttler.request() and image.find(...):
        do_something()

方法：

名称	描述
request	检查是否允许请求。此函数立即返回，不会阻塞。

request

request() -> bool

检查是否允许请求。此函数立即返回，不会阻塞。

返回：

类型	描述
bool	如果允许，返回 True，否则返回 False

Profiler

性能分析器。对 cProfile 的简单封装。

使用方法：

with Profiler('profile.prof'):
    # ...

# 或者
profiler = Profiler('profile.prof')
profiler.begin()
# ...
profiler.end()

is_windows

is_windows() -> bool

检查当前是否为 Windows 系统

is_linux

is_linux() -> bool

检查当前是否为 Linux 系统

is_macos

is_macos() -> bool

检查当前是否为 macOS 系统

require_windows

require_windows(feature_name: str | None = None, class_: type | None = None) -> None

要求必须在 Windows 系统上运行，否则抛出 NotImplementedError

windows_only

windows_only(feature_name: str | None = None)

装饰器：在 Windows 以外平台调用时抛出 NotImplementedError。 适用于函数和类。对于类，会装饰其 init 方法，确保实例化时检查平台。

crop

crop(img: MatLike, /, x1: float = 0, y1: float = 0, x2: float = 1, y2: float = 1) -> MatLike

按比例裁剪图像。

参数：

名称	类型	描述	默认
img	MatLike	图像	必需
x1	float	裁剪区域左上角相对X坐标。范围 [0, 1]，默认为 0	0
y1	float	裁剪区域左上角相对Y坐标。范围 [0, 1]，默认为 0	0
x2	float	裁剪区域右下角相对X坐标。范围 [0, 1]，默认为 1	1
y2	float	裁剪区域右下角相对Y坐标。范围 [0, 1]，默认为 1	1

cropped

cropped(device: Device, x1: float = 0, y1: float = 0, x2: float = 1, y2: float = 1) -> DeviceHookContextManager

Hook 设备截图与点击操作，将截图裁剪为指定区域，并调整点击坐标。

在进行 OCR 识别或模板匹配时，可以先使用此函数缩小图像，加快速度。

参数：

名称	类型	描述	默认
device	Device	设备对象	必需
x1	float	裁剪区域左上角相对X坐标。范围 [0, 1]，默认为 0	0
y1	float	裁剪区域左上角相对Y坐标。范围 [0, 1]，默认为 0	0
x2	float	裁剪区域右下角相对X坐标。范围 [0, 1]，默认为 1	1
y2	float	裁剪区域右下角相对Y坐标。范围 [0, 1]，默认为 1	1

until

until(condition: Callable[[], bool], timeout: float = 60, interval: float = 0.5, critical: bool = False) -> bool

等待条件成立，如果条件不成立，则返回 False 或抛出异常。

参数：

名称	类型	描述	默认
condition	Callable[[], bool]	条件函数。	必需
timeout	float	等待时间，单位为秒。	60
interval	float	检查条件的时间间隔，单位为秒。	0.5
critical	bool	如果条件不成立，是否抛出异常。	False

measure_time

measure_time(logger: Logger | None = None, level: Literal['debug', 'info', 'warning', 'error', 'critical'] = 'info', file_path: str | None = None) -> Callable

测量函数执行时间的装饰器

参数：

名称	类型	描述	默认
logger	Logger | None	logging.Logger实例，如果为None则使用root logger	None
level	Literal['debug', 'info', 'warning', 'error', 'critical']	日志级别，可以是'debug', 'info', 'warning', 'error', 'critical'	'info'
file_path	str | None	记录执行时间的文件路径，如果提供则会将结果追加到文件中	None

cv2_imread

cv2_imread(path: str, flags: int = cv2.IMREAD_COLOR) -> MatLike

对 cv2.imread 的简单封装。 支持了对带中文的路径的读取。

参数：

名称	类型	描述	默认
path	str	图片路径	必需
flags	int	cv2.imread 的 flags 参数	IMREAD_COLOR

返回：

类型	描述
MatLike	OpenCV 图片

cv2_imwrite

cv2_imwrite(path: str, img: MatLike)

对 cv2.imwrite 的简单封装。 支持了对带中文的路径的写入。