From 10134ad492457b41545d069de4c341ff565f44e5 Mon Sep 17 00:00:00 2001 From: lingh Date: Mon, 6 Jul 2026 15:45:06 +0800 Subject: [PATCH] Drop dead detect_background_color; sync docs with landed optimizations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - chroma.py: remove detect_background_color — orphaned since auto-detection goes through estimate_background_model -> _background_border_cluster; nothing in the repo calls it. - settings.py: fix stale "Segmentation always stays fp32" comment (--precision now fans out to the BiRefNet models too). - README: add a measured CPU performance section (9700X reference numbers, memory ceiling explanation, Zen 2 fallback guidance). - docs/hair_gap_artifacts.md: record that the cross-check cost note is obsolete — reuse_as_seg returns the net model count to 2, bf16 and chunked attention absorb the rest. - docs/green_screen_matting_workflow.md: add the 2026-07 additions to the architecture-evolution note. Co-Authored-By: Claude Opus 4.8 --- README.md | 20 ++++++++++++++++++++ bgfilter/chroma.py | 16 ---------------- bgfilter/settings.py | 8 ++++---- docs/green_screen_matting_workflow.md | 1 + docs/hair_gap_artifacts.md | 8 ++++++++ 5 files changed, 33 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 07c3e80..7f0373f 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,26 @@ D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli ` --debug-dir Outputs\debug ``` +## Performance (CPU reference numbers) + +Measured on a Ryzen 9700X (Zen 5, native bf16), 32 GB RAM, default settings +(cross-check on, reused as seg; chunked global attention on): + +| input | precision | warm / image | peak memory | +|---|---|---|---| +| 1024x1536 | fp32 | ~45 s | — | +| 1024x1536 | bf16 | ~33 s | — | +| 2048x2048 | bf16 | ~53 s | 11.4 GB (batch), 8.1 GB (single image) | + +The memory ceiling is the cross-check BiRefNet_HR forward (fixed +`input_size` 2048 regardless of the image size) — genuine live activations +of a full-resolution dense prediction net. Before chunked attention and the +mimalloc fix, the same 2048x2048 bf16 run peaked at 25.2 GB; a fully +un-optimized fp32 run would need an estimated 55-60 GB (ViTMatte's un-chunked +N^2 attention alone ~39 GB). CPUs without native bf16 (e.g. Zen 2) auto-fall +back to fp32 — on such machines prefer `--no-cross-check` if memory or +latency is tight. + ## Chroma-alpha debug mode `--matting-method chroma` skips ViTMatte and uses chroma confidence directly as the diff --git a/bgfilter/chroma.py b/bgfilter/chroma.py index 64d4afb..18a8827 100644 --- a/bgfilter/chroma.py +++ b/bgfilter/chroma.py @@ -112,22 +112,6 @@ def _background_border_cluster( return full, share, agree -def detect_background_color( - rgb: np.ndarray, settings: ChromaSettings | None = None -) -> tuple[float, float, float]: - """Detect a single flat background colour from the image border. - - Returns the colour as a 0..1 RGB triple. Raises RuntimeError (via - :func:`_background_border_cluster`) if the border is not dominated by one flat - colour, so callers fail loudly rather than matting against a wrong colour. - Pure: reads pixels only, with no matting side effects. - """ - settings = settings or ChromaSettings() - rgb_f, lab = convert_color_spaces(rgb) - mask, _, _ = _background_border_cluster(lab, settings) - return tuple(float(x) for x in np.median(rgb_f[mask], axis=0)) - - def estimate_background_model( rgb: np.ndarray, settings: ChromaSettings, diff --git a/bgfilter/settings.py b/bgfilter/settings.py index b5aaf23..3b7eec2 100644 --- a/bgfilter/settings.py +++ b/bgfilter/settings.py @@ -129,10 +129,10 @@ class ModelSettings: matting_method: str = "vitmatte" fallback_to_chroma_alpha: bool = False # ViTMatte compute precision: "fp32" or "bf16". bf16 halves the matting - # model's activation memory (its full-resolution attention is the pipeline's - # memory peak) with visually identical alpha, but needs bf16-capable - # hardware (any modern GPU, or a CPU with AVX512-BF16/AMX) — otherwise it - # falls back to fp32 with a warning. Segmentation always stays fp32. + # model's activation memory with visually identical alpha, but needs + # bf16-capable hardware (any modern GPU, or a CPU with AVX512-BF16/AMX) — + # otherwise it falls back to fp32 with a warning. The BiRefNet models have + # their own precision fields; --precision sets all of them at once. precision: str = "fp32" # Query-chunked global attention (exact math, bitwise-identical output): # the VitDet backbone's 4 global blocks materialize an N^2 attention map — diff --git a/docs/green_screen_matting_workflow.md b/docs/green_screen_matting_workflow.md index 5278cda..7cda5c7 100644 --- a/docs/green_screen_matting_workflow.md +++ b/docs/green_screen_matting_workflow.md @@ -11,6 +11,7 @@ - **两条管线**（`segmentation.enabled` 切换）：无分割模型的 Chroma + ViTMatte；或单个语义分割模型（默认 birefnet，可切 anime-seg，用 `--seg-backend`）定 trimap 拓扑，ViTMatte 细化。 - **背景色泛化**：`screen_color` 先验（如 `#CFEFFF`）；`null` 时自动从图像边框探测平背景色（探测不到干净平背景会报错），不再写死绿幕。 - **已移除**：染绿修复（recolor）、发丝补救（dropout-fill）、BiRefNet+anime-seg 结合方案——它们只是给“生图即染色/断裂”的坏素材擦屁股；源头改用干净背景生图后不再需要。 +- **新增（2026-07）**：交叉模型否决（`cross_check`，BiRefNet_HR-matting 第二意见 min 融合，清发丝缝隙残蓝，见 `docs/hair_gap_artifacts.md`）；其前向默认兼任 seg mask（`reuse_as_seg`，净模型数回到 2）；`--precision bf16` 一个旋钮加速全部三类模型；ViTMatte 全局 attention 默认按 query 分块（输出逐位不变，2048² 内存峰值 25→11 GB）。 下文其余章节描述绿幕基线流程，仍然有效。 diff --git a/docs/hair_gap_artifacts.md b/docs/hair_gap_artifacts.md index 50a2dce..1f85511 100644 --- a/docs/hair_gap_artifacts.md +++ b/docs/hair_gap_artifacts.md @@ -89,6 +89,14 @@ min 融合;B2 的意见锐化(remap 0.5→0.95)被否——数字更低(0.673 vs **已落地(2026-07-04,默认开启)。** 新增 `cross_check` 设置块 + `--cross-check/--no-cross-check`;pipeline 在 clean_alpha 后插入 `cross_check_alpha`(alpha_post.py),第二意见加载复用 BiRefNetSegmenter。 + +**成本已消化(2026-07-06)。** 当年"+1 个模型 +1 次推理"的账已改写: +`cross_check.reuse_as_seg`(默认开)让 HR-matting 前向兼任 seg mask, +**净模型数回到 2 个**(trimap 99.8% 不变,先导 Outputs/segreuse/); +`--precision bf16` 经 autocast + deform_conv2d shim 覆盖 BiRefNet +(35s→26s @2048);ViTMatte 全局 attention 分块(逐位等价)把内存峰值 +从 25.2GB 压到 11.4GB(2048×2048 bf16,9700X)。CPU 上开 cross-check +的常规图约 33s/张(bf16)。 验证:开启时 TestImage3 输出与评审原型逐字节一致;`--no-cross-check` 与 旧 baseline 逐字节一致;FixImage1(粉底)脸部无损、发缘粉残留被清, 唯一副作用是羽化权重外溢到暗豁免区边缘(弓弦零星像素最多 -0.5,中位