Description

The NVIDIA^® DriveWorks Graph Calibration Tool constructs a graph representation which is then further optimized.

Note: SW Release Applicability: This tool is available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

Prerequisites

This tool is available on the x86 Host System and NVIDIA DRIVE^™ OS Linux.

Running the Tool

Run the tool by executing:

/calibration-graph-cli --targetDB=[path to target database]
                       --dir=[path to directory containing calibration images]
                       --data=[path to a calibration data description json]
                       --graph=[path to a calibration graph json]
                       --showDebug

Parameters

--targetDB=[path to target database]
        Description: The target database to use. Automatically assigned `targets.json` when loading from `dir` structure.
                     Ignored when the [graph] parameter is supplied.

--dir=[path to directory containing calibration images]
        Description: Path to a directory with known structure to load calibration images from (see next section). 
                     Any `calib-data`, `graph`, and `calibrated-graph` files in the directory will be overwritten. 
                     Ignored when the [data] or [graph] parameters are supplied.

--data=[path to a calibration data description json]
        Description: Path to a calibration data description json. 
                     Any graph and calibrated-graph json files in the directory will be overwritten. 
                     Ignored when the [graph] parameter is supplied.

--graph=[path to a calibration graph json]
        Description: Path to a calibration graph json. Can be used to reload a previously calibrated graph and produce validation images.

--showDebug
        Description: When enabled, displays additional debugging information about the calibration procedure.

Possible Calibration Inputs

Expected File Structure

[calib-data-path]
- [external]
  - image-0.png/jpg - These are the external camera images. They can have any name.
  - ...
  - image-M.png/jpg
- [extrinsics]
  - camera-0.png/jpg - Image containing extrinsic constraints for the camera with name.
  - ...
  - camera-N.png/jpg
  - external-dlsr.png - Still frame for DLSR external camera intrinsics constraints. If these are not present, the tool will use images from calib-data-path/external (Optional).
  - ...
  - external-dlsr.png
- [intrinsics]
  - camera-0.h264 - Video containing intrinsic constraints for the camera with name.
  - ...
  - camera-N.h264
- targets.json - The target database with the measured bar lengths.
- special-targets.json - Json file with ids of special targets in the scene (wheel targets, ground targets).

Special Targets

Some targets are considered "special". For example, targets attached to wheels, or targets laying flat on the floor that constrain the ground plane. These special targets must be declared in a separate special-targets.json file, with a structure similar to the following example:

{
    "ground_targets": [99,100],
    "ignore_targets": [142],
    "wheel_targets":
    {
        "rearLeft": 181,
        "rearRight": 182,
        "frontLeft": 180,
        "frontRight": 183
    }
}

Extracting Intrinsic Constraints

Use the Intrinsics Constraints Tool to extract the intrinsic constraints from a recorded video. The tool then generates a JSON file with the camera constraints.

To use the Intrinsics Constraints Tool

Navigate to the following path by running the following:

cd <calib-data-path>/intrinsics

If the target used is a checkerboard pattern:

./calibration-intrinsics-constraints --use-checkerboard=11x8
                                     --input-video=<camera-0>.h264
                                     --output=<camera-0>.json

If the target uses april tags:

./calibration-intrinsics-constraints --targetsDB=../targets.json
                                     --input-video=<camera-0>.h264
                                     --output=<camera-0>.json

To provide constraints for the external DLSR camera from still images

./calibration-intrinsics-constraints --targetsDB=../targets.json
                                     --input-folder=external-dlsr
                                     --output=external.json

This tool has to be executed for each input video of each camera that needs to be calibrated intrinsically.

Building and Calibrating the Graph

Running the tool without arguments assumes the known file structure above. It will determine the names of the cameras from the extrinsics folder.
Then it will look in the intrinsic folder for corresponding json files with the intrinsic constraints. All external images will be used for intrinsic calibration and for extrinsics constraints.

./calibration-graph-cli

An Already Calibrated Graph

One of the outputs of the tool is a calibrated-graph.json file. This file includes all constraints (intrinsic and extrinsic) used for calibration. Running the tool with

./calibration-graph-cli --graph=calibrated-graph.json

will load the constraints from the graph, initialize the graph with the values in the file, re-run the non-linear optimization, and rewrite all the outputs.

A Calibration Data JSON

The calibration data can be explicitly specified in a json file. The format of this json file is best understood by example. See /sdk/data/tests/tools/calibration-calibgraph/gt-scenes/quicksilver/SceneQuicksilver-v2/calib-data.json for an example with 12 cameras.

./calibration-graph-cli --data=calib-data.json

Outputs

The tool outputs progress to the console. Note the warnings in yellow and errors in red. They indicate possible problems with the calibration.
The main output of the tool is the calibrated-graph.json. This contains all constraints, the calibrated camera models, the camera poses, the target poses, etc.
This file contains calibration results which cannot be consumed by the DriveWorks SDK yet and are neither readable by the human. The results can be converted with Calibrated Graph to Rig File Tool into a valid rig.json file which represents the whole camera rig configuration and can be directly consumed by DriveWorks’ dwRig module.
Intrinsic validation images (validation-intrinsics-<camera>.jpg) shows the set of points used for intrinsic calibration.
Blue=detected, red=reprojected, yellow=line joining detection and reprojection. Large yellow lines indicate outliers.
Extrinsic validation images (validation-<camera>.jpg) shows the image used for extrinsic calibration with overlaid results. Detected targets have a green overlay.
Detected tags have their corner detections (same colors as the intrinsic reprojections).
The ground plane is drawn as a series of green lines 1m apart (lines at x=0 and y=0 are orange).

Table of Contents