Atlas Depth Layer Mask 🎭

This is the node the layered matte-painting workflow is built around. In the classic 2.5D stack, you split a shot into depth bands and give each one its own clean plate - a piece of the background that's been painted/inpainted so the camera can move behind the foreground. AtlasDepthLayerMask produces the masks that make that possible: for one depth band, it hands you the band's own pixels, the nearer stuff that occludes it, and optionally the holes.

If that sounds like a lot of outputs, it is - three masks plus a report. But each has one clear consumer, and understanding that mapping is 90% of using the node well.

The three masks

• layer_mask - the band's own pixels. "Everything in this depth slice is this layer."
• occlusion_mask - everything nearer than the band that hides it. This is the one that feeds the inpaint pipeline: occlusion_mask → INPAINT_ExpandMask → INPAINT_InpaintWithModel builds that band's clean plate. It's the whole reason this node exists.
• hole_mask - optional, and off by default. It comes from building the band's actual relief mesh and reading its real tear/sky holes - which is why the tooltip warns it's not free: compute_hole_mask=True is a real (duplicate) mesh build, unlike the other two masks. When you do turn it on, its relief_grid and depth_edge_rel must match the downstream AtlasCleanPlateLayer call, or the hole data won't reflect the final mesh.

Inputs that matter

Required: solve (the ATLAS_SOLVE) and depth (the shared ATLAS_DEPTH_MAP). Then the band definition:

• near_m / far_m - the band's edges in metres. 0 means auto.
• near_pct / far_pct - used when the metres are 0. Same log-depth convention as AtlasDepthBandSplit: these are positions along the scene's log-depth range, not pixel percentiles. The tooltip is blunt about why - pixel percentiles waste 0–0.9 on the foreground. For a typical foreground object, try 0.2–0.4.
• feather_px (default 4) - a safety margin dilating the occlusion mask's edge.
• band_side + band_split - wire one AtlasDepthBandSplit into every band node with band_side set (foreground/background) so the fg/bg boundary lives in exactly one widget and the layers can't drift apart. This is the recommended setup.
• exclude_mask - an external exclusion (a real sky segmentation from SAM/RMBG) that replaces the internal sky heuristic, so it must cover everything you want gone.
• band_override - a string like near_pct=0.2 far_pct=0.5 that wins over the widgets, used to flow VLM-derived band boundaries in from AtlasAssessImage. Errors loudly on garbage.

Output: also a report that documents what the band resolved to.

How to use it

Instantiate once per background band. The occluded regions (what the foreground hides) get inpainted into that band's clean plate; the far band keeps its own layer. Priorities run farthest-first in this pack - the sky dome sits behind everything. This is the same logic the all-in-one AtlasInput node bakes in when you set layers 2–4, but here you control each band's edges yourself.

Install

Same pack, same one-liner:

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

Restart (or Manager → "atlas-camera"). Needs the [neural] tier for the depth upstream (torch + GeoCalib + transformers, per INSTALL.md). Watch the kornia<0.8.3 cap so the extras don't break LTXVideo. Brand-new pack with no community folklore yet - the tooltips here are unusually long for a reason: read the ones on near_pct and compute_hole_mask before you tune.