Calibrate Geometry Documentation

Documentation for the Skip Robotics camera intrinsic calibration tool.

Overview

The Skip Robotics intrinsic / stereo calibration tool is called CalibrateGeometry. It is an interactive GUI application for collecting data and estimating camera calibrations. The tool also includes functionality for inspecting and verifying calibration results.

Starting the tool

After installing, run the following command from the terminal to see the full list of arguments:

$ skipr_calibrate_geometry --help
version: 0.1.0
Program arguments:
  --help                                print usage help message
  -i [ --image_input ] arg              Source of images.
  -f [ --camera_file ] arg              The camera parameters file.
  --camera_fixed                        Camera fixed and target is being moved.
  -m [ --model ] arg (=RATIONAL)        The distortion model being used.
  -d [ --dataset ] arg                  The calibration dataset directory to
                                        use.
  --tag_family arg (=tag36h11)          The family of fiducial tags to look
                                        for.
  --tag_decimation arg (=2)             Detect fiducials tags using smaller
                                        image to improve speed. Image is
                                        reduced by this factor.
  -r [ --rows ] arg (=8)                The number of columns in the the
                                        calibration pattern.
  -c [ --cols ] arg (=6)                The number of rows in the calibration
                                        pattern.
  -s [ --square ] arg (=0.029999999999999999)
                                        The size of each chessboard square in
                                        meters.
  -t [ --tag ] arg (=0.024)             The size of each fiducial tag in
                                        meters.
  --min_control_points arg (=12)        The minimum number of control points in
                                        a calibration view.
  --min_sharpness arg (=0.10000000000000001)
                                        The minimum sharpness score to add
                                        calibration images to the dataset_.
  --min_isotropy arg (=0.84999999999999998)
                                        The minimum isotropy score to add
                                        calibration images to the dataset_.
  -n [ --max_images ] arg (=1000)       The maximum number of calibration
                                        pattern captures to use as part of the
                                        solution.
  --outlier_threshold arg (=2)          Threshold for removing outlier
                                        residuals. Measured in pixels.
  --target_warp                         Enable calibration target
                                        deformation/warp modeling.
  --high_distortion                     Enable solver mode for high distortion
                                        lenses.
  --residuals arg                       The residuals and auxillary solution
                                        data output file.

At minimum, the following command line arguments must be provided:

  1. A image sequence / data source:
  1. Parameters of the calibration target:
  1. Locations where the collected dataset and output calibration will be saved:

For example, the follow command will start a calibration session for a UVC camera with an AprilTag based target. This assumes an 8x11 checkerboard pattern. Each square is 0.025m x 0.025m and the fiducial tags are 0.018m x 0.018m.

$ skipr_calibrate_geometry --rows 8 --cols 11 --square 0.025 --tag 0.01875 --image_input "uvc:///dev/video0" --dataset intrinsics_dataset -f calibration.json --tag_family tag36h11

GUI Overview

After starting the tool, you'll see the following screen:

Starting screen of the calibration tool.

The GUI operates in two basic modes: data collection and data inspection. The initial screen shows an empty dataset in Inspect mode.

The right hand panel side shows various controls. The lower tabs show various reports about the dataset and calibration solution (when available). The upper left portion of the screen (blank in the screenshow above) shows the collected images.

Controls

The right hand side of the screen shows controls for data collection, running the calibration solver, viewing the images in the dataset, and calibration target detection.

Data Collection

Data collection controls screenshot.

The data collection control panel is used for adding new images to the dataset from the image sequence source specified on the command line.

Calibration Solver

Calibration controls screenshot

This is the main panel for running the calibration solver itself after collecting a dataset.

Dataset

Dataset controls screenshot.

This panel is used to inspect the dataset and calibration results.

Target Detection

Target detection controls screenshot.

The target detection controls are used to configure the calibration target detector. This includes the type of target (classical, aptiltags, ChAruco, etc.) and the row x column dimensions of the checkerboard pattern.

Background Processing

This area displays status text about long-running background operations, such as the solver.

Dataset collection and calibration

Starting from the initial screen, use the 'Data Collection' controls to start the image sequence. This will display a live camera feed in the upper left portion of the screen.

Align the calibration target in front of the camera and press 'Toggle Data Collection' to begin recording the dataset.

Once data collection is enabled, the tool with switch from 'Inspect' to 'Gather' mode:

CalibrateGeometry tool in 'Gather mode'.

Move the camera in front of the target slowly (or vice versa), collecting data from different angles.

When a calibration target is detected, the average sharpness and isotropy of all detected corners will be plotted on the panel at the bottom of the screen.

On the left of the sharpness plots, a histogram showing currently collected view angles and distances will appear. A separate histogram will appear for each camera in a stereo pair.

After collecting a dataset, press the 'Calibrate' button in the 'Calibration Solver' section of the control panel. This will run the calibration algorithm in the background.

Dataset Statistics and RMSE value

When a calibration has been computed the tabs at the lower portion of the screen will show statistics and reports about the solution and dataset. In 'Overview' mode, these will be aggregated statistics over the whole dataset. Otherwise, the statistics will be reported on a per-image basis when you move through the dataset.

Residual Statistics

The 'Residual Histogram' and 'Residual Scatter' tabs show visualizations of the distribution of residuals. These can be used to confirm calibration quality.

Data Distribution

The 'Data Distribution' tab shows a histogram of the entire dataset, using the same format as the live histogram shown during data collection.

RMSE, Bias, and Outliers

These tabs show a heatmap of the local RMSE error, bias, and the number of outliers. They can be used to confirm good data has been collected uniformly across the entire field of view and that there are not areas with poor data quality. Additional data can always be added to the dataset to fill in any gaps. The scale on these heat maps ranges from 0 to the scale of the outlier threshold set in the 'Calibration Solver' control panel.

Target Warp

The 'Target Warp' tab shows the estimated physical target warping/bending as a heatmap. A legend at the bottom gives the numerical values in millimeters.