BGfilter/configs/default.yaml

# Background-colour prior. null = auto-detect the flat background colour from the
# image border (raises if the border is not one clean flat colour). A hex string
# like "#CFEFFF" sets it explicitly. Also overridable via --screen-color.
screen_color: null

chroma:
  # false = non-flat background mode (--no-chroma): no colour key; segmentation
  # alone drives the trimap (mode forced to "seg") and every colour-keyed stage
  # is bypassed (auto-detect, hue split, chroma suppression, despill, the
  # cross-check veto). Needs segmentation.enabled and matting_method vitmatte.
  enabled: true

model:
  model_name: hustvl/vitmatte-base-composition-1k
  device: cpu
  matting_method: vitmatte
  fallback_to_chroma_alpha: false
  # "bf16" halves ViTMatte activation memory and is ~3x faster on native-bf16
  # CPUs (visually identical alpha); needs bf16-capable hardware (modern GPU /
  # AVX512-BF16 CPU), else falls back to fp32. --precision bf16 sets bf16 here
  # AND on the BiRefNet models below in one go.
  precision: fp32
  # Query-chunked global attention (exact, bitwise-identical output): caps the
  # VitDet global blocks' N^2 attention transient at O(N * chunk) — 19.8 -> 4.0
  # GB at 2048x2048 for ~15% more ViTMatte time. 0 = stock one-shot attention.
  attn_query_chunk: 2048

segmentation:
  # enabled: true  = single-segmenter pipeline (one seg model drives the trimap)
  # enabled: false = no seg model, chroma-only pipeline (Chroma + ViTMatte)
  enabled: true
  backend: birefnet           # single trimap segmenter; switchable at runtime: --seg-backend birefnet|anime-seg
  model_name: ZhengPeng7/BiRefNet  # matches backend; --seg-backend anime-seg auto-selects skytnt/anime-seg
  device: cpu
  input_size: 1024
  # BiRefNet forward precision: "bf16" runs via autocast (~1.4x on native-bf16
  # CPUs, visually identical), else falls back to fp32. anime-seg ignores this.
  precision: fp32

trimap:
  sure_bg_threshold: 0.92
  sure_fg_threshold: 0.12
  unknown_radius_ratio: 0.012
  fg_safe_radius_ratio: 0.006
  seg_core_threshold: 0.60
  seg_loose_threshold: 0.08
  # Trimap mode (segmentation pipeline only; also settable via --trimap-mode):
  #   directional          = chroma + seg + hue split; background-hued residual
  #                          (blue between hair) -> unknown, white shirt kept. (default)
  #   seg                  = original fuse_trimap (no hue split).
  #   directional-hard-bg  = hard-remove background-hued pixels (aggressive; can eat
  #                          cool/shadowed white cloth).
  mode: directional
  seg_low: 0.15
  bg_hue_proj_min: 4.0
  # Semantic override (directional mode): chroma-unknown pixels with seg confidence
  # at/above this stay sure-FG even when background-hued — rescues bright skin on a
  # warm (same-hue-family) background that the hue split would otherwise hand to
  # ViTMatte/suppression, which misfire exactly there. Never overrides chroma
  # sure-background. Set > 1.0 to disable.
  seg_force_fg: 0.98

alpha_post:
  chroma_suppress: true
  chroma_suppress_bg_low: 0.35
  chroma_suppress_bg_high: 0.80
  chroma_suppress_strength: 1.0
  # Matte-confidence gate: suppression fades where ViTMatte's raw alpha is high
  # (ramp lo -> hi), so colour evidence only vetoes the matte where it is unsure.
  # Set suppress_raw_lo: 1.0 to disable.
  suppress_raw_lo: 0.85
  suppress_raw_hi: 0.98

cross_check:
  # Cross-model veto: a second, trimap-free matting model may only LOWER alpha
  # (min-fusion), only on background-hued bright pixels the primary result is
  # confident about — clears colour-drifted background residue between hair
  # strands that chroma, segmentation and ViTMatte all read as foreground.
  # Costs one extra model (~0.9 GB download) and one inference pass per image.
  # Disable with enabled: false or --no-cross-check.
  enabled: true
  model_name: ZhengPeng7/BiRefNet_HR-matting
  input_size: 2048
  # Reuse the cross-check forward as the seg mask: one HR-matting inference
  # drives both trimap topology and the veto, skipping the primary seg model
  # (saves its ~9s forward + ~0.9 GB load; CPU pipeline ~66s -> ~45s). Pilot:
  # trimap 99.8% identical, no structural change (fingers/wisps/bowstring OK).
  # Only applies to the birefnet backend (same-family swap); anime-seg keeps
  # its own forward, with the cross-check running independently on top.
  # Default OFF (server-edition): the dedicated segmenter keeps its own forward
  # and the veto stays independent; enable with --cross-check-as-seg.
  reuse_as_seg: false
  # Cross-check forward precision, same semantics as segmentation.precision
  # (bf16 via autocast: 2048 pass ~35s -> ~26s on a native-bf16 CPU).
  precision: fp32
  proj_min: 3.0        # bg-hue projection above which a pixel is suspect
  l_min: 45.0          # Lab lightness below which a pixel is exempt (dark hair)
  feather_sigma: 2.0   # zone-boundary feather, px
  gate_lo: 0.70        # primary alpha below this -> fully exempt
  gate_hi: 0.95        # primary alpha above this -> fully vetoable

foreground:
  enabled: true
  method: ml
  fallback_to_unmix: true
  ml_regularization: 0.00001
  # Legacy "unmix" method params (used only when method: unmix).
  edge_low: 0.005
  edge_high: 0.995
  min_unmix_alpha: 0.08
  unmix_strength: 0.70
  local_strength: 0.45
  local_blur_radius: 11
  local_alpha_threshold: 0.92
  local_bg_confidence_max: 0.20
  green_excess_margin: 0.015
  bg_confidence_weight: 0.70

despill:
  # Off: despill has no positional/semantic guard, so a subject sharing the
  # background's hue (blue suit on a blue backdrop) gets desaturated/hue-shifted
  # (~ΔE 35, blue -> purple). Re-enable per-job only when edge spill matters.
  enabled: false
  edge_low: 0.005
  strength: 0.92
  edge_expand_radius: 2
  alpha_weight_floor: 0.35
  color_margin_lab: 4.0    # Lab chroma margin along the background-colour direction