flowocr 0.1.0__py3-none-any.whl

flowocr/extract/refine_video.py

@@ -0,0 +1,271 @@
+"""回抠的**像素测量**那一半：开视频、按 run 的解码窗取裁剪、量终点 / 首字 / 全字的信号，写进 `job["measured"]`。
+
+2026-09-22 从 `flowocr.analyze.refine_boundaries` 拆出来（正规化 project-structure：打开视频、测像素信号在阶段 1；
+在已有证据上结算时间在阶段 2）。**这里不写时间**——`measure()` 的输出是五元组 `(new_e, ok_gone, sig, last_full, end_how)`，
+和 `run_ocr2 --refine-fused` 在线量好、经 `edge_refine.measured_from_records` 重建出来的是**同一种证据**；
+结算只有 `flowocr.analyze.refine_boundaries.apply` 一份。
+
+两条取帧的路：`refine_sequential`（cv2 顺序解码，窗内 retrieve、窗外 grab）和 `refine_ffmpeg`
+（ffmpeg 子进程只送各 run 的解码窗，av1 走 libdav1d；像素和 cv2 那条路不逐字节相同，时刻可能差 ±1 帧）。
+`make_job` 定每条 run 要哪些帧（打字机窗 / 结尾窗 / 模板帧），时间 ↔ 帧号两头都走 `ptsclock.IndexClock`。
+"""
+from __future__ import annotations
+
+import time
+
+import cv2
+import numpy as np
+
+from flowocr.extract import framesource, ptsclock
+from flowocr.extract import typewriter_fuse as TF
+
+
+PAD = 6
+"""首字 / 全字的裁剪在框外各扩这么多像素（首尾字格要带一点边，不然贴边的笔画被切掉）。"""
+
+LEAD_US = 50_000
+"""打字机窗在"首字前一个采样间隔"之外再往前多取这么久：窗口首帧当"还没字"的参照。"""
+
+def crop_of(frame: np.ndarray, box: list[float], pad: int = 0) -> tuple[np.ndarray, tuple[int, int, int, int]]:
+    """灰度裁剪 + 框在裁剪里的位置 (x0, y0, x1, y1)。贴边时外扩被截掉，位置照实给。"""
+    h, w = frame.shape[:2]
+    bx0, by0 = max(0, int(box[0])), max(0, int(box[1]))
+    bx1, by1 = min(w, int(box[2])), min(h, int(box[3]))
+    if bx1 - bx0 < 4 or by1 - by0 < 4:
+        return np.zeros((4, 4), np.uint8), (0, 0, 4, 4)
+    x0, y0 = max(0, bx0 - pad), max(0, by0 - pad)
+    x1, y1 = min(w, bx1 + pad), min(h, by1 + pad)
+    return (cv2.cvtColor(frame[y0:y1, x0:x1], cv2.COLOR_BGR2GRAY),
+            (bx0 - x0, by0 - y0, bx1 - x0, by1 - y0))
+
+def video_codec(path: str) -> str:
+    """容器里的视频编码四字码（`av01` / `vp09` / `avc1` / `hev1`…），小写；打不开就是空串。"""
+    cap = cv2.VideoCapture(path)
+    v = int(cap.get(cv2.CAP_PROP_FOURCC)) if cap.isOpened() else 0
+    cap.release()
+    return "".join(chr((v >> (8 * k)) & 0xFF) for k in range(4)).strip().lower() if v else ""
+
+def video_fps(path: str) -> float:
+    cap = cv2.VideoCapture(path)
+    fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+    cap.release()
+    # 打不开的文件 OpenCV 给 **−1**，`or 30.0` 放它过去：整条时间轴按负帧率算，
+    # 产物是垃圾而**一行报错都没有**（2026-09-17 审计时拿错路径撞上的：起点平均移动 8158 s）。
+    # `--decoder obs` 不开视频，但仍要这个 fps 换算帧号，所以这一步一样不能猜
+    if fps <= 0:
+        raise SystemExit(f"读不出帧率（{fps}）：{path} 打不开或不是视频。"
+                         f"回抠所有时刻都按它换算，猜一个会让整条时间轴错到不像话")
+    return fps
+
+SEEK_WORTH_FRAMES = 900
+"""跳过这么多帧以上才值得 seek，否则 grab 过去更便宜。
+按实测（seek 85 ms / grab 0.3 ms）盈亏点在约 280 帧，这里取三倍余量——
+估偏了也只是多 grab 一会儿，不会出错。"""
+
+def first_true(lo: int, hi: int, pred) -> tuple[int, bool]:
+    """[lo, hi] 里第一个满足的下标 + **找没找到**。都不满足时返回 `(hi, False)`。
+
+    第二个返回值不是可有可无的（methodology-audit-4 报告 C5）：
+    原来"没找到"和"边界正好在 hi"返回同一个值，调用方分不开，
+    于是**搜索失败的默认端点被当成了观测到的边界**。
+    """
+    for i in range(lo, hi + 1):
+        if pred(i):
+            return i, True
+    return hi, False
+
+def last_true(lo: int, hi: int, pred) -> tuple[int, bool]:
+    """[lo, hi] 里最后一个满足的下标 + 找没找到。都不满足时返回 `(lo, False)`。"""
+    for i in range(hi, lo - 1, -1):
+        if pred(i):
+            return i, True
+    return lo, False
+
+def make_job(run: dict, frame_us: int, us_per_frame: float, clock=None) -> dict:
+    """一条 run 要解码的帧窗。span = 一个采样间隔的帧数：
+
+    * `[lo, hi_start]`：打字机窗，从首字前一个多采样间隔到采样级全字之后一个采样间隔（最后一帧当"最终样子"）；
+    * `[e, hi]`：找全字消失；
+    * `mid`：消失判据的模板帧——**中间那次观测**，不是时间跨度的中点（n_obs=1 时中点已经没字了）。
+
+    **时间 ↔ 帧号两头都走 `clock`**（`ptsclock.IndexClock`，2026-09-17）：run 的时间是真实 pts，
+    而 `us_per_frame = 1e6 / src_fps` 是容器**平均**帧率——丢帧缺口的素材上两者差到几百毫秒（f4 20 分钟 −260 ms、
+    f3 7.2 h 处 9.5 s），窗口就开在错的地方、写回去的时刻也带着同一份偏差。
+    `clock=None` 时退回常量换算，和改之前**逐位相同**（CFR 素材上两者恒等）。"""
+    clock = clock or ptsclock.IndexClock(us_per_frame)
+    span = int(round(frame_us / us_per_frame))
+    s_idx = int(round(clock.idx_of(run["t_start"])))
+    e_idx = int(round(clock.idx_of(run["t_end"] - frame_us)))
+    mid_us = run["t_start"] + max(0, run.get("n_obs", 1) - 1) / 2 * frame_us
+    mid_idx = int(round(clock.idx_of(mid_us)))
+    tfs = run.get("t_full_sampled")
+    tfs_idx = int(round(clock.idx_of(tfs if tfs is not None else run["t_start"])))
+    lo = max(0, s_idx - span - int(round(LEAD_US / us_per_frame)))
+    # 窗口末帧就是"最终样子"的模板，**不许越过末次观测帧**：短条目（n_obs=2，采样级全字就是末次观测）
+    # 往后多取一个采样间隔，模板会落在字已经消失 / 下一句的帧上，全字出现被判成消失那一刻
+    # （水族馆 `(粉塵爆発…！)` 晚了 45 帧，2026-09-12）
+    hi_start = max(s_idx, min(tfs_idx + span, e_idx))
+    # 结尾窗：末次观测前半个多采样间隔（首帧当"字还完整"的模板）到 t_end 之后 0.2 s（淡出 / 交叉淡出的尾巴）
+    end_lo = max(mid_idx, int(round(clock.idx_of(run["t_end"] - 1.5 * frame_us - 50_000))))
+    end_hi = int(round(clock.idx_of(run["t_end"] + 200_000)))
+    return {"run": run, "box": run["box"], "s": s_idx, "e": e_idx, "mid": mid_idx, "span": span,
+            "end_lo": end_lo, "end_hi": end_hi,
+            "lo": min(lo, mid_idx, end_lo), "tw_lo": lo, "hi_start": hi_start,
+            "hi": max(e_idx + span, mid_idx, hi_start, end_hi),
+            "us_per_frame": us_per_frame, "clock": clock, "frame_us": frame_us, "crops": {}, "ocr": [],
+            "refined": False, "moved": False, "d_start": 0.0, "d_end": 0.0}
+
+def wants(job: dict, i: int) -> bool:
+    """这一帧在不在 job 的解码窗里（打字机窗 / 结尾窗 / 模板帧）。"""
+    return ((job["tw_lo"] <= i <= job["hi_start"]) or (job["e"] <= i <= job["hi"]) or i == job["mid"]
+            or (job["end_lo"] <= i <= job["end_hi"]))
+
+def refine_ffmpeg(video: str, jobs: list[dict], thr: float, progress_every: int, pix: str = "nv12",
+                  step: int = 1, scale: float = 1.0) -> None:
+    """同 refine_sequential，但解码走 ffmpeg 子进程：先把所有 job 要的帧号并成区间，`select` 只送这些帧
+    （av1 走 libdav1d，OpenCV 内置的 av1 解码慢 12 倍；hw-decode-results 报告）。
+    帧的像素和 cv2 那条路**不逐字节相同**（nv12 -> BGR 的转换，max|Δ| 约 3），回抠出的时刻可能差 ±1 帧。"""
+    if not jobs:
+        return
+    jobs.sort(key=lambda j: j["lo"])
+    cap = cv2.VideoCapture(video)
+    fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+    W, H = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)), int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    cap.release()
+    need = set()
+    for j in jobs:
+        need.update(i for i in range(j["lo"], j["hi"] + 1) if wants(j, i))
+    intervals = framesource.merge_intervals(sorted(need), gap=2)
+    keep = [j["mid"] for j in jobs]                  # 模板帧无论 step 都要
+    # **窗口解码要用同一份时钟**（2026-09-18 审计的 P1）：make_job 已经按真实 pts 算窗口了，
+    # 但 seek 还在按 base/src_fps 走，取到的帧和标的帧号会错配。时钟就是各 job 共用的那一个。
+    clock = jobs[0]["clock"]
+    src = framesource.FfmpegWindows(video, intervals, src_fps=fps, width=W, height=H, pix=pix,
+                                    step=step, keep=keep, scale=scale,
+                                    ts_of=(lambda i: clock.t_of(i) / 1e6) if len(clock) else None)
+    n_send = len(framesource.window_frames(intervals, step, keep))
+    print(f"  [解码] ffmpeg 窗口模式：{len(intervals)} 个区间、{n_send} 帧（step {step}、scale {scale}；"
+          f"顺序解码要过 {jobs[-1]['hi']} 帧）", flush=True)
+    if scale < 1.0:                                  # 框按同一比例缩；裁剪 / 融合都在缩后的像素上做
+        for j in jobs:
+            j["box"] = [v * scale for v in j["run"]["box"]]
+    active: list[dict] = []
+    ji, done = 0, 0
+    t0 = time.time()
+    for idx, _t, frame in src:
+        while ji < len(jobs) and jobs[ji]["lo"] <= idx:
+            active.append(jobs[ji]); ji += 1
+        for j in active:
+            if wants(j, idx):
+                j["crops"][idx] = crop_of(frame, j["box"], PAD)
+        still = []
+        for j in active:
+            if idx >= j["hi"] and idx >= j["mid"]:
+                measure(j, thr)
+                done += 1
+                if progress_every and done % progress_every == 0:
+                    print(f"  已回抠 {done}/{len(jobs)} 条，用时 {(time.time()-t0)/60:.1f} min", flush=True)
+            else:
+                still.append(j)
+        active = still
+    for j in active:
+        measure(j, thr)
+    if src.stopped_early:
+        print("  ⚠ ffmpeg 窗口解码提前结束：" + " | ".join(src.stderr_tail[-3:]), flush=True)
+
+def refine_sequential(video: str, jobs: list[dict], thr: float, progress_every: int) -> None:
+    """单向走一遍视频，每个 job 的解码窗一关就 `measure`（量终点、收集像素信号）；写时间在 `apply`。"""
+    if not jobs:
+        return
+    jobs.sort(key=lambda j: j["lo"])
+    cap = cv2.VideoCapture(video)
+    total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    idx, ji, done = 0, 0, 0
+    active: list[dict] = []
+    t0 = time.time()
+
+    while idx < total and (ji < len(jobs) or active):
+        while ji < len(jobs) and jobs[ji]["lo"] <= idx:
+            active.append(jobs[ji]); ji += 1
+        if not active:
+            nxt = jobs[ji]["lo"] if ji < len(jobs) else total
+            if nxt - idx > SEEK_WORTH_FRAMES:
+                cap.set(cv2.CAP_PROP_POS_FRAMES, nxt)
+                idx = nxt
+                continue
+        if not cap.grab():
+            break
+        need = [j for j in active if wants(j, idx)]
+        if need:
+            ok, frame = cap.retrieve()
+            if ok:
+                for j in need:
+                    j["crops"][idx] = crop_of(frame, j["box"], PAD)
+        idx += 1
+        still = []
+        for j in active:
+            if idx > j["hi"] and idx > j["mid"]:
+                measure(j, thr)
+                done += 1
+                if progress_every and done % progress_every == 0:
+                    print(f"  已回抠 {done}/{len(jobs)} 条，用时 {(time.time()-t0)/60:.1f} min", flush=True)
+            else:
+                still.append(j)
+        active = still
+    for j in active:
+        measure(j, thr)
+    cap.release()
+
+def measure(job: dict, thr: float) -> None:
+    """解码窗关上时调：量终点、收集首字 / 全字的像素信号（`typewriter_fuse.signals`），**不写时间**。"""
+    crops, run = job["crops"], job["run"]
+    job["crops"] = {}
+    if job["mid"] not in crops:
+        return
+
+    def inner(c):
+        img, (x0, y0, x1, y1) = c
+        return img[y0:y1, x0:x1]
+    template = inner(crops[job["mid"]])
+    if template.size < 64:
+        return
+
+    def looks_full(i: int) -> bool:
+        c = crops.get(i)
+        return c is not None and TF.ncc(inner(c), template) >= thr
+
+    # 没被观测到的那一侧**原样退回**，不写"精确"的新时间（audit-4 C5）。
+    # 终点和首字 / 全字各自有各自的证据：终点没观测到（长条目中途背景变了、模板不再像）
+    # 不该连带把打字机两个时刻也丢掉——gi-s2 上两条 17–23 s 的台词就是这么整条没回抠的。
+    t_gone, ok_gone = last_true(job["e"], job["hi"], looks_full)
+    clock = job["clock"]                             # 帧号 -> 真实时间（见 make_job 的说明）
+    old_e = run["t_end"]
+    new_e = int(round(clock.t_of(t_gone + 1))) if ok_gone else old_e
+    sig = None
+    idxs = [i for i in range(job["tw_lo"], job["hi_start"] + 1) if i in crops]
+    # step > 1 时窗内只有每 step 帧一张；两端都要在，中间至少有一半（step 1 时就是原来的"一帧不缺"）
+    if idxs and idxs[0] == job["tw_lo"] and idxs[-1] == job["hi_start"] and \
+            len(idxs) * job.get("step", 1) >= job["hi_start"] - job["tw_lo"] + 1:
+        sig = TF.signals(np.stack([crops[i][0] for i in idxs]), [int(round(clock.t_of(i))) for i in idxs],
+                         crops[idxs[-1]][1], run["text"])
+    # 结尾两个关键帧：字形对比度曲线（typewriter_fuse.end_keyframes）。给得出"完全消失"就用它当 t_end，
+    # 给不出（下一句紧接着在同位置出现、窗口首帧字就不完整）退回上面的整框相关系数
+    # 开放边界（见 `edge_refine.measured_from_records`）：最后还像的那一帧之后，窗里再没有真解到的帧——
+    # 一路像到窗尾，或者视频先结束了（片尾还在屏上的字）：没看到它消失，t_end 只是下界
+    end_open = ok_gone and not any(i in crops for i in range(t_gone + 1, job["hi"] + 1))
+    end_how = ("open" if end_open else "ncc") if ok_gone else None
+    last_full = None
+    eidx = [i for i in range(job["end_lo"], job["end_hi"] + 1) if i in crops]
+    if eidx and eidx[0] == job["end_lo"] and eidx[-1] == job["end_hi"] and \
+            len(eidx) * job.get("step", 1) >= job["end_hi"] - job["end_lo"] + 1:
+        last_full, gone = TF.end_keyframes(np.stack([crops[i][0] for i in eidx]),
+                                           [int(round(clock.t_of(i))) for i in eidx], crops[eidx[0]][1], run["text"])
+        # 末次观测那一帧 OCR 还读到了字：曲线说更早就消失 = 被背景 / 模板骗了，不采纳
+        # （水族馆一条被判到 t_full_sampled 之前，产物校验当场拒收，2026-09-12）
+        if gone is not None and gone > clock.t_of(job["e"]):
+            new_e, ok_gone, end_how = gone, True, "curve"
+        if last_full is not None and last_full < clock.t_of(job["e"]) - job["frame_us"]:
+            last_full = None
+    if end_how == "open":
+        last_full = None
+    job["measured"] = (new_e, ok_gone, sig, last_full, end_how)

flowocr/extract/regions.py

@@ -0,0 +1,387 @@
+"""自选 OCR 范围与识别组（ocr-regions 计划）：范围的解析、某一时刻的生效遮罩、det 框按遮罩拆分。
+
+**语义**（方案，owner 定）：
+
+* 一个识别组 = 若干正矩形 / 负矩形。坐标是整幅画面宽高的**百分比**，可带原片时间段 `[t0, t1)`（秒，缺省 = 片头 / 片尾）。
+  组 g 在时刻 t 的有效范围 `R_g(t) = ∪ 生效正矩形 − ∪ 生效负矩形`。
+  组里**一个正矩形都没配** = 隐含全屏正矩形；**配了但此刻一个都不生效** = 此刻范围为空（不退回全屏）。
+* 范围外的像素按 rec 的 padding 语义**填中灰**：rec 归一化 `(x/255 − 0.5)/0.5` 后补 0，对应原像素 127.5；
+  uint8 只能取整，用 `FILL = 128`（张量里是 +0.0039，不宣称逐位相同，方案）。det 看到的是**同一种颜色**的像素，
+  不是它张量里的 0（det 的逐通道归一化不同）。
+* **det 框按遮罩拆**：框 B 里的有效像素 `B ∩ R_g(t)` 没有 → 丢；连通 → 一个框（有孔也不拆）；
+  **被完全分断成几块 → 每块一个子框**，裁到那一块的最小外接矩形，外接矩形里**不属于它的有效像素也要涂灰**
+  （包括同一父框的另一块）。连通性是**框内有效范围**的连通性，按 **4 邻接**（只在角上相碰不算连通）。
+  没被分断的框也裁到有效部分的外接矩形：外面那圈本来就是灰的，留着只会让 rec 读一段灰。
+* 时间：范围只在"配置切换"时刻变（`boundaries`）；那一刻前后的观测**不能被一个事件跨过**——
+  由下游按 `_meta.regions` 里的切点断开（build_tracks），这里只负责给出切点。
+
+像素坐标：百分比 × 宽高后**四舍五入**，矩形是半开区间 `[x0, x1) × [y0, y1)`，并截到画面内。
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+FILL = 128
+"""范围外像素的填充值（见文件头：rec padding 的 127.5 取整）。"""
+
+
+@dataclass(frozen=True)
+class Rect:
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+    neg: bool = False
+    t0: float | None = None
+    t1: float | None = None
+
+    def active(self, t: float) -> bool:
+        return (self.t0 is None or t >= self.t0) and (self.t1 is None or t < self.t1)
+
+    def pixels(self, W: int, H: int) -> tuple[int, int, int, int]:
+        c = lambda v, n: min(n, max(0, int(round(v / 100.0 * n))))   # noqa: E731
+        return c(self.x0, W), c(self.y0, H), c(self.x1, W), c(self.y1, H)
+
+
+def parse_rect(d: dict) -> Rect:
+    box = d["box"]
+    if len(box) != 4:
+        raise ValueError(f"矩形要 [x0, y0, x1, y1]（百分比）：{d}")
+    x0, y0, x1, y1 = (float(v) for v in box)
+    if not (0 <= x0 < x1 <= 100 and 0 <= y0 < y1 <= 100):
+        raise ValueError(f"矩形坐标要 0 ≤ x0 < x1 ≤ 100、0 ≤ y0 < y1 ≤ 100（百分比）：{d}")
+    t = d.get("t") or [None, None]
+    t0, t1 = (None if v is None else float(v) for v in t)
+    if t0 is not None and t1 is not None and not t0 < t1:
+        raise ValueError(f"时间段要 t0 < t1：{d}")
+    return Rect(x0, y0, x1, y1, bool(d.get("neg", False)), t0, t1)
+
+
+class RegionGroup:
+    """一个识别组在一段视频上的范围。`mask_at(t)` 返回 None = 此刻不受限（全屏），否则 H×W 的 bool。"""
+
+    def __init__(self, name: str, rects: list[Rect], W: int, H: int) -> None:
+        self.name, self.rects, self.W, self.H = name, list(rects), W, H
+        self.has_pos = any(not r.neg for r in self.rects)
+        self._cache: dict[tuple, np.ndarray | None] = {}
+
+    @property
+    def unrestricted(self) -> bool:
+        """整段都是全屏（默认组，或者只有空的配置）：调用方可以整个跳过遮罩。"""
+        return not self.rects
+
+    def key_at(self, t: float) -> tuple[int, ...]:
+        return tuple(i for i, r in enumerate(self.rects) if r.active(t))
+
+    def mask_for(self, key: tuple[int, ...]) -> np.ndarray | None:
+        if key in self._cache:
+            return self._cache[key]
+        act = [self.rects[i] for i in key]
+        pos = [r for r in act if not r.neg]
+        neg = [r for r in act if r.neg]
+        if not self.has_pos and not neg:
+            m = None                                       # 没配正矩形、此刻也没负矩形：全屏
+        else:
+            m = np.zeros((self.H, self.W), bool)
+            if self.has_pos:
+                for r in pos:
+                    x0, y0, x1, y1 = r.pixels(self.W, self.H)
+                    m[y0:y1, x0:x1] = True
+            else:
+                m[:] = True                                # 没配正矩形 = 隐含全屏正矩形，仍扣负矩形
+            for r in neg:
+                x0, y0, x1, y1 = r.pixels(self.W, self.H)
+                m[y0:y1, x0:x1] = False
+            if m.all():
+                m = None
+        self._cache[key] = m
+        return m
+
+    def mask_at(self, t: float) -> np.ndarray | None:
+        return self.mask_for(self.key_at(t))
+
+    def boundaries(self) -> list[float]:
+        """范围可能变化的时刻（秒，升序）。只列**真的变了遮罩**的：拆法不同的等价配置不产生切点。"""
+        ts = sorted({v for r in self.rects for v in (r.t0, r.t1) if v is not None})
+        out = []
+        for t in ts:
+            before, after = self.mask_for(self.key_at(t - 1e-6)), self.mask_for(self.key_at(t))
+            if not _same(before, after):
+                out.append(t)
+        return out
+
+    def observable_us(self, box, t0_us: int, t1_us: int) -> int:
+        """[t0, t1) 里这个框位**看得见**的时长（µs）：按切点分段，**框里有有效像素**的段加起来（方案：
+        常驻度 / UI 占比 / 时间支持的分母用"相关位置允许观察的时间"，关闭时段不算文字缺席）。
+
+        2026-09-23（Codex 审计 P2）：原来只看框中心——带孔的连通框（有孔不拆）中心落在孔里、或区域的中位中心落在两块之间时，
+        明明看得见却算成 0，调用方再 `max(1, ·)` 把占比放大成上百万。"""
+        cuts = [int(round(b * 1e6)) for b in self.boundaries() if t0_us < b * 1e6 < t1_us]
+        edges = [t0_us, *cuts, t1_us]
+        tot = 0
+        for a, b in zip(edges, edges[1:]):
+            m = self.mask_at((a + b) / 2e6)
+            if m is None or box_hits(box, m):
+                tot += b - a
+        return tot
+
+    def union_bbox(self) -> tuple[int, int, int, int] | None:
+        """整段里**任何时刻**有效像素的外接矩形 `(x0, y0, x1, y1)`（像素，右下开）；某时刻全屏 / 从来没有有效像素时返回 None（没得裁）。
+        方案的"遮罩加单个最小外接矩形"：一个**静态**的框，盖住每一刻的有效范围——时变配置也对（框里被关掉的部分本来就是涂过的）。"""
+        keys = {self.key_at(-1e18)} | {self.key_at(t) for t in self.boundaries()}
+        rows = cols = None
+        for key in keys:
+            m = self.mask_for(key)
+            if m is None:
+                return None
+            r, c = m.any(axis=1), m.any(axis=0)
+            rows = r if rows is None else rows | r
+            cols = c if cols is None else cols | c
+        if rows is None or not rows.any():
+            return None
+        ys, xs = np.flatnonzero(rows), np.flatnonzero(cols)
+        return int(xs[0]), int(ys[0]), int(xs[-1]) + 1, int(ys[-1]) + 1
+
+    def changed_area(self, t: float) -> np.ndarray | None:
+        """切点 t 前后遮罩不同的像素（bool H×W）；None = 没变。下游拿它判"哪些事件被这个切点切到"。"""
+        before, after = self.mask_for(self.key_at(t - 1e-6)), self.mask_for(self.key_at(t))
+        if _same(before, after):
+            return None
+        full = np.ones((self.H, self.W), bool)
+        return (full if before is None else before) != (full if after is None else after)
+
+
+def take(polys: list, boxes: list, own_of: dict, keep: list[int]) -> tuple[list, list, dict]:
+    """按保留的下标 `keep` 同时取多边形、框和子框遮罩（`split_polys` 的三件套是平行的，**必须一起重排**）。"""
+    return ([polys[i] for i in keep], [boxes[i] for i in keep],
+            {j: own_of[i] for j, i in enumerate(keep) if i in own_of})
+
+
+def box_hits(box, area: np.ndarray) -> bool:
+    """框（至少 1 像素，截到画面内）里有没有 `area` 为真的像素。"""
+    H, W = area.shape
+    x0, y0 = min(W - 1, max(0, int(box[0]))), min(H - 1, max(0, int(box[1])))
+    x1, y1 = max(x0 + 1, min(W, int(box[2]))), max(y0 + 1, min(H, int(box[3])))
+    return bool(area[y0:y1, x0:x1].any())
+
+
+def _same(a: np.ndarray | None, b: np.ndarray | None) -> bool:
+    if a is None or b is None:
+        return a is None and b is None
+    return bool(np.array_equal(a, b))
+
+
+def fill_rects(mask: np.ndarray) -> list[tuple[int, int, int, int]]:
+    """`~mask` 拆成矩形 `(y0, y1, x0, x1)`：先按"行完全相同"分横带，每条带里按列取连续段。**纯函数，守卫直接测。**
+    遮罩都是矩形的并减矩形，拆出来只有几块；一个遮罩只拆一次（`apply_mask` 按对象缓存）。"""
+    H = mask.shape[0]
+    cuts = np.flatnonzero(np.any(mask[1:] != mask[:-1], axis=1)) + 1
+    ys = [0, *cuts.tolist(), H]
+    out = []
+    for y0, y1 in zip(ys, ys[1:]):
+        d = np.diff(np.concatenate(([0], (~mask[y0]).astype(np.int8), [0])))
+        out += [(y0, y1, int(a), int(b)) for a, b in zip(np.flatnonzero(d == 1), np.flatnonzero(d == -1))]
+    return out
+
+
+_RECTS: dict[int, tuple[np.ndarray, list]] = {}
+
+
+def apply_mask(frame: np.ndarray, mask: np.ndarray | None) -> np.ndarray:
+    """范围外涂 FILL（**原地**，返回同一个数组）。frame 是 H×W×C 或 H×W，和 mask 同尺寸。
+    按矩形切片赋值、结果和 `frame[~mask] = FILL` 逐位相同——布尔索引在 1080p 上一帧 48 ms，
+    自选范围的一组整体反而比全屏慢 59%（hsr-s2 35.7 对 22.4 s，2026-09-24）；切片赋值约 1 ms。"""
+    if mask is None:
+        return frame
+    hit = _RECTS.get(id(mask))
+    if hit is None or hit[0] is not mask:               # 遮罩对象是 RegionGroup / aux_masker 缓存着的，id 稳定
+        hit = _RECTS[id(mask)] = (mask, fill_rects(mask))
+    for y0, y1, x0, x1 in hit[1]:
+        frame[y0:y1, x0:x1] = FILL
+    return frame
+
+
+def label4(m: np.ndarray) -> tuple[int, np.ndarray]:
+    """4 邻接连通域标号（同 `cv2.connectedComponents(connectivity=4)` 的约定：0 = 背景，块从 1 起），**不依赖 cv2**（守卫在没装 cv2 的解释器里跑）。
+    做法：按行 / 列的变化点把遮罩压成小网格——任意两条相邻变化点之间的格子内部必然一致——在网格上 BFS，再展开回像素。
+    范围是轴对齐矩形拼出来的，网格只有几格到几十格。"""
+    h, w = m.shape
+    yb = np.concatenate(([0], np.flatnonzero(np.any(m[1:] != m[:-1], axis=1)) + 1, [h]))
+    xb = np.concatenate(([0], np.flatnonzero(np.any(m[:, 1:] != m[:, :-1], axis=0)) + 1, [w]))
+    cell = m[yb[:-1]][:, xb[:-1]]
+    cl = np.zeros(cell.shape, np.int32)
+    n = 0
+    for i0, j0 in zip(*np.nonzero(cell)):
+        if cl[i0, j0]:
+            continue
+        n += 1
+        cl[i0, j0] = n
+        stack = [(i0, j0)]
+        while stack:
+            i, j = stack.pop()
+            for a, b in ((i - 1, j), (i + 1, j), (i, j - 1), (i, j + 1)):
+                if 0 <= a < cell.shape[0] and 0 <= b < cell.shape[1] and cell[a, b] and not cl[a, b]:
+                    cl[a, b] = n
+                    stack.append((a, b))
+    lab = np.repeat(np.repeat(cl, np.diff(yb), axis=0), np.diff(xb), axis=1)
+    return n + 1, lab
+
+
+def split_box(box, mask: np.ndarray | None) -> list[tuple[list[int], np.ndarray | None]]:
+    """一个 det 框按遮罩拆（见文件头）。返回 [(子框, own)]：`own` 是子框大小的 bool，
+    **子框里有不属于这一块的有效像素时**才给（rec / 复用取裁剪时要把 ~own 涂灰），否则 None。
+    mask 为 None（此刻全屏）原样返回。"""
+    bx0, by0, bx1, by1 = (int(v) for v in box)
+    if mask is None:
+        return [([bx0, by0, bx1, by1], None)]
+    H, W = mask.shape
+    # det 框可能略出画面：负坐标切片会从另一头绕回来，先截到画面里再切
+    x0, y0, x1, y1 = max(0, bx0), max(0, by0), min(W, bx1), min(H, by1)
+    m = mask[y0:y1, x0:x1]
+    if m.size and m.all():
+        return [([bx0, by0, bx1, by1], None)]              # 整框都在范围里：原样（不拿截过的框替换）
+    if not m.any():
+        return []
+    n, lab = label4(m)
+    out = []
+    for k in range(1, n):
+        ys, xs = np.nonzero(lab == k)
+        sx0, sy0, sx1, sy1 = int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1
+        sub = lab[sy0:sy1, sx0:sx1]
+        own = sub == k
+        foreign = (sub != k) & (sub != 0)
+        out.append(([x0 + sx0, y0 + sy0, x0 + sx1, y0 + sy1], own if foreign.any() else None))
+    out.sort(key=lambda s: (s[0][0], s[0][1]))
+    return out
+
+
+def masked_crop(frame: np.ndarray, box, own: np.ndarray | None) -> np.ndarray:
+    """子框的裁剪：`own` 给了就把不属于这一块的像素涂灰（返回副本，不写坏源帧）。"""
+    x0, y0, x1, y1 = box
+    c = frame[y0:y1, x0:x1]
+    if own is None:
+        return c
+    c = c.copy()
+    c[~own] = FILL
+    return c
+
+
+# ---------- 接进管线用的几件（run_ocr2 / build_tracks） ----------
+
+def group_spec(path: str | Path, name: str = "") -> dict:
+    """配置文件里挑出**一个组**的规格（规范化的 dict，进 `_meta.config` 当复用判据用：同内容换路径算同一条臂，
+    改了文件内容就对不上）。文件里只有一个组时 `name` 可以不给；多个组必须给——每组是一条独立 OCR 线（方案）。"""
+    spec = json.loads(Path(path).read_text(encoding="utf-8"))
+    groups = spec.get("groups") or [{"name": "all", "rects": []}]          # 没有组 = 一个隐含的全屏组（方案表第一行）
+    names = [g.get("name") for g in groups]
+    if any(not n for n in names) or len(set(names)) != len(names):
+        raise ValueError(f"{path}：每个组要有唯一的 name（产物按组分文件）：{names}")
+    if not name:
+        if len(groups) != 1:
+            raise ValueError(f"{path} 里有 {len(groups)} 个组 {names}，要用 --region-group 挑一个")
+        g = groups[0]
+    else:
+        hit = [g for g in groups if g.get("name") == name]
+        if not hit:
+            raise ValueError(f"{path} 里没有组 {name!r}（有 {names}）")
+        g = hit[0]
+    rects = [parse_rect(r) for r in g.get("rects") or ()]          # 早校验
+    return {"name": g["name"], "rects": [{"box": [r.x0, r.y0, r.x1, r.y1], "neg": r.neg, "t": [r.t0, r.t1]}
+                                         for r in rects]}
+
+
+def from_spec(spec: dict, W: int, H: int) -> RegionGroup:
+    """`group_spec` 的 dict -> RegionGroup（run_ocr2 起组、build_tracks 从 obs 的 `_meta.regions` 重建都走它）。"""
+    return RegionGroup(spec["name"], [parse_rect(r) for r in spec.get("rects") or ()], W, H)
+
+
+class MaskedSource:
+    """包一层取帧来源：每帧按它的真实 pts 涂掉范围外的像素（**det 之前**，方案），其余属性原样转给里面那个。
+    帧是来源每次新给的数组（run_ocr2 的 det_stream 注释），原地涂不会写坏别人的东西。"""
+
+    def __init__(self, source, group: RegionGroup) -> None:
+        self._src, self._g = source, group
+
+    def __iter__(self):
+        for idx, t_sec, frame in self._src:
+            yield idx, t_sec, apply_mask(frame, self._g.mask_at(t_sec))
+
+    def __getattr__(self, k):
+        return getattr(self._src, k)
+
+
+def aux_masker(group: RegionGroup, Ws: int, Hs: int, src_fps: float):
+    """辅助流（缩小的灰度帧，edge_refine 的帧环）用的遮罩：同一个范围按比例缩到辅助流尺寸（最近邻），按帧号换算时间。
+    ⚠ 辅助流只有帧号没有逐帧 pts（edge_refine 文件头），时间按 `帧号 / 名义帧率` 算——切点附近可能差一帧。
+    辅助流的帧可能是只读的（`np.frombuffer`），要涂就先拷。"""
+    ry = np.minimum((np.arange(Hs) * group.H) // Hs, group.H - 1)       # 最近邻取样（不依赖 cv2）
+    rx = np.minimum((np.arange(Ws) * group.W) // Ws, group.W - 1)
+    cache: dict[tuple, np.ndarray | None] = {}
+
+    def pre(idx: int, frame: np.ndarray) -> np.ndarray:
+        key = group.key_at(idx / src_fps)
+        if key not in cache:
+            m = group.mask_for(key)
+            cache[key] = None if m is None else m[ry][:, rx]
+        m = cache[key]
+        if m is None:
+            return frame
+        return apply_mask(frame.copy(), m)
+    return pre
+
+
+class CroppedDet:
+    """`--region-crop`（方案的对照臂）：det 只看组范围的静态外接矩形那一块（`RegionGroup.union_bbox`；范围外本来就涂过），
+    多边形平移回原片坐标。和 `FastDet` 同接口（`predict` / `predict_batch`）。
+    ⚠ **会改 det 的输入尺寸**（缩放策略按边长走，小块可能被放大）——框会变，所以它进复用判据、是一条要单独对质量和速度的臂，不是调度旋钮。"""
+
+    def __init__(self, inner, bbox: tuple[int, int, int, int]) -> None:
+        self.inner, self.bbox = inner, bbox
+        self.off = np.array([bbox[0], bbox[1]])
+
+    def _crop(self, img: np.ndarray) -> np.ndarray:
+        x0, y0, x1, y1 = self.bbox
+        return np.ascontiguousarray(img[y0:y1, x0:x1])
+
+    def _shift(self, polys):
+        return [np.asarray(p) + self.off for p in polys]
+
+    def predict(self, img: np.ndarray):
+        polys, scores = self.inner.predict(self._crop(img))
+        return self._shift(polys), scores
+
+    def predict_batch(self, imgs: list) -> list[tuple]:
+        return [(self._shift(p), s) for p, s in self.inner.predict_batch([self._crop(im) for im in imgs])]
+
+    # 流水的两半（`FastDet.infer_batch` / `post_batch`）：裁在前半、平移在后半
+    def infer_batch(self, imgs: list) -> tuple:
+        return self.inner.infer_batch([self._crop(im) for im in imgs])
+
+    def post_batch(self, state: tuple) -> list[tuple]:
+        return [(self._shift(p), s) for p, s in self.inner.post_batch(state)]
+
+
+def split_polys(polys, mask: np.ndarray | None):
+    """det 的多边形按遮罩拆（`split_box`）。返回 (新多边形表, 新框表, {新下标: own})。
+    框没被遮到的原样保留多边形；裁过 / 拆过的换成子框的矩形（几何裁剪不是模型的新检测，方案第 2 条）。"""
+    boxes_in = [[round(min(float(p[0]) for p in q)), round(min(float(p[1]) for p in q)),     # 口径同 run_ocr2.poly_to_box
+                 round(max(float(p[0]) for p in q)), round(max(float(p[1]) for p in q))] for q in polys]
+    if mask is None:
+        return list(polys), boxes_in, {}
+    out_p, out_b, own_of = [], [], {}
+    for q, b in zip(polys, boxes_in):
+        for sb, own in split_box(b, mask):
+            out_p.append(q if sb == b else [[sb[0], sb[1]], [sb[2], sb[1]], [sb[2], sb[3]], [sb[0], sb[3]]])
+            if own is not None:
+                own_of[len(out_b)] = own
+            out_b.append(sb)
+    return out_p, out_b, own_of
+
+
+def cuts_us(group: RegionGroup) -> list[tuple[int, np.ndarray]]:
+    """时间关闭段的切点（µs）+ 那一刻遮罩变了的像素：下游判"哪些事件被这个切点切到"（build_tracks.build_runs）。"""
+    return [(int(round(t * 1e6)), group.changed_area(t)) for t in group.boundaries()]