Implement green screen matting pipeline

README.md

@@ -0,0 +1,94 @@
+# 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 `
+  --device cuda
+```
+
+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 `
+  --device cpu
+```
+
+## Batch
+
+```powershell
+D:\MiniConda\envs\lightML\python.exe -m bgfilter.cli `
+  --input-dir Samples `
+  --output-dir Outputs `
+  --debug-dir Outputs\debug `
+  --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 `
+  --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
+despill_mask.png
+preview_black.png
+preview_white.png
+preview_gray.png
+preview_red.png
+preview_blue.png
+qa_grid.png
+metadata.json
+```
+
+## Current Notes
+
+- `Samples/` and `Outputs/` are ignored by Git.
+- `ViTMatte` model weights are loaded from Hugging Face on first use.
+- Current despill is conservative and edge-local. Strong green spill around hair may
+  still need parameter tuning or a stronger foreground color estimation pass.