Staged Composite Options

This node is not a compositor. It's the dials for one - a settings bundle you wire into the compositor so you don't have to rebuild its tuning every time you change the layout. If you've seen UC_StagedLayeredBackgroundComposite or UC_StagedMediaPipeFaceBackgroundComposite in a workflow and wondered where the cleanup settings come from, this is that node.

What it is and why you'd bother

In the UtilsCollection staging pipeline, a background image gets a stack of cut-out foregrounds laid on top, and each cutout needs a bit of housekeeping: the background-removal mask has stray specks, the edge is jagged, the resize resampling matters. Those cleanup and resize choices are exactly what this node bundles into one Background Options struct. Leave it disconnected and the compositor runs on sensible defaults. Connect it and you get one place to tune how every cutout behaves, which is worth it the moment you're doing a multi-layer composite and don't want to live-tune a mask's morphology mid-edit.

It ships in ComfyUI-UtilsCollection by silveroxides - the same person behind the Chroma-GGUF quants on HuggingFace. Install it once and every compositor node comes along:

cd ComfyUI/custom_nodes
git clone https://github.com/silveroxides/ComfyUI-UtilsCollection

Then restart ComfyUI. Or use Manager → Install Custom Nodes → search "ComfyUI-UtilsCollection". Dependencies are refreshingly light - requirements.txt is just opencv-python and typing-extensions; the heavy lifting (BiRefNet, MediaPipe) is done by ComfyUI core, not this pack.

How it works

Every field maps to a mask or resize operation the compositor runs before blending. The ones you'll actually touch:

• mask_threshold (0.5) - where the removal model's soft mask gets cut to hard bounds. Bump it up if your cutouts are keeping too much background.
• artifact_cleanup_radius - an opening radius in pixels: erodes then dilates, which deletes small thin mask artifacts. 0 disables it.
• gap_fill_radius - the closing counterpart: fills cracks and pinholes in the mask. 0 disables it.
• border_cleanup_width - strips weak foreground predictions along the source image's edge. 0 disables it. This one rescues you when the removal model leaves a fringe of background hugging the frame border.
• feather_radius - inward mask-edge softness, so the cutout doesn't sit on a hard 1-pixel seam.

Then the resampling pair: image_resize_method (default auto: FP32 area reduction when shrinking, bicubic when enlarging) and mask_resize_method (auto = area shrink / bilinear enlarge to keep soft coverage; nearest-exact forces a hard binary edge). foreground_blend at 1.0 is fully foreground; at 0.0 it's a 50/50 normal blend where something sits underneath - background-only areas stay fully foreground either way. The one advanced field, mask_processing_resolution, caps the longest edge used for mask refinement (0 = the connected model's native size) and is worth leaving alone until you're on a VRAM budget.

Output and wiring

It outputs a single Background Options socket (type UC_STAGED_LAYERED_BACKGROUND_OPTIONS) - a struct, not pixels. Wire it into the background_options input of UC_StagedLayeredBackgroundComposite or UC_StagedMediaPipeFaceBackgroundComposite. Because it's just a config dict, changing a value re-runs the staging stage only, not the whole graph - which is the whole point of separating the dials from the compositor.

Where people get burned: these settings do nothing unless the compositor that consumes them re-stages. If you edited placement after a run_staged pass, the retained cutouts are reused and a new mask_threshold may not visibly apply until you force a restage (run_staging or full_run). Retained cutouts also live in server memory and die on restart - rebuild them and your new cleanup settings apply.