Running the arena registration scan

Running the arena registration scan

The run-arena-registration-scan program performs the automated scan needed to fit the (stage, pixel) ↔ physical coordinate mapping. It is implemented in recorder/src/runArenaRegistrationScan/runArenaRegistrationScan_main.cpp.

Prerequisites

1. The arena directory must already contain metadata.yaml, mapping_board.pdf, and active_area.png. For the built-in arena146 these are pre-generated; re-generate them by running scripts/arena/make_arena146_config.py from spotlight-tools/.
2. Print mapping_board.pdf at 100% scale and place it in the arena.
3. Compile the C++ code (see Compiling CPP code). The run-arena-registration-scan binary requires libdmtx-dev (sudo apt install libdmtx-dev).

Procedure

Step 1 – Live preview / DataMatrix alignment

Run the program:

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

A window opens with a live behavior-camera preview and crosshairs. Manually move the stages so that the DataMatrix barcode printed at the centre of the mapping board is centred under the crosshairs, then press ENTER.

The program decodes the DataMatrix and verifies its checksum against metadata.yaml. A mismatch (e.g. wrong board in the arena) aborts with an error.

Step 2 – Automated AprilTag scan

The program automatically visits every AprilTag position listed in metadata.yaml in sequence. At each position it:

1. Moves the stage to the arena coordinates of the tag's centre (using the offset derived from the DataMatrix step).
2. Waits for the stages to settle (number of settling frames is configurable in recorder_config.yaml under motion_control/apriltag_mapping_settling_frames).
3. Acquires 10 consecutive frames.
4. Saves apriltag<id>_img<i>.jpg and appends a row to apriltag_stage_positions.csv under <arena_dir>/mapping_scan/.

Progress is shown in the preview window. The scan completes in a few minutes for arena146 (8 AprilTags × 10 frames).

Step 3 – Fit the registration model

Once the scan is complete, run fit-arena-registration from spotlight-tools/:

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

See Fitting the calibration model for details.

Command-line help

$ ./run-arena-registration-scan --help
Usage: ./run-arena-registration-scan -p PROFILE_DIR -a ARENA_DIR [OPTIONS]
  -p, --profile-dir PATH  Profile directory
  -a, --arena PATH        Arena directory (containing metadata.yaml)
  -v, --verbose           Debug-level logging
  --verbosity LEVEL       trace/debug/info/warn/error/critical/off