Distance estimation¶

The two phases¶

1. Calibration — per deployment. A handful of its Resources get reference points marked at known distances (a Calibration sample each); running the calibration action fits a calibration model from those samples and stores it as that deployment's Deployment calibration result. There's no separate "calibration deployment" concept — calibration is attached directly to the deployment that needs it, because camera placement (height/tilt/angle), not just the camera/lens model, affects the depth-to-distance mapping.
2. Estimation — running the estimation action on a deployment integrates the depth-model output across each tracked object, using that same deployment's active calibration result, and writes the median distance into ClassificationDynamicAttrs.distance.

Before you begin¶

• A deployment exists for the camera/lens combination you want to calibrate
• A depth-model AI Provider (trapperai-predictors-torch-depth or trapperai-predictors-hailo-depth) is configured and active
• You can physically visit the deployment site to place reference markers (or already have footage with known-distance markers)

Steps¶

1. Capture calibration footage in the field¶

Set up the camera the way you'll deploy it (same height, tilt, lens). Place a target with a clear visual marker (a tripod with flagging tape works) at known distances — e.g. 2 m, 5 m, 10 m, 15 m, 20 m. Capture 5–10 photos / a short video at each distance, and record each (distance, target visual ID) pair in your field notebook.

A handful of distinct distances (5–8) is plenty — the calibration is a function-fit, not a brute-force lookup.

2. Set up the deployment and upload the footage¶

1. Geomap → Deployments, click the + icon.
2. Fill in the camera + location as usual. There's no calibration-specific flag to set — any deployment can be calibrated.
3. Save, then upload the calibration footage via any path (Citizen Science frontend, trapper-tools, FTPS) — the resources land in this deployment like any other.

3. Collect reference points¶

For each reference resource, Geomap → Calibration samples, click the + icon, and pick the Resource and Deployment. The Calibration data field is where you mark the visual target and enter the known distance in metres (canonical shape: a list of {bbox, distance, frame_index} reference points — frame_index lets one record hold points drawn on different frames of the same video). Repeat for every distance you captured.

4. Fit the calibration model¶

Select the deployment(s) in Geomap → Deployments, and run the Run depth calibration for selected deployments action. Its form (page title: "Re-run depth calibration") asks for:

The result is stored as a Deployment calibration result (visible inline on the deployment, and as its own Geomap → Deployment calibration results list) — Depth provider, Is active, Calibration job id. Re-fit any time you edit reference points by repeating this action.

5. Run distance estimation¶

Select the same deployment(s) and run Run distance estimation for selected deployments (override existing results). Its form ("Re-run distance estimation") requires a Classification project with a depth AI model, and lets you override that project's defaults per run:

The action's own description is explicit that it requires an active calibration result on the deployment — run step 4 first. Leaving an override field empty falls back to the Classification Project's prediction_config defaults for the "Distance Estimation" job type.

For new resources, this same estimation runs automatically as part of the AI pipeline once the depth AI model is set on the Classification Project — this manual action is for re-running on existing data or for tuning the override parameters without changing the project defaults.

Verify it worked¶

Open a resource and check the per-object distance values in the classification panel — the metric is "median distance across the smoothed track", shown as a numeric column on each ClassificationDynamicAttrs row.

A useful sanity check: run estimation against the calibration footage itself and verify the predicted distance matches the ground truth at each marker.

Troubleshooting¶

For cross-system context: depth-model schemas live in trapper-schemas/src/trapper_schemas/depth/, predictor implementations in trapper-ai-worker/packages/predictors-torch-depth/.

Next steps¶

• Configure trackers — tracking quality directly affects how well distance estimation can integrate across frames