Atlas Instance Mask (SAM3) 🎭

AtlasInstanceMask is the "which one did you mean?" node. SAM3 can segment a scene into separate instances and hand them back as a stack of masks - one per detected object - but that stack is not directly useful for much until you pick a single instance out of it. This node does exactly that: it takes a multi-instance mask stack and returns the one you asked for, optionally scoped by a restriction mask and gated by a minimum coverage threshold. Think of it as the index operator for SAM's output, with a couple of guardrails bolted on.

In the atlas-camera world, instance-level masks are what let you treat individual things in a photo - a car, a building, a person - as separate elements of the projection rather than one undifferentiated depth layer. And the guardrails matter more than they sound: a segmenter's instance count varies from frame to frame, and asking for instance 5 of a scene that only produced 3 should give you a clean empty mask and a note, not a crash or a wrong object.

How it works

You feed it the multi-instance mask (the "separate" output from a SAM3-based node like AtlasSAM3Mask), and instance_index selects one layer. The node pulls that slice, clamps it to a clean 0–1 mask, and then applies two filters:

• restrict_mask - optional; multiplies the instance mask by a region mask, so you only keep the part of the instance that falls inside your region of interest.
• min_coverage (default 0.001) - if the surviving mask covers less than this fraction of the frame, it's rejected as a dud and returned empty. Segmentation is noisy; a stray speck that's 0.0001% of the frame shouldn't get composited onto your plate.

The report output tells you which instance you got and what its coverage was, including when it was rejected for being too small.

The inputs

mask and instance_index (0–127) are required. restrict_mask and min_coverage are optional. Outputs are the single-instance mask and a report.

Install and gotchas

Part of the pack: install once via ComfyUI Manager (search atlas-camera) or git clone https://github.com/mikejamesvfx/atlas-camera.git into custom_nodes, restart. The node itself is pure tensor selection - but it's only useful with a SAM3 separation upstream, and native SAM3 needs the [sam3] extra (transformers>=5.5.4). Without it, the pack falls back to third-party segmenters that may not load on Apple Silicon or AMD at all - worth knowing if you're on one of those.

The practical gotchas: instance order is not guaranteed to be stable across runs or images, so "instance 3 is the building" is a habit that will eventually betray you - always check the report's coverage line, or pair it with a restrict_mask so the wrong pick lands outside your region and gets rejected. And remember min_coverage is a floor, not a target: a legitimately small foreground object in a big frame can fall under a careless threshold and silently vanish.

It's a small selector with unusually thoughtful failure behaviour - exactly the kind of glue node that saves you from re-running a GPU-heavy segmenter every time you want a different object.