Description

The NVIDIA^® DriveWorks Intrinsics Constraints tool extracts intrinsics constraints used during calibration for each individual camera. It takes any of the following as input:

A recorded video with a checkerboard pattern.
A recorded video with an AprilTag target moved in front of the cameras.
A sequence of still frames containing the AprilTag target in front of the cameras. This is useful when modelling the intrinsics for DLSR cameras.

It then exports all required constraints in a JSON file, placed in the intrinsics subfolder in the directory structure.

Prerequisites

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

This tool creates output files that are placed into the current working directory by default. Please ensure the following for your convenience:

Write permissions are enabled for the current working directory.
Include the tools folder in the binary search path of the system.
Execute from your home directory.

Running the Tool

The Intrinsics Constraints tool accepts the following parameters. Several of these parameters are required based on the input type.
For more information, please refer to the Examples.

./calibration-intrinsics-constraints --use-checkerboard=12x9
                                     --targetDB=[targetDB_file_path]
                                     --input-video=/[video_path]/camera-0.h264
                                     --input-folder=[folder_path]
                                     --output=/[calib_data_path]/intrinsics/camera-0.json
                                     --camera-model=[ftheta]
                                     --rig=[path/to/rig/file]
                                     [--max-constraints=0]
                                     [--skipFrameCount=0]
                                     --blur-filter=[0,1]
                                     --distance-threshold-stability=[1 or higher]
                                     --failed-detections=[none, all, partial]
                                     --output-frame-folder=[folder_path]

Parameters

--use-checkerboard=[NxN checkerboard grid]
        Description: The input NxN checkerboard grid.
        Example: --use-checkerboard=12x9

--targetDB=[path to targetDB file, default=]
        Description: Path to AprilTag target database. Enables detection of AprilTag targets. Either this or [targetDB] must be supplied.

--apriltags=[{CPU, CPU_FAST, GPU}, default=CPU]
        Description: April tag detection backend. The CPU backend is most accurate, while CPU_FAST/GPU provide faster but potentially less accurate detections.

--input-video=[path to input video]
        Description: The file path where the input video is, for checkerboards and AprilTag videos.

--input-folder=[path to input folder]
        Description: The file path where the input folder is, for still frames with AprilTag targets.

--output=[path to output file]
        Description: The file path where the intrinsics constraints will be saved.
                     If this parameter is blank, they will automatically be saved to '[input-video].json'.

--camera-model=[camera model, default=ftheta]
        Description: Camera model used for calibration. Available options are: [pinhole, ocam, ftheta]. The camera model is not used in any way for extracting the constraints. It is passed directly into the produced json file and may be used by other tools.

--rig=[path to rig file, default=]
        Description: Rig file with initial guess of camera intrinsics. Only available for `ftheta` calibration.

--max-constraints=[integer, default=0]
        Description: If non-zero, the maximum number of constraints after which stopping the intrinsic constraint extraction process.

--skipFrameCount=[integer, default=0]
        Description: Number of frames to skip at the beginning of the video.

--blur-filter=[0,1]
        Description: When set to 1, does not collect constraints if detected corners are too blurry. Only applies to checkerboard. 

--distance-threshold-stability=[1 or higher]
        Description: Threshold for maximum pixel distance between detections of two consecutive frames that is required to accept the detection as a constraint. A small value requires the calibration target to be still during at least 2 frames. With a higher value it will also add constraints while the calibration target is moving. High values should be avoided as it could cause motion-blur, an thus worse constraints. 

--failed-detections=[none, all, partial]
        Description: none - no images are output, all - all images that don't add to constraints are output, partial - images that contain detections, but aren't used as constraints are output. 

--output-frame-folder=[folder_path]
        Description: Path to a folder where the video frames will be saved. If blank they won't be saved. This option is valid only for video input.

Examples

For a 12x9 Checkerboard

./calibration-intrinsics-constraints --use-checkerboard=12x9
                                     --input-video=/[video_path]/camera-0.h264
                                     --output=/[calib_data_path]/intrinsics/camera-0.json

For an AprilTag Video

./calibration-intrinsics-constraints --targetDB=/[calib_data_path]/targets.json
                                     --input-video=/[video_path]/camera-0.h264
                                     --output=/[calib_data_path]/intrinsics/camera-0.json

For a Sequence of Still Frames with an AprilTag Target

./calibration-intrinsics-constraints --targetDB=/[calib_data_path]/targets.json
                                     --input-folder=[folder_path]
                                     --output=/[calib_data_path]/intrinsics/external.json

Output

The tool will open a window playing back the input video and indicate with a red or green border if a new intrinsic constraint has been collected (i.e. target or checkerboard has been found)

Warning: For correct results, the tool must be able to find at least 30 checkerboard squares per camera.

Table of Contents