flowocr 0.1.0__py3-none-any.whl

flowocr/extract/fast_det.py

@@ -0,0 +1,214 @@
+"""det 的前后处理（推理在 ORT 服务里）。前处理最早是为绕开 PaddleX 的 Python 前处理链写的，要求和它**逐字节相同**。
+
+为什么（fps-and-rec-budget 报告）：det 每帧的时间里，`run()` 和进出拷贝之外
+还有一大块是 **PaddleX 的 Python 前后处理 + 胶水**——换运行时（ORT / TensorRT）动不到它。
+它有多大，同一次运行里的逐段计时见 一次性探针 `probe_infer_split.py`（原来那个"约 12 ms"
+是跨两次运行相减估的，端到端只兑现了 3–4 ms/帧，别再引）。这一层做的事本身很少：
+
+    Read(PP-OCRv6 det 的配置里是 BGR，不换序) -> Resize(长边 960、对齐 32)
+    -> Normalize(逐通道 astype/乘/加) -> ToCHW(transpose) -> ToBatch(stack)
+
+慢在实现：`Normalize` 走 `cv2.split` -> 三次 `astype(float32)` -> 三次乘加 -> `cv2.merge`，
+每一步都新建一个 6.3 MB 的数组；再加上每个 op 上的 `@benchmark.timeit` 装饰器。
+
+这里把 **astype + 乘 + 加** 折成**一张 256×1×3 的 float32 LUT**，`cv2.LUT` 一趟 C++ 出结果；
+若某个模型的 Read 真要 RGB，换序也折进 LUT 的下标（见 `__init__` 里按 Read op 实测的那段）。
+**这是恒等变换，不是近似**：LUT 里存的就是 `v * alpha[c] + beta[c]`，
+uint8 的 256 个取值全枚举，float32 的乘加逐位相同。
+
+后处理（DBPostProcess）是正确性关键的一块：用 `flowocr.extract.detpost` 里照抄 PaddleX 的那份
+（照抄时和 PaddleX 逐字节相同；2026-10 运行时去掉 Paddle 之后，守卫对着冻结的 PaddleX 输出做回归）。
+
+用法：
+
+    fast = FastDet.from_onnx(onnx_path, runner, default_yml_ok)  # 配置读 ONNX 旁边的 inference.yml，后处理是 detpost 的
+    polys = fast.predict(frame_bgr)
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from flowocr.extract import detpost
+from flowocr.extract import timeline as _tl   # --timeline：det 拆成前处理 / 推理 / 后处理三段（关着零开销）
+
+
+class FastDet:
+    """一组前后处理参数（`detpost.DetSpec`）+ 一个 `runner([blob]) -> preds` + 一个后处理对象。"""
+
+    def __init__(self, spec: detpost.DetSpec, runner, post_op) -> None:
+        self.spec = spec
+        self.runner = runner
+        self.post_op = post_op
+        self.thresh, self.box_thresh, self.unclip_ratio = spec.thresh, spec.box_thresh, spec.unclip_ratio
+        self.max_side_limit = spec.max_side_limit
+        self.limit_side_len, self.limit_type = spec.limit_side_len, spec.limit_type
+
+        # **通道序按配置的 Read op 来，别照 PaddleX 源码猜**：`_build()` 里写的是 `ReadImage(format="RGB")`，
+        # 但配置里的 `DecodeImage: img_mode: BGR` 会把它整个换掉——PP-OCRv6 det 实际是
+        # **BGR 进、alpha/beta 直接按通道下标用**（那组常数虽然长得像 ImageNet 的 RGB 均值，
+        # 但模型就是这么训的）。我按源码前几行假设了换序，产物立刻对不上。
+        if spec.img_mode == "RGB":
+            self._swap = True          # 需要 BGR->RGB：换序折进 LUT 下标
+            order = [2, 1, 0]
+        elif spec.img_mode == "BGR":
+            self._swap = False
+            order = [0, 1, 2]
+        else:
+            raise ValueError(f"快路径不支持 Read format={spec.img_mode}")
+
+        lut = np.empty((256, 1, 3), np.float32)
+        v = np.arange(256, dtype=np.float32)
+        for c in range(3):
+            k = order[c]               # 输入第 c 通道在模型眼里是第 k 个通道
+            lut[:, 0, c] = v * np.float32(spec.alpha[k]) + np.float32(spec.beta[k])
+        self._lut = lut
+        self._bufs: dict[str, np.ndarray] = {}
+
+    @classmethod
+    def from_onnx(cls, onnx_path: str, runner, default_yml_ok: bool) -> "FastDet":
+        """配置读 ONNX 旁边的 `inference.yml`（官方仓库自带；模型名也从它来，`spec.model_name`），后处理用 `detpost.DBPostProcess`。
+        旁边没有 yml 时**只有** `default_yml_ok`（默认模型的官方 ONNX / 以前自转的 `ocr_args.OLD_DET_ONNX`，
+        `ocr_args.EQUIV_VALUES` 把两者当同一类）按默认模型的官方 yml 取；自带的别的 ONNX 缺 yml 就报错——
+        按默认模型的阈值和缩放跑别的权重，框会悄悄变（审计 2026-09-25）。"""
+        yml = Path(onnx_path).with_name("inference.yml")
+        if not yml.is_file():
+            if not default_yml_ok:
+                raise ValueError(f"{onnx_path} 旁边没有 inference.yml：自带的 det ONNX 要连同它的 inference.yml 放在同一个目录")
+            from flowocr import models
+            yml = Path(models.path("det")).with_name("inference.yml")
+            print(f"[det] {onnx_path} 旁边没有 inference.yml，前后处理配置按默认模型的官方 yml：{yml}", flush=True)
+        spec = detpost.DetSpec.from_yml(yml)
+        return cls(spec, runner, detpost.DBPostProcess(spec))
+
+    # -- 前处理 ---------------------------------------------------------------
+
+    def _resize_shape(self, h: int, w: int) -> tuple[int, int, float, float]:
+        """照抄 processors.py 的 resize_image_type0，**包括那两处 int() 截断**。"""
+        lsl, lt = self.limit_side_len, self.limit_type
+        if lt == "max":
+            ratio = float(lsl) / (h if h > w else w) if max(h, w) > lsl else 1.0
+        elif lt == "min":
+            ratio = float(lsl) / (h if h < w else w) if min(h, w) < lsl else 1.0
+        elif lt == "resize_long":
+            ratio = float(lsl) / max(h, w)
+        else:
+            raise ValueError(f"not support limit type {lt}")
+        rh, rw = int(h * ratio), int(w * ratio)
+        if max(rh, rw) > self.max_side_limit:
+            r2 = float(self.max_side_limit) / max(rh, rw)
+            rh, rw = int(rh * r2), int(rw * r2)
+        rh = max(int(round(rh / 32) * 32), 32)
+        rw = max(int(round(rw / 32) * 32), 32)
+        return rh, rw, rh / float(h), rw / float(w)
+
+    def _target_hw(self, h: int, w: int) -> tuple[int, int]:
+        """这帧会被缩到多大（含 PaddleX 那条"太小先补到 32"的规矩）。"""
+        if h + w < 64:
+            h, w = max(32, h), max(32, w)
+        return self._resize_shape(h, w)[:2]
+
+    def preprocess(self, img: np.ndarray, *, copy: bool = False, dst: np.ndarray | None = None):
+        """⚠ 返回的 blob 默认是**复用的缓冲区**，下一次调用就会被覆盖。
+
+        要留着（比如攒一批做对照）就传 `copy=True`。复用不是微优化：
+        每帧新分配 6.3 MB 再释放，实测让端到端多花约 4.5 ms/帧——
+        新页是冷的，`copy_from_cpu` 读它要吃缺页。
+        给了 `dst`（形状 `(1, 3, rh, rw)` 的 float32 视图）就直接写进它——批处理用，省一次拷贝。
+        """
+        if img.ndim != 3 or img.shape[2] != 3 or img.dtype != np.uint8:
+            # LUT 是按 uint8 的 256 个取值建的，换了 dtype 就不是恒等变换了；
+            # 通道数不对 `cv2.LUT` 会用同一张表去套，静默算出别的东西。
+            raise ValueError(f"快路径只吃 3 通道 uint8，拿到 {img.shape} {img.dtype}")
+        src_h, src_w = img.shape[:2]
+        if src_h + src_w < 64:
+            # PaddleX 的 `resize()` 在这里先补零到至少 32×32，再算比例，
+            # 而返回的 shape 向量记的仍是**原始**尺寸。真素材碰不到，但换形状对账会咬。
+            pad = np.zeros((max(32, src_h), max(32, src_w), img.shape[2]), img.dtype)
+            pad[:src_h, :src_w] = img
+            img = pad
+        h, w = img.shape[:2]
+        rh, rw, ratio_h, ratio_w = self._resize_shape(h, w)
+        if (rh, rw) != (h, w):
+            img = cv2.resize(img, (rw, rh), dst=self._buf("rs", (rh, rw, 3), np.uint8))
+            ratio_h, ratio_w = rh / float(h), rw / float(w)
+        else:
+            ratio_h = ratio_w = 1.0
+        # uint8 HWC -> 归一化的 float32 HWC，一趟 C++（BGR->RGB 若需要则已折进 LUT 系数）
+        normed = cv2.LUT(img, self._lut, dst=self._buf("norm", (rh, rw, 3), np.float32))
+        chw = normed.transpose(2, 0, 1)
+        if self._swap:                             # LUT 只改了系数，通道位置还要真的换
+            chw = chw[::-1]
+        if dst is not None:
+            if dst.shape != (1, 3, rh, rw) or dst.dtype != np.float32:
+                raise ValueError(f"dst 形状不对：要 {(1, 3, rh, rw)} float32，给的 {dst.shape} {dst.dtype}")
+            blob = dst
+        else:
+            blob = self._buf("blob", (1, 3, rh, rw), np.float32)
+        blob[0] = chw                              # 写进常驻缓冲，不新分配
+        return (blob.copy() if copy else blob), np.array([src_h, src_w, ratio_h, ratio_w])
+
+    def _buf(self, key: str, shape: tuple, dtype) -> np.ndarray:
+        b = self._bufs.get(key)
+        if b is None or b.shape != shape or b.dtype != dtype:
+            b = np.empty(shape, dtype)
+            self._bufs[key] = b
+        return b
+
+    # -- 全流程 ---------------------------------------------------------------
+
+    def predict(self, img: np.ndarray):
+        t = time.perf_counter()
+        blob, shape = self.preprocess(img)
+        t = _tl.span("det_pre", t)
+        preds = self.runner([blob])
+        t = _tl.span("det_infer", t)
+        polys, scores = self.post_op(
+            preds, [shape],
+            thresh=self.thresh,
+            box_thresh=self.box_thresh,
+            unclip_ratio=self.unclip_ratio,
+        )
+        _tl.span("det_post", t)
+        return polys[0], scores[0]
+
+    def predict_batch(self, imgs: list[np.ndarray]) -> list[tuple]:
+        """几帧一次送进模型（`run_ocr2 --det-batch`）。返回每帧的 `(polys, scores)`，顺序同输入。
+
+        **不逐字节等于逐帧**：cuDNN 按批大小可能换卷积算法，f5 上 48 帧里 2 帧 poly 有细微差
+        （一次性探针 `probe_det_batch.py`）。尺寸不一的帧拼不了批，退回逐帧。
+        """
+        return self.post_batch(self.infer_batch(imgs))
+
+    def infer_batch(self, imgs: list[np.ndarray]) -> tuple:
+        """`predict_batch` 的前半：前处理 + 推理，返回一个不透明的 state 交给 `post_batch`（2026-09-25，`run_ocr2 --det-lookahead`：
+        辅助线程跑这一半，和上一批的后处理重叠——det 线程原来把前处理 1.5 s、推理 10.9 s、后处理 3.7 s 串在一起）。
+        state 里只有 runner 返回的新数组和 shape 向量：前处理的常驻缓冲区下一次就被覆盖，不能留在 state 里。"""
+        if len(imgs) == 1 or len({im.shape for im in imgs}) != 1:
+            return ("done", [self.predict(im) for im in imgs])
+        t = time.perf_counter()
+        rh, rw = self._target_hw(*imgs[0].shape[:2])
+        batch = self._buf(f"batch{len(imgs)}", (len(imgs), 3, rh, rw), np.float32)
+        shapes = [self.preprocess(im, dst=batch[i:i + 1])[1] for i, im in enumerate(imgs)]
+        t = _tl.span("det_pre", t)
+        preds = self.runner([batch])
+        _tl.span("det_infer", t)
+        return ("preds", preds, shapes)
+
+    def post_batch(self, state: tuple) -> list[tuple]:
+        """`predict_batch` 的后半：DB 后处理。和 `infer_batch` 合起来就是原来的 `predict_batch`，计算一步不差。"""
+        if state[0] == "done":
+            return state[1]
+        _, preds, shapes = state
+        t = time.perf_counter()
+        polys, scores = self.post_op(
+            preds, shapes,
+            thresh=self.thresh,
+            box_thresh=self.box_thresh,
+            unclip_ratio=self.unclip_ratio,
+        )
+        _tl.span("det_post", t)
+        return list(zip(polys, scores))

flowocr/extract/ffcheck.py

@@ -0,0 +1,87 @@
+"""ffmpeg / ffprobe 在不在、够不够用，推理后端装对了没有，以及这一趟的运行时版本（release-plan F13 / F8）。
+
+ffmpeg **不随包分发**（owner 2026-09-25：避开 ffmpeg 构建的再分发义务），用户自己装、放进 `PATH`。
+这里只拦"缺了必挂"的：两个可执行文件、`showinfo`（逐帧 pts 从它的 stderr 读，`framesource` 文件头）、`select`、`scale`。
+**硬解能力不在这里判**：NVDEC / `scale_cuda` 缺了由 `framesource.hwaccel_blocker` 试解不过、退回软解（原因写进 `_meta`），
+照这台机器实际能跑的走，不按构建选项猜。版本下限没有依据（只在 8.0 上跑过），所以不卡版本号，只记下来。
+"""
+from __future__ import annotations
+
+import functools
+import importlib.metadata
+import platform
+import shutil
+import subprocess
+import sys
+
+REQUIRED_FILTERS = ("showinfo", "select", "scale")
+DISTS = ("flowocr", "numpy", "opencv-contrib-python", "onnxruntime-gpu", "onnxruntime")
+"""`_meta.runtime` 记哪些包的版本（按分发名查元数据、不 import）。"""
+
+
+def _run(cmd: list[str]) -> str:
+    return subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace",
+                          timeout=30).stdout
+
+
+@functools.lru_cache(maxsize=1)
+def probe() -> dict:
+    """`{"ffmpeg": 路径, "ffprobe": 路径, "version": 首行, "missing": [缺的东西]}`。一个进程只探一次。"""
+    ff, fp = shutil.which("ffmpeg"), shutil.which("ffprobe")
+    missing = [n for n, p in (("ffmpeg", ff), ("ffprobe", fp)) if p is None]
+    version = ""
+    if ff:
+        try:
+            version = (_run([ff, "-hide_banner", "-version"]).splitlines() or [""])[0].strip()
+            names = {ln.split()[1] for ln in _run([ff, "-hide_banner", "-filters"]).splitlines()
+                     if len(ln.split()) >= 3 and ln[:1] == " "}
+            missing += [f"滤镜 {f}" for f in REQUIRED_FILTERS if f not in names]
+        except (OSError, subprocess.SubprocessError) as exc:      # 在 PATH 上但起不来（损坏、权限、卡住）
+            missing.append(f"能运行的 ffmpeg（{ff}：{type(exc).__name__}: {exc}）")
+    return {"ffmpeg": ff, "ffprobe": fp, "version": version, "missing": missing}
+
+
+def require() -> dict:
+    """缺了就带着说明退出；够用就返回 `probe()`。"""
+    p = probe()
+    if p["missing"]:
+        raise SystemExit(f"ffmpeg 不够用：缺 {', '.join(p['missing'])}。flowocr 不带 ffmpeg，要自己装一个完整构建"
+                         f"（如 gyan.dev / BtbN 的 Windows full build），把它的 bin 目录放进 PATH（ffmpeg 与 ffprobe 都要）")
+    return p
+
+
+ORT_DISTS = ("onnxruntime-gpu", "onnxruntime")
+"""推理后端的两个分发：装的是同一个 `onnxruntime` 顶层包，只能有一个（`[nvidia]` / `[cpu]` 两个 extra 各装一个）。"""
+
+
+def require_runtime() -> None:
+    """推理后端装对了没有、平台是不是验证过的。装成包时 extras 的互斥进不了元数据，所以起跑时查：
+    一个都没有 -> 退出并说装哪个 extra；两个都在 -> 退出并说只留一个（后装的那个盖掉前一个，可能装成了不带 CUDA 的那份）；
+    不是 Windows -> 打一行警告照跑（owner 2026-10-02：只在 Windows 上验证过，不挡想试的人）。"""
+    have = []
+    for d in ORT_DISTS:
+        try:
+            importlib.metadata.version(d)
+            have.append(d)
+        except importlib.metadata.PackageNotFoundError:
+            pass
+    if not have:
+        raise SystemExit("没装推理后端（onnxruntime）。装的时候选一个 extra：有 NVIDIA 显卡 `flowocr[nvidia]`，没有 `flowocr[cpu]`"
+                         "（源码装就是 `uv sync --frozen --extra nvidia` 或 `--extra cpu`）")
+    if len(have) > 1:
+        raise SystemExit("onnxruntime-gpu 和 onnxruntime 同时装着，两个会互相覆盖。只留一个：重装时 extra 只选 nvidia 或 cpu 之一"
+                         "（源码装删掉 .venv 再 `uv sync`）")
+    if sys.platform != "win32":
+        print(f"[平台] ⚠ flowocr 只在 Windows 上验证过，这台是 {platform.system()}：照跑，出了问题欢迎反馈", flush=True)
+
+
+def runtime() -> dict:
+    """这一趟的运行时：Python、各推理库的版本、ffmpeg 的版本行。**只追溯、不进复用判据**（同一组 config 可以出自不同运行时）。"""
+    pkgs = {}
+    for d in DISTS:
+        try:
+            pkgs[d] = importlib.metadata.version(d)
+        except importlib.metadata.PackageNotFoundError:
+            pass
+    return {"python": sys.version.split()[0], "platform": platform.platform(), "packages": pkgs,
+            "ffmpeg": probe()["version"]}

flowocr/extract/framegrid.py

@@ -0,0 +1,265 @@
+"""取哪些帧：**时间网格**（2026-09-24，owner：三种间隔都不要求整除，"采样帧 ⊆ 高精帧环 ⊆ 辅助流"嵌套）。
+
+帧号一律是 pts 帧号 `round(t × 名义帧率)`（`framesource.id_rate`），网格锚在帧号 0 上：
+
+* `TimeGrid(p, q)`：帧率比 p/q（约分、≤ 1）的网格。第 k 格是帧 `ceil(k·q/p)`；第 i 帧在格上 ⇔ `floor(i·p/q)` 在这一帧变了。
+  floor / ceil / 前后格 / 区间里的格都是整数闭式，不逐帧循环。**p = 1 时就是原来的"每 q 帧一帧"**（`uniform`），
+  公式逐项退化成原来的整除算术——所以整除的情形和改之前逐字节相同。采样用它（`--fps`）。
+* `AuxGrid(own, sample)`：辅助流 = 自己的网格（`--aux-max-fps`）∪ 采样网格（**嵌套**：采样帧一定在辅助流里）。
+  回抠的边界锚在采样帧上（融合把首字夹在 [t_start − 一个间隔, t_start]），采样帧不在辅助流里边界就落不到它上面
+  （09-16 那次：格子没对齐、首字系统性晚 1 帧、产物校验当场拒收）。两个都等距、而且采样步长是辅助步长的倍数时，
+  并集就是自己那个网格（`uniform`），证据记录照旧只写 `step`。
+
+ffmpeg 的 `select` 表达式和 Python 用同一组整数算 floor（`N·p/q` 的分子是精确整数、商离整数至少 1/q，双精度不会判错），
+两边选出来的帧一致（守卫在 6 小时帧号内抽查）。**纯函数，守卫直接测。**
+"""
+from __future__ import annotations
+
+from fractions import Fraction
+
+FPS_DEN = 10_000
+"""帧率换成有理数时分母的上限：59.94（60000/1001）、23.976（24000/1001）这类名义帧率都精确落得下。"""
+CAP_TOL = 1e-3
+"""辅助流上限落到整数步长的容差（相对）：60.0000x 这类名义帧率不算超（同时间网格之前的步长判据）。"""
+SNAP_DEN = 100
+SNAP_REL = 1e-5
+"""两个帧率之比离一个**分母 ≤ `SNAP_DEN` 的简单分数**不到 `SNAP_REL`（相对）就吸附上去（2026-09-24 审计）。
+为什么：用户敲的是 `29.97` / `59.94`，素材的名义帧率是 30000/1001 / 60000/1001——两边各自有理数化之后比值是 999999/2000000，
+离 1/2 只差 1e-6，却被当成真不整除（不等距网格、`--fps 59.94` 直接报错、辅助流每 4.6 h 静默少一帧）。
+1e-5 的相对误差 6 小时累计 0.2 s；真不整除的（59.94 上 2 fps 是 1001/30000，离 1/30 差 1e-3）不受影响。"""
+
+
+class TimeGrid:
+    __slots__ = ("p", "q")
+
+    def __init__(self, p: int, q: int) -> None:
+        if p < 1 or q < 1:
+            raise ValueError(f"网格的帧率比要为正：{p}/{q}")
+        f = min(Fraction(p, q), Fraction(1))
+        self.p, self.q = f.numerator, f.denominator
+
+    @classmethod
+    def for_rate(cls, src_fps: float, fps: float) -> "TimeGrid":
+        """素材 `src_fps` 上取 `fps` 帧 / 秒（比素材还高就是每帧都要）。"""
+        if src_fps <= 0 or fps <= 0:
+            raise ValueError(f"帧率要为正：素材 {src_fps} / 要的 {fps}")
+        r = Fraction(fps).limit_denominator(FPS_DEN) / Fraction(src_fps).limit_denominator(FPS_DEN)
+        s = r.limit_denominator(SNAP_DEN)
+        if abs(s - r) <= SNAP_REL * r:
+            r = s
+        return cls(r.numerator, r.denominator)
+
+    @classmethod
+    def every(cls, step: int) -> "TimeGrid":
+        """每 `step` 帧一帧（探针 / 旧产物的整数步长）。"""
+        return cls(1, max(1, int(step)))
+
+    @property
+    def uniform(self) -> bool:
+        return self.p == 1
+
+    @property
+    def step(self) -> int | None:
+        """等距时的步长；不等距是 None。"""
+        return self.q if self.p == 1 else None
+
+    @property
+    def max_gap(self) -> int:
+        """相邻两格最多隔几帧（等距就是步长）。"""
+        return -(-self.q // self.p)
+
+    def fps(self, src_fps: float) -> float:
+        return src_fps * self.p / self.q
+
+    def interval_us(self, src_fps: float) -> float:
+        """名义间隔（微秒）。不等距时实际间隔在它上下差不到一帧。"""
+        return 1e6 * self.q / (self.p * src_fps)
+
+    def as_list(self) -> list[int]:
+        return [self.p, self.q]
+
+    # ---------- 选帧（整数闭式）----------
+    def at(self, k: int) -> int:
+        """第 k 格的帧号 `ceil(k·q/p)`。"""
+        return -(-k * self.q // self.p)
+
+    def index(self, i: int) -> int:
+        """不大于 i 的最近一格是第几格（`floor(i·p/q)`）。"""
+        return i * self.p // self.q
+
+    def member(self, i: int) -> bool:
+        return self.at(self.index(i)) == i
+
+    def floor(self, i: int) -> int:
+        return self.at(self.index(i))
+
+    def ceil(self, i: int) -> int:
+        return self.at(self.index(i - 1) + 1)
+
+    def prev(self, i: int) -> int:
+        """严格小于 i 的最近一格。"""
+        return self.floor(i - 1)
+
+    def next(self, i: int) -> int:
+        """严格大于 i 的最近一格。"""
+        return self.at(self.index(i) + 1)
+
+    def nearest(self, x: float) -> int:
+        """离帧号 x（可以是小数）最近的一格（按**帧距**；一样近取前一格）——窗口起点对齐用。
+        等距时就是原来的 `round(x / q) * q`（逐位保留，含 Python 的银行家舍入）。
+        不等距时不能按格号四舍五入：60 fps 上 2.2 fps 的前两格是 0 / 28，x = 13.7 的格号 0.502 会舍到 28，而 0 更近（2026-09-24 Codex 审计）。"""
+        if self.p == 1:
+            return self.at(round(x / self.q))
+        lo = self.floor(int(x // 1))
+        hi = self.next(lo)
+        return lo if x - lo <= hi - x else hi
+
+    def frames(self, lo: int, hi: int) -> list[int]:
+        """[lo, hi] 里的格（升序）。"""
+        if hi < lo:
+            return []
+        if self.p == 1:
+            q = self.q
+            return list(range(lo + (-lo) % q, hi + 1, q))
+        return [self.at(k) for k in range(self.index(lo - 1) + 1, self.index(hi) + 1)]
+
+    def n_frames(self, lo: int, hi_excl: int) -> int:
+        """[lo, hi_excl) 里最多交付几格（ffmpeg 的 `-frames:v`）。等距的照旧是 `ceil((hi − lo) / q)`（起点对齐时就是精确数）。"""
+        if self.p == 1:
+            return max(1, -(-(hi_excl - lo) // self.q))
+        return max(1, self.index(hi_excl - 1) - self.index(lo - 1))
+
+    def cond(self, n: str) -> str:
+        """ffmpeg 表达式：帧号表达式 `n` 在格上（逗号已转义）。"""
+        if self.p == 1:
+            return rf"not(mod({n}\,{self.q}))"
+        return rf"not(eq(floor({n}*{self.p}/{self.q})\,floor(({n}-1)*{self.p}/{self.q})))"
+
+    def select(self, n: str) -> str:
+        """`select` 的条件；空串 = 每帧都要。等距时和加时间网格之前逐字相同。"""
+        return "" if self.p == 1 and self.q == 1 else self.cond(n)
+
+    def describe(self, src_fps: float) -> str:
+        if self.p == 1:
+            return "每帧一帧" if self.q == 1 else f"每 {self.q} 帧一帧"
+        return f"按时间网格 {self.fps(src_fps):.3f} fps（{self.p}/{self.q}）"
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, TimeGrid) and (self.p, self.q) == (other.p, other.q)
+
+    def __hash__(self) -> int:
+        return hash((self.p, self.q))
+
+    def __repr__(self) -> str:
+        return f"TimeGrid({self.p}/{self.q})"
+
+
+def meta_stride(meta: dict) -> int:
+    """obs `_meta` 里的**等距**采样步长。只认等距采样的探针（按"每 stride 帧一帧"数帧号的那几个）用它：
+    时间网格上不等距的产物没有 `stride`，直接 `meta["stride"]` 是一个看不出原因的 KeyError（2026-09-24 审计）。"""
+    s = meta.get("stride")
+    if not s:
+        raise ValueError(f"这份 obs 的采样不等距（`_meta.sample_grid` = {meta.get('sample_grid')}），这个探针只认等距采样"
+                         f"（每 stride 帧一帧）；用整除素材帧率的 --fps 重跑一份")
+    return int(s)
+
+
+class AuxGrid:
+    """辅助流：自己的网格 ∪ 采样网格（嵌套）。"""
+    __slots__ = ("own", "sample")
+
+    def __init__(self, own: TimeGrid, sample: TimeGrid) -> None:
+        self.own, self.sample = own, sample
+
+    @classmethod
+    def for_video(cls, src_fps: float, aux_max_fps: float, sample: TimeGrid) -> "AuxGrid":
+        """辅助流帧率 = min(上限, 素材帧率)。上限**不超过它 `CAP_TOL`** 就落得到某个整数步长（素材帧率 / k）时取那个步长：
+        它是上限、不是目标值——119.88 fps 的素材给 60 就该隔帧（59.94 fps），不该为多出的 0.1% 走不等距网格（2026-09-24 Fable 复审）。"""
+        k = max(1, round(src_fps / aux_max_fps))
+        if src_fps / k <= aux_max_fps * (1 + CAP_TOL):
+            return cls(TimeGrid.every(k), sample)
+        return cls(TimeGrid.for_rate(src_fps, aux_max_fps), sample)
+
+    @classmethod
+    def from_list(cls, g: list[int]) -> "AuxGrid":
+        """`as_list()` 的逆：`[p, q, 采样 p, 采样 q]`（跨进程 / 进 `_meta` / 证据记录的写法）。"""
+        return cls(TimeGrid(g[0], g[1]), TimeGrid(g[2], g[3]))
+
+    @classmethod
+    def from_spec(cls, rec: dict) -> "AuxGrid":
+        """证据记录里的写法 -> 网格：`grid` 或等距的 `step`（等距时并集就是自己的网格，采样网格取它自己）。"""
+        if rec.get("grid"):
+            return cls.from_list(rec["grid"])
+        g = TimeGrid.every(rec.get("step") or 1)
+        return cls(g, g)
+
+    def as_list(self) -> list[int]:
+        return self.own.as_list() + self.sample.as_list()
+
+    @property
+    def uniform(self) -> bool:
+        """并集退化成自己那个等距网格：自己每帧都要（什么都盖得住），或两个都等距、采样步长是辅助步长的倍数。"""
+        return self.own.p == 1 and (self.own.q == 1 or (self.sample.p == 1 and self.sample.q % self.own.q == 0))
+
+    @property
+    def step(self) -> int | None:
+        return self.own.q if self.uniform else None
+
+    def key(self) -> tuple:
+        """复用判据比的规范形。等距的并集按步长比；不等距的按两个网格比——**帧集合相同、写法不同的偶尔会不相等**
+        （如 2/3 ∪ 1/3 和 2/3 ∪ 2/3），后果只是多重建一次，不会把不同的帧集合判成相同（2026-09-24 审计把原来"帧集合相同就相等"改准）。"""
+        return ("step", self.own.q) if self.uniform else tuple(self.as_list())
+
+    def spec(self) -> dict:
+        """写进证据记录的样子：等距的照旧只写 `step`（和旧产物逐字节相同），不等距的写 `grid`。"""
+        return {"step": self.own.q} if self.uniform else {"grid": self.as_list()}
+
+    def member(self, i: int) -> bool:
+        return self.own.member(i) or self.sample.member(i)
+
+    def floor(self, i: int) -> int:
+        return self.own.floor(i) if self.uniform else max(self.own.floor(i), self.sample.floor(i))
+
+    def ceil(self, i: int) -> int:
+        return self.own.ceil(i) if self.uniform else min(self.own.ceil(i), self.sample.ceil(i))
+
+    def prev(self, i: int) -> int:
+        return self.floor(i - 1)
+
+    def frames(self, lo: int, hi: int) -> list[int]:
+        if self.uniform:
+            return self.own.frames(lo, hi)
+        return sorted(set(self.own.frames(lo, hi)) | set(self.sample.frames(lo, hi)))
+
+    def n_frames(self, lo: int, hi_excl: int) -> int:
+        """[lo, hi_excl) 里辅路最多交付几帧（`-frames:v`、`AuxReader` 读几帧）。"""
+        if self.uniform:
+            return self.own.n_frames(lo, hi_excl)
+        return max(1, len(self.frames(lo, hi_excl - 1)))
+
+    def cover_floor(self, last_idx: int) -> int:
+        """辅助流交付到的最后一帧至少要到这里，才算盖住了采样流的最后一帧（判"辅助流半路断了"）。
+        等距的照旧留 `q − 1` 帧余量；不等距的：采样帧一定在辅助流里（嵌套），要盖到不大于它的最近一个入选帧。"""
+        if self.uniform:
+            return last_idx - (self.own.q - 1)
+        return self.floor(last_idx)
+
+    def select(self, n: str) -> str:
+        """ffmpeg `select` 的条件；空串 = 每帧都要。等距时和加时间网格之前逐字相同。"""
+        if self.uniform:
+            return self.own.select(n)
+        return f"({self.sample.cond(n)}+{self.own.cond(n)})"
+
+    def describe(self, src_fps: float) -> str:
+        if self.uniform:
+            return self.own.describe(src_fps)
+        return f"按时间网格 {self.own.fps(src_fps):.3f} fps（{self.own.p}/{self.own.q}，含采样帧）"
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, AuxGrid) and self.key() == other.key()
+
+    def __hash__(self) -> int:
+        return hash(self.key())
+
+    def __repr__(self) -> str:
+        return f"AuxGrid({self.own} ∪ 采样 {self.sample})"