lhk229
2b3b62ed3f
The veto's suspect zone was defined by background-hue projection, so --no-chroma silently skipped it. Without a key colour there is no hue test to lean on, so in complex mode the gate instead requires the second opinion itself to be confidently near-empty (second_lo -> second_hi ramp, default 0.15 -> 0.40): regions the HR-matting model decisively rejects can be cleared, while thin strands it merely blurs to mid-alpha are untouched -- protecting exactly the crisp-strand advantage the pipeline has over a raw BiRefNet mask. Flat mode's gate is unchanged. Validation (BG_IMAGE01-04, cuda fp32): flat default path bit-identical; complex-mode veto touches 0.007-0.025% of pixels, visibly clearing blurred residue near strands and milky specks in hair gaps with no strand erosion. Costs the HR-matting forward in --no-chroma runs (0.61 -> 1.6 s/image warm GPU); disable with --no-cross-check. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
203 lines
10 KiB
Python
203 lines
10 KiB
Python
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ChromaSettings:
|
|
# False = non-flat-background mode (--no-chroma): no colour key at all.
|
|
# Segmentation alone drives the trimap (mode forced to "seg"), and the
|
|
# colour-keyed stages are bypassed: background auto-detect, the directional
|
|
# hue split, chroma alpha suppression, despill, and the unmix foreground
|
|
# fallback. The cross-check veto still runs (if enabled) with a hue-free
|
|
# gate -- see CrossCheckSettings.second_lo/hi. Requires
|
|
# segmentation.enabled and matting_method 'vitmatte'.
|
|
enabled: bool = True
|
|
border_ratio: float = 0.04
|
|
min_samples: int = 2048
|
|
lab_sigma_min: float = 10.0
|
|
rgb_sigma_min: float = 0.08
|
|
# Background-colour auto-detection (used when screen_color is None): find the
|
|
# flat colour that dominates the image border; raise if none is clean enough.
|
|
detect_cluster_radius: float = 12.0 # Lab radius grouping border pixels into the background cluster
|
|
detect_min_border_share: float = 0.55 # min fraction of the border that must be this one colour
|
|
detect_corner_tol: float = 20.0 # max Lab distance a corner may sit from the cluster centre
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class TrimapSettings:
|
|
sure_bg_threshold: float = 0.92
|
|
sure_fg_threshold: float = 0.12
|
|
unknown_radius_ratio: float = 0.012
|
|
fg_safe_radius_ratio: float = 0.006
|
|
min_unknown_radius: int = 4
|
|
min_fg_safe_radius: int = 2
|
|
# Semantic fusion thresholds (used by fuse_trimap when segmentation is on).
|
|
seg_core_threshold: float = 0.60
|
|
seg_loose_threshold: float = 0.08
|
|
# Trimap mode for the segmentation pipeline (the chroma-only pipeline ignores it):
|
|
# "directional" (default) -- chroma magnitude + seg + a hue-direction split. In
|
|
# the chroma-unknown zone a confidently-segmented pixel stays foreground
|
|
# unless it is displaced toward the background hue: a neutral background-
|
|
# coloured garment (e.g. a white shirt) is kept, while a background-hued
|
|
# residual (e.g. blue trapped between hair strands) is left UNKNOWN for
|
|
# ViTMatte / chroma-suppress to clear.
|
|
# "seg" -- original fuse_trimap: seg topology + chroma veto, no hue split.
|
|
# "directional-hard-bg" -- like "directional" but hard-marks background-hued
|
|
# pixels as background; more aggressive, can eat cool/shadowed white cloth.
|
|
mode: str = "directional"
|
|
seg_low: float = 0.15 # seg below this -> background-eligible; at/above -> foreground-eligible
|
|
bg_hue_proj_min: float = 4.0 # Lab a*/b* projection onto bg direction above which a pixel is background-hued
|
|
# Semantic override for the directional hue split: a chroma-unknown pixel whose
|
|
# seg confidence is at/above this is kept sure-FG even when background-hued.
|
|
# A saturated seg signal outranks colour evidence that only says "same hue
|
|
# family as the background" (bright skin on a warm background, measured raw
|
|
# ViTMatte failures at proj ~7-10). Chroma sure-background is never overridden,
|
|
# and the silhouette band still re-opens the boundary for anti-aliasing.
|
|
# Set > 1.0 to disable. (seg masks are uint8-quantised: 0.98 = 250/255.)
|
|
seg_force_fg: float = 0.98
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class AlphaPostSettings:
|
|
min_component_area_ratio: float = 0.00001
|
|
fill_hole_area_ratio: float = 0.00002
|
|
alpha_floor: float = 0.002
|
|
alpha_ceil: float = 0.998
|
|
# Chroma-guided alpha suppression: in the unknown band, pull alpha toward 0
|
|
# where background-colour confidence is high, clearing spill in gaps/holes.
|
|
chroma_suppress: bool = True
|
|
chroma_suppress_bg_low: float = 0.35
|
|
chroma_suppress_bg_high: float = 0.80
|
|
chroma_suppress_strength: float = 1.0
|
|
# Matte-confidence gate: fade the suppression where ViTMatte itself is confident
|
|
# the pixel is opaque (raw alpha ramps lo -> hi), so colour evidence only vetoes
|
|
# the matte where the matte is unsure. Protects background-coloured subjects
|
|
# (white shirt on pastel blue, blush on pink) that chroma alone cannot tell from
|
|
# background residue. Set suppress_raw_lo >= 1.0 to disable the gate.
|
|
suppress_raw_lo: float = 0.85
|
|
suppress_raw_hi: float = 0.98
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class CrossCheckSettings:
|
|
# Cross-model veto: a trimap-free matting model gives a second opinion that
|
|
# may only LOWER alpha (min-fusion), only on background-hued, non-dark pixels
|
|
# (the suspect zone) where the primary result is confident (gate_lo->gate_hi
|
|
# alpha ramp). Clears colour-drifted background residue between hair strands
|
|
# that chroma, segmentation and the primary matte all read as foreground;
|
|
# already-soft wisps and dark hair are exempt by construction.
|
|
enabled: bool = True
|
|
model_name: str = "ZhengPeng7/BiRefNet_HR-matting"
|
|
input_size: int = 2048
|
|
# Reuse the cross-check forward as the segmentation mask: one HR-matting
|
|
# inference serves both trimap topology and the second opinion, skipping the
|
|
# primary seg model entirely (saves its load + forward; measured ~20 s/image
|
|
# on CPU, ~0.9-1.3 GB VRAM on GPU). Pilot-validated on TestImage3/FixImage1:
|
|
# trimap 99.8% identical. Default OFF on server-edition: the dedicated
|
|
# segmenter keeps its own forward and the veto stays an independent signal;
|
|
# opt in with --cross-check-as-seg. Only applies to the birefnet backend
|
|
# (a same-family swap); needs cross_check and segmentation both enabled.
|
|
reuse_as_seg: bool = False
|
|
# Compute precision of the cross-check forward: "fp32" or "bf16" (autocast;
|
|
# needs bf16-capable hardware, else falls back to fp32 with a warning).
|
|
precision: str = "fp32"
|
|
proj_min: float = 3.0 # bg-hue projection above which a pixel is suspect
|
|
l_min: float = 45.0 # Lab lightness below which a pixel is exempt (dark hair)
|
|
feather_sigma: float = 2.0 # Gaussian feather of the zone boundary, in px
|
|
gate_lo: float = 0.70 # primary alpha below this -> fully exempt
|
|
gate_hi: float = 0.95 # primary alpha above this -> fully vetoable
|
|
# Complex-background mode only (chroma disabled -> no hue-defined suspect
|
|
# zone): the veto instead requires the second opinion itself to be
|
|
# confidently near-empty -- full strength at/below second_lo, none at/above
|
|
# second_hi. Thin structures the downsampled second model merely blurs to
|
|
# mid-alpha stay untouched; only decisively-rejected regions can be cleared.
|
|
second_lo: float = 0.15
|
|
second_hi: float = 0.40
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ForegroundSettings:
|
|
enabled: bool = True
|
|
method: str = "ml" # "ml" (pymatting) or "unmix" (legacy heuristic)
|
|
fallback_to_unmix: bool = True
|
|
ml_regularization: float = 1e-5
|
|
# Legacy "unmix" method parameters (used only when method == "unmix").
|
|
edge_low: float = 0.005
|
|
edge_high: float = 0.995
|
|
min_unmix_alpha: float = 0.08
|
|
unmix_strength: float = 0.70
|
|
local_strength: float = 0.45
|
|
local_blur_radius: int = 11
|
|
local_alpha_threshold: float = 0.92
|
|
local_bg_confidence_max: float = 0.20
|
|
green_excess_margin: float = 0.015
|
|
bg_confidence_weight: float = 0.70
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class DespillSettings:
|
|
# Off by default: despill pulls foreground chroma along the background-hue axis
|
|
# with no positional or semantic guard, so a subject sharing the background's hue
|
|
# (e.g. a blue suit on a blue backdrop) is desaturated/hue-shifted (~ΔE 35, blue
|
|
# -> purple). This is the root default the cpu-fast lane inherits. Re-enable
|
|
# per-config or with --despill only when edge spill genuinely matters.
|
|
enabled: bool = False
|
|
edge_low: float = 0.005
|
|
strength: float = 0.92
|
|
edge_expand_radius: int = 2
|
|
alpha_weight_floor: float = 0.35
|
|
# Margin, in Lab a*/b* units, of chroma allowed along the background-colour
|
|
# direction before it counts as spill. Larger keeps more of the subject's own
|
|
# colour.
|
|
color_margin_lab: float = 4.0
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ModelSettings:
|
|
model_name: str = "hustvl/vitmatte-base-composition-1k"
|
|
device: str = "cpu"
|
|
matting_method: str = "vitmatte"
|
|
fallback_to_chroma_alpha: bool = False
|
|
# ViTMatte compute precision: "fp32" or "bf16". bf16 halves the matting
|
|
# model's activation memory with visually identical alpha, but needs
|
|
# bf16-capable hardware (any modern GPU, or a CPU with AVX512-BF16/AMX) —
|
|
# otherwise it falls back to fp32 with a warning. The BiRefNet models have
|
|
# their own precision fields; --precision sets all of them at once.
|
|
precision: str = "fp32"
|
|
# Query-chunked global attention (exact math, bitwise-identical output):
|
|
# the VitDet backbone's 4 global blocks materialize an N^2 attention map —
|
|
# ~19 GB at 2048x2048. Blocks seeing more than this many tokens compute it
|
|
# in query chunks of this size instead, capping the transient at
|
|
# O(N * chunk): 19.8 -> 4.0 GB for ~15% more ViTMatte time. 0 disables.
|
|
attn_query_chunk: int = 2048
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class SegmentationSettings:
|
|
enabled: bool = True # False = chroma-only pipeline (no seg model)
|
|
backend: str = "birefnet" # "birefnet" (general) or "anime-seg" (anime characters)
|
|
model_name: str = "ZhengPeng7/BiRefNet"
|
|
device: str = "cpu"
|
|
input_size: int = 1024
|
|
# Compute precision of the BiRefNet forward: "fp32" or "bf16" (autocast; needs
|
|
# bf16-capable hardware, else falls back to fp32 with a warning). The ONNX
|
|
# anime-seg backend ignores this.
|
|
precision: str = "fp32"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class PipelineSettings:
|
|
chroma: ChromaSettings = ChromaSettings()
|
|
trimap: TrimapSettings = TrimapSettings()
|
|
alpha_post: AlphaPostSettings = AlphaPostSettings()
|
|
cross_check: CrossCheckSettings = CrossCheckSettings()
|
|
foreground: ForegroundSettings = ForegroundSettings()
|
|
despill: DespillSettings = DespillSettings()
|
|
model: ModelSettings = ModelSettings()
|
|
segmentation: SegmentationSettings = SegmentationSettings()
|
|
# Background-colour prior. None = auto-detect the flat background colour from the
|
|
# image border (raises if there is no clean flat background). A hex string like
|
|
# "#CFEFFF" sets it explicitly.
|
|
screen_color: str | None = None
|