screenshot-vision-algorithm 0.3.8__tar.gz → 0.3.13__tar.gz

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenshot_vision_algorithm
-Version: 0.3.8
+Version: 0.3.13
 Summary: Multi-platform screenshot vision algorithms: WeChat (card bbox, speaker bands, avatar detection, OCR helpers), XHS & Zhihu (planned)
 License: MIT
 Requires-Python: >=3.10
@@ -209,7 +209,7 @@ profile.templates_dir       # Path — 内嵌模板 PNG 目录
 
 | 函数 | 说明 |
 |------|------|
-| `detect_left_avatar_column_layout(...)` | 用 Hough 圆检测左侧头像列 |
+| `detect_left_avatar_column_layout(...)` | 群聊左列：圆角方块主路径，左列 `<3` 时 Hough 兜底 |
 | `find_avatar_anchor_for_nickname_bbox(...)` | 为昵称 bbox 找到对应的发言人头像锚点 |
 | `nickname_bbox_in_avatar_column(...)` | 判断昵称 bbox 是否在头像列区域内 |
 | `left_avatar_ytops(layout)` | 提取所有头像的 Y 坐标列表 |

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/README.md

@@ -190,7 +190,7 @@ profile.templates_dir       # Path — 内嵌模板 PNG 目录
 
 | 函数 | 说明 |
 |------|------|
-| `detect_left_avatar_column_layout(...)` | 用 Hough 圆检测左侧头像列 |
+| `detect_left_avatar_column_layout(...)` | 群聊左列：圆角方块主路径，左列 `<3` 时 Hough 兜底 |
 | `find_avatar_anchor_for_nickname_bbox(...)` | 为昵称 bbox 找到对应的发言人头像锚点 |
 | `nickname_bbox_in_avatar_column(...)` | 判断昵称 bbox 是否在头像列区域内 |
 | `left_avatar_ytops(layout)` | 提取所有头像的 Y 坐标列表 |

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "screenshot_vision_algorithm"
-version = "0.3.8"
+version = "0.3.13"
 description = "Multi-platform screenshot vision algorithms: WeChat (card bbox, speaker bands, avatar detection, OCR helpers), XHS & Zhihu (planned)"
 readme = "README.md"
 license = { text = "MIT" }

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/src/screenshot_vision_algorithm/android/wechat/algorithms/avatar_column.py

@@ -1,6 +1,8 @@
-"""左列头像圆心检测（列表页 / 群聊页共用几何先验）。
+"""左列头像检测（列表页 / 群聊页共用几何先验）。
+
+群聊：**圆角方块**为主路径；左列检出数 ``< CHAT_LEFT_AVATAR_HOUGH_FALLBACK_THRESHOLD`` 时
+回退 **Hough 圆**。列表会话行仍可在 ``template_matching`` 侧单独走 roundrect + §14 门控。
 
-列表会话行与群聊发言人归因共用同一套 Hough + median_x 过滤 + y 向去重，
 产出 ``AvatarCentroid`` 供 ROI 守门与 PRD §5 纵向筒使用。
 """
 
@@ -23,6 +25,7 @@ from screenshot_vision_algorithm.android.wechat.algorithms.template_matching imp
     CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE,
     CONVERSATION_LIST_AVATAR_ROI_LEFT_BASELINE,
     CONVERSATION_LIST_AVATAR_ROI_RIGHT_BASELINE,
+    conversation_list_avatar_roundrect_avatar_centroids_ordered,
 )
 
 # 与列表页 Hough 对齐（1080 基准）；群聊左列头像物理尺寸与列表一致。
@@ -32,6 +35,10 @@ _LIST_HOUGH_MAX_R_BASELINE = 80
 _LIST_YMIN_GAP_BASELINE = 118
 _LIST_SAME_ICON_DY_MAX_BASELINE = 18
 
+# 群聊：roundrect 主路径；左列 < 阈值时 Hough 兜底。
+CHAT_LEFT_AVATAR_HOUGH_FALLBACK_THRESHOLD = 3
+CHAT_ROUNDRECT_MIN_ROWS = 1
+
 # 绑定：昵称行与头像锚点的最大竖直间距（px @ 1080）。
 NICKNAME_AVATAR_BIND_MAX_DY_BASELINE = 140
 
@@ -64,25 +71,48 @@ def _sw(scale_w: float) -> float:
     return max(float(scale_w), 1e-6)
 
 
-def detect_left_avatar_column_layout(
+def _empty_layout(scale_w: float) -> LeftAvatarColumnLayout:
+    xt = int(round(float(CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE) * scale_w))
+    return LeftAvatarColumnLayout(centroids=(), median_cx=0.0, column_x_half_width_px=xt)
+
+
+def _layout_from_centroids(
+    centroids: list[AvatarCentroid],
+    *,
+    column_x_half_width_px: int,
+) -> LeftAvatarColumnLayout:
+    if not centroids:
+        return LeftAvatarColumnLayout(
+            centroids=(),
+            median_cx=0.0,
+            column_x_half_width_px=column_x_half_width_px,
+        )
+    median_cx = float(np.median(np.array([c.cx for c in centroids], dtype=np.float64)))
+    return LeftAvatarColumnLayout(
+        centroids=tuple(centroids),
+        median_cx=median_cx,
+        column_x_half_width_px=column_x_half_width_px,
+    )
+
+
+def _detect_left_avatar_column_layout_hough(
     screen_bgr: np.ndarray,
     scale_w: float,
     *,
-    y_top: int = 0,
-    y_bottom_excl: Optional[int] = None,
+    y_top: int,
+    y_bottom_excl: int,
 ) -> LeftAvatarColumnLayout:
-    """在左列 ROI 内 Hough 圆 → median_x 过滤 → y 向去重（与列表页同参）。"""
+    """Hough 圆检测（列表/群聊 legacy 参数）。"""
     sw = _sw(scale_w)
     xt = int(round(float(CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE) * sw))
-    empty = LeftAvatarColumnLayout(centroids=(), median_cx=0.0, column_x_half_width_px=xt)
+    empty = _empty_layout(sw)
 
     if cv2 is None or screen_bgr is None or getattr(screen_bgr, "size", 0) == 0:
         return empty
 
     h_full, w_full = screen_bgr.shape[:2]
     y1 = int(max(0, min(y_top, h_full - 1)))
-    y2 = int(y_bottom_excl if y_bottom_excl is not None else h_full)
-    y2 = int(max(y1 + 8, min(y2, h_full)))
+    y2 = int(max(y1 + 8, min(y_bottom_excl, h_full)))
     x1_roi = int(max(0, round(CONVERSATION_LIST_AVATAR_ROI_LEFT_BASELINE * sw)))
     x2_roi = int(min(w_full, round(CONVERSATION_LIST_AVATAR_ROI_RIGHT_BASELINE * sw)))
     if y2 <= y1 + 40 or x2_roi <= x1_roi + 24:
@@ -148,6 +178,68 @@ def detect_left_avatar_column_layout(
     )
 
 
+def _detect_left_avatar_column_layout_roundrect(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    y_top: int,
+    y_bottom_excl: int,
+) -> LeftAvatarColumnLayout:
+    """圆角方块主路径（群聊 content_bounds ROI）。"""
+    sw = _sw(scale_w)
+    xt = int(round(float(CONVERSATION_LIST_AVATAR_MEDIAN_X_HALF_WIDTH_BASELINE) * sw))
+    empty = _empty_layout(sw)
+
+    if screen_bgr is None or getattr(screen_bgr, "size", 0) == 0:
+        return empty
+
+    pts = conversation_list_avatar_roundrect_avatar_centroids_ordered(
+        screen_bgr,
+        sw,
+        roi_y1=int(y_top),
+        roi_y2_excl=int(y_bottom_excl),
+        min_rows=CHAT_ROUNDRECT_MIN_ROWS,
+        trim_list_footer=False,
+    )
+    if not pts:
+        return empty
+
+    centroids = [
+        AvatarCentroid(cx=int(cx), cy=int(cy), r=max(8, int(r)))
+        for cx, cy, r in pts
+    ]
+    return _layout_from_centroids(centroids, column_x_half_width_px=xt)
+
+
+def detect_left_avatar_column_layout(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    y_top: int = 0,
+    y_bottom_excl: Optional[int] = None,
+) -> LeftAvatarColumnLayout:
+    """群聊左列头像：roundrect 主路径；``<3`` 时 Hough 兜底（取检出更多的一侧）。"""
+    sw = _sw(scale_w)
+    h_full = int(screen_bgr.shape[0]) if screen_bgr is not None else 0
+    y1 = int(max(0, min(y_top, max(h_full - 1, 0))))
+    y2 = int(y_bottom_excl if y_bottom_excl is not None else h_full)
+    y2 = int(max(y1 + 8, min(y2, h_full)))
+
+    roundrect_layout = _detect_left_avatar_column_layout_roundrect(
+        screen_bgr, sw, y_top=y1, y_bottom_excl=y2,
+    )
+    n_rr = len(roundrect_layout.centroids)
+    if n_rr >= CHAT_LEFT_AVATAR_HOUGH_FALLBACK_THRESHOLD:
+        return roundrect_layout
+
+    hough_layout = _detect_left_avatar_column_layout_hough(
+        screen_bgr, sw, y_top=y1, y_bottom_excl=y2,
+    )
+    if len(hough_layout.centroids) > n_rr:
+        return hough_layout
+    return roundrect_layout
+
+
 def find_avatar_anchor_for_nickname_bbox(
     layout: LeftAvatarColumnLayout,
     bbox_xyxy: tuple[int, int, int, int],
@@ -208,3 +300,28 @@ def nickname_bbox_in_avatar_column(
 def left_avatar_ytops(layout: LeftAvatarColumnLayout) -> list[int]:
     """供 PRD §5：头像顶 y（圆心减半径）。"""
     return [c.y_top for c in layout.centroids]
+
+
+def completely_inside_avatar_x_zone(
+    bbox_xyxy: tuple[int, int, int, int],
+    *,
+    cx: int,
+    r: int,
+) -> bool:
+    """PRD §8B：OCR 块是否完全被包含在左列头像区 X 范围 ``[0, cx+r]`` 内。"""
+    x1, _, x2, _ = bbox_xyxy
+    x_right = float(cx) + float(r)
+    return float(x1) >= 0.0 and float(x2) <= x_right
+
+
+def left_avatar_cx_r_for_band(
+    layout: LeftAvatarColumnLayout,
+    band_y0: float,
+    band_y1: float,
+) -> tuple[int, int] | None:
+    """返回与 ``speaker_band`` 对应的左列头像 ``(cx, r)``（圆心 Y 最接近 band 中线）。"""
+    if layout.empty:
+        return None
+    mid = (float(band_y0) + float(band_y1)) / 2.0
+    best = min(layout.centroids, key=lambda c: abs(float(c.cy) - mid))
+    return int(best.cx), int(best.r)

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/src/screenshot_vision_algorithm/android/wechat/algorithms/speaker_band.py

@@ -191,11 +191,14 @@ def detect_chat_side_avatar_ytops(
         left_ys = _hough_ytops_in_column(
             gray, x1=0, x2=left_x2, y1=y1, y2=y2, scale_w=scale_w,
         )
-    col_w = int(round(CHAT_SIDE_AVATAR_COLUMN_WIDTH_BASELINE * sw))
-    right_x1 = max(0, w_full - col_w)
-    right_ys = _hough_ytops_in_column(
-        gray, x1=right_x1, x2=w_full, y1=y1, y2=y2, scale_w=scale_w,
-    )
+    # 左列已有检出时禁用右列 timeline，避免标题栏 y≈119 假阳合成单筒。
+    right_ys: list[int] = []
+    if not left_ys:
+        col_w = int(round(CHAT_SIDE_AVATAR_COLUMN_WIDTH_BASELINE * sw))
+        right_x1 = max(0, w_full - col_w)
+        right_ys = _hough_ytops_in_column(
+            gray, x1=right_x1, x2=w_full, y1=y1, y2=y2, scale_w=scale_w,
+        )
     return left_ys, right_ys
 
 
@@ -221,6 +224,7 @@ def build_prd_speaker_vertical_bands(
     scale_w: float,
     first_avatar_gap_reject_baseline: int = CHAT_BAND_FIRST_AVATAR_TOP_GAP_REJECT_BASELINE,
     first_band_top_extend_baseline: int = CHAT_FIRST_BAND_TOP_EXTEND_BASELINE,
+    avatar_merge_min_sep_baseline: int = 24,
 ) -> PrdChatVerticalLayout:
     """由时间序头像顶构造 PRD §5 顶隙 orphan + 左闭右开发言人筒。
 
@@ -248,7 +252,7 @@ def build_prd_speaker_vertical_bands(
 
     # 时间轴序去重：过近视为同一人头像重复检出
     merged_starts: list[int] = []
-    min_sep = int(round(24 * sw))
+    min_sep = int(round(int(avatar_merge_min_sep_baseline) * sw))
     for e in timeline:
         y = int(e.y_top)
         if not merged_starts or y - merged_starts[-1] >= min_sep:

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/src/screenshot_vision_algorithm/android/wechat/algorithms/template_matching.py

@@ -1812,28 +1812,25 @@ def split_conversation_rows_by_avatar_centroids(
     return out, "ok", None
 
 
-def conversation_list_avatar_roundrect_centroid_mid_y_ordered(
+def _avatar_roundrect_centroids_in_left_roi(
     screen_bgr: np.ndarray,
     scale_w: float,
     *,
-    screen_h: int,
-    list_first_row_top_px: int,
-    min_rows: int = 4,
-) -> Optional[list[int]]:
-    """圆角方块路径：自上而下整屏头像 **质心 y（px）**，不写行带。"""
+    roi_y1: int,
+    roi_y2_excl: int,
+    min_rows: int,
+    trim_list_footer: bool = True,
+) -> Optional[list[tuple[int, int, int]]]:
+    """圆角方块路径：左列 ROI 内头像 ``(cx_full, cy_full, r)``，自上而下排序。"""
     sw = max(float(scale_w), 1e-6)
     _, w_full = screen_bgr.shape[:2]
-    slack_top = int(round(22 * sw))
-    roi_y1 = max(0, int(list_first_row_top_px) - slack_top)
-    roi_y2_excl_pt = conversation_list_avatar_hough_roi_y2_exclusive_px(int(screen_h), sw)
-    roi_y2 = max(roi_y1 + 8, roi_y2_excl_pt)
     x1_roi = max(0, int(round(CONVERSATION_LIST_AVATAR_ROI_LEFT_BASELINE * sw)))
     x2_roi = min(w_full, int(round(CONVERSATION_LIST_AVATAR_ROI_RIGHT_BASELINE * sw)))
-    if roi_y2 <= roi_y1 + 40 or x2_roi <= x1_roi + 24:
+    if roi_y2_excl <= roi_y1 + 40 or x2_roi <= x1_roi + 24:
         return None
 
     crop_gray = cv2.cvtColor(
-        screen_bgr[roi_y1:roi_y2, x1_roi:x2_roi], cv2.COLOR_BGR2GRAY,
+        screen_bgr[roi_y1:roi_y2_excl, x1_roi:x2_roi], cv2.COLOR_BGR2GRAY,
     )
     blur = cv2.GaussianBlur(crop_gray, (5, 5), 0)
     mk_base = float(LIST_AVATAR_ROUNDRECT_MORPH_GRAD_KERNEL_BASELINE)
@@ -1854,7 +1851,7 @@ def conversation_list_avatar_roundrect_centroid_mid_y_ordered(
         cv2.CHAIN_APPROX_SIMPLE,
     )
 
-    cand: list[tuple[float, float, float]] = []
+    cand: list[tuple[float, float, float, float]] = []
     s_min = float(LIST_AVATAR_ROUNDRECT_BBOX_SIDE_MIN_BASELINE) * sw
     s_max = float(LIST_AVATAR_ROUNDRECT_BBOX_SIDE_MAX_BASELINE) * sw
     asp_min = float(LIST_AVATAR_ROUNDRECT_MIN_ASPECT)
@@ -1887,8 +1884,9 @@ def conversation_list_avatar_roundrect_centroid_mid_y_ordered(
             continue
         xc = float(M["m10"] / M["m00"])
         yc = float(M["m01"] / M["m00"])
+        half_r = max(8.0, min(bw_i, bh) / 2.0)
         merit = bb_a * extent * sol
-        cand.append((merit, xc, yc))
+        cand.append((merit, xc, yc, half_r))
 
     if len(cand) < min_rows:
         return None
@@ -1901,10 +1899,11 @@ def conversation_list_avatar_roundrect_centroid_mid_y_ordered(
         if abs(trip[1] - median_x) <= float(xt)
     ]
 
-    roi_h_calc = max(0, int(roi_y2) - int(roi_y1))
-    foot = int(round(float(LIST_AVATAR_HOUGH_MAX_CROP_Y_FROM_ROI_BOTTOM_BASELINE) * sw))
-    if roi_h_calc > foot + 24:
-        filt = [trip for trip in filt if float(trip[2]) <= float(roi_h_calc - foot)]
+    roi_h_calc = max(0, int(roi_y2_excl) - int(roi_y1))
+    if trim_list_footer:
+        foot = int(round(float(LIST_AVATAR_HOUGH_MAX_CROP_Y_FROM_ROI_BOTTOM_BASELINE) * sw))
+        if roi_h_calc > foot + 24:
+            filt = [trip for trip in filt if float(trip[2]) <= float(roi_h_calc - foot)]
 
     if len(filt) < min_rows:
         return None
@@ -1913,29 +1912,80 @@ def conversation_list_avatar_roundrect_centroid_mid_y_ordered(
 
     ymin_gap = round(118 * sw)
     same_icon_dy_max = float(LIST_AVATAR_STACK_SAME_ICON_MAX_CENTER_DY_BASELINE) * sw
-    stacked_h: list[tuple[float, float, float]] = []
+    stacked_h: list[tuple[float, float, float, float]] = []
 
-    for mer, xc, yc in filt:
+    for mer, xc, yc, half_r in filt:
         if not stacked_h:
-            stacked_h.append((mer, xc, yc))
+            stacked_h.append((mer, xc, yc, half_r))
             continue
-        pr_mer, _px, py_prev = stacked_h[-1]
+        pr_mer, _px, py_prev, _pr = stacked_h[-1]
         dy = float(yc) - float(py_prev)
         if dy < ymin_gap:
             if dy <= same_icon_dy_max:
                 if mer > pr_mer:
-                    stacked_h[-1] = (mer, xc, yc)
+                    stacked_h[-1] = (mer, xc, yc, half_r)
             else:
-                stacked_h.append((mer, xc, yc))
+                stacked_h.append((mer, xc, yc, half_r))
         else:
-            stacked_h.append((mer, xc, yc))
+            stacked_h.append((mer, xc, yc, half_r))
 
     if len(stacked_h) < min_rows:
         return None
 
-    return [
-        roi_y1 + int(round(yc)) for _me, _xc, yc in stacked_h
-    ]
+    out: list[tuple[int, int, int]] = []
+    for _me, xc, yc, half_r in stacked_h:
+        cx_full = int(round(x1_roi + xc))
+        cy_full = int(round(roi_y1 + yc))
+        ri = max(8, int(round(half_r)))
+        out.append((cx_full, cy_full, ri))
+    return out
+
+
+def conversation_list_avatar_roundrect_avatar_centroids_ordered(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    roi_y1: int,
+    roi_y2_excl: int,
+    min_rows: int = 1,
+    trim_list_footer: bool = False,
+) -> Optional[list[tuple[int, int, int]]]:
+    """群聊/通用：左列圆角方块头像 ``(cx, cy, r)`` 全图坐标。"""
+    return _avatar_roundrect_centroids_in_left_roi(
+        screen_bgr,
+        scale_w,
+        roi_y1=roi_y1,
+        roi_y2_excl=roi_y2_excl,
+        min_rows=min_rows,
+        trim_list_footer=trim_list_footer,
+    )
+
+
+def conversation_list_avatar_roundrect_centroid_mid_y_ordered(
+    screen_bgr: np.ndarray,
+    scale_w: float,
+    *,
+    screen_h: int,
+    list_first_row_top_px: int,
+    min_rows: int = 4,
+) -> Optional[list[int]]:
+    """圆角方块路径：自上而下整屏头像 **质心 y（px）**，不写行带。"""
+    sw = max(float(scale_w), 1e-6)
+    slack_top = int(round(22 * sw))
+    roi_y1 = max(0, int(list_first_row_top_px) - slack_top)
+    roi_y2_excl_pt = conversation_list_avatar_hough_roi_y2_exclusive_px(int(screen_h), sw)
+    roi_y2 = max(roi_y1 + 8, roi_y2_excl_pt)
+    pts = _avatar_roundrect_centroids_in_left_roi(
+        screen_bgr,
+        sw,
+        roi_y1=roi_y1,
+        roi_y2_excl=roi_y2,
+        min_rows=min_rows,
+        trim_list_footer=True,
+    )
+    if pts is None:
+        return None
+    return [cy for _cx, cy, _r in pts]
 
 
 def prd_wechat_main_list_row_count_by_gap_y12(
@@ -2226,6 +2276,7 @@ __all__ = [
     "LIST_ROW_GEOMETRY_Y12_GAP_SPREAD_MAX_BASELINE",
     "LIST_ROW_SCREEN_HEIGHT_CALIBRATION_Y12_BASELINE",
     "conversation_list_avatar_roundrect_centroid_mid_y_ordered",
+    "conversation_list_avatar_roundrect_avatar_centroids_ordered",
     "prd_wechat_main_list_row_count_by_gap_y12",
     "prd_wechat_main_list_row_count_gap_y12_from_screen_roundrect",
     "CONVERSATION_RIGHT_SIDE_RESERVED_BASELINE",

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/src/screenshot_vision_algorithm/android/wechat/ocr/nickname_binding.py

@@ -113,7 +113,7 @@ References:
 from __future__ import annotations
 
 import re
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, field
 from dataclasses import replace as dataclass_replace
 from pathlib import Path
 from statistics import median
@@ -230,6 +230,44 @@ class NicknameOcrConfig:
     """Prefix / substring tags that exclude a block from nickname
     consideration even if all geometric criteria pass."""
 
+    # ── 以下字段可由 rules_config.yaml 覆盖（housekeeping 胶水层读 yaml → 灌参）──
+
+    skip_block_patterns: tuple[str, ...] = ()
+    """附加正则列表，逐条编译后传递给 ``_should_skip_block``。
+    内置正则（时间戳/纯数字/系统提示等）**始终并行生效**，
+    config 提供的是追加规则，不替代内置逻辑。"""
+
+    inside_y_tolerance_px: float = 4.0
+    """``_completely_inside`` 的 Y 方向容差（px @ 1080 基准 × scale_w）。
+    默认 4.0 与 ``card_binding.inside_y_tolerance_px`` 对齐。"""
+
+    cross_band_distance_threshold_px: float = 50.0
+    """Step C 跨 band 距离门控基线（px @ 1080 × scale_w）。
+    文字底部到卡片所属 speaker_band 顶部超过此值则不作为昵称。"""
+
+    # ── speaker_band 参数（同名传给 build_prd_speaker_vertical_bands）──
+
+    first_avatar_gap_reject_baseline: int = 30
+    """orphan 间隙阈值（px @ 1080）。"""
+
+    first_band_top_extend_baseline: int = 20
+    """首个 band 上移量（px @ 1080）。"""
+
+    avatar_merge_min_sep_px: int = 24
+    """头像合并最小间距（px @ 1080 × scale_w）。"""
+
+    rejection_rules: tuple[dict[str, Any], ...] = field(default_factory=tuple)
+    """声明式文本/几何拒绝规则（rules_config rejection_rules；geometry 子集亦在此）。"""
+
+    geometry_rules: tuple[dict[str, Any], ...] = field(default_factory=tuple)
+    """附加几何规则（rules_config geometry_rules）。"""
+
+    group_display_name: str = ""
+    """会话顶栏群名 OCR；候选昵称 normalize 后与之 core 匹配则 drop。"""
+
+    use_declarative_rules: bool = True
+    """True 且 ``rejection_rules`` 非空时用声明式 filter 驱动 ``_classify`` / Step B。"""
+
 
 _ATTRIBUTION_PREFIX_DROPS: tuple[str, ...] = (
     "撤回了一条消息",
@@ -710,7 +748,12 @@ def _load_prd_layout_optional(
     bounds = compute_chat_content_vertical_bounds(arr, sw, screen_h=oh)
     ly, ry = detect_chat_side_avatar_ytops(arr, sw, bounds)
     timeline = merge_avatar_ytops_time_order(ly, ry)
-    return build_prd_speaker_vertical_bands(timeline, bounds, scale_w=sw)
+    return build_prd_speaker_vertical_bands(
+        timeline, bounds, scale_w=sw,
+        first_avatar_gap_reject_baseline=config.first_avatar_gap_reject_baseline,
+        first_band_top_extend_baseline=config.first_band_top_extend_baseline,
+        avatar_merge_min_sep_baseline=config.avatar_merge_min_sep_px,
+    )
 
 
 def _finalize_prd_attribution(
@@ -852,6 +895,7 @@ def _resume_thumb_bindings_and_orphans(
     original_width: int,
     config: NicknameOcrConfig,
     layout_opt: Any = None,
+    avatar_layout: Any = None,
     scale_w: float = 1.0,
     image_size: tuple[int, int] | None = None,
 ) -> tuple[tuple[ResumeThumbBinding, ...], int, set[int]]:
@@ -887,7 +931,7 @@ def _resume_thumb_bindings_and_orphans(
     # OCR bbox 与卡片 bbox 各有 ±2~3px 抖动：卡内标题行可能比卡顶高出 1~3px，
     # 若按严格包含判定会被误认为"卡外文字"而误绑为昵称（2026-06-11 真实案例）。
     # 真昵称行整体位于卡片上方（y2 < 卡顶），不受此容差影响。
-    _inside_tol = 4.0 * max(scale_w, 1.0)
+    _inside_tol = float(config.inside_y_tolerance_px) * max(scale_w, 1.0)
 
     def _completely_inside(block_bbox: tuple, card_bbox: tuple) -> bool:
         bx1, by1, bx2, by2 = block_bbox
@@ -902,6 +946,26 @@ def _resume_thumb_bindings_and_orphans(
             and by2 <= cy2 + _inside_tol
         )
 
+    def _completely_inside_avatar_x(block_bbox: tuple, *, cx: int, r: int) -> bool:
+        try:
+            from screenshot_vision_algorithm.android.wechat.algorithms.avatar_column import (
+                completely_inside_avatar_x_zone,
+            )
+        except ImportError:
+            return False
+        return completely_inside_avatar_x_zone(block_bbox, cx=cx, r=r)
+
+    def _avatar_cx_r_for_band(band_y0: float, band_y1: float) -> tuple[int, int] | None:
+        if avatar_layout is None or getattr(avatar_layout, "empty", True):
+            return None
+        try:
+            from screenshot_vision_algorithm.android.wechat.algorithms.avatar_column import (
+                left_avatar_cx_r_for_band,
+            )
+        except ImportError:
+            return None
+        return left_avatar_cx_r_for_band(avatar_layout, band_y0, band_y1)
+
     def _should_skip_block(b: "TextBlock") -> bool:
         t = (b.text or "").strip()
         if not t:
@@ -917,8 +981,25 @@ def _resume_thumb_bindings_and_orphans(
             return True
         if _is_favorite_card_label(t):
             return True
+        # ── 附加正则（来自 rules_config.yaml skip_patterns，编译后缓存）──
+        if _compiled_skip_patterns:
+            for _pat in _compiled_skip_patterns:
+                try:
+                    if _pat.search(t):
+                        return True
+                except Exception:
+                    continue
         return False
 
+    # ── 编译 config 追加的正则（函数内缓存，避免每次 block 重新编译）──
+    _compiled_skip_patterns: list[re.Pattern] = []
+    if config.skip_block_patterns:
+        for p in config.skip_block_patterns:
+            try:
+                _compiled_skip_patterns.append(re.compile(p))
+            except re.error:
+                pass
+
     bindings: list[ResumeThumbBinding] = []
     orphan = 0
     excluded_indices: set[int] = set()
@@ -1008,10 +1089,15 @@ def _resume_thumb_bindings_and_orphans(
 
                 matched_nickname: Optional[str] = None
                 best_y: float = float('inf')
+                _band_avatar_cx_r = _avatar_cx_r_for_band(_band_y0, _band_y1)
                 for i, b in enumerate(blocks):
                     bb = b.bbox_xyxy
                     _by1, _by2 = float(bb[1]), float(bb[3])
 
+                    # Step B 仅采纳 _classify 标为 nickname_candidate 的块（含 rejection_rules）
+                    if i < len(classes) and classes[i] != "nickname_candidate":
+                        continue
+
                     # ── 规则 (0)：block 必须与当前 speaker_band 有 Y 交集 ──
                     if not (_by2 > _band_y0 and _by1 < _band_y1):
                         continue
@@ -1046,6 +1132,12 @@ def _resume_thumb_bindings_and_orphans(
                     if is_fully_inside:
                         continue
 
+                    # PRD §8B：排除完全被包含在头像区 X 范围 [0, cx+r] 内的文字
+                    if _band_avatar_cx_r is not None:
+                        _acx, _ar = _band_avatar_cx_r
+                        if _completely_inside_avatar_x(bb, cx=_acx, r=_ar):
+                            continue
+
                     # ── 按距离选最优：取 y_bottom 最接近 band 上界的块 ──
                     if _by2 < best_y:
                         best_y = _by2
@@ -1056,26 +1148,38 @@ def _resume_thumb_bindings_and_orphans(
             best_i: Optional[int] = None
             best_bottom: float = -1.0
             card_top = float(tbb[1])
+            _step_c_avatar_cx_r: tuple[int, int] | None = None
+            if band_idx is not None and band_idx >= 0 and layout_opt is not None:
+                _sb_list_c = getattr(layout_opt, "speaker_bands", ())
+                if band_idx < len(_sb_list_c):
+                    _by0_c, _by1_c = float(_sb_list_c[band_idx][0]), float(_sb_list_c[band_idx][1])
+                    _step_c_avatar_cx_r = _avatar_cx_r_for_band(_by0_c, _by1_c)
             for i, b in enumerate(blocks):
                 bcx = float(b.bbox_xyxy[3])  # block bottom
                 if bcx >= card_top:
                     continue
+                if i < len(classes) and classes[i] != "nickname_candidate":
+                    continue
                 if _should_skip_block(b):
                     continue
+                if _step_c_avatar_cx_r is not None:
+                    _acx, _ar = _step_c_avatar_cx_r
+                    if _completely_inside_avatar_x(b.bbox_xyxy, cx=_acx, r=_ar):
+                        continue
                 if bcx > best_bottom:
                     best_bottom = bcx
                     best_i = i
 
             if best_i is not None:
                 # PRD §B.1 C：距离检查——文字底部到卡片所属 speaker_band 顶部
-                # 超过阈值（50px baseline × scale_w）则不作为昵称
+                # 超过阈值（config.cross_band_distance_threshold_px × scale_w）则不作为昵称
                 _use_as_nickname = True
                 if band_idx is not None and band_idx >= 0:
                     _sb_list = getattr(layout_opt, "speaker_bands", ())
                     if band_idx < len(_sb_list):
                         _band_y0 = float(_sb_list[band_idx][0])
                         _gap = _band_y0 - best_bottom  # positive → block above band
-                        _threshold = 50.0 * float(scale_w)
+                        _threshold = float(config.cross_band_distance_threshold_px) * float(scale_w)
                         if _gap > _threshold:
                             _use_as_nickname = False
                 if _use_as_nickname:
@@ -1257,34 +1361,95 @@ def _classify(
     avatar_layout: Any = None,
 ) -> str:
     """Return ``"nickname_candidate"`` / ``"bubble_text"`` / ``"drop"``."""
+    from screenshot_vision_algorithm.android.wechat.ocr.nickname_declarative_rules import (
+        geometry_rules_only,
+        run_geometry_rules_drop,
+        run_rejection_rules_drop,
+        text_matches_group_display_name,
+        text_rejection_rules,
+    )
+
     text = block.text.strip()
     if not text:
         return "drop"
     if block.confidence < config.min_confidence:
         return "drop"
-    if (
-        _is_pure_time(text)
-        or _is_pure_digits(text)
-        or _is_chat_timestamp_or_divider(text)
-        or _is_favorite_card_label(text)
-    ):
-        return "drop"
+
+    use_declarative = bool(
+        config.use_declarative_rules and config.rejection_rules
+    )
+
+    if use_declarative:
+        text_rules = text_rejection_rules(config.rejection_rules)
+        if text_rules and run_rejection_rules_drop(text, text_rules):
+            return "drop"
+        if config.group_display_name and text_matches_group_display_name(
+            text, config.group_display_name
+        ):
+            return "drop"
+        geo = geometry_rules_only(config.rejection_rules, config.geometry_rules)
+        if geo and run_geometry_rules_drop(
+            block,
+            geo,
+            screen_width=original_width,
+            median_height=median_height,
+            screen_midline_ratio=config.screen_midline_ratio,
+        ):
+            return "drop"
+    else:
+        if (
+            _is_pure_time(text)
+            or _is_pure_digits(text)
+            or _is_chat_timestamp_or_divider(text)
+            or _is_favorite_card_label(text)
+        ):
+            return "drop"
+
+    if _compiled_skip_patterns_for_config(config):
+        for _pat in _compiled_skip_patterns_for_config(config):
+            try:
+                if _pat.search(text):
+                    return "drop"
+            except Exception:
+                continue
 
     is_left = _is_on_left_half(block, original_width, config.screen_midline_ratio)
 
+    if _starts_with_system_prefix(text, config.system_prefix_drops):
+        return "bubble_text"
+
     if (
         len(text) <= config.nickname_max_chars
-        and not _starts_with_system_prefix(text, config.system_prefix_drops)
         and is_left
         and _is_avatar_column_nickname_row(
             block, original_width, config, avatar_layout
         )
     ):
+        if use_declarative:
+            geo = geometry_rules_only(config.rejection_rules, config.geometry_rules)
+            if geo and run_geometry_rules_drop(
+                block,
+                geo,
+                screen_width=original_width,
+                median_height=median_height,
+                screen_midline_ratio=config.screen_midline_ratio,
+            ):
+                return "bubble_text"
         return "nickname_candidate"
 
     return "bubble_text"
 
 
+def _compiled_skip_patterns_for_config(config: NicknameOcrConfig) -> tuple[re.Pattern[str], ...]:
+    out: list[re.Pattern[str]] = []
+    for p in config.skip_block_patterns:
+        try:
+            out.append(re.compile(p))
+        except re.error:
+            pass
+    return tuple(out)
+
+
 def _merge_two_text_blocks(a: TextBlock, b: TextBlock, *, joiner: str) -> TextBlock:
     ax1, ay1, ax2, ay2 = a.bbox_xyxy
     bx1, by1, bx2, by2 = b.bbox_xyxy
@@ -1712,6 +1877,7 @@ def extract_nicknames(
             original_width=original_width,
             config=cfg,
             layout_opt=layout_opt,
+            avatar_layout=avatar_layout,
             scale_w=scale_w,
             image_size=ocr_result.original_size,
         )
@@ -1836,6 +2002,7 @@ def extract_nicknames(
         original_width=original_width,
         config=cfg,
         layout_opt=layout_opt,
+        avatar_layout=avatar_layout,
         scale_w=scale_w,
         image_size=ocr_result.original_size,
     )

screenshot_vision_algorithm-0.3.13/src/screenshot_vision_algorithm/android/wechat/ocr/nickname_declarative_rules.py

@@ -0,0 +1,206 @@
+"""Declarative nickname filter rules (rejection_rules + geometry_rules).
+
+Mirrors ``skill_self_evolution.rule_runner`` semantics without requiring that
+package inside ``screenshot_vision_algorithm`` (pip 包自洽).
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from screenshot_vision_algorithm.android.wechat.ocr.text_ocr_adapter import TextBlock
+
+# Strip emoji / symbols for group-name core comparison (PRD 群备注 vs 顶栏).
+_GROUP_NAME_STRIP_RE = re.compile(
+    r"[\U0001F300-\U0001FAFF\U00002600-\U000027BF\U0000FE00-\U0000FE0F"
+    r"\(\)（）\[\]【】\s]+"
+)
+
+
+def normalize_group_display_core(text: str) -> str:
+    """Normalize group title/remark for comparison (drop emoji, spaces, brackets)."""
+    t = unicodedata.normalize("NFC", (text or "").strip())
+    t = _GROUP_NAME_STRIP_RE.sub("", t)
+    # Remove trailing member-count suffix e.g. 阿姨简历群(417)
+    t = re.sub(r"\(\d+\)$", "", t)
+    t = re.sub(r"（\d+）$", "", t)
+    return t.strip()
+
+
+def text_matches_group_display_name(text: str, group_display_name: str) -> bool:
+    """True when OCR text is the same group name as session top-bar title (core match)."""
+    gdn = normalize_group_display_core(group_display_name)
+    if not gdn or len(gdn) < 2:
+        return False
+    cand = normalize_group_display_core(text)
+    if not cand:
+        return False
+    if cand == gdn:
+        return True
+    # Substring only when both sides are long enough (avoid false positives).
+    if len(cand) >= 4 and len(gdn) >= 4:
+        if cand in gdn or gdn in cand:
+            return True
+    return False
+
+
+def _rule_drops_text(text: str, rule: dict[str, Any]) -> bool:
+    t = (text or "").strip()
+    if not t:
+        return True
+    rtype = rule.get("type")
+    action = rule.get("action", "drop")
+    if action != "drop":
+        return False
+    if rtype == "regex":
+        pat = rule.get("pattern")
+        if pat and re.search(str(pat), t):
+            return True
+    elif rtype == "prefix":
+        for kw in rule.get("keywords") or []:
+            if t.startswith(str(kw)):
+                return True
+    elif rtype == "length":
+        mn = int(rule.get("min", 0))
+        mx = int(rule.get("max", 999))
+        if not (mn <= len(t) <= mx):
+            return True
+    return False
+
+
+def text_rejection_rules(rules: tuple[dict[str, Any], ...] | list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        r for r in rules
+        if isinstance(r, dict) and r.get("type") in ("regex", "prefix", "length")
+    ]
+
+
+def geometry_rules_only(
+    rejection_rules: tuple[dict[str, Any], ...] | list[dict[str, Any]],
+    geometry_rules: tuple[dict[str, Any], ...] | list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    out = [r for r in rejection_rules if isinstance(r, dict) and r.get("type") == "geometry"]
+    out.extend(r for r in (geometry_rules or []) if isinstance(r, dict))
+    return out
+
+
+def run_rejection_rules_drop(text: str, rules: list[dict[str, Any]]) -> bool:
+    """Return True if any rule drops the text."""
+    for rule in rules:
+        if _rule_drops_text(text, rule):
+            return True
+    return False
+
+
+def _block_width(block: "TextBlock") -> int:
+    x1, _, x2, _ = block.bbox_xyxy
+    return max(0, int(x2) - int(x1))
+
+
+def _block_height(block: "TextBlock") -> int:
+    _, y1, _, y2 = block.bbox_xyxy
+    return max(1, int(y2) - int(y1))
+
+
+def _block_center_x(block: "TextBlock") -> float:
+    x1, _, x2, _ = block.bbox_xyxy
+    return (float(x1) + float(x2)) / 2.0
+
+
+def run_geometry_rules_drop(
+    block: "TextBlock",
+    rules: list[dict[str, Any]],
+    *,
+    screen_width: int,
+    median_height: float,
+    screen_midline_ratio: float = 0.5,
+) -> bool:
+    """Return True if any geometry rule drops the block."""
+    for rule in rules:
+        if not isinstance(rule, dict) or rule.get("type") != "geometry":
+            continue
+        if rule.get("action", "drop") != "drop":
+            continue
+        constraint = str(rule.get("constraint", ""))
+        operator = str(rule.get("operator", "lt"))
+        value = float(rule.get("value", 0))
+        matched = False
+
+        if constraint == "horizontal_position":
+            midline_x = float(screen_width) * float(screen_midline_ratio)
+            cx = _block_center_x(block)
+            if operator == "lt":
+                matched = cx < midline_x
+            elif operator == "lte":
+                matched = cx <= midline_x
+            elif operator == "gt":
+                matched = cx > midline_x
+            elif operator == "gte":
+                matched = cx >= midline_x
+        elif constraint == "bbox_width":
+            bw = float(_block_width(block))
+            if operator == "lt":
+                matched = bw < value
+            elif operator == "lte":
+                matched = bw <= value
+            elif operator == "gt":
+                matched = bw > value
+            elif operator == "gte":
+                matched = bw >= value
+        elif constraint == "char_height_ratio":
+            mh = max(float(median_height), 1.0)
+            ratio = float(_block_height(block)) / mh
+            if operator == "lt":
+                matched = ratio < value
+            elif operator == "lte":
+                matched = ratio <= value
+            elif operator == "gt":
+                matched = ratio > value
+            elif operator == "gte":
+                matched = ratio >= value
+
+        if matched:
+            return True
+    return False
+
+
+def block_passes_nickname_filters(
+    block: "TextBlock",
+    *,
+    rejection_rules: tuple[dict[str, Any], ...],
+    geometry_rules: tuple[dict[str, Any], ...],
+    group_display_name: str,
+    screen_width: int,
+    median_height: float,
+    screen_midline_ratio: float,
+    skip_patterns: tuple[str, ...] = (),
+) -> bool:
+    """Unified filter for Step B/C and declarative classify (True = may be nickname)."""
+    text = (block.text or "").strip()
+    if not text:
+        return False
+    text_rules = text_rejection_rules(rejection_rules)
+    if text_rules and run_rejection_rules_drop(text, text_rules):
+        return False
+    if group_display_name and text_matches_group_display_name(text, group_display_name):
+        return False
+    geo = geometry_rules_only(rejection_rules, geometry_rules)
+    if geo and run_geometry_rules_drop(
+        block,
+        geo,
+        screen_width=screen_width,
+        median_height=median_height,
+        screen_midline_ratio=screen_midline_ratio,
+    ):
+        return False
+    if skip_patterns:
+        for pat in skip_patterns:
+            try:
+                if re.search(pat, text):
+                    return False
+            except re.error:
+                continue
+    return True

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/src/screenshot_vision_algorithm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenshot_vision_algorithm
-Version: 0.3.8
+Version: 0.3.13
 Summary: Multi-platform screenshot vision algorithms: WeChat (card bbox, speaker bands, avatar detection, OCR helpers), XHS & Zhihu (planned)
 License: MIT
 Requires-Python: >=3.10
@@ -209,7 +209,7 @@ profile.templates_dir       # Path — 内嵌模板 PNG 目录
 
 | 函数 | 说明 |
 |------|------|
-| `detect_left_avatar_column_layout(...)` | 用 Hough 圆检测左侧头像列 |
+| `detect_left_avatar_column_layout(...)` | 群聊左列：圆角方块主路径，左列 `<3` 时 Hough 兜底 |
 | `find_avatar_anchor_for_nickname_bbox(...)` | 为昵称 bbox 找到对应的发言人头像锚点 |
 | `nickname_bbox_in_avatar_column(...)` | 判断昵称 bbox 是否在头像列区域内 |
 | `left_avatar_ytops(layout)` | 提取所有头像的 Y 坐标列表 |

{screenshot_vision_algorithm-0.3.8 → screenshot_vision_algorithm-0.3.13}/src/screenshot_vision_algorithm.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ src/screenshot_vision_algorithm/android/wechat/ocr/__init__.py
 src/screenshot_vision_algorithm/android/wechat/ocr/avatar_guard.py
 src/screenshot_vision_algorithm/android/wechat/ocr/badge_ocr.py
 src/screenshot_vision_algorithm/android/wechat/ocr/nickname_binding.py
+src/screenshot_vision_algorithm/android/wechat/ocr/nickname_declarative_rules.py
 src/screenshot_vision_algorithm/android/wechat/ocr/text_ocr_adapter.py
 src/screenshot_vision_algorithm/android/wechat/profiles/__init__.py
 src/screenshot_vision_algorithm/android/wechat/profiles/android.py
@@ -43,4 +44,5 @@ src/screenshot_vision_algorithm/android/wechat/templates/android/8.0.69/wechat_n
 src/screenshot_vision_algorithm/android/xhs/__init__.py
 src/screenshot_vision_algorithm/android/zhihu/__init__.py
 tests/test_card_bbox.py
+tests/test_chat_left_avatar.py
 tests/test_package.py

screenshot_vision_algorithm-0.3.13/tests/test_chat_left_avatar.py

@@ -0,0 +1,88 @@
+"""群聊左列头像：roundrect 主 + Hough 兜底 + 右列禁入。"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import cv2
+import pytest
+
+from screenshot_vision_algorithm.android.wechat.algorithms.avatar_column import (
+    CHAT_LEFT_AVATAR_HOUGH_FALLBACK_THRESHOLD,
+    detect_left_avatar_column_layout,
+    left_avatar_ytops,
+)
+from screenshot_vision_algorithm.android.wechat.algorithms.speaker_band import (
+    build_prd_speaker_vertical_bands,
+    compute_chat_content_vertical_bounds,
+    detect_chat_side_avatar_ytops,
+    merge_avatar_ytops_time_order,
+)
+
+_FIXTURE_ROOT = Path(
+    os.environ.get(
+        "SVA_CHAT_AVATAR_FIXTURE_ROOT",
+        r"E:\projects\housekeeping_ai_match\build\wx_match_sessions\wechat"
+        r"\ahxvcp3910405060\20260626\session_20260626093025_ahxvcp3910405060"
+        r"\customer_images",
+    )
+)
+
+_CASES = {
+    "scr_002": "002_chat_initial_ahxvcp3910405060_20260626093028_scaling.png",
+    "scr_054": "054_chat_resume_rescan_ahxvcp3910405060_20260626093325_scaling.png",
+    "scr_075": "075_chat_resume_rescan_ahxvcp3910405060_20260626093428_scaling.png",
+}
+
+
+def _load_case(name: str):
+    path = _FIXTURE_ROOT / _CASES[name]
+    if not path.is_file():
+        pytest.skip(f"fixture missing: {path}")
+    img = cv2.imread(str(path))
+    if img is None:
+        pytest.skip(f"unreadable fixture: {path}")
+    h, w = img.shape[:2]
+    sw = w / 1080.0
+    bounds = compute_chat_content_vertical_bounds(img, sw, screen_h=h)
+    return img, sw, bounds
+
+
+@pytest.mark.parametrize("name,min_bands", [("scr_002", 3), ("scr_054", 3), ("scr_075", 3)])
+def test_chat_left_avatar_roundrect_produces_multiple_bands(name: str, min_bands: int):
+    img, sw, bounds = _load_case(name)
+    layout = detect_left_avatar_column_layout(
+        img, sw, y_top=bounds.y_top, y_bottom_excl=bounds.y_bottom_excl,
+    )
+    assert len(layout.centroids) >= min_bands
+
+    ly, ry = detect_chat_side_avatar_ytops(img, sw, bounds)
+    assert ry == []
+    assert len(ly) >= min_bands
+
+    timeline = merge_avatar_ytops_time_order(ly, ry)
+    prd = build_prd_speaker_vertical_bands(timeline, bounds, scale_w=sw)
+    assert len(prd.speaker_bands) >= min_bands
+    assert prd.speaker_bands != ((bounds.y_top, bounds.y_bottom_excl),)
+
+
+def test_scr_054_not_single_false_right_band():
+    img, sw, bounds = _load_case("scr_054")
+    ly, ry = detect_chat_side_avatar_ytops(img, sw, bounds)
+    assert ry == []
+    timeline = merge_avatar_ytops_time_order(ly, ry)
+    prd = build_prd_speaker_vertical_bands(timeline, bounds, scale_w=sw)
+    assert len(prd.speaker_bands) >= 3
+
+
+def test_hough_fallback_threshold_constant():
+    assert CHAT_LEFT_AVATAR_HOUGH_FALLBACK_THRESHOLD == 3
+
+
+def test_left_ytops_match_layout():
+    img, sw, bounds = _load_case("scr_002")
+    layout = detect_left_avatar_column_layout(
+        img, sw, y_top=bounds.y_top, y_bottom_excl=bounds.y_bottom_excl,
+    )
+    assert left_avatar_ytops(layout) == [c.y_top for c in layout.centroids]