Profiles and arenas

To segregate settings between experiments or experimenters, Spotlight uses two separate directory types: profiles and arenas. Both are passed to every C++ program via command-line flags.

Profile directory

A profile holds machine-specific settings that are independent of which arena is mounted — the camera configuration, stage serial numbers, motion limits, and muscle-camera ROI.

Profiles live under ~/Spotlight/profiles/. A typical profile directory looks like:

~/Spotlight/profiles/sibo_260514/
│
│ # ===== Recorder configurations (to be created manually) =====
├── recorder_config.yaml     # camera/stage/tracking/GUI settings
│
│ # ===== File generated by align-cameras =====
└── muscle_camera_roi.yaml   # params defining how muscle camera images should be
                             # cropped to align with behavior images

The profile directory is passed to all C++ programs with -p / --profile-dir. See Software dependencies and configurations for details on recorder_config.yaml, and Aligning the two cameras for how muscle_camera_roi.yaml is generated.

Arena directory

An arena directory holds the physical description of a specific arena and its fitted registration model. The same arena directory is re-used across many recordings as long as the physical arena has not changed.

Arenas live under ~/Spotlight/arenas/. The directory is populated in stages by different tools:

~/Spotlight/arenas/arena146/      # base directory for arena specs
│
│ # ===== Arena definition (PDF to be generated manually) =====
├── arena146_spec.pdf             # source-of-truth arena drawing (generated by CAD)
│
│ # ===== Data generated by scripts/arena/make_arena146_config.py =====
├── metadata.yaml                 # marker positions, arena dim, checksum, etc.
├── mapping_board.pdf             # printable board with AprilTag markers + DataMatrix
├── active_area.png               # rasterised active area mask (0=wall, 255=accessible)
│
│ # ===== Data collected by run-arena-registration-scan =====
├── mapping_scan/
│   ├── apriltag0_img0.jpg        # AprilTag images recorded by the behavior camera
│   ├── apriltag0_img1.jpg
│   ├── ...
│   └── apriltag_stage_positions.csv  # motion stage positions when images were taken
│
│ # ===== Data generated by fit-arena-registration =====
└── model/
    ├── calibration_points.csv    # pixel coordinates of detected AprilTag corners
    ├── calibration_result.yaml   # fitted linear transform between coordinate systems
    ├── detections/
    │   ├── apriltag0_img0.jpg    # debug images showing AprilTag detections
    │   ├── apriltag0_img1.jpg
    │   └── ...
    └── diagnostics.png           # diagnostic plot showing linear mapping model fitting

The arena directory is passed with -a / --arena-dir:

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

Note

The arena directory must contain a valid model/calibration_result.yaml before run-spotlight will start. Complete the registration scan and model fit first (see Calibration implementation and procedure).

Setting up a new arena directory

Step 1 — Create the arena spec PDF

Design the arena in CAD and/or Illustrator/InkScape/etc. and export a PDF that encodes marker geometry using colored shapes:

• Red (#ff0000) squares → AprilTag positions (sorted by shortest-path traversal from the DataMatrix)
• Green (#00ff00) square → DataMatrix position
• Black (#000000) shapes → active-area / maze walls

The red and green boxes should be squares.

For arena146, pre-generated assets are already bundled with spotlight-tools. Skip to Step 2b.

Step 2 — Generate the arena config assets

The arena directory needs three derived files before the registration scan can run:

• metadata.yaml — AprilTag and DataMatrix positions, arena dimensions, checksum
• mapping_board.pdf — printable board with embedded AprilTag markers and DataMatrix barcode
• active_area.png — rasterised active-area mask

Option A — Copy pre-generated assets (arena146 only):

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

Option B — Regenerate from the spec PDF:

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

This runs ArenaConfig (in spotlight_tools.arena.arena), which reads the spec PDF using pymupdf and writes all three assets in place.

Note

The DataMatrix barcode encoded in mapping_board.pdf carries an 8-character hex checksum derived from all marker positions and the active-area bitmap. run-arena-registration-scan decodes this barcode at startup to verify the correct board is mounted before the scan begins.

Step 3 — Print the mapping board

Print mapping_board.pdf at 100% scale (no fit-to-page scaling). Cut to the arena boundary (a thin cut-border is drawn 1 mm inside the page edge). Place the board in the arena with the printed side facing the camera.

Step 4 — Run the registration scan and fit the model

With the printed board in place, proceed to Calibration implementation and procedure.