screenshot-vision-algorithm 0.3.0__py3-none-any.whl

screenshot_vision_algorithm/android/wechat/ocr/avatar_guard.py

@@ -0,0 +1,434 @@
+"""昵称行左侧「头像栏」影像守门：标准 ROI + 可选 Hough 头像锚点对齐 ROI。
+
+纹理（Laplacian + RGB）与列边缘形状须 **同时** 满足（布尔过滤，非算分）。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+Side = Literal["left", "right"]
+
+import numpy as np
+from loguru import logger
+
+try:
+    import cv2
+except ImportError:
+    cv2 = None  # type: ignore[assignment]
+
+try:
+    from processor.left_avatar_column import AvatarCentroid
+except ImportError:
+    AvatarCentroid = None  # type: ignore[misc, assignment]
+
+
+def bgr_roi_laplacian_variance(roi: np.ndarray) -> float:
+    if cv2 is None or roi.size == 0 or roi.shape[0] < 6 or roi.shape[1] < 6:
+        return 0.0
+    try:
+        roi = np.ascontiguousarray(roi, dtype=np.uint8)
+        gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+        blur = cv2.GaussianBlur(gray, (3, 3), 0)
+        return float(cv2.Laplacian(blur, cv2.CV_64F).var())
+    except Exception:
+        return 0.0
+
+
+def bgr_roi_color_std_mean(roi: np.ndarray) -> float:
+    flat = roi.reshape(-1, 3).astype(np.float32)
+    if flat.size == 0:
+        return 0.0
+    return float(np.std(flat, axis=0).mean())
+
+
+def bgr_roi_edge_shape_ok(
+    roi: np.ndarray,
+    *,
+    sig_cols_min: float = 15.0,
+    right_left_ratio_min: float = 1.2,
+) -> bool:
+    if cv2 is None or roi.size == 0 or roi.shape[0] < 6 or roi.shape[1] < 6:
+        return False
+    try:
+        roi = np.ascontiguousarray(roi, dtype=np.uint8)
+        gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+        sobelx = cv2.Sobel(gray.astype(np.float32), cv2.CV_64F, 1, 0, ksize=3)
+    except Exception:
+        return False
+    col_edge = np.mean(np.abs(sobelx), axis=0)
+    if col_edge.size == 0:
+        return False
+    third = max(1, len(col_edge) // 3)
+    left_avg = float(np.mean(col_edge[:third]))
+    right_avg = float(np.mean(col_edge[2 * third :]))
+    edge_thresh = max(float(np.percentile(col_edge, 60)), 3.0)
+    sig_cols = float(np.sum(col_edge > edge_thresh))
+    right_left_ratio = right_avg / max(left_avg, 1.0)
+    return bool(sig_cols >= sig_cols_min and right_left_ratio > right_left_ratio_min)
+
+
+def _roi_passes_texture(
+    roi: np.ndarray,
+    *,
+    laplacian_min: float,
+    rgb_std_min: float,
+) -> bool:
+    lap_var = bgr_roi_laplacian_variance(roi)
+    rgb_std = bgr_roi_color_std_mean(roi)
+    return lap_var >= float(laplacian_min) and rgb_std >= float(rgb_std_min)
+
+
+def _roi_passes_texture_and_shape(
+    roi: np.ndarray,
+    *,
+    laplacian_min: float,
+    rgb_std_min: float,
+    edge_sig_cols_min: float,
+    edge_right_left_ratio_min: float,
+) -> bool:
+    if not _roi_passes_texture(roi, laplacian_min=laplacian_min, rgb_std_min=rgb_std_min):
+        return False
+    return bgr_roi_edge_shape_ok(
+        roi,
+        sig_cols_min=edge_sig_cols_min,
+        right_left_ratio_min=edge_right_left_ratio_min,
+    )
+
+
+def _crop_standard_roi(
+    bgr: np.ndarray,
+    *,
+    nickname_x1: int,
+    y_top: int,
+    y_bottom: int,
+    gutter_px: int,
+    min_roi_width_px: int,
+) -> Optional[np.ndarray]:
+    h_i, w_i = bgr.shape[:2]
+    x_end = int(max(0, min(int(nickname_x1) - int(gutter_px), w_i)))
+    if x_end < int(min_roi_width_px):
+        return None
+    y_t = int(max(0, min(y_top, h_i - 1)))
+    y_b = int(max(y_t + 4, min(y_bottom, h_i)))
+    roi = np.ascontiguousarray(bgr[y_t:y_b, 0:x_end])
+    if roi.size == 0 or roi.shape[1] < int(min_roi_width_px):
+        return None
+    return roi
+
+
+def _crop_anchor_aligned_roi(
+    bgr: np.ndarray,
+    *,
+    anchor: "AvatarCentroid",
+    nickname_x1: int,
+    y_bottom: int,
+    gutter_px: int,
+    min_roi_width_px: int,
+) -> Optional[np.ndarray]:
+    """头像圆顶 → 昵称行底；与列表页「先定位头像再裁窗」一致。"""
+    h_i, w_i = bgr.shape[:2]
+    x_end = int(max(0, min(int(nickname_x1) - int(gutter_px), w_i)))
+    if x_end < int(min_roi_width_px):
+        return None
+    y_t = int(max(0, min(anchor.y_top, h_i - 1)))
+    y_b = int(max(y_t + 4, min(y_bottom, h_i)))
+    roi = np.ascontiguousarray(bgr[y_t:y_b, 0:x_end])
+    if roi.size == 0 or roi.shape[1] < int(min_roi_width_px):
+        return None
+    return roi
+
+
+def _crop_avatar_disk_roi(
+    bgr: np.ndarray,
+    *,
+    anchor: "AvatarCentroid",
+    nickname_x1: int,
+    gutter_px: int,
+    min_roi_width_px: int,
+) -> Optional[np.ndarray]:
+    """头像圆附近紧凑窗，专供形状守门（避免锚点条带过高稀释列边缘）。"""
+    h_i, w_i = bgr.shape[:2]
+    pad = max(4, int(round(anchor.r * 0.15)))
+    x_end = int(max(0, min(int(nickname_x1) - int(gutter_px), w_i)))
+    x_start = int(max(0, anchor.cx - anchor.r - pad))
+    if x_end - x_start < int(min_roi_width_px):
+        return None
+    y_t = int(max(0, anchor.cy - anchor.r - pad))
+    y_b = int(min(h_i, anchor.cy + anchor.r + pad))
+    if y_b <= y_t + 4:
+        return None
+    roi = np.ascontiguousarray(bgr[y_t:y_b, x_start:x_end])
+    if roi.size == 0 or roi.shape[1] < int(min_roi_width_px):
+        return None
+    return roi
+
+
+def _crop_standard_roi_right(
+    bgr: np.ndarray,
+    *,
+    nickname_x2: int,
+    y_top: int,
+    y_bottom: int,
+    gutter_px: int,
+    min_roi_width_px: int,
+) -> Optional[np.ndarray]:
+    """靠右发言：昵称行右缘以右至屏右缘（与左栏 ``_crop_standard_roi`` 对称）。"""
+    h_i, w_i = bgr.shape[:2]
+    x_start = int(min(w_i, max(0, int(nickname_x2) + int(gutter_px))))
+    if w_i - x_start < int(min_roi_width_px):
+        return None
+    y_t = int(max(0, min(y_top, h_i - 1)))
+    y_b = int(max(y_t + 4, min(y_bottom, h_i)))
+    roi = np.ascontiguousarray(bgr[y_t:y_b, x_start:w_i])
+    if roi.size == 0 or roi.shape[1] < int(min_roi_width_px):
+        return None
+    return roi
+
+
+def nickname_row_passes_prd_avatar_guard(
+    bgr: Optional[np.ndarray],
+    *,
+    nickname_x1: int,
+    nickname_x2: int,
+    y_top: int,
+    y_bottom: int,
+    side: Side,
+    avatar_anchor: Optional["AvatarCentroid"] = None,
+    gutter_px: int = 10,
+    min_roi_width_px: int = 40,
+    laplacian_min: float = 48.0,
+    rgb_std_min: float = 4.0,
+) -> bool:
+    """PRD §九 7（2）：**须**有 Hough 头像锚点，且锚点条带 + 圆盘纹理均通过（**禁止**仅靠标准条带纹理∧形状即放行）。"""
+    if cv2 is None or bgr is None or bgr.size == 0:
+        return False
+    if avatar_anchor is None:
+        return False
+    tex_kw = dict(laplacian_min=laplacian_min, rgb_std_min=rgb_std_min)
+    if side == "left":
+        roi_strip = _crop_anchor_aligned_roi(
+            bgr,
+            anchor=avatar_anchor,
+            nickname_x1=nickname_x1,
+            y_bottom=y_bottom,
+            gutter_px=gutter_px,
+            min_roi_width_px=min_roi_width_px,
+        )
+        roi_disk = _crop_avatar_disk_roi(
+            bgr,
+            anchor=avatar_anchor,
+            nickname_x1=nickname_x1,
+            gutter_px=gutter_px,
+            min_roi_width_px=min_roi_width_px,
+        )
+    else:
+        roi_strip = _crop_anchor_aligned_roi(
+            bgr,
+            anchor=avatar_anchor,
+            nickname_x1=nickname_x2,
+            y_bottom=y_bottom,
+            gutter_px=gutter_px,
+            min_roi_width_px=min_roi_width_px,
+        )
+        roi_disk = _crop_avatar_disk_roi(
+            bgr,
+            anchor=avatar_anchor,
+            nickname_x1=nickname_x2,
+            gutter_px=gutter_px,
+            min_roi_width_px=min_roi_width_px,
+        )
+    if roi_strip is not None and roi_disk is not None:
+        if _roi_passes_texture(roi_strip, **tex_kw) and _roi_passes_texture(
+            roi_disk, **tex_kw
+        ):
+            return True
+    # 已绑定 Hough 锚点但圆盘纹理偏弱时：仍要求标准条带纹理∧形状（**禁止**无锚点条带放行）。
+    shape_kw = dict(
+        laplacian_min=laplacian_min,
+        rgb_std_min=rgb_std_min,
+        edge_sig_cols_min=15.0,
+        edge_right_left_ratio_min=1.2,
+    )
+    if side == "left":
+        roi_std = _crop_standard_roi(
+            bgr,
+            nickname_x1=nickname_x1,
+            y_top=y_top,
+            y_bottom=y_bottom,
+            gutter_px=gutter_px,
+            min_roi_width_px=min_roi_width_px,
+        )
+    else:
+        roi_std = _crop_standard_roi_right(
+            bgr,
+            nickname_x2=nickname_x2,
+            y_top=y_top,
+            y_bottom=y_bottom,
+            gutter_px=gutter_px,
+            min_roi_width_px=min_roi_width_px,
+        )
+    if roi_std is not None and _roi_passes_texture_and_shape(roi_std, **shape_kw):
+        return True
+    return False
+
+
+def nickname_row_passes_avatar_roi(
+    bgr: Optional[np.ndarray],
+    *,
+    nickname_x1: int,
+    y_top: int,
+    y_bottom: int,
+    avatar_anchor: Optional["AvatarCentroid"] = None,
+    gutter_px: int = 10,
+    min_roi_width_px: int = 40,
+    laplacian_min: float = 48.0,
+    rgb_std_min: float = 4.0,
+    edge_sig_cols_min: float = 15.0,
+    edge_right_left_ratio_min: float = 1.2,
+    prd_strict: bool = False,
+    nickname_x2: int = 0,
+    side: Side = "left",
+) -> bool:
+    """标准 ROI：纹理∧列缘形状；锚点路径：条带纹理 + 圆盘纹理（几何先验定位头像）。
+
+    ``prd_strict=True`` 时委托 :func:`nickname_row_passes_prd_avatar_guard`（验收 SSOT）。
+    """
+    if prd_strict:
+        return nickname_row_passes_prd_avatar_guard(
+            bgr,
+            nickname_x1=nickname_x1,
+            nickname_x2=nickname_x2 or nickname_x1,
+            y_top=y_top,
+            y_bottom=y_bottom,
+            side=side,
+            avatar_anchor=avatar_anchor,
+            gutter_px=gutter_px,
+            min_roi_width_px=min_roi_width_px,
+            laplacian_min=laplacian_min,
+            rgb_std_min=rgb_std_min,
+        )
+    if cv2 is None or bgr is None or bgr.size == 0:
+        return False
+
+    kw = dict(
+        laplacian_min=laplacian_min,
+        rgb_std_min=rgb_std_min,
+        edge_sig_cols_min=edge_sig_cols_min,
+        edge_right_left_ratio_min=edge_right_left_ratio_min,
+    )
+
+    roi_std = _crop_standard_roi(
+        bgr,
+        nickname_x1=nickname_x1,
+        y_top=y_top,
+        y_bottom=y_bottom,
+        gutter_px=gutter_px,
+        min_roi_width_px=min_roi_width_px,
+    )
+    if roi_std is not None and _roi_passes_texture_and_shape(roi_std, **kw):
+        return True
+
+    if avatar_anchor is None:
+        return False
+
+    roi_strip = _crop_anchor_aligned_roi(
+        bgr,
+        anchor=avatar_anchor,
+        nickname_x1=nickname_x1,
+        y_bottom=y_bottom,
+        gutter_px=gutter_px,
+        min_roi_width_px=min_roi_width_px,
+    )
+    roi_disk = _crop_avatar_disk_roi(
+        bgr,
+        anchor=avatar_anchor,
+        nickname_x1=nickname_x1,
+        gutter_px=gutter_px,
+        min_roi_width_px=min_roi_width_px,
+    )
+    if roi_strip is None or roi_disk is None:
+        return False
+    tex_kw = dict(laplacian_min=laplacian_min, rgb_std_min=rgb_std_min)
+    return _roi_passes_texture(roi_strip, **tex_kw) and _roi_passes_texture(
+        roi_disk, **tex_kw
+    )
+
+
+def avatar_roi_pass(
+    bgr: Optional[np.ndarray],
+    *,
+    nickname_x1: int,
+    y_top: int,
+    y_bottom: int,
+    avatar_anchor: Optional["AvatarCentroid"] = None,
+    gutter_px: int = 10,
+    min_roi_width_px: int = 40,
+    laplacian_min: float = 48.0,
+    rgb_std_min: float = 4.0,
+    edge_sig_cols_min: float = 15.0,
+    edge_right_left_ratio_min: float = 1.2,
+    require_edge_shape: bool = True,
+    strict_narrow_only: bool = False,
+    **legacy: Any,
+) -> bool:
+    """``avatar_roi_pass`` 为 ``nickname_row_passes_avatar_roi`` 别名；忽略扩展类旧参数。"""
+    _ = legacy
+    if strict_narrow_only and avatar_anchor is None:
+        pass
+    if not require_edge_shape:
+        logger.debug("avatar_roi_pass: require_edge_shape=False 已弃用，仍使用纹理∧形状")
+    return nickname_row_passes_avatar_roi(
+        bgr,
+        nickname_x1=nickname_x1,
+        y_top=y_top,
+        y_bottom=y_bottom,
+        avatar_anchor=avatar_anchor,
+        gutter_px=gutter_px,
+        min_roi_width_px=min_roi_width_px,
+        laplacian_min=laplacian_min,
+        rgb_std_min=rgb_std_min,
+        edge_sig_cols_min=edge_sig_cols_min,
+        edge_right_left_ratio_min=edge_right_left_ratio_min,
+    )
+
+
+def nickname_left_roi_passes_avatar_signal(
+    bgr: Optional[np.ndarray],
+    *,
+    nickname_x1: int,
+    y_top: int,
+    y_bottom: int,
+    avatar_anchor: Optional["AvatarCentroid"] = None,
+    gutter_px: int = 10,
+    min_roi_width_px: int = 40,
+    laplacian_min: float = 48.0,
+    rgb_std_min: float = 4.0,
+    edge_sig_cols_min: float = 15.0,
+    edge_right_left_ratio_min: float = 1.2,
+    **kwargs: Any,
+) -> bool:
+    _ = kwargs
+    return nickname_row_passes_avatar_roi(
+        bgr,
+        nickname_x1=nickname_x1,
+        y_top=y_top,
+        y_bottom=y_bottom,
+        avatar_anchor=avatar_anchor,
+        gutter_px=gutter_px,
+        min_roi_width_px=min_roi_width_px,
+        laplacian_min=laplacian_min,
+        rgb_std_min=rgb_std_min,
+        edge_sig_cols_min=edge_sig_cols_min,
+        edge_right_left_ratio_min=edge_right_left_ratio_min,
+    )
+
+
+def load_png_bgr(png_path: Any) -> Optional[np.ndarray]:
+    if cv2 is None or png_path is None:
+        return None
+    try:
+        return cv2.imread(str(png_path))
+    except Exception as e:
+        logger.warning("nickname_avatar_guard: imread 失败 path=%s err=%s", png_path, e)
+        return None

screenshot_vision_algorithm/android/wechat/ocr/badge_ocr.py

@@ -0,0 +1,232 @@
+"""Optional PaddleOCR pass to read digits off unread badges on the main
+conversation list.
+
+Why this module exists
+----------------------
+The bulk of :func:`TopGroupScanDriver.scan_pinned_groups` is **OCR-free** —
+it only has to tell whether a row has an unread badge (red blob near the
+avatar's top-right corner) and whether the row is pinned (grey cell
+background). The digit count ("3", "12", "99+") is a **nice-to-have**
+used by downstream prioritisation (iterate rows with larger counts
+first) and logging. We keep it behind an opt-in flag so:
+
+- The fast path stays fast — PaddleOCR takes ~1.5 s per cold init + a
+  few hundred ms per badge, which would slow every live scan loop.
+- Unit tests don't need a working Paddle install to cover the badge
+  geometry path.
+
+Usage
+-----
+Call :func:`ocr_unread_badge_digits` AFTER ``scan_pinned_groups``
+produced its rows. The function lazily imports PaddleOCR, crops a small
+padded window around each ``UnreadDotHit``, binarises (red-bg/white-fg
+→ black-bg/white-fg), upscales 6x, and returns a map
+``{hit_index → (digits, score)}`` (positional hit index ``0 …``) for every row whose OCR confidently
+matches a digit pattern. Rows without a confident read are absent.
+
+Digit regex
+-----------
+``\\d+\\+?`` — matches "1", "23", "99+", "0" (the last is never shown
+by WeChat but we still accept it to keep the regex portable).
+
+Thresholds / pre-processing are the d4-auto-scan calibration values
+that scored ~90%+ on the edb1a89f baseline when the previous scratch
+tool ``tools/detect_unread_badges.py`` (since removed) was still
+around. Kept as module-level constants so Day 7 calibration can bump
+them without touching the driver.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+import cv2  # type: ignore
+import numpy as np  # type: ignore
+from loguru import logger
+
+from screenshot_vision_algorithm.android.wechat.algorithms.template_matching import UnreadDotHit
+
+_DIGIT_RE = re.compile(r"\d+\+?")
+
+# Pre-processing ------------------------------------------------------------
+
+#: Padding (in pixels AT RAW SCALE) around each badge bbox before cropping.
+#: PaddleOCR's detection head needs ~20% whitespace margin around the glyph.
+#: We take ``max(8, w // 3)`` / ``max(8, h // 3)`` so both 27-px solid dots
+#: and 50-px digit badges get proportionally sized margins.
+PAD_MIN = 8
+PAD_DIV = 3
+
+#: Red-mask HSV cut (``cv2.inRange`` low/high). Matches the white-pixel
+#: detector used downstream — pixels that are BRIGHT and DESATURATED get
+#: promoted to white, everything else (red badge body, avatar bleed,
+#: anti-aliased purple) falls to black.
+WHITE_HSV_LO: tuple[int, int, int] = (0, 0, 200)
+WHITE_HSV_HI: tuple[int, int, int] = (179, 60, 255)
+
+#: Fallback grey-scale brightness threshold: if HSV mask misses an AA
+#: near-white pixel (V < 200 but > 180 visually white), the classic
+#: ``threshold`` pass recaptures it.
+GRAY_THRESH = 180
+
+#: Upscale factor applied to the binarised badge crop. PP-OCRv5 mobile
+#: wants ~32 px min glyph height; a single-digit 27-px badge at 6x
+#: becomes 162 px, well above that floor.
+OCR_UPSCALE = 6.0
+
+
+def _binarise(crop_bgr: np.ndarray) -> np.ndarray:
+    """Convert a red-bg / white-fg badge crop to clean black-bg / white-fg.
+
+    Two strategies OR'd together:
+      1. HSV ``inRange`` for near-white (low saturation + high value).
+      2. Gray-scale ``threshold`` at ``GRAY_THRESH`` to recapture AA edges.
+
+    Returns a single-channel ``uint8`` mask. The caller should 3-channel
+    expand + cubic-upscale it for PaddleOCR.
+    """
+    gray = cv2.cvtColor(crop_bgr, cv2.COLOR_BGR2GRAY)
+    hsv = cv2.cvtColor(crop_bgr, cv2.COLOR_BGR2HSV)
+    is_white = cv2.inRange(
+        hsv, np.asarray(WHITE_HSV_LO, dtype=np.uint8),
+        np.asarray(WHITE_HSV_HI, dtype=np.uint8),
+    )
+    _, bright = cv2.threshold(gray, GRAY_THRESH, 255, cv2.THRESH_BINARY)
+    return cv2.bitwise_or(is_white, bright)
+
+
+# PaddleOCR init (lazy, cached) --------------------------------------------
+
+_OCR_SINGLETON = None
+_OCR_VERSION_MAJOR: Optional[int] = None
+
+
+def _get_ocr():
+    """Lazy PaddleOCR factory. Cached for the process lifetime."""
+    global _OCR_SINGLETON, _OCR_VERSION_MAJOR
+    if _OCR_SINGLETON is not None:
+        return _OCR_SINGLETON, _OCR_VERSION_MAJOR
+
+    try:
+        from paddleocr import PaddleOCR  # type: ignore
+        import paddleocr as _pkg  # type: ignore
+    except ImportError as e:
+        raise RuntimeError(
+            "ocr_unread_badge_digits requires paddleocr; "
+            "pip install paddleocr"
+        ) from e
+
+    try:
+        ver_major = int(str(getattr(_pkg, "__version__", "2.0.0")).split(".")[0])
+    except Exception:  # pragma: no cover
+        ver_major = 2
+
+    logger.info("initialising PaddleOCR v%d (once-per-process)", ver_major)
+    if ver_major >= 3:
+        ocr = PaddleOCR(
+            use_textline_orientation=False,
+            lang="ch", device="cpu",
+            text_detection_model_name="PP-OCRv5_mobile_det",
+            text_recognition_model_name="PP-OCRv5_mobile_rec",
+        )
+    else:  # pragma: no cover — legacy 2.x fallback, project pins 3.x
+        ocr = PaddleOCR(use_angle_cls=False, lang="ch", use_gpu=False)
+
+    _OCR_SINGLETON = ocr
+    _OCR_VERSION_MAJOR = ver_major
+    return ocr, ver_major
+
+
+# Public API ---------------------------------------------------------------
+
+
+def ocr_unread_badge_digits(
+    screen_bgr: np.ndarray,
+    hits: tuple[UnreadDotHit, ...] | list[UnreadDotHit],
+) -> dict[int, tuple[str, float]]:
+    """Read digit(s) off each badge.
+
+    Args:
+        screen_bgr: The FULL conversation-list screenshot (the same
+            ``np.ndarray`` the driver passed to ``detect_unread_dots``).
+            We crop from the raw image so the badge stays at native
+            resolution before the 6x upscale.
+        hits: Sequence of :class:`UnreadDotHit`. Indexing in the
+            returned dict is POSITIONAL (``0..len(hits)-1``), NOT
+            ``UnreadDotHit`` identity — this keeps the function
+            ``dataclass(frozen=True)``-safe.
+
+    Returns:
+        ``{i: (digits, score)}`` for each hit index that produced a
+        confident digit match. Hits without a match are absent from
+        the dict (rather than mapped to ``None``) so callers can use
+        ``dict.get(i)`` freely.
+
+    Raises:
+        RuntimeError: if ``paddleocr`` is not installed.
+    """
+    if not hits:
+        return {}
+
+    ocr, ver_major = _get_ocr()
+    H, W = screen_bgr.shape[:2]
+    out: dict[int, tuple[str, float]] = {}
+
+    for i, b in enumerate(hits):
+        pad_x = max(PAD_MIN, b.w // PAD_DIV)
+        pad_y = max(PAD_MIN, b.h // PAD_DIV)
+        cx1 = max(0, b.x - pad_x)
+        cy1 = max(0, b.y - pad_y)
+        cx2 = min(W, b.x + b.w + pad_x)
+        cy2 = min(H, b.y + b.h + pad_y)
+        crop = screen_bgr[cy1:cy2, cx1:cx2]
+        if crop.size == 0:
+            continue
+        binary = _binarise(crop)
+        bin_bgr = cv2.merge([binary, binary, binary])
+        upscaled = cv2.resize(
+            bin_bgr, None, fx=OCR_UPSCALE, fy=OCR_UPSCALE,
+            interpolation=cv2.INTER_CUBIC,
+        )
+        texts: list[str] = []
+        scores: list[float] = []
+        try:
+            if ver_major >= 3:
+                results = list(ocr.predict(upscaled))
+                if results:
+                    r = results[0]
+                    texts = list(r.get("rec_texts", []))
+                    scores = [float(s) for s in r.get("rec_scores", [])]
+            else:  # pragma: no cover
+                raw = ocr.ocr(upscaled, cls=False)
+                if raw and raw[0]:
+                    texts = [line[1][0] for line in raw[0]]
+                    scores = [float(line[1][1]) for line in raw[0]]
+        except Exception as e:  # pragma: no cover — OCR backend failure
+            logger.debug("badge %d OCR failed: %s", i, e)
+            continue
+
+        best_digits: Optional[str] = None
+        best_score = 0.0
+        for text, score in zip(texts, scores):
+            m = _DIGIT_RE.search(text.strip())
+            if not m:
+                continue
+            if score > best_score:
+                best_digits = m.group(0)
+                best_score = float(score)
+        if best_digits is not None:
+            out[i] = (best_digits, round(best_score, 3))
+            logger.debug(
+                "badge[%d] bbox=(%d,%d,%d,%d) digits=%r score=%.3f",
+                i, b.x, b.y, b.w, b.h, best_digits, best_score,
+            )
+
+    logger.info(
+        "ocr_unread_badge_digits: %d/%d badge(s) produced a digit match",
+        len(out), len(hits),
+    )
+    return out
+
+
+__all__ = ["ocr_unread_badge_digits"]