Calibration implementation and procedure

Important

Prerequisites:

• Read Profiles and arenas.
• Read Calibration algorithm.
• Compile the C++ programs following Compiling CPP code (sudo apt install libdmtx-dev required for run-arena-registration-scan).
• Upload the Arduino program following Uploading Arduino code.
• Install the Python tools following Installing Python code.

Step 1: Prepare the arena directory

The arena directory (e.g. ~/Spotlight/arenas/arena146/) must contain metadata.yaml, mapping_board.pdf, and active_area.png. For arena146 these are pre-generated. Copy them from the package assets:

cp -r <spotlight-tools>/src/spotlight_tools/assets/arena_configs/arena146/* \
      ~/Spotlight/arenas/arena146/

If the arena spec PDF changes, regenerate them:

cd spotlight-tools/
python scripts/arena/make_arena146_config.py

See Profiles and arenas for details.

Step 2: Print and place the mapping board

Print ~/Spotlight/arenas/arena146/mapping_board.pdf at 100% scale. Cut along the outer border and place the board in the arena with the printed side facing the camera.

Step 3: Run the arena registration scan

./run-arena-registration-scan \
    -p ~/Spotlight/profiles/sibo_260514 \
    -a ~/Spotlight/arenas/arena146

1. A live camera preview opens. Move the stages so the DataMatrix barcode (printed at the center of the board) is centred under the red crosshairs, then press ENTER.
2. The program decodes the DataMatrix and verifies the checksum. If it fails, check that the correct board is in the arena.
3. The stage automatically visits each AprilTag, acquires 10 frames per tag, and saves everything to ~/Spotlight/arenas/arena146/mapping_scan/.
4. The scan takes a few minutes to complete. Status is shown in the preview window.

See Running the calibration scan for full details.

Step 4: Fit the registration model

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

This writes model/calibration_result.yaml, model/calibration_points.csv, and model/diagnostics.png to the arena directory.

Check diagnostics.png to verify the fit quality (RMSE should be ≲ 0.1 mm; see Calibration algorithm for targets).

See Fitting the calibration model for full details.

Step 5: Verify by running the recording application

./run-spotlight \
    -p ~/Spotlight/profiles/sibo_260514 \
    -a ~/Spotlight/arenas/arena146

The application reads model/calibration_result.yaml and metadata.yaml from the arena directory automatically. If either file is missing or malformed, it exits with an error message.