BGfilter/README.md

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.

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:

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

conda activate lightML
pip install -r requirements.txt

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

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

Single Image

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

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

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:

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.

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:

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.