Add recolor pass to clean residual contamination colour

Add bgfilter/recolor.py: after despill, propagate clean neighbour chroma into
pixels whose colour is still off (residual green, or the magenta a green unmix
overshoots into), keeping luminance partway so hair texture survives. It installs
a real observed colour rather than subtracting, so it cannot overshoot. Despill
already neutralises the matte edge (off ~ 0 there), so recolor only touches the
contaminated interior and the wisps the dropout-fill rescued.

Runs as a final colour pass on the despilled foreground; pymatting + despill keep
their stronger edge handling. On the samples the magenta fringe drops sharply
(TestImage vis-magenta 0.065->0.014, TestImage2 0.085->0.031) with edge green
unchanged (vis-green ~0.02). Debug output color_mask.png replaces the despill /
foreground-background / foreground-correction maps; smoke updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

bgfilter/settings.py

@@ -79,6 +79,19 @@ class DespillSettings:
     alpha_weight_floor: float = 0.35
 
 
+@dataclass(frozen=True)
+class RecolorSettings:
+    enabled: bool = True
+    person_threshold: float = 0.5      # clean reference = subject above this seg/alpha
+    coverage_soft: float = 0.08        # recolour ramps in over alpha 0..this
+    contam_low: float = 0.02           # residual off-colour where recolour starts
+    contam_high: float = 0.12          # residual off-colour for full recolour
+    clean_dom_max: float = 0.03        # reference = subject pixels below this off-colour
+    propagate_radius_ratio: float = 0.02
+    min_reference_weight: float = 0.05
+    luminance_strength: float = 0.5    # how far to pull luminance to the clean neighbour
+
+
 @dataclass(frozen=True)
 class ModelSettings:
     model_name: str = "hustvl/vitmatte-small-composition-1k"
@@ -102,5 +115,6 @@ class PipelineSettings:
     alpha_post: AlphaPostSettings = AlphaPostSettings()
     foreground: ForegroundSettings = ForegroundSettings()
     despill: DespillSettings = DespillSettings()
+    recolor: RecolorSettings = RecolorSettings()
     model: ModelSettings = ModelSettings()
     segmentation: SegmentationSettings = SegmentationSettings()