kotonebot 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

kotonebot/backend/core.py

@@ -1,6 +1,5 @@
 import logging
-from functools import cache
-from typing import Callable
+from typing import TYPE_CHECKING, Callable
 from typing_extensions import deprecated
 
 import cv2
@@ -8,7 +7,11 @@ from cv2.typing import MatLike
 
 from kotonebot.util import cv2_imread
 from kotonebot.primitives import RectTuple, Rect, Point
-from kotonebot.errors import ResourceFileMissingError
+if TYPE_CHECKING:
+    from kotonebot.primitives.visual import Image
+else:
+    from kotonebot.primitives.visual import Image as _PrimitivesImage
+    Image = deprecated('Use kotonebot.primitives.Image instead.')(_PrimitivesImage)
 
 @deprecated('unused')
 class Ocr:
@@ -21,52 +24,6 @@ class Ocr:
         self.text = text
         self.language = language
 
-# TODO: 这个类和 kotonebot.primitives.Image 重复了
-@deprecated('Use kotonebot.primitives.Image instead.')
-class Image:
-    def __init__(
-        self,
-        *,
-        path: str | None = None,
-        name: str | None = 'untitled',
-        data: MatLike | None = None,
-    ):
-        self.path = path
-        self.name = name
-        self.__data: MatLike | None = data
-        self.__data_with_alpha: MatLike | None = None
-
-    @cache
-    def binary(self) -> 'Image':
-        return Image(data=cv2.cvtColor(self.data, cv2.COLOR_BGR2GRAY))
-
-    @property
-    def data(self) -> MatLike:
-        if self.__data is None:
-            if self.path is None:
-                raise ValueError('Either path or data must be provided.')
-            self.__data = cv2_imread(self.path)
-            if self.__data is None:
-                raise ResourceFileMissingError(self.path, 'sprite')
-            logger.debug(f'Read image "{self.name}" from {self.path}')
-        return self.__data
-    
-    @property
-    def data_with_alpha(self) -> MatLike:
-        if self.__data_with_alpha is None:
-            if self.path is None:
-                raise ValueError('Either path or data must be provided.')
-            self.__data_with_alpha = cv2_imread(self.path, cv2.IMREAD_UNCHANGED)
-            if self.__data_with_alpha is None:
-                raise ResourceFileMissingError(self.path, 'sprite with alpha')
-            logger.debug(f'Read image "{self.name}" from {self.path}')
-        return self.__data_with_alpha
-    
-    def __repr__(self) -> str:
-        if self.path is None:
-            return f'<Image: memory>'
-        else:
-            return f'<Image: "{self.name}" at {self.path}>'
 
 # TODO: 这里的其他类应该移动到 primitives 模块下面
 class HintBox(Rect):

kotonebot/backend/image.py

@@ -161,11 +161,19 @@ def template_match(
     # 统一参数
     template = unify_image(template, transparent)
     image = unify_image(image)
+    th, tw = template.shape[:2]
+    ih, iw = image.shape[:2]
+    if th > ih or tw > iw:
+        raise ValueError(f"Template size ({tw}x{th}) is larger than image size ({iw}x{ih}).")
     
     # 处理矩形区域
     original_image = image
     if rect is not None:
         x, y, w, h = rect.xywh
+        if h < th or w < tw:
+            raise ValueError(
+                f"rect size ({w}x{h}) is smaller than template size ({tw}x{th})."
+            )
         image = image[y:y+h, x:x+w]
     
     if transparent is True and mask is not None:
@@ -186,12 +194,35 @@ def template_match(
             if mask is not None:
                 mask = preprocessor.process(mask)
     # 匹配模板
-    if mask is not None:
-        # https://stackoverflow.com/questions/35642497/python-opencv-cv2-matchtemplate-with-transparency
-        # 使用 Mask 时，必须使用 TM_CCORR_NORMED 方法
-        result = cv2.matchTemplate(image, template, cv2.TM_CCORR_NORMED, mask=mask)
+    if not colored:
+        # 当 colored=False 时，使用灰度匹配以忽略颜色差异并提高速度
+        # 准备灰度图用于匹配
+        if image.ndim == 3:
+            img_for_match = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        else:
+            img_for_match = image
+
+        if template.ndim == 3:
+            tpl_for_match = cv2.cvtColor(template, cv2.COLOR_BGR2GRAY)
+        else:
+            tpl_for_match = template
+
+        # 如果有 mask，确保为单通道二值掩码
+        if mask is not None:
+            if mask.ndim == 3:
+                mask = cv2.cvtColor(mask, cv2.COLOR_BGR2GRAY)
+            mask = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)[1]
+            # 使用带 mask 的归一化相关性方法
+            result = cv2.matchTemplate(img_for_match, tpl_for_match, cv2.TM_CCORR_NORMED, mask=mask)
+        else:
+            result = cv2.matchTemplate(img_for_match, tpl_for_match, cv2.TM_CCOEFF_NORMED)
     else:
-        result = cv2.matchTemplate(image, template, cv2.TM_CCOEFF_NORMED)
+        if mask is not None:
+        # https://stackoverflow.com/questions/35642497/python-opencv-cv2-matchtemplate-with-transparency
+            # 使用 Mask 时，必须使用 TM_CCORR_NORMED 方法
+            result = cv2.matchTemplate(image, template, cv2.TM_CCORR_NORMED, mask=mask)
+        else:
+            result = cv2.matchTemplate(image, template, cv2.TM_CCOEFF_NORMED)
     
     # ========== 整理结果 ==========
     # 去重、排序、转换为 TemplateMatchResult

kotonebot/backend/loop.py

@@ -1,208 +1,222 @@
-import time
-from functools import lru_cache, partial
-from typing import Callable, Any, overload, Literal, Generic, TypeVar, cast, get_args, get_origin
-from typing_extensions import deprecated
-
-from cv2.typing import MatLike
-
-from kotonebot.util import Interval
-from kotonebot import device, image, ocr
-from kotonebot.backend.core import Image
-from kotonebot.backend.ocr import TextComparator
-from kotonebot.client.protocol import ClickableObjectProtocol
-from .context import vars
-
-@deprecated('No longer used.')
-class LoopAction:
-    def __init__(self, loop: 'Loop', func: Callable[[], ClickableObjectProtocol | None]):
-        self.loop = loop
-        self.func = func
-        self.result: ClickableObjectProtocol | None = None
-
-    @property
-    def found(self):
-        """
-        是否找到结果。若父 Loop 未在运行中，则返回 False。
-        """
-        if not self.loop.running:
-            return False
-        return bool(self.result)
-
-    def __bool__(self):
-        return self.found
-
-    def reset(self):
-        """
-        重置 LoopAction，以复用此对象。
-        """
-        self.result = None
-
-    def do(self):
-        """
-        执行 LoopAction。
-        :return: 执行结果。
-        """
-        if not self.loop.running:
-            return
-        if self.loop.found_anything:
-            # 本轮循环已执行任意操作，因此不需要再继续检测
-            return
-        self.result = self.func()
-        if self.result:
-            self.loop.found_anything = True
-
-    def click(self, *, at: tuple[int, int] | None = None):
-        """
-        点击寻找结果。若结果为空，会跳过执行。
-
-        :return:
-        """
-        if self.result:
-            if at is not None:
-                device.click(*at)
-            else:
-                device.click(self.result)
-
-    def call(self, func: Callable[[ClickableObjectProtocol], Any]):
-        pass
-
-
-class Loop:
-    def __init__(
-            self,
-            *,
-            timeout: float = 300,
-            interval: float = 0.3,
-            auto_screenshot: bool = True,
-            skip_first_wait: bool = True
-    ):
-        self.running = True
-        self.found_anything = False
-        self.auto_screenshot = auto_screenshot
-        """
-        是否在每次循环开始时（Loop.tick() 被调用时）截图。
-        """
-        self.__last_loop: float = -1
-        self.interval = interval
-        """每次循环后等待的时间。"""
-        self.screenshot: MatLike | None = None
-        """上次截图时的图像数据。"""
-        self.__skip_first_wait = skip_first_wait
-        self.__is_first_tick = True
-
-    def __iter__(self):
-        self.__is_first_tick = True
-        vars.flow.check()
-        return self
-
-    def __next__(self):
-        if not self.running:
-            raise StopIteration
-        self.found_anything = False
-        self.__last_loop = time.time()
-        return self.tick()
-
-    def tick(self):
-        if not (self.__is_first_tick and self.__skip_first_wait):
-            time.sleep(self.interval)
-        self.__is_first_tick = False
-
-        if self.auto_screenshot:
-            self.screenshot = device.screenshot()
-        self.__last_loop = time.time()
-        self.found_anything = False
-        return self
-
-    def exit(self):
-        """
-        结束循环。
-        """
-        self.running = False
-
-    @overload
-    @deprecated('Use plain if statement instead.')
-    def when(self, condition: Image) -> LoopAction:
-        ...
-
-    @overload
-    @deprecated('Use plain if statement instead.')
-    def when(self, condition: TextComparator) -> LoopAction:
-        ...
-
-    @deprecated('Use plain if statement instead.')
-    def when(self, condition: Any):
-        """
-        判断某个条件是否成立。
-
-        :param condition:
-        :return:
-        """
-        if isinstance(condition, Image):
-            func = partial(image.find, condition)
-        elif isinstance(condition, TextComparator):
-            func = partial(ocr.find, condition)
-        else:
-            raise ValueError('Invalid condition type.')
-        la = LoopAction(self, func)
-        la.reset()
-        la.do()
-        return la
-
-    @deprecated('Use plain if statement instead.')
-    def until(self, condition: Any):
-        """
-        当满足指定条件时，结束循环。
-
-        等价于 ``loop.when(...).call(lambda _: loop.exit())``
-        """
-        return self.when(condition).call(lambda _: self.exit())
-
-    @deprecated('Use image.find() and device.click() instead.')
-    def click_if(self, condition: Any, *, at: tuple[int, int] | None = None):
-        """
-        检测指定对象是否出现，若出现，点击该对象或指定位置。
-
-        ``click_if()`` 等价于 ``loop.when(...).click(...)``。
-
-        :param condition: 检测目标。
-        :param at: 点击位置。若为 None，表示点击找到的目标。
-        """
-        return self.when(condition).click(at=at)
-
-StateType = TypeVar('StateType')
-class StatedLoop(Loop, Generic[StateType]):
-    def __init__(
-        self,
-        states: list[Any] | None = None,
-        initial_state: StateType | None = None,
-        *,
-        timeout: float = 300,
-        interval: float = 0.3,
-        auto_screenshot: bool = True
-    ):
-        self.__tmp_states = states
-        self.__tmp_initial_state = initial_state
-        self.state: StateType
-        super().__init__(timeout=timeout, interval=interval, auto_screenshot=auto_screenshot)
-
-    def __iter__(self):
-        # __retrive_state_values() 只能在非 __init__ 中调用
-        self.__retrive_state_values()
-        return super().__iter__()
-
-    def __retrive_state_values(self):
-        # HACK: __orig_class__ 是 undocumented 属性
-        if not hasattr(self, '__orig_class__'):
-            # 如果 Foo 不是以参数化泛型的方式实例化的，可能没有 __orig_class__
-            if self.state is None:
-                raise ValueError('Either specify `states` or use StatedLoop[Literal[...]] syntax.')
-        else:
-            generic_type_args = get_args(self.__orig_class__) # type: ignore
-            if len(generic_type_args) != 1:
-                raise ValueError('StatedLoop must have exactly one generic type argument.')
-            state_values = get_args(generic_type_args[0])
-            if not state_values:
-                raise ValueError('StatedLoop must have at least one state value.')
-            self.states = cast(tuple[StateType, ...], state_values)
-            self.state = self.__tmp_initial_state or self.states[0]
-            return state_values
+import time
+from functools import lru_cache, partial
+from typing import Callable, Any, overload, Literal, Generic, TypeVar, cast, get_args, get_origin
+from typing_extensions import deprecated
+
+from cv2.typing import MatLike
+
+from kotonebot.config.config import conf
+from kotonebot.util import Interval
+from kotonebot import device, image, ocr
+from kotonebot.backend.core import Image
+from kotonebot.backend.ocr import TextComparator
+from kotonebot.client.protocol import ClickableObjectProtocol
+from .context import vars
+
+@deprecated('No longer used.')
+class LoopAction:
+    def __init__(self, loop: 'Loop', func: Callable[[], ClickableObjectProtocol | None]):
+        self.loop = loop
+        self.func = func
+        self.result: ClickableObjectProtocol | None = None
+
+    @property
+    def found(self):
+        """
+        是否找到结果。若父 Loop 未在运行中，则返回 False。
+        """
+        if not self.loop.running:
+            return False
+        return bool(self.result)
+
+    def __bool__(self):
+        return self.found
+
+    def reset(self):
+        """
+        重置 LoopAction，以复用此对象。
+        """
+        self.result = None
+
+    def do(self):
+        """
+        执行 LoopAction。
+        :return: 执行结果。
+        """
+        if not self.loop.running:
+            return
+        if self.loop.found_anything:
+            # 本轮循环已执行任意操作，因此不需要再继续检测
+            return
+        self.result = self.func()
+        if self.result:
+            self.loop.found_anything = True
+
+    def click(self, *, at: tuple[int, int] | None = None):
+        """
+        点击寻找结果。若结果为空，会跳过执行。
+
+        :return:
+        """
+        if self.result:
+            if at is not None:
+                device.click(*at)
+            else:
+                device.click(self.result)
+
+    def call(self, func: Callable[[ClickableObjectProtocol], Any]):
+        pass
+
+
+class Loop:
+    def __init__(
+            self,
+            *,
+            timeout: float = 300,
+            interval: float = 0.3,
+            auto_screenshot: bool = True,
+            skip_first_wait: bool = True
+    ):
+        self.running = True
+        self.found_anything = False
+        self.auto_screenshot = auto_screenshot
+        """
+        是否在每次循环开始时（Loop.tick() 被调用时）截图。
+        """
+        self.__last_loop: float = -1
+        self.interval = interval
+        """每次循环后等待的时间。"""
+        self.screenshot: MatLike | None = None
+        """上次截图时的图像数据。"""
+        self.__skip_first_wait = skip_first_wait
+        self.__is_first_tick = True
+
+    def __iter__(self):
+        self.__is_first_tick = True
+        vars.flow.check()
+        return self
+
+    def __next__(self):
+        if not self.running:
+            raise StopIteration
+        self.found_anything = False
+        self.__last_loop = time.time()
+        return self.tick()
+
+    def tick(self):
+        if not (self.__is_first_tick and self.__skip_first_wait):
+            time.sleep(self.interval)
+        self.__is_first_tick = False
+
+        if self.auto_screenshot:
+            self.screenshot = device.screenshot()
+        self.__last_loop = time.time()
+        self.found_anything = False
+        # 执行全局回调
+        callbacks = conf().loop.loop_callbacks
+        while True:
+            did = False
+            for cb in callbacks:
+                did = cb(self)
+                if did:
+                    time.sleep(self.interval)
+                    self.screenshot = device.screenshot()
+                    break
+            if not did:
+                break
+
+        return self
+
+    def exit(self):
+        """
+        结束循环。
+        """
+        self.running = False
+
+    @overload
+    @deprecated('Use plain if statement instead.')
+    def when(self, condition: Image) -> LoopAction:
+        ...
+
+    @overload
+    @deprecated('Use plain if statement instead.')
+    def when(self, condition: TextComparator) -> LoopAction:
+        ...
+
+    @deprecated('Use plain if statement instead.')
+    def when(self, condition: Any):
+        """
+        判断某个条件是否成立。
+
+        :param condition:
+        :return:
+        """
+        if isinstance(condition, Image):
+            func = partial(image.find, condition)
+        elif isinstance(condition, TextComparator):
+            func = partial(ocr.find, condition)
+        else:
+            raise ValueError('Invalid condition type.')
+        la = LoopAction(self, func)
+        la.reset()
+        la.do()
+        return la
+
+    @deprecated('Use plain if statement instead.')
+    def until(self, condition: Any):
+        """
+        当满足指定条件时，结束循环。
+
+        等价于 ``loop.when(...).call(lambda _: loop.exit())``
+        """
+        return self.when(condition).call(lambda _: self.exit())
+
+    @deprecated('Use image.find() and device.click() instead.')
+    def click_if(self, condition: Any, *, at: tuple[int, int] | None = None):
+        """
+        检测指定对象是否出现，若出现，点击该对象或指定位置。
+
+        ``click_if()`` 等价于 ``loop.when(...).click(...)``。
+
+        :param condition: 检测目标。
+        :param at: 点击位置。若为 None，表示点击找到的目标。
+        """
+        return self.when(condition).click(at=at)
+
+StateType = TypeVar('StateType')
+class StatedLoop(Loop, Generic[StateType]):
+    def __init__(
+        self,
+        states: list[Any] | None = None,
+        initial_state: StateType | None = None,
+        *,
+        timeout: float = 300,
+        interval: float = 0.3,
+        auto_screenshot: bool = True
+    ):
+        self.__tmp_states = states
+        self.__tmp_initial_state = initial_state
+        self.state: StateType
+        super().__init__(timeout=timeout, interval=interval, auto_screenshot=auto_screenshot)
+
+    def __iter__(self):
+        # __retrive_state_values() 只能在非 __init__ 中调用
+        self.__retrive_state_values()
+        return super().__iter__()
+
+    def __retrive_state_values(self):
+        # HACK: __orig_class__ 是 undocumented 属性
+        if not hasattr(self, '__orig_class__'):
+            # 如果 Foo 不是以参数化泛型的方式实例化的，可能没有 __orig_class__
+            if self.state is None:
+                raise ValueError('Either specify `states` or use StatedLoop[Literal[...]] syntax.')
+        else:
+            generic_type_args = get_args(self.__orig_class__) # type: ignore
+            if len(generic_type_args) != 1:
+                raise ValueError('StatedLoop must have exactly one generic type argument.')
+            state_values = get_args(generic_type_args[0])
+            if not state_values:
+                raise ValueError('StatedLoop must have at least one state value.')
+            self.states = cast(tuple[StateType, ...], state_values)
+            self.state = self.__tmp_initial_state or self.states[0]
+            return state_values

kotonebot/backend/ocr.py

@@ -36,9 +36,15 @@ def sanitize_text(text: str) -> str:
     """
     对识别结果进行清理。此函数将被所有 OCR 引擎调用。
     
-    默认使用 `global_character_mapping` 中的映射数据进行清理。
+    默认行为为先将文本 `Unicode 规范化`_，然后使用 `global_character_mapping` 中的映射数据进行清理。
     可以重写此函数以实现自定义的清理逻辑。
+
+    .. note::
+        Unicode 规范化最常见的一个行为是将全角字符转换为半角字符。
+
+    .. _Unicode 规范化: https://docs.python.org/zh-cn/3.14/library/unicodedata.html#unicodedata.normalize
     """
+    text = unicodedata.normalize('NFKC', text)
     for k, v in global_character_mapping.items():
         text = text.replace(k, v)
     return text