Make Refs Composite By SAM3

Reference sheets are the unglamorous secret of consistent video

Multi-reference video generation - MiniMax H3 reference mode, LTX IC-LoRA guides, Wan SCAIL - loves a reference sheet: all your subject images laid out on one fixed-size canvas so the model sees the whole cast in a single conditioning pass. Building that sheet is normally a manual slog in an image editor: cut out your subject, paste on a canvas, resize, repeat. This node automates it, and its party trick is that it uses SAM3 to cut the subject out for you.

easy makeRefsCompositeBySam3 takes your images and a prompt describing the subject, detects the subject in each image with SAM3, and composites the masked subjects onto a canvas at your target width × height. One composite IMAGE + one MASK out, ready to feed a reference-conditioning pipeline.

How it works

Two modes, chosen by composite_mode:

• original (default) - skips SAM3 entirely. Each image is placed on the canvas as-is, and the mask output is a full-white mask (everything included). Cheap, instant, no model needed. Use this when your references are already clean cutouts or when SAM3's segmentation isn't buying you anything.
• sam3_masked - the real deal. It tokenizes your prompt with the clip input, then runs each image through SAM3_VideoTrack with your detection_threshold to find the prompted subject, converts the track to a mask with SAM3_TrackToMask, and composites only the segmented subject onto the canvas. This is where "detect subject in prompt using SAM3" from the README happens.

Either way, the final step is _compose_refs: it arranges the (masked or original) images on a canvas of your width × height against a background of white or black, and produces both the composite image and its mask.

SAM3 matters here because it's the current generation of Meta's segmentation model - the one where a short noun phrase returns a mask for every matching instance without a separate GroundingDINO step. It's the natural fit for "grab the character out of this photo."

The inputs that matter

• images - your reference photos.
• prompt - in sam3_masked mode this is required (empty prompt → hard error). It's the subject description SAM3 looks for, e.g. "a woman with red hair."
• model + clip - the SAM3 model and text encoder. Only used in sam3_masked mode.
• width / height (1024) - the target canvas size. This is what your downstream model sees, so set it to the generation resolution.
• detection_threshold (0.5) - SAM3's confidence bar for accepting a detection. Crank it up if it's grabbing wrong objects; lower it if it misses the subject.
• background - white or black canvas behind the composites.
• composite_mode - original or sam3_masked, the big switch above.

Outputs: composite (IMAGE) - the arranged canvas; mask (MASK) - where the subjects actually are.

Setup and the traps

Pack install (Manager → ComfyUI-Easy-Media, or git clone + restart). The sam3_masked path imports comfy_extras.nodes_sam3, so you need a ComfyUI build with SAM3 support - if it's missing, the node raises a clear "requires ComfyUI with SAM3_VideoTrack support" error. You'll also need the SAM3 model itself loaded and wired to model.

Where it bites:

• Original mode is the easy win. If you don't have a SAM3 model or your references are already clean, don't install anything - original mode needs no model, no clip, and no prompt. The SAM3 machinery only activates when you select sam3_masked.
• Empty prompt in sam3_masked mode → immediate error, on purpose. The prompt is what SAM3 searches for; without it there's nothing to detect.
• Threshold tuning. At 0.5 the detection can be greedy or shy depending on your subject. If the composite shows half the image or nothing, nudge detection_threshold rather than the prompt.
• Canvas mismatch. Your width/height is the conditioning canvas - setting it to a wildly different aspect than your generation resolution means the downstream model sees scaled references. Match it to the generation.

For anyone building multi-character or multi-reference video workflows, this node is the "arrange the cast" step you didn't know you were missing - and SAM3 makes it genuinely cut-out-clean instead of rough-square crops.