# BgFilter

Offline character matting for AI-generated images on a flat-colour background.
Green screen is the default; any flat colour (e.g. a pastel `#CFEFFF`) works via a
`screen_color` prior.

```text
RGB input
  -> chroma bg-confidence (keyed to the screen colour)
  -> [optional] semantic segmentation mask
  -> trimap -> ViTMatte -> alpha cleanup
  -> 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: `anime-seg` (default, ONNX) or `birefnet` (needs `trust_remote_code`).

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.

## Background colour

Default is green auto-detection. For any other flat background, pass the colour as a
hex prior so both the chroma key and the de-spill work off it:

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

or set `screen_color: "#CFEFFF"` in the config (`null` = green auto-detect). The
chroma key then scores pixels by perceptual (Lab/RGB) distance to that colour, and
de-spill removes chroma along that colour's direction instead of the green channel.

## 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 `
  --config configs\default.yaml `
  --screen-color "#CFEFFF" `
  --device cuda
```

The CLI reads `configs/default.yaml` when `--config` is provided. Command-line
options override config values, so tuning usually happens in YAML while runtime
choices such as `--device cpu` or `--screen-color` stay on the command line.

## Batch

```powershell
D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
  --input-dir Samples `
  --output-dir Outputs `
  --debug-dir Outputs\debug `
  --config configs\default.yaml `
  --device cuda
```

## 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 `
  --config configs\default.yaml `
  --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.