# BgFilter

Offline green screen character matting for AI-generated character images.

The first implementation follows the workflow in
[`docs/green_screen_matting_workflow.md`](docs/green_screen_matting_workflow.md):

```text
RGB input -> chroma confidence -> trimap -> ViTMatte -> alpha cleanup -> despill -> RGBA PNG -> QA previews
```

## 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 `
  --device cuda
```

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

Use CPU for validation when CUDA is unavailable:

```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 `
  --device cpu
```

## 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-Only Debug Mode

This mode skips ViTMatte and uses chroma confidence as an alpha seed. It is useful
for fast debugging of chroma confidence, trimap, despill, and QA outputs.

```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
alpha.png
foreground_rgb.png
foreground_background.png
foreground_correction.png
despill_mask.png
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 green 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
```

## Current Notes

- `Samples/` and `Outputs/` are ignored by Git.
- `ViTMatte` model weights are loaded from Hugging Face on first use.
- Foreground color estimation uses pymatting's `estimate_foreground_ml` to
  propagate clean foreground colour into semi-transparent edges before final
  de-spill, writing the estimated foreground, background, and a correction map.
  Set `foreground.method: unmix` to fall back to the legacy heuristic.