Segs To Masks (NH)

NH_SEGS is a nice data structure right up to the moment you want to do something with it. ComfyUI's own nodes - InpaintModelConditioning, Mask Composite, Image Composite Masked, Join Image with Alpha, the whole ecosystem - know nothing about it. They take MASK.

Segs To Masks is the simplest of the exit ramps, and often the right one. Give it instances, get plain masks back, plus a text list of what they are.

What comes out

Four outputs, and the gap between the first two is the whole point:

masks is one mask per instance, stacked image after image in batch order. Three people on photo one and two on photo two gives you five masks. Feed that into a batch of inpaints and every person gets their own pass with their own mask, which is the only sane way to do per-subject work.

union is one mask per image: everything found in that frame, merged. This is what you want when you're masking "the subject" and don't care that it was three instances.

labels is a STRING with one label per line, in the same order as masks. That's the diagnostic output, and it's the one people sleep on. Wire it into a text node or a Show Text and you can see exactly what strings the segmenter emitted - which is how you find out that Body Segment called it top when you asked for dress, or that SAM 3 returned red car and not car.

count is how many instances there are. Note the deliberate mismatch: when there are none, count is 0 but masks still holds one empty mask, so the node after it doesn't blow up on an empty tensor. Small thing, saves a lot of "why did my graph fail on the one photo with no people in it".

How it works

Instances keep their mask cropped to their own box - that's the trick that lets dozens of instances on an 8K photo stay light in memory. This node is where that gets paid for: it builds a full-size mask per instance at the size of the picture.

Which is why the node has a memory guard. Every full-size mask is 4 bytes per pixel, about 145 MB on a 7360×4912 photo. When the set of masks would need more than roughly half your free RAM - hundreds of instances on a huge photo - it stops with an error rather than swapping your machine to death. The advice in that error is correct: use Segs Select to keep only what you need, or Segs Compose to get one mask. Ninety-nine times out of a hundred, "I want per-instance masks for 300 detections on an 8K image" is a workflow problem, not a node problem.

Where it fits

The classic chain is SAM 3, then a filter, then this:

Load Image → SAM3 Segment (person) → Segs Select (sort_by: left_to_right) → Segs To Masks
                                                                          ├─ masks → per-person inpaint
                                                                          └─ labels → Show Text

Because Segs Select keeps its instances sorted, masks comes out in that order - left to right - and labels reads back person, person, person. Predictable ordering out of a segmentation model is worth a lot when you're batching.

If you only need one mask, take the mask output of SAM3 Segment or Segs Select directly and skip this node. If you need a new combination, that's Segs Compose. If you need Impact Pack's SEGS, that's Segs To Impact SEGS. This node is for the case where the individual instances matter.

Installing it

ComfyUI Manager, search NH-Nodes, install, restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/jetthuangai/NH-Nodes.git
cd NH-Nodes
python -m pip install -r requirements.txt

Nothing extra downloads; it works on instances the segmentation nodes already made. The pack wants a recent ComfyUI (tested on 0.41) and Python 3.10+. The gigabytes belong to SAM 3 and Body Segment, not here.

Common issues

"The masks would need more memory than is free." Not a bug. Filter upstream - Segs Select, or Segs Compose for a single mask.

Downstream nodes see the wrong number of masks. Check count. If it's higher than you expected, your concepts or your threshold found more than you thought; run Segs Preview and look.

Labels don't match what you typed. Body Segment and the other people nodes return one instance per part for the whole photo, so three people give you one hair, not three. And SAM 3 labels are the English words it searched for - áo đỏ comes back as red top.

The masks don't line up with a resized image. Every mask is the size of the picture the segs came from. Restore the geometry first with NH Restore Image Geometry, or resize the masks with the same numbers - don't resize the image alone.