Mask Refiner

A coarse mask from SAM is rarely finished. It's got holes, fuzzy edges, background bleed, maybe a thin antenna that got eroded away. Mask Refiner (MEC) is the cleanup stage - a chain of up to eleven training-free refinement passes, each with its own toggle, that polish a mask toward production quality without loading a single model weight.

Think of it as the "make it actually usable" node you bolt onto the end of a segmentation. The pack's bigger MaskOps node has auto-polish built in; this one gives you the manual, stage-by-stage control for when auto isn't enough.

How it works

Stages run in fixed order, each gated by a toggle: hole-fill → morphology → thin-structure recover → joint bilateral → guided filter → DenseCRF → edge-snap → optional CascadePSP-style multi-pass → feather → gamma → threshold. Missing optional dependencies silently disable just their stage - the rest still run, which is a thoughtful design.

The on-by-default magic is auto_edge_lock (default on): it pins the mask to real image edges so it stops bleeding into the background, tuning the guided filter + edge-snap by subject_class. Pick face, hair, garment, object, or hard_surface and it adapts - hair gets thin-recovery and a soft band, hard surfaces get a tight band and max snap. This single toggle + subject picker does most of the work people are trying to do with DenseCRF, for free.

Everything else is opt-in per stage: enable_hole_fill, morph_op (close/open/dilate/erode), enable_thin_recover (saves hair strands and antennas), enable_joint_bilateral, enable_guided_filter, enable_dense_crf (sharpest edges, needs pydensecrf), enable_edge_snap, cascade_passes, plus finishers: feather_sigma, gamma, threshold.

There are also five presets - balanced, fast, hair, aggressive, crf_heavy - that fill in sensible numerics for every enabled stage, and an advanced_overrides_json for power users who want to override individual stage parameters (gf_radius, crf_iterations, speck_min_area, ...). The optional enable_integrity_check appends per-frame stats (coverage, abrupt drops, frame jumps) to the info JSON - a lightweight video QA.

Outputs

mask (the refined hard mask), alpha (soft alpha before thresholding - grab this if you want a soft matte), preview (RGB×alpha for a quick diff), and info (JSON listing which stages ran or were skipped - invaluable when a dep is missing and a stage silently didn't run).

Install and dependencies

cd ComfyUI/custom_nodes
git clone https://github.com/Code2Collapse/ComfyUI-CustomNodePacks.git
pip install opencv-python>=4.7.0 scipy>=1.10.0

Optional deps unlock stages: opencv-contrib-python (joint bilateral + domain transform), scikit-image (thin recovery), scipy (hole fill/morphology helpers - already a pack dep), pydensecrf (DenseCRF). Each missing dep disables only its stage, so don't over-install - add pydensecrf only if you genuinely need CRF-sharp edges. Restart after install and confirm [MEC] Loaded ... in the console.

The habit worth forming: turn on auto_edge_lock, set subject_class, then inspect info to see what ran. Reach for the exotic stages (DenseCRF, domain transform) only when the cheap ones lose.