TartanCalib

Introduction

TartanCalib contributes state-of-the-art calibration for wide-angle lenses, by implementing an iterative calibration pipeline and adaptive subPixel refinement of AprilTags. The code for TartanCalib is built upon the Kalibr toolbox, is easy to use, and robust. If you are interested in helping us extend the features of TartanCalib, please reach out to Bart (email).

For more information, visit our project page here.

Installation

Docker (Preferred)

To use the Dockerfiles provided in this repository, ensure that you have Docker installed on your system.

1. Clone and build docker image

    git clone https://github.com/castacks/tartancalib
    cd tartancalib
    docker build -t tartancalib -f Dockerfile_ros1_20_04 .
   

2. Mount data folder and share xhost within container for GUI. For more information, read the ROS wiki on Docker.

    FOLDER=/path/to/your/data/on/host
    xhost +local:root
    docker run -it -e "DISPLAY" -e "QT_X11_NO_MITSHM=1" \
        -v "/tmp/.X11-unix:/tmp/.X11-unix:rw" \
        -v "$FOLDER:/data" tartancalib
   

3. When in the Docker container, follow the Usage section of this readme to run calibration commands.

Local Installation

TartanCalib and Kalibr are integrated within ROS. Ensure that you have ROS installed within your system.

• Ubuntu 16.04 ROS 1 Kinetic
• Ubuntu 18.04 ROS 1 Melodic
• Ubuntu 20.04 ROS 1 Noetic

1. Install dependencies required for TartanCalib.

Ubuntu 16

    sudo apt-get update && apt-get install -y \
    git wget autoconf automake \
    python2.7-dev python-pip python-scipy python-matplotlib \
    ipython python-wxgtk3.0 python-tk python-igraph \
    libeigen3-dev libboost-all-dev libsuitesparse-dev \
    doxygen \
    libopencv-dev \
    libpoco-dev libtbb-dev libblas-dev liblapack-dev libv4l-dev \
    python-catkin-tools     

Ubuntu 18

    sudo apt-get update && apt-get install -y \
    git wget autoconf automake nano \
    python3-dev python-pip python-scipy python-matplotlib \
    ipython python-wxgtk4.0 python-tk python-igraph \
    libeigen3-dev libboost-all-dev libsuitesparse-dev \
    doxygen \
    libopencv-dev \
    libpoco-dev libtbb-dev libblas-dev liblapack-dev libv4l-dev \
    python-catkin-tools

Ubuntu 20

    sudo apt-get update && apt-get install -y \
    git wget autoconf automake nano \
    python3-dev python3-pip python3-scipy python3-matplotlib \
    ipython3 python3-wxgtk4.0 python3-tk python3-igraph \
    libeigen3-dev libboost-all-dev libsuitesparse-dev \
    doxygen \
    libopencv-dev \
    libpoco-dev libtbb-dev libblas-dev liblapack-dev libv4l-dev \
    python3-catkin-tools python3-osrf-pycommon

2. Clone and build repository

    mkdir ~/tartan_ws && cd ~/tartan_ws
    mkdir src && cd src
    git clone https://github.com/castacks/tartancalib
    cd ..
    export ROS1_DISTRO=noetic # kinetic=16.04, melodic=18.04, noetic=20.04
    source /opt/ros/$ROS1_DISTRO/setup.bash
    catkin init
    catkin config --extend /opt/ros/$ROS1_DISTRO
    catkin config --merge-devel # Necessary for catkin_tools >= 0.4.
    catkin config --cmake-args -DCMAKE_BUILD_TYPE=Release
    catkin build

3. Source catkin workspace

    cd ~/tartan_ws && source devel/setup.bash

4. Follow Usage section to get calibrating!

Usage

Step 1 - Create rosbag dataset

This can be done through a multitude of different ways. If you have a physical setup linked to ROS, directly recording the sensor stream to a rosbag would be easiest. There are also methods of cutting common video formats into rosbags. The rosbag api is well documented and contains examples that would potentially be helpful if you are new to working with bag files.

Step 2 - Define calibration board through YAML files

Kalibr supports three different calibration targets with different parameters associated to each target. Kalibr's wiki has more information on calibration targets in YAML. An example of an aprilgrid YAML file is provided below:

    #example for aprilgrid
    target_type: 'aprilgrid' #gridtype
    tagCols: 10                 #number of apriltags
    tagRows: 7                  #number of apriltags
    tagSize: 0.025              #size of apriltag, edge to edge [m]
    tagSpacing: 0.3             #ratio of space between tags to tagSize
                                #example: tagSize=2m, spacing=0.5m --> tagSpacing=0.25[-]

The method should also work with checkerboards but would require some adaptation. In general grids of AprilTags are most robust.

Step 3 - Run calibration

This is sample code for running calibration with certain parameters changed. Please refer to the table below for the full range of configurable parameters.

In a terminal or bash file:

    export ROS1_DISTRO=noetic # kinetic=16.04, melodic=18.04, noetic=20.04
    source /opt/ros/$ROS1_DISTRO/setup.bash

In a terminal, for example:

    cd ~/tartan_ws && source devel/setup.bash
    rosrun kalibr tartan_calibrate \
    --bag /path/to/bagfile.bag \
    --target /path/to/target.yaml \
    --topics /camera_0/image_raw /camera_1/image_raw \
    --min-init-corners-autocomplete 29 \
    --min-tag-size-autocomplete 2 \
    --correction-threshold 10.1 \
    --models omni-radtan omni-radtan \
    --dont-show-report
    --save_dir /path/to/output/

<br>

Below is a table of basic parameters to get TartanCalib running. You will minimally have to configure the following parameters.

| Basic Parameter | Description | | ----------------------------- | ----------- | | bag | Path to calibration bagfile. | | target | Path to target YAML files. | | topics | List of camera topics within bag file to calibrate. If you have three cameras with topic names /camera_n/image_raw, use --topics camera_0/image_raw camera_1/image_raw camera_2/image_raw. Note that ordering here has to match ordering within --models | | models | Choose the camera/distortion model pair to be fitted. The following choices are currently available: pinhole-radtan, pinhole-equi, pinhole-fov, omni-none, omni-radtan, eucm-none, ds-none. For more details on supported models, check out Kalibr's documentation. |
| log_dest | Save filename of logs. All output filenames will begin with this parameter. (Default: log)| | save_dir | Save directory of YAML files containing calibration information, and a pickle with log data. Must end with a trailing slash. (Default: /data/) | | debug_image_dir | Save directory of PNG files for debugging. Must be an existing folder, and debug_image_dir must end with a trailing slash if a folder is specified. Images are saved by default to your workspace folder. (Default: '') |

<br>

Below is a table of advanced parameters if you'd like to have greater control over TartanCalib's algorithm.

| Advanced Parameter | Description | | ------------------ | ----------- | | outputMatlab | When selected, outputs Matlab matrix for use in BabelCalib (or similar). | | projections | Choose from four possible modes: cornerpredictor, pinhole, homography, and none. Cornerpredictor is the autocomplete method described within the paper, and is recommended for best results. | | debug-modes | Choose from 7 possible debug modes for additional debug images: pointcloudprojection, pinholeprojection, originalprojection, targetpointcloud, individualprojections, reprojectionpoints | fovs | When using pinhole projection mode, this parameter represents FOV of pinhole. This argument accepts multiple pinholes corresponding to each topic. For example, if your bag contains two topics, /camera_0/image_raw, and /camera_1/image_raw, to generate three pinholes of FOVs 30, 60, 90 for camera_0 and one pinhole of fov 90 for camera_1, use --fovs 30 60 90 --fovs 90. Note that the number of arguments for fovs must correspond with poses and resolutions. | | poses | When using pinhole projection mode, this parameter represents pose of pinhole. As with fovs, this argument can be configured for multiple projections. | | resolutions | When using pinhole projection mode, this parameter represents resolution of pinhole. As with fovs, this argument can be configured for multiple projections. | | min-init-corners-autocomplete | The algorithm minimally requires this number of corners for autocomplete. With values that are too small, the pose of the board might be too uncertain for accurate results. (Default: 24)| |