lhk229
9b7a192599
After the full-foreground despill (5ddf0cd) the residual green was confined to
semi-transparent hair (alpha < 0.5): 85% of the worst pixels had alpha < 0.3,
where a pixel-wise unmix (divide by small alpha) is too noisy to trust.
Replace the hand-rolled unmix/local-blur estimator with pymatting's
estimate_foreground_ml (Germer et al. multi-level closed form), which propagates
reliable foreground colour from high-alpha neighbours into the fringe and
estimates the background, so green spill is unmixed rather than clamped. The
despill pass stays as a light cleanup on top.
- foreground.method selects "ml" (default) or "unmix" (legacy heuristic kept as
a fallback when pymatting is unavailable, matching the chroma fallback idiom).
- ForegroundEstimate now exposes rgb (F), background (B) and a correction map;
debug outputs become foreground_rgb / foreground_background / foreground_correction.
Controlled comparison (same ViTMatte alpha, only foreground method changed),
edge_green_excess:
TestImage p95 0.176->0.031, mean 0.061->0.005
TestImage2 p95 0.165->0.004, mean 0.052->0.002
Adds pymatting (pulls in numba) to requirements.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
BgFilter
Offline green screen character matting for AI-generated character images.
The first implementation follows the workflow in
docs/green_screen_matting_workflow.md:
RGB input -> chroma confidence -> trimap -> ViTMatte -> alpha cleanup -> despill -> RGBA PNG -> QA previews
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 `
--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:
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
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.
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
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.
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
Current Notes
Samples/andOutputs/are ignored by Git.ViTMattemodel weights are loaded from Hugging Face on first use.- Foreground color estimation uses pymatting's
estimate_foreground_mlto propagate clean foreground colour into semi-transparent edges before final de-spill, writing the estimated foreground, background, and a correction map. Setforeground.method: unmixto fall back to the legacy heuristic.