The calibration command is a thin usability wrapper around Kalibr to help with calibrating cameras and generating calibration targets.

stray calibration generate

This command creates a calibration target that you can print and use to calibrate your cameras.


<target-yaml>Path to the target.yaml file

First you should define a calibration target using a yaml configuration file (saved as target.yaml). Here is an example configuration for a board that can be printed on an A2 size poster:

target_type: 'aprilgrid'
tagCols: 8
tagRows: 5
tagSize: 0.05
tagSpacing: 0.3
  • target_type defines the type of calibration board to generate and can be either "aprilgrid", "checkerboard" or "circlegrid". We recommend "aprilgrid"
  • tagCols determines how many tags to place in the horizontal direction in the grid
  • tagRows determines how many tags to place in the vertical direction in the grid
  • tagSize determines the size of each individual tag
  • tagSpacing determines the spacing between the tags as a percentage, the actual spacing is equal to tagSize * tagSpacing

If you are generating a target for a specific print size, it helps to make sure the size is properly defined and fits the target. This avoids having to scale the target and you can skip measuring the target after scaling and printing. The total width of the target is calculated as tagCols * tagSize + (tagCols - 1) * tagSpacing * tagSize. The total height is tagRows * tagSize + (tagRows - 1) * tagSize * tagSpacing.

Running the stray calibration generate <target-yaml> command will create a target.pdf file in your current directory, which you can print.

We recommend using a larger target, but still small enough so that you can easily observe it from all different angles. We have found that using targets anywhere between the size of an A2 sheet of paper and 0.75x0.75m meters to be convenient, but still large enough to accurately capture.

Be sure to check that no scaling is applied when printing the target. After printing, make sure that the tag did not get scaled by measuring the tag with a ruler. If needed, update the tagSize field in the target.yaml file to reflect the actual size, as the file and tag size will be used again in the calibration step.

stray calibration run <type> <scene>

This command runs camera calibration. It can calibrate intrinsic parameters of the camera as well as camera-to-imu calibration.


<type>noneintrinsicsThe type of calibration to run. Currently only intrinsics is supported.
<scene>Path to the scene to use in calibration
--targetPath to the target.yaml file
--cameraPath to the camchain.yaml file (only for camera_imu calibration)
--imuPath to the imu_noise.yaml file (only for camera_imu calibration)

Camera Intrinsics Calibration

Now that we have a calibration board, we can move on to the actual intrinsics calibration step. In this step, we will collect a dataset where we observe the calibration board from many different viewpoints, covering as many orientations and angles as possible. From this dataset, we can estimate the intrinsic parameters of the camera.

First, mount your calibration board on a flat surface, for example a wall or a table. Make sure that the calibration grid is perfectly flat on the surface and wrinkle free.

Record a dataset with your camera covering as many views as possible. A few things to keep in mind:

  • Try to capture the whole board on every frame
  • Capture the board from as many different camera poses as possible
  • Ensure an even distribution of the different poses, as to not bias the dataset
  • Make sure the calibration board is entirely visible in the image
  • Use images of the same size that you intend to use with stray studio integrate (or alternatively scale the calibration afterwards with stray calibration scale to match the image size)

Here is an example:

Convert your dataset into the Stray scene format. Only the color directory is needed for running intrinsics calibration. We recommend capturing frames at somewhere between 5 to 10hz, as using higher frame rates will needlessly slow down computing the calibration without much benefit.

Run the intrinsics calibration step with the command stray calibration run intrinsics <scene-path> <target-yaml>.

The command will extract the calibration target from each image and recover the intrinsic parameters through optimization. Once done, the command will create a camera_intrinsics.json file in the scene data directory, which contains the intrinsic parameters of the camera, including the intrinsics matrix and distortion coefficients. You can then copy or import this file over to all other scenes captured with this camera.

The command will output a calibration-report.pdf file into the scene directory you used. You can check the report to make sure the reprojection errors are less than a few pixels. The smaller the better. If they are large, try recording a new dataset or run the calibration with a higher resolution.

Another output, camchain.yaml is a yaml file containing intrinsics parameters.

Now you are done, and can proceed to integrate and annotate some scenes!

stray calibration scale

If you calibrated your sensor with a specific resolution, you can fix this by scaling the calibration to the size of the current dataset. You might want to run calibration at full resolution while only storing your datasets at a smaller resolution.


<scenes>Paths to the scenes. The camera_intrinsics.json file needs to be present at minimum
--widthDesired new width of the calibration
--heightDesired new height of the calibration

The stray calibration scale <scenes> --width <new-width> --height <new-height> command reads the current camera_intrinsics.json file in each scene and scales it to the new width and height.


Visit our issue tracker for help and direct support.