Add complex-background matting mode to the service via background_mode

Backports master's non-flat matting (chroma.enabled: false + the hue-free
cross-check gate) into server-edition, and exposes it over HTTP without
surfacing the internal "chroma" wording: /remove-background gains a
background_mode form field (flat, default | complex). complex maps to
chroma disabled -- no colour key, segmentation alone drives the trimap and
every colour-keyed stage (auto-detect, hue split, chroma suppression,
despill) is bypassed. The cross-check veto still works in complex mode via
its second-opinion-confidence gate (cross_check.second_lo/hi) but defaults
OFF there (it costs the HR-matting forward); an explicit cross_check=on
re-enables it.

No new model weights: complex mode reuses the already-provisioned BiRefNet
seg + ViTMatte (+ optional HR-matting cross-check). Flat mode is unchanged
(bit-identical), and server-edition's own extras (cross_check.lock,
foreground.use_gpu CuPy path) are preserved -- the port is surgical, not a
copy of master's files.

- settings: ChromaSettings.enabled, CrossCheckSettings.second_lo/hi
- config: override_settings chroma passthrough
- despill/foreground: model=None safe guards (foreground keeps GPU path)
- alpha_post: cross_check_alpha hue-free gate when proj is None
- pipeline: _process_rgb complex branch (seg-only trimap, skip colour stages)
- service/app: process(chroma=), background_mode field, complex-defaults-off
  cross-check, X-BGFilter-Background-Mode header
- cli: --chroma/--no-chroma
- configs/docs: gpu.yaml + default.yaml + README/README_ZH

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-07-14 14:04:58 +08:00
parent 28d3fe8842
commit c56e58affe
13 changed files with 166 additions and 33 deletions
+14
View File
@@ -4,6 +4,15 @@
# off (it false-positives on subjects sharing the background hue).
screen_color: null
chroma:
# true = flat-colour background (default). false = non-flat/complex background
# mode: no colour key; segmentation alone drives the trimap (mode forced to
# "seg") and the colour-keyed stages are bypassed (auto-detect, hue split,
# chroma suppression, despill). The cross-check veto still runs if enabled,
# using its hue-free gate (cross_check.second_lo/hi). The service selects this
# per request via background_mode=flat|complex; this is only the base default.
enabled: true
model:
model_name: hustvl/vitmatte-base-composition-1k
device: cuda
@@ -51,6 +60,11 @@ cross_check:
feather_sigma: 2.0
gate_lo: 0.70
gate_hi: 0.95
# Complex-background (non-flat) mode only: no hue-defined suspect zone, so the
# veto requires the second opinion itself to be confidently near-empty -- full
# strength at/below second_lo, fading to none at/above second_hi.
second_lo: 0.15
second_hi: 0.40
foreground:
enabled: true