Calibration implementation and procedure

Important

Prerequisites:

• Read The use of "profiles".
• Install the Python tools following Installing Python code first.
• Read Calibration algorithm.

"Profiles"

To segregate settings from different experiments or experimenters, we make use of "profiles." Each profile consists of its independent recording configurations and calibration data (fitted mappings). All profile data is stored under ~/Spotlight, and each profile is saved as a subdirectory under it.

Step 1: Generate and print ArUco board

Use the generate-calibration-board command line tool following the help message below.

username@hostname:~/project/spotlight-control$ generate-calibration-board --help
usage: generate-calibration-board [-h] [OPTIONS]

Generate an ArUco board with the specified parameters.

╭─ options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit                                                               │
│ --arena-size-x-mm FLOAT                                                                                               │
│                         The width of the arena in mm. (default: 48)                                                   │
│ --arena-size-y-mm FLOAT                                                                                               │
│                         The height of the arena in mm. (default: 72)                                                  │
│ --aruco-scale-mm FLOAT  Side length of each square (i.e. "pixel") inside each aruco                                   │
│                         code (mm). (default: 0.3)                                                                     │
│ --aruco-spacing-unitblk INT                                                                                           │
│                         Space between each two aruco codes (in squres, i.e. "pixels"). (default: 2)                   │
│ --output-path STR       The path to save the generated SVG file. (default: '~/Spotlight/aruco_board/aruco_board.svg') │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

TODO

Step 2: Execute calibration scan

TODO

Step 3: Fit calibration model

Use the generate-calibration-board command line tool following the help message below.

username@hostname:~/project/spotlight-control$ fit-calibration-model --help
usage: fit-calibration-model [-h] [OPTIONS]

Fit the calibration model for the ArUco board.

╭─ options ──────────────────────────────────────────────────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit                                                │
│ --profile-dir STR       Path to the profile directory. (default: '~/Spotlight/default/')               │
│ --arena-width FLOAT     Width of the arena in mm. (default: 48)                                        │
│ --arena-height FLOAT    Height of the arena in mm. (default: 72)                                       │
│ --aruco-scale-mm FLOAT  Size of each "pixel" (i.e. "block") of the ArUco markers in mm. (default: 0.3) │
│ --aruco-spacing-unitblk INT                                                                            │
│                         Spacing between each ArUco marker in "pixel" (i.e. "block"). (default: 2)      │
│ --visualize-aruco-detections, --no-visualize-aruco-detections                                          │
│                         Whether to visualize the ArUco detections. (default: False)                    │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────╯

TODO