Collect H3 RefMod Masks

If you've been extracting MiniMax H3 references with a subject mask and wondering why backgrounds keep bleeding into your mod, this node fixes one very specific version of that. One input, one output, no pixels of its own. It exists because a mask batch and a mask list are not the same thing, and the extractor wants the list kind.

What it's for, in the wider workflow

Quick context, because RefMod is new vocabulary. ComfyUI-MiniMaxH3Mod (by Luisa, luisacaotica) saves H3 image, video and audio references as reusable .safetensors files - it calls them mods - which you later load and feed to Apply H3 RefMod so they get appended to your native H3 conditioning. It is not LoRA training: extraction runs your reference through the H3 VAE and stores the resulting latent plus metadata. H3 itself is MiniMax's 33B open-weight omni-modal video model - native stereo audio, plus a licence that geofences the US, EU, UK and Korea out of running it locally at all.

Create H3 RefMod already has a mask input, and 90% of the time that's all you need. But that socket takes a MASK batch, and a batch is a stack of same-sized tensors. Portrait headshot plus landscape dance clip, and one gets squeezed into the other's dimensions before the mask reaches extraction. Collect H3 RefMod Masks is the v0.2.6 workaround: masks keep their own height and width all the way to the extractor, which then resizes and crops each one to match its reference.

How it works

Read the source and it's about eight lines. The node sets INPUT_IS_LIST = True, so ComfyUI hands it the whole incoming list in one call instead of mapping the node over each item - that's the "consumes the list once" note in the README, and the actual reason this is a separate node rather than a list-typed socket on the extractor. Then it flattens: a [N,H,W] batch becomes N single masks of [1,H,W], each clamped to float 0–1. Empty input raises Connect at least one mask to Collect H3 RefMod Masks. No resizing, no batching, no opinion.

The output type is H3_MASK_LIST, which only the two creator nodes understand.

Order matters. Masks map to references in extraction order: images, then videos, then anything from a folder bundle. One mask broadcasts to every reference; anything else throws mask has N entries but there are M references. You also can't run both sockets at once - connect mask and mask_list and you get Connect mask or mask_list, not both, the author admitting the mapping is genuinely ambiguous.

At extraction time the mask is bilinear-resized to the reference's encoded size (center-cropped alongside the image in encode mode, where refs share a canvas), then average-pooled to the latent grid. Inside the mask the latent is untouched; outside it, each cell blends toward a heavily blurred copy of itself - not noise, not grey, a blur of itself, so the result stays in-distribution. background_retention sets the floor weight there: 0 fully collapses it, 1 makes the mask do nothing.

Inputs and outputs that matter

• masks (MASK, required) - the only input. Take a single mask, a batch, or a real list from an upstream list node.
• mask_list (H3_MASK_LIST, output) - wire it to mask_list on Create H3 RefMod or Create H3 RefMod Master, and don't also connect those nodes' plain mask socket.

That's the whole node. It is deliberately boring.

Installing it

Same as the rest of the pack. Via ComfyUI Manager, search ComfyUI-MiniMaxH3Mod; or:

cd ComfyUI/custom_nodes
git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod

Restart ComfyUI and the node shows up under MiniMax-H3/mod. requirements.txt pulls safetensors, numpy and Pillow (torch comes from ComfyUI); the optional opencv-python/imageio are only for the folder loader, so this node needs nothing extra. Manager installs deps for you, or run pip install -r requirements.txt. Development is Windows-tested and the pack is flagged under construction, schemas still moving.

Where people get burned

The mask is a suppression weight, not a cutout. Wire a tight subject mask expecting a clean composite and you get a soft, blurred halo where the background was. That's the design - the H3 DiT patchifies in 2×2 cells, so a hard edge wouldn't survive anyway.

Two more, both from the source:

• Pixels cropped by an upstream batch node cannot be recovered. If something earlier already forced your refs to a common size, the collector gets uniform masks and there's nothing to preserve. Build the mask list before the batching.
• With no mask connected, extraction prints ignored: background_retention (no mask). The widget stays visible and editable, so it's easy to sit there turning a knob that does nothing. This pack is chatty about what it's ignoring, and that's a feature.

Last thing: the mask is an extraction-time filter. None of it is stored in the mod, so it won't hand you a reusable mask for later inpainting - it just decides which pixels of the reference influence the latent.