Library Integration for IMU - Calibration Container

From RidgeRun Developer Wiki

Follow Us On Twitter LinkedIn Email Share this page




RidgeRun Video Stabilization Library
Table of Contents [Sticky]





Introduction

Calibrated cameras offer two advantages when working with video stabilization:

  1. The intrinsic camera matrix is used to convert between real-world coordinates and image space dimensions.
  2. The distortion parameters are used to remove distortion from images caused by camera lens.

We explain the calibration theory in this article in more detail.

The RidgeRun Video Stabilization Library provides a camera calibration tool to obtain the intrinsic camera matrix and distortion parameters. In order to simplify the construction and usage of the camera calibration tool, we also provide a docker container that runs the calibration tool on a set of samples and provides the resulting calibration data.

Building the Calibration Container Image

Note
We provide a prebuilt image in Docker Hub. If you only intend to use the container directly for calibration without rebuilding it, jump to Using the Calibration Container.

Dependencies

  1. Compulsory dependencies: Make sure to have the compulsory dependencies for the RidgeRun Video Stabilization Library.
  2. Docker: Additionally, Docker is used to build and run the calibration container. To install Docker, follow these guides:
    1. Installation instructions for Ubuntu
    2. Manage docker as a non root user

Build Steps

Once the code for the video stabilizer library has been obtained, follow these steps from the project root to build the docker image for the calibration container:

  1. Obtain the project submodules: 
    git submodule update --init --recursive
meson subprojects download
  2. Build the docker image: 
    export DOCKER_BUILDKIT=1
docker build -f ./docker/Dockerfile -t ridgerun/video-stabilization-library:cameracalibrator_latest .

Using the Calibration Container

To use the calibration container, the host must first have a directory that is going to be mounted as a volume on the container and where the calibration results will be stored. In the following commands, replace </path/to/host-volume> with the absolute path to this directory.

This directory must contain a subdirectory named samples that contains all the calibration samples. These samples are expected to be jpg files.

Below we instructions for using the calibration container in 4 different configurations:

We also provide an example where we combine configurations:

Default Configuration

Run the calibration container with: 

docker run --rm --name calibration-container --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume ridgerun/video-stabilization-library:cameracalibrator_latest

This will save a calibration.yml file in the mounted volume with the calibration data. Additionally a samples-undistorted subdirectory will be created in the mounted volume and it will contain all the undistorted samples.

Example of container usage with default configuration

Configuring Calibration Technique

To specify the calibration technique, run the calibration container with: 

docker run --rm --name calibration-container --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume ridgerun/video-stabilization-library:cameracalibrator_latest -t <technique>

Replace <technique> with the desired technique. The available techniques are:

  1. fisheye: This is the default technique and it uses the fisheye lens model to calibrate the samples.
  2. brown: This uses the Brown-Comrady lens model to calibrate the samples.
Example of container usage using brown technique

Interactive Sample Selection

To interactively select samples, run the calibration container with: 

docker run --rm --name calibration-container --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume -it ridgerun/video-stabilization-library:cameracalibrator_latest

This allows the use of the following commands to select samples used for calibration:

  1. ENTER: Selects the sample
  2. n + ENTER: Discards the sample
  3. q + ENTER: Ends the sample selection and starts the calibration
Example of container usage with interactive sample selection

Previewing Samples

To preview the samples during the sample selection step (assuming the host uses the X window system), run the calibration container with: 

xhost +local:
docker run --rm --name calibration-container -e DISPLAY=$DISPLAY --mount type=bind,src=/tmp/.X11-unix,dst=/tmp/.X11-unix,readonly --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume ridgerun/video-stabilization-library:cameracalibrator_latest -p

These commands allows the container access to the X server on the host so that it can open a preview window.

Example of container usage with sample previews

Combining Configurations

The previous configurations can be combined to customize the calibration experience. For example, the following commands use the Brown-Comrady lens model to calibrate, they allow the user to interactively select samples, and they display a preview of the samples during the selection step: 

xhost +local:
docker run --rm --name calibration-container -e DISPLAY=$DISPLAY --mount type=bind,src=/tmp/.X11-unix,dst=/tmp/.X11-unix,readonly --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume -it ridgerun/video-stabilization-library:cameracalibrator_latest -p -t brown
Example of container usage with combined features




Retrieved from "https://developer.ridgerun.com/wiki/index.php?title=RidgeRun_Video_Stabilization_Library/Library_Integration_for_IMU/Calibration_Container&oldid=71279"