Atlas Fit Depth Calibration 📐

AtlasFitDepthCalibration is the pack's quietest flex: it calibrates a monocular depth model's systematic error against measured depth, then stores a correction you can reuse. The insight is simple and genuinely useful. A model like Depth Anything gets a scene's structure mostly right, but its metric values drift - distances come out a few percent long or short, and the drift is consistent for a given kind of scene. If you have one shot where you know the truth, you can measure that drift and fix it for every ordinary photograph of the same scene type where you don't.

The intended truth source is AtlasLoadRecord3D - a phone capture (ARKit/LiDAR) that carries per-pixel metric depth in metres. The point is explicitly not to improve the LiDAR capture; it already has measured depth and needs no correcting. The point is transfer: learn how the model misreads "outdoor street" or "indoor room" on the one frame where you have ground truth, then apply that learned correction on plates where you don't.

How it works

You wire two depth maps in: measured (the truth side, flagged metric) and predicted (the same frame through the model you want to calibrate, at the same resolution). The node fits a correction - how well a simple model (the fit picks among candidates) explains the residual error - reports before/after error, and, only if you flip save on, writes it into a calibration store keyed by (model_id, scene_type).

That store key matters: corrections are looked up by an exact match and never fall back. A correction fitted on an outdoor scene is only valid for outdoor scenes, so if you shoot interiors and exteriors you calibrate both. The note field is free text for "which capture, which lens, which day" - the docs are blunt that you will want it.

The inputs

Both measured and predicted are required. Then:

• scene_type (default outdoor) - half the store key; the kind of scene the correction applies to.
• model (default auto) - auto fits all candidate models and picks on held-out error, simplest-first among ties. Pick one explicitly only if you know your sensor.
• mask - restrict the fit to certain pixels. The docs suggest wiring the capture's confidence mask to drop low-confidence LiDAR returns; strongly worth doing.
• store_path - where the calibration store lives (default atlas_depth_calibration.json, relative to ComfyUI's working directory).
• save (default off) - the safety rail. Fit and read the report first; only turn this on when it looks right. It overwrites any existing entry for the same (model, scene_type) key.
• note - free text stored beside the coefficients.

Outputs are correction_json and a detailed report.

Install and gotchas

Ships with the pack - ComfyUI Manager → search atlas-camera, or git clone https://github.com/mikejamesvfx/atlas-camera.git into custom_nodes, restart. The calibration math itself is lightweight, but the predicted side needs your depth backend installed (the default Depth Anything V2 is transformers-only and needs no extra install; GeoCalib sits behind the neural solve).

The gotchas are worth reading carefully because the node refuses, loudly, rather than silently fitting garbage:

• The measured side must be flagged metric. A correction fitted onto a relative depth map learns that map's arbitrary scale, not the world's - the node warns you explicitly.
• Resolutions must match. Measured and predicted at different sizes, or a mask that doesn't match the depth, and the node refuses the fit.
• A correction that doesn't reduce error is rejected in spirit - the report flags "no improvement" so you don't store a slower-but-no-better depth chain.

This is the kind of node that rewards a disciplined workflow: one calibrated capture per scene type you actually shoot, notes on the lens and day, and suddenly the depth maps feeding your relief mesh are in real metres instead of "probably about right."