Atlas Occlusion Mask 🕳

The atlas-camera patch pipeline works like this: a novel view (a patch, a LoRA-generated repair) shows you geometry that the primary photo either can't see or only sees at a grazing angle. Before you composite that patch in, you need a mask of exactly where the primary is missing that information. Atlas Occlusion Mask is that mask. White means "the primary camera has no valid coverage here, a patch should fill it"; black means "the primary already has it, head-on." It's the 🕳 in Atlas/04 · Masks.

It's the phase-gate of the patch path: no mask, no idea whether you're genuinely adding information or smearing a patch over pixels the primary already owns.

How it works

The node places the target/patch camera identically to how AtlasAddPatchView will place it later - same named-view widgets, same orbit construction - so the mask lines up with whatever patch geometry that node derives from the same image. Then it projects the primary's coverage onto the scene and marks the failures:

• simple mode (default) - Phase-1 tests only: frustum, behind-camera, and out-of-frame failures, plus a facing-angle gate (angle_threshold, default 90° = only true "can't see it" failures; lower it and surfaces too grazing to the primary also get masked).
• depth_shadow mode - adds the real matte-painting trick: a camera-as-light shadow test. Surfaces hidden behind nearer geometry from the primary's view get masked, using primary_depth as the shadow map. This is the true "MPTK-style" test, and it needs primary_depth wired - the shared AtlasDepthMap run on the primary photo. Without it, the mode falls back to simple and the report says so.

The patch_* and source_* dropdowns exist to keep the mask aligned with the LoRA that generated the target image - they describe which azimuth/elevation/distance the target was generated at and which view the source photo already is. The contract is blunt: they must match the values you'll use in AtlasAddPatchView, or the mask and the patch drift. If you'd rather not hand-sync, patch_view_override / exact_view_override accept the snapped or raw orbit strings from AtlasBlockoutViewport.

Inputs and outputs

Required: solve and target_image. Optional: the view dropdowns above, flip_azimuth, depth_model (default DA-V2-Metric-Outdoor), device, angle_threshold, dilate_px (expand the white region), soft_edge_px (feather it), power (gamma remap after blur), occlusion_mode, primary_depth, depth_bias (relative depth tolerance before a point counts as shadowed), and the two view overrides.

Outputs: occlusion_mask (white = missing) and coverage_mask (the inverse view - white = valid primary coverage).

Installing it

Core node; depth_model/primary_depth are inputs, not a dependency of this node:

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

Restart, find it in Atlas/04 · Masks (ComfyUI Manager: "atlas-camera").

Common issues

The alignment contract is where people burn time. The patch azimuth/elevation/distance and source view must agree between this mask and the AtlasAddPatchView wiring - if you generate the target at "front-right quarter view" but tell the mask "front view," the mask shows the wrong holes. If that's fiddly, use patch_view_override / exact_view_override from AtlasBlockoutViewport so one string drives both, and the "never-drift" contract holds. For final compositing, set dilate_px and soft_edge_px sensibly - a hair of dilation plus a feather is usually enough; the power knob >1 makes the patch contribution more solid near the feathered edge.