Merge branch 'server-edition' of ssh://genarrative-station:2222/lhk229/BGfilter into server-edition

README.md

@@ -9,6 +9,7 @@ RGB input
   -> chroma bg-confidence (keyed to the auto-detected or given colour)
   -> [optional] semantic segmentation mask
   -> trimap -> ViTMatte -> alpha cleanup
+  -> cross-model veto (second matting opinion on bg-hued residue)
   -> pymatting foreground -> despill -> RGBA PNG -> QA previews
 ```
 
@@ -28,6 +29,15 @@ Both share pymatting foreground estimation and a colour de-spill. There is **no*
 green-contamination rescue / recolour layer — with clean source images it is
 unnecessary, so it was removed.
 
+Both also run a **cross-model veto** by default: a second, trimap-free matting
+model (`ZhengPeng7/BiRefNet_HR-matting`) may only *lower* alpha, only on
+background-hued bright pixels the primary result is confident about — this clears
+colour-drifted background residue trapped between hair strands that the chroma
+key, the segmenter and ViTMatte all read as foreground. Costs one extra model
+download (~0.9 GB) and one inference pass per image; disable with
+`--no-cross-check` (see the `cross_check` config section, and
+`docs/hair_gap_artifacts.md` for the analysis behind it).
+
 The segmentation trimap defaults to `directional` mode (chroma + seg + a hue-direction
 split: it keeps a background-coloured garment such as a white shirt while dropping a
 background-hued residual such as blue trapped between hair strands). Switch with
@@ -146,6 +156,9 @@ Two endpoints:
   - `file` (required) — the source image. The field name is fixed as `file`.
   - `screen_color` (optional) — `#RRGGBB` prior; omit/empty for auto-detect.
   - `seg_model` (optional) — `birefnet` (default) or `anime-seg`.
+  - `cross_check` (optional) — `1`/`0` (also `true`/`false`/`yes`/`no`/`on`/`off`);
+    per-request override of the cross-model veto. Omit/empty to use the service
+    default. The response reports the effective state in `X-BGFilter-Cross-Check`.
 
 ```bash
 # default (birefnet + auto background colour)
@@ -158,6 +171,10 @@ curl -sS \
   -F "screen_color=#CFEFFF" \
   -F "seg_model=anime-seg" \
   http://127.0.0.1:18083/remove-background -o output.png
+
+# enable the cross-model veto for this request only (see below; slow on CPU)
+curl -sS -F "file=@input.png" -F "cross_check=1" \
+  http://127.0.0.1:18083/remove-background -o output.png
 ```
 
 Config comes from `BGFILTER_CONFIG` (defaults to `configs/default.yaml` when present);
@@ -165,6 +182,14 @@ Config comes from `BGFILTER_CONFIG` (defaults to `configs/default.yaml` when pre
 caps input size (default ~4MP → `413`); `BGFILTER_PRELOAD=1` loads the default models at
 startup. Run a single worker (`--workers 1`) — each worker loads its own copy of the models.
 
+Unlike the CLI, the service defaults the **cross-model veto to off** — it adds one
+extra large-model inference (~35 s/image on CPU, 14 s → 49 s total). Enable it
+per request with the `cross_check` form field, or flip the service default with
+`BGFILTER_CROSS_CHECK=1` (worth it on GPU or when hair-gap residue matters more
+than latency); `/healthz` reports the default as `crossCheck`. The cross-check
+model is lazy-loaded: it is never preloaded at startup, so the first request that
+enables it also pays the one-time model load (~1 GB) on top of the inference.
+
 ## Quality Check
 
 The quality checker measures alpha validity and edge spill on semi-transparent edge
@@ -209,7 +234,8 @@ D:\MiniConda\envs\lightML\python.exe scripts\smoke_samples.py `
   (as the service does in production).
 - Bundling weights in the project — instead of the HF cache, drop each model into a
   plain folder named after the repo basename under `models/`:
-  `models/vitmatte-base-composition-1k`, `models/BiRefNet`, `models/anime-seg`. The loader
+  `models/vitmatte-base-composition-1k`, `models/BiRefNet`, `models/anime-seg`,
+  `models/BiRefNet_HR-matting` (cross-check second opinion, default on). The loader
   prefers a matching local folder and falls back to the HF repo id / cache when absent, so
   it is opt-in. Populate them with e.g. `hf download ZhengPeng7/BiRefNet --local-dir
   models/BiRefNet`. Override the base directory with `BGFILTER_WEIGHTS_DIR`. `models/` is