BFS H3 SAM 3.1 Cast Tracking

What this node is for

BFS H3 SAM 3.1 Cast Tracking turns a handful of clicks into masks. You told the workflow "Picture 1 is the person clicked at frame 214," and this node segments that person on that frame, tracks them forward and backward through the whole clip, and hands back one mask per Picture. Those masks are what let the H3 reference-attention nodes weight the right face in the right place.

The alternative - hoping the prompt's "the woman in the red jacket" is enough to keep two references from cross-contaminating - works until it doesn't. A tracked mask is a spatial claim, and regional attention respects spatial claims.

Also worth flagging up front: it uses SAM3_Detect, SAM3_VideoTrack and SAM3_TrackToMask from ComfyUI's own comfy_extras/nodes_sam3.py. There's no bespoke segmenter bundled, and no insightface. If your ComfyUI doesn't have native SAM 3 nodes, this node can't work.

How the tracking actually runs

The frames get downsampled first, to a longest side of max_tracking_side (default 640, 128–1536 in steps of 32). That's a tracking-resolution knob, not an output-resolution one - masks are kept at that working size and applied as attention regions, so 640 is plenty and 1536 mostly buys you time-to-fail.

Then, per binding:

1. SAM3_Detect runs on the single key frame with your positive points (and any shift-click negatives), producing the initial mask. If it comes back empty, the node raises rather than silently continuing: "SAM 3.1 found an empty initial mask for Picture N; adjust its selection points."
2. Forward tracking runs SAM3_VideoTrack over the rest of the clip in chunks of at most 150 frames, carrying the last mask forward as the new seed between chunks. SAM3_TrackToMask converts each chunk's track data into a mask.
3. Backward tracking does the same thing on the reversed prefix and flips the result, so the frames before your key frame get a mask too. The two halves are stitched at the key frame.

threshold (default 0.5) is the detector's confidence cutoff. Raise it if the track drifts onto a bystander; lower it if the subject keeps vanishing.

Outputs are cast_masks (a BFS_H3_CAST_MASKS bundle, one entry per Picture, plus the source frame count) and report. The report is JSON stats per Picture - empty_frames and mean_coverage - and it's the field you should actually read. The node also writes a preview mp4 into temp with each track tinted a different colour. Those colours are preview only; nothing is burned into your guide.

Where it plugs in

Select Cast (images) ──→ SAM 3.1 Cast Tracking ──→ Apply Cast Reference Bindings ──→ guider

images is the full loaded 24 fps guide (the same one that goes into the loop's Start node), model is the SAM checkpoint - either from BFS H3 Optional SAM 3.1 Model or a plain core CheckpointLoaderSimple - and cast_selection is the bundle from the click selector. enabled off returns an empty bundle, so the downstream apply node has nothing to do.

The inputs are lazy: if the upstream select node blocked itself in setup mode, or SAM is switched off, the graph won't force a load.

Install and models

cd ComfyUI/custom_nodes
git clone https://github.com/alisson-anjos/ComfyUI-BFSNodes.git
cd ComfyUI-BFSNodes
pip install -r requirements.txt

Restart, hard-refresh the browser. The checkpoint goes in ComfyUI/models/checkpoints/sam3.1_multiplex_fp16.safetensors - the Comfy-Org one from huggingface.co/Comfy-Org/sam3.1. Nothing downloads automatically; that's deliberate, and the optional loader says so.

Note the licence wrinkle the KB is clear about: SAM and SAM 2 are Apache 2.0, SAM 3 is under Meta's custom SAM Licence. If you're shipping commercial output, read it before building a pipeline on this.

Common issues

Empty initial mask. Your click missed the subject, or the point landed on a limb that SAM reads as part of the background. Click the torso, not the edge of a sleeve, and add a negative point on whatever it keeps grabbing.

Masks snap to the wrong person after a crossing. One point anchor doesn't survive arbitrary occlusions or crossings - the docs say so directly. There's no closed-loop mask repair in this version. Options: pick a key frame after the crossing, split the shot at the cut, or accept it and check the report numbers.

Tracking broke on the frame-index mismatch. The key frame index is relative to the loaded clip. If you changed the loader's trim after selecting, every frame reference is stale.

It's slow on a long clip. Two passes over the video (forward and backward), at 150-frame chunks, per Picture. A 60-second clip with three bound Pictures is a lot of SAM inference. Track on the full clip once and let the loop slice it - that's the intended pattern, and it's faster than re-tracking per shot.