Staged MediaPipe Face Options

A small config node with a very specific job: it holds the settings for how UC_StagedMediaPipeFaceBackgroundComposite finds, cuts out, and initially places faces. On its own it does nothing - it's a settings struct you wire into the face compositor's face_options socket. Think of it as the "face layer" counterpart to the UC_StagedLayeredBackgroundCompositeOptions node, which handles the ordinary foreground cutouts.

Why you'd reach for it

If you've ever run a face-detect composite and gotten 12 boxes on one crowd shot, or a face layer that lands halfway off the canvas, this is where you fix that before it happens. The face detection uses ComfyUI core's MediaPipe FaceLandmarkerModel - the same Apache-2.0 detection path as the MediaPipe Face Composite family - so no extra weights beyond the mediapipe_face_fp32.safetensors file that core auto-downloads into ComfyUI/models/detection.

The inputs that matter

• detection_threshold (0.55) - minimum MediaPipe confidence to keep a face. Raise it when you're getting false positives on background clutter; lower it when real faces get dropped.
• maximum_faces (16) - cap per foreground image. The hard ceiling is 16, so a crowd shot still only yields the 16 most confident faces. Crank it if you're compositing a group.
• bbox_expansion (64) - pixels added around each face box before extraction. This is the dial that decides whether you get a tight face or head-and-shoulders. 64px on a 1024px canvas is a reasonable default; bump it for portraits.
• mask_expansion - grow the face mask by pixels; negative values shrink it. Handy when the face mask bleeds over hair.
• face_feather_radius (8) - inward softness on the extracted face-mask edge, so the pasted face doesn't sit on a visible seam.
• initial_face_scale (0.25) - the layer's starting size relative to the background's shortest side. 0.25 is "about a quarter of the frame"; you'll often dial this to taste per scene.
• face_blend - 1.0 is fully face; 0.0 gives a 50/50 normal blend where another foreground or face sits underneath.

It outputs one Face Options socket of type UC_STAGED_MEDIAPIPE_FACE_OPTIONS, which plugs straight into the face compositor.

How to install it

This ships inside ComfyUI-UtilsCollection (author: silveroxides), so it installs with the whole pack:

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

Restart ComfyUI afterward, or just search "ComfyUI-UtilsCollection" in Manager. The pack's own dependencies are minimal (opencv-python, typing-extensions); the face model is ComfyUI core's.

Where people trip up

Because this is a pure config struct, its values only matter when the compositor re-stages. Change bbox_expansion after a run_staged pass and you'll swear nothing happened - the retained cutouts were made with the old geometry. Force a restage (run_staging or full_run) and the new face boxes appear. Also remember the retention gotcha that hits the whole staging family: cutouts live in server memory and are gone after a ComfyUI restart, so your careful face placement needs a staging pass again.