# BgFilter

Offline character matting for AI-generated images on a flat-colour background.
The background colour is **auto-detected** from the image border (green, pastel, any
flat colour); pass `--screen-color` to set it explicitly.

```text
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
```

## Pipelines

Two pipelines, selected by `segmentation.enabled` in the config:

- **Chroma-only** (`enabled: false`) — Chroma + ViTMatte, no segmentation model.
  Lightest / fastest; leans entirely on the colour key for topology.
- **Single segmenter** (`enabled: true`, default) — one segmentation model drives the
  trimap topology (holes, hair), ViTMatte then refines the soft edges. Backend is
  switchable: `birefnet` (default, general salient objects — text, logos, photos; needs
  `trust_remote_code`) or `anime-seg` (ONNX, tuned for anime characters). Switch at
  runtime with `--seg-backend anime-seg` (it also selects the matching weights).

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).

When the cross-check is on, that same HR-matting forward is **reused as the
segmentation mask by default**, skipping the primary seg model entirely (one
less model to load, ~20 s faster per image on CPU). Pilot-validated
(TestImage3 / FixImage1): trimap 99.8% identical, no structural change to
fingers, hair wisps or thin lines. Disable with `--no-cross-check-as-seg` to
run the dedicated seg model instead.

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
`--trimap-mode seg` (topology only, no hue split) or `directional-hard-bg` (aggressive
— hard-removes background-hued pixels; can eat cool/shadowed white cloth).

## Background colour

By default (`screen_color: null`) the background colour is **auto-detected** from the
image border: the dominant flat colour of the border strip becomes the key colour. If
the border is not one clean flat colour — a gradient, texture, or a subject filling the
frame — detection **fails with an error**; pass `--screen-color` explicitly in that case.

To set it yourself, give a hex prior:

```powershell
... --screen-color "#CFEFFF"
```

or `screen_color: "#CFEFFF"` in the config. Either way the chroma key scores pixels by
perceptual (Lab/RGB) distance to the colour, and de-spill removes chroma along that
colour's direction. (A supplied hex is refined against nearby border pixels; an
auto-detected colour is used directly.)

## Environment

Use the conda environment `lightML`.

```powershell
conda activate lightML
pip install -r requirements.txt
```

If the shell is not activated, call the environment Python directly:

```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli --help
```

## Single Image

```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
  --input Samples\TestImage.png `
  --output Outputs\TestImage_rgba.png `
  --debug-dir Outputs\TestImage_debug
```

No `--config` is needed — the built-in defaults are identical to
`configs/default.yaml`. Pass `--config configs\default.yaml` only after you edit that
file to tune the detailed parameters. Runtime choices stay on the command line:
`--device` (default **CPU**; use `--device cuda` for GPU), `--precision` (default
`fp32`; `bf16` speeds up all three models and halves the matting model's activation
memory with visually identical alpha — needs bf16-capable hardware, falls back to
fp32 elsewhere; large inputs additionally get ViTMatte's global attention computed
in query chunks by default — exact, bitwise-identical, caps the memory spike at
~4 GB instead of ~19 GB at 2048x2048, see `model.attn_query_chunk`), `--seg-backend`
(default `birefnet`; `anime-seg` for anime characters), `--screen-color` (default:
auto-detect the flat background), and `--trimap-mode`.

## Batch

```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
  --input-dir Samples `
  --output-dir Outputs `
  --debug-dir Outputs\debug
```

## Chroma-alpha debug mode

`--matting-method chroma` skips ViTMatte and uses chroma confidence directly as the
alpha seed. Useful for fast inspection of chroma confidence, trimap, and despill.
(Distinct from the chroma-only *pipeline* above, which still runs ViTMatte.)

```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
  --input-dir Samples `
  --output-dir Outputs\chroma `
  --debug-dir Outputs\chroma_debug `
  --matting-method chroma `
  --device cpu
```

## Outputs

For each processed image, the CLI writes an RGBA PNG and optional debug files:

```text
bg_confidence.png
trimap.png
seg_mask.png          # segmentation pipeline only
alpha.png
foreground_rgb.png    # despilled foreground colour
color_mask.png        # per-pixel despill weight
preview_black.png
preview_white.png
preview_gray.png
preview_red.png
preview_blue.png
qa_grid.png
metadata.json
```

## Quality Check

The quality checker measures alpha validity and edge spill on semi-transparent edge
pixels.

```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.quality_cli `
  Outputs\TestImage_rgba.png `
  --max-edge-green-excess-p95 0.30
```

Run the bundled sample smoke check:

```powershell
D:\MiniConda\envs\lightML\python.exe scripts\smoke_samples.py `
  --samples-dir Samples `
  --output-dir Outputs\smoke_samples `
  --config configs\default.yaml `
  --device cpu `
  --fallback-to-chroma-alpha `
  --max-edge-green-excess-p95 0.30
```

## Notes

- `Samples/` and `Outputs/` are ignored by Git.
- ViTMatte and segmentation weights load from Hugging Face on first use. Behind a
  firewall set `HF_ENDPOINT=https://hf-mirror.com` (and bypass a flaky local proxy).
  `anime-seg` (`skytnt/anime-seg`) is a plain ONNX download; `birefnet`
  (`ZhengPeng7/BiRefNet`) ships custom modelling code so it needs
  `trust_remote_code=True` plus `timm` / `einops` / `kornia`.
- Foreground colour estimation uses pymatting's `estimate_foreground_ml` to propagate
  clean foreground colour into semi-transparent edges before de-spill. Set
  `foreground.method: unmix` to fall back to the legacy heuristic.
- `docs/green_screen_matting_workflow.md` is the original phase-1 green-screen spec;
  this README reflects the current, generalised architecture.