ausboss-ComfyUI-AusBoss/js/docs/AUSBOSS_NODES_RefineMask.md

Mask Refine

Cleans up a segmentation mask in one pass: grow or shrink the coverage, optionally fill enclosed holes, melt staircase jaggies, feather the edge, optionally snap the edge to a guide image, then remap the levels. Both the refined mask and its inverse are returned, so no separate invert node is needed.

The panel shows the refined mask itself once the node has run, so the effect of a setting is visible without wiring a preview node beside it. The small preview switch at the right of the bar above the picture turns it off: the picture's box disappears, the node is that much shorter, and no preview file is written. Turn it back on and the node returns to its height with the last result in it; if the node ran while the switch was off, it asks you to run the workflow again. The switch is the node's optional preview input.

The buttons

• AUTO — reads the size of the mask on the panel and sets expand and blur to a sensible starting point for it. A feather is a fraction of the picture, not a fixed pixel count: the 8 px grow that covers a watermark's rim on a 576-tall clip is a smear on a thumbnail and invisible on a 4K plate, so the values scale with the mask's short edge. They are a starting point to nudge, not a correct answer — how far a mask has to grow depends on how tight the segmentation was, which nothing can read off the picture. Needs one run first, since that is when the panel learns the mask's size.
• MORE — the fold on the card under blur shows or hides the advanced rows. The node opens on expand and blur alone; the rest are one click away. Hidden rows keep their values, so a workflow that set them is unaffected, and the choice is remembered per node.

Controls

• mask: BHW mask; white is the selected area.
• expand: Pixels to grow (+) or shrink (-). Soft input values survive.
• blur: Gaussian feather strength in pixels; 0 keeps hard edges.

Advanced (behind MORE)

• fill_holes: Fills fully enclosed gaps inside the mask before feathering. Gaps that touch the image border are left alone.
• Max hole size (max_hole_size): The biggest hole fill_holes fills, as a percent of the picture. Use it when you paint around something you want to keep: at 2, the small gaps a quick brush leaves still fill, but a person, pet or object you left unpainted stays as it is. 0, the default, fills every hole whatever its size. It only matters while fill_holes is on.
• smooth: Melts staircase jaggies by this many pixels while keeping a hard edge — the mask is binarized, blurred, and re-binarized, so nothing is feathered. 0 is off. Use this on blocky segmentation output; use blur when you actually want a soft edge.
• black_point / white_point: Levels remap applied last. Values at or below black_point become fully black and values at or above white_point become fully white; the range between rescales linearly. Raise black_point a little to clear gray haze, lower white_point to solidify the core. The defaults (0.0 / 1.0) change nothing.
• Edge (edge_refine): off, guided (guided filter), or matting. Both refinements snap the mask edge to the connected guide_image and run per frame, so video batches stay interruptible:
  • guided filter — fast edge-aware filtering of the soft mask against the guide image. The filter radius scales with expand.
  • matting — closed-form alpha matting: the binarized mask eroded by the edge radius counts as definite foreground, the dilation marks where definite background begins, and the band between is solved against the guide image. Pair it with the levels remap to tidy the solved alpha.
• guide_image (optional input): RGB frames the mask belongs to, matching the mask's size; one frame is broadcast across a mask batch. Required when edge_refine is not off.

Optional installs

Everything above runs on the pack's stock dependencies except the two edge_refine tiers:

• guided filter needs opencv-contrib: python -m pip install opencv-contrib-python
• matting needs pymatting: python -m pip install "pymatting>=1.1"

Run them with the Python that runs ComfyUI (for the Windows portable build, python_embeded\python.exe -m pip install ...).

They are listed in the pack's pyproject.toml under [project.optional-dependencies] as the guided-filter and matting groups. Without the install, selecting that tier fails with a message naming the missing package; the rest of the node is unaffected.

Outputs

• mask: The refined BHW mask.
• mask_inverted: 1 - mask, for operations that target the background.

Operations run in a fixed order — expand, fill holes, smooth, blur, edge refine, black/white point — so feathered edges are never re-hardened by a later step and the levels remap always cleans the final result.

Technical details

Max hole size measures each hole after expand has moved the mask, as a share of that picture's whole area, so the same setting works at any resolution; in a batch every picture is judged on its own. A hole exactly at the limit is filled. 100 and above fill every hole, the same as 0. An unpainted area that touches the picture's edge is never a hole, at any setting, because the mask does not close around it.

On the test masks, at 0.25 to 16 megapixels, the gaps a quick brush left between strokes and the spots it missed were at most 1.3% of the picture, and the subjects left unpainted (a person, a dog, a shoe, a cat) at least 18%. A face kept on its own was 2.1% to 5.3%: 2 keeps a face from a three-quarter shot or closer, while a face in a full-length shot is smaller and would still fill. A very loose hand with a big brush can leave long bands between strokes that pass 2%: raise the setting, or paint over them.