Pertineo ViTMatte Tiled (Sequence)

The batch-based refiner is great until your shot is 400 frames long. Then "load plate, matte plate, save matte" turns into 40 GB of system RAM and a progress bar that starts over from frame one if anything goes wrong at frame 317.

Pertineo ViTMatte Tiled (Sequence) is the same matting, re-plumbed for real shots: folders in, folders out, one frame in memory at a time. You point it at a plate folder and a trimap folder, give it an output folder, and walk away. It's also the node that makes the hybrid workflow possible - the one where a compositor builds trimaps by hand in Nuke, you run the matting, and they read the matte back into the comp.

What it does differently

Nothing about the matting core changes: overlapping tiles, cosine-weighted blending, no downscaling, flip-TTA if you want it. What changes is the loop.

It reads frame pairings by frame number, not by position - plate frame 1042 pairs with trimap frame 1042. It streams: one frame loaded, matted, written, released. And skip_existing is on by default, so aborting at frame 317 and re-queuing picks up at 318 instead of redoing the shot. That one checkbox is the difference between a four-hour render you're scared of and a four-hour render you can iterate on.

It writes the matte as 16-bit PNG or 32-bit float EXR, using the plate's own zero-padding for the frame numbers. It reports preview_last_frame - the final matte, as a MASK, so you can eyeball it - and output_folder as a STRING.

The inputs

Paths (all three are multiline, and all three are forgiving):

• plate_folder - the sequence ViTMatte runs on, PNG/TIFF in sRGB or EXR. You can paste the folder, the path of any one frame (copy-paste from your file manager works), a file:// URI, or a pattern like name.####.png, name.%04d.png, name.$F4.exr.
• trimap_folder - a trimap sequence, written raw/linear: 0 background, 0.5 unknown, 1 foreground. Frame numbers must match the plate.
• output_folder - created if it doesn't exist.

Plus filename_prefix (alpha by default, files come out <prefix>.<frame>.<ext>) and output_format (png (16 bit) or exr (32 bit float)).

Matting settings - same set as the refiner, same defaults: model (base/small/custom), tile_size (1024), overlap (256), flip_tta, clamp_known, quantize_trimap, and the optional custom_model.

Shot controls: exr_plate_to_srgb (leave on - ViTMatte expects sRGB and EXRs are scene-linear), skip_existing, and start_frame / end_frame with -1 meaning "both ends". Wire those from Pertineo Frames for Model if the rest of your graph already has a canonical range.

Install

ComfyUI Manager → Pertineo VFX, restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/pertineo/comfyui-pertineo-vfx
pip install -r comfyui-pertineo-vfx/requirements.txt

OpenEXR>=3.2 is the pack's only dependency and this node is one of the two that uses it. Weights come down on first run - the official hustvl ViTMatte base or small checkpoint into ComfyUI/models/vitmatte, via huggingface_hub. The repo ships two example graphs in example_workflows/: matting_ltx_alpha_refiner.json and matting_vitmatte_sequence.json. Start from the second one.

Where people get burned

Frame numbers that don't intersect. Plate and trimap must share frame numbers; that's the pairing rule. Press Run and the node validates both paths first, reporting a missing folder, a folder with no numbered images, or "no frame numbers in common" right on the node, before it loads a thing. Worth reading, because the alternative is a very slow way to find out.

Half-matching sequences get quietly shortened. Frames that exist in only one folder are skipped with a console warning. Both sequences stay consistent with each other, but your matte may be shorter than the plate you thought you were rendering. Look at the frame count it logs at the start.

Resuming into the wrong prefix. skip_existing checks for <prefix>.<frame>.<ext> in the output folder. Change the prefix between runs and everything looks new - you'll re-render the whole shot, or worse, end up with two naming schemes in one folder.

The trimap written in sRGB. Still the single most common way to get a bad matte out of ViTMatte: 0.5 becomes ~0.73, and the model gets a trimap that means something else. Write raw/linear and disable dithering. quantize_trimap (on by default) rescues a slightly-off trimap by snapping it back to 0/0.5/1, but don't rely on it as a colour-management strategy.

Licence, again. These are the hustvl weights trained on Composition-1k, which traces back to the Adobe Deep Image Matting dataset and its non-commercial restriction. The node prints a reminder every time it loads them. For paid work, either clear it or point custom_model at weights you trained or licensed.

Nothing renders and you think it's hung. It always re-runs by design, and prints both paths plus the frame range before starting. If that log line never appears, check the console for a failed import in the matting group.