Skip to content

Calibration implementation and procedure

Jump to bottom
Sibo Wang-Chen edited this page Apr 13, 2025 · 9 revisions

Important

Prerequisites:

Step 1: Generate and print ArUco board

Use the generate-calibration-board command line tool following the help message below, which you can also obtain by running generate-calibration-board --help:

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') │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

A SVG file is then created at the location specified by --output-path. Using a program such as Adobe Illustrator or Inkscape, create an A4-sized document. Insert the content of the output SVG file into the canvas and create a rectangle in agreement with the size specified by --arena-size-x-mm and --arena-size-y-mm. Center the content of the SVG file with respect to the rectangle. (Note: this process can be automated but I'm marking it as very low priority and not planned).

Then, print this A4-sized document at 100% scale. Cut out the rectangle, and this is the calibration board. Take a moment to figure out the correct orientation of the board. Put the board on top of the arena (printed size down). Then, using a pencil, lightly mark the top right corner of the board for future convenience.

Step 2: Execute calibration scan

Place the calibration board on top of the arena (printed side down). Pay attention to the orientation of the board — the top right corner should be marked. Take a laser-cut acrylic piece on top of the calibration board to lay it flat.

Open the SpotlightController program. This is one of the binary files compiled from the C++ code. The flags that you can pass to the program are unimportant for now; simply run it with no flag. Observe the view of the ArUco codes from both cameras. Focus both lenses so that the markers appear sharp. Once satisfied, close the SpotlightController GUI window.

Then, run the RunCalibration program. This is another one of the binary files compiled from the C++ code. You can specify the profile directory and logging verbosity according to the following help message, which you can also obtain by running RunCalibration --help.

Usage: RunCalibration [OPTIONS]
Options:
  -h, --help                 Display this help message
  -p, --profile-dir PATH     Path to profile directory (default: ~/Spotlight/default/)
  -v, --verbose              Enable verbose output (debug level)
  --verbosity LEVEL          Set verbosity level (trace, debug, info, warn, error, critical, off)

This program (which does not come with a GUI) will then scan the whole arena in strides specified in recorder_config.yaml. Depending on the arena size the scan will complete in ~5 minutes. The images taken during this procedure can be found at <profile_directory>/calibration/aruco_scan/.

In this procedure, one should pay particular attention to the following entries in recorder_config.yaml:

  • motion_control/calibration_scan_stride_mm
  • motion_control/calibration_scan_exposure_time_us TODO: Update this

Step 3: Fit calibration model

Use the generate-calibration-board command line tool following the help message below, which you can also obtain by running generate-calibration-board --help:

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)                    │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────╯

The pixel locations of the detected ArUco markers will be saved under <profile_directory>/calibration/calibration_points.csv and the final parameters of the calibration mappings (as explained in Calibration algorithm) will be saved under <profile_directory>/calibration/calibration_result.yaml.

Clone this wiki locally