Fitting the arena registration model

Fitting the arena registration model

Once a registration scan is complete (see Running the calibration scan), use fit-arena-registration to fit the calibration model. This tool is implemented in spotlight-tools/scripts/fit_arena_registration.py and calls spotlight_tools.arena.registration.fit_arena_registration.

Inputs (expected under <arena_dir>)

File	Description
metadata.yaml	AprilTag corner positions in arena (mm) coordinates.
mapping_scan/apriltag<id>_img<i>.jpg	10 images per AprilTag from the scan.
mapping_scan/apriltag_stage_positions.csv	Stage position per image.

Fitting procedure

1. Detect AprilTags in each scan image using the pupil_apriltags detector (tag family tag16h5). Detections with a low decision margin are discarded (false positives are common with tag16h5).
2. Reject within-burst outliers using MAD (median absolute deviation) filtering per (tag, corner) group. The stage is stationary during each 10-frame burst so corner scatter should be sub-pixel; anything significantly larger is a detection artifact.
3. Fit a linear model physical = A * [stage_x, stage_y, pixel_x, pixel_y, 1] using RANSAC, independently for the x and y axes. Re-estimate on the combined inliers with plain least squares.
4. Analytically invert the pixel↔physical block to produce the inverse mapping.

A good fit has RMSE ≲ 0.1 mm and R² ≈ 1.

Outputs (written to <arena_dir>/model/)

File	Description
calibration_result.yaml	Forward and inverse mapping coefficients.
calibration_points.csv	Per-corner point set used for the fit.
diagnostics.png	Predicted vs actual scatter, residual histograms, spatial residual map.
detections/ (optional)	Per-image detection overlays (--visualize-detections).

Usage

fit-arena-registration -a ~/Spotlight/arenas/arena146

Full help:

$ fit-arena-registration --help

Key options:

Option	Default	Description
-a, --arena-dir	(required)	Arena directory path.
--min-decision-margin	20.0	Drop AprilTag detections below this margin.
--mad-threshold	3.0	Per-burst outlier rejection threshold (sigma-equivalent).
--ransac-residual-threshold	0.5	RANSAC inlier threshold (mm).
--visualize-detections	False	Save per-image detection overlays.

After fitting, run-spotlight will automatically load model/calibration_result.yaml from the arena directory.