Atlas Card Mask 🃏

If you've ever cleaned up a street photo and wished the car in the shot were just a layer you could grab, this is that node. AtlasCardMask reaches into a solved Atlas scene, finds one "card" - an object the evidence pipeline segmented out of the photograph - and hands you its exact pixels as a MASK, plus the measured depth band it lives in. It's the bridge between the evidence-first AtlasRealPlateToScene node and the per-object layer nodes (AtlasCleanPlateLayer), so it only makes sense once you're running the card-split part of the pipeline: cars and buildings as masked relief, signs as cards.

How it works

Atlas doesn't do the usual "depth map goes in, mesh pops out" thing. Its evidence layer tracks objects as cards: each one carries a full-frame alpha (mask_b64) and a measured camera distance in metres, recovered when the plate was solved. This node is deliberately boring - pure decode plus a little arithmetic, no plate read, no depth read, no image load.

• The card's stored alpha is decoded to a MASK (float32 in [0,1], same frame as the plate).
• Its measured camera_distance_m becomes a depth band: near_m and far_m, spaced by band_margin_m (default 3 m) either side of the card.
• invert emits 1-alpha instead - the "everything except this card" form, useful as an exclude mask.

The card input is a text field, not a dropdown, and that's on purpose: card names are per-episode dynamic, so a static list would be wrong by the time you loaded a workflow. You can type either the source name (CARD_CAR) or the concept (car). Type something that isn't there and the node errors loudly, listing every card on the solve with its concept - annoying, but way better than silently grabbing nothing.

The inputs and outputs that matter

You set exactly two things: card (name or concept) and, occasionally, band_margin_m if the default 3 m band swallows a neighbouring object. invert is the only other knob.

The four outputs tell the story: mask (MASK) goes into AtlasCleanPlateLayer's object_mask or layer_matte, near_m and far_m become that layer's depth band so the card only claims pixels at its own distance, and report (STRING) gives you the numbers - distance, coverage in pixels, mask shape - for checking your work. Wire mask → object_mask, near_m/far_m → near/far, and the layer inherits the card's measured position.

Installing

This is one of the mikejamesvfx/atlas-camera pack's nodes, so the install is the pack install: search "atlas-camera" in ComfyUI Manager, or:

cd <ComfyUI>/custom_nodes
git clone https://github.com/mikejamesvfx/atlas-camera.git

Then restart ComfyUI. The core nodes need zero extra pip packages - no GPU required for the mask decode itself. The catch is upstream: AtlasCardMask only has cards to extract if AtlasRealPlateToScene ran, and that node sits in the evidence-plate lane that depends on the private atlas-world package, distributed separately from the public pack. If you hit the error about atlas-world, that's the install hint telling you pip install -e path/to/atlas-world and restart. The node itself is pure decode and works without it once a solve carrying cards exists.

Where people get burned

• "card 'x' is not a roundtripped card source" - you typo'd the name, or the card isn't on this solve. Read the error; it lists what's actually available.
• Cards show up but the band is off - band_margin_m is in real metres. A 3 m half-band around a 1 m-tall object is generous; for tight geometry, drop it to 1.
• Nothing to extract - you're feeding a solve that never went through the card roundtrip. Re-run AtlasRealPlateToScene first.

One honest note: this node is for the deep end of the Atlas pipeline, not the quickstart. If you're a beginner and this is your first Atlas node, start at AtlasInput and let the front door work for you before you start pulling cards apart.