tools/calibration/doc/dwx_calibration_overview.md

Go to the documentation of this file.

# Copyright (c) 2019-2020 NVIDIA CORPORATION. All rights reserved.

@page dwx_calibration_overview Calibration Overview

@tableofcontents

DriveWorks considers *calibration* as a representation and estimation of both the
(extrinsic) position and orientation as well as the intrinsics parameters for each individual sensor on a
vehicle. This is also known as an estimation for vehicle-specific parameters.

A precise knowledge of these values enables accurate mapping of perceived
objects in individual sensor frames into other sensor frames, or back into
the world frame.

DriveWorks provides multiple APIs, tools, and samples showing how to calibrate
sensors and vehicle parameters, and this section of the documentation summarizes
existing tools and APIs with the list of supported sensors.

@section dwx_calibration_overview_static 1.0 Static vs Dynamic Calibration

**Static Calibration** is the process of estimating a sensor's calibration parameters
with respect to the vehicle while it is *stationary*. These parameters include:
intrinsics model, extrinsic position and orientation.

Static Calibration consists of multiple steps involving several DriveWorks tools
and tutorials to achieve the desired outcome. These for instance include the
@ref dwx_imu_calibration_tool to estimate IMU orientation, or the @ref dwx_camera_calibration_tools 
to estimate camera intrinsics parameters, position and orientation. The
@ref dwx_camera_calibration tutorial provides assistance in setting up an environment optimized for calibration.

**Dynamic Calibration**, also known as self-calibration, is the process of estimating
a sensor's calibration parameters with respect to the vehicle while it is *non-stationary*.
This process does not require a specifically prepared environment to optimize calibration.
Instead, certain driving maneuvers can influence how these dynamic calibration estimates are obtained.
These maneuvers can include extensive turns, stronger acceleration, or smooth driving in a straight line.
Although DriveWorks APIs and tools do not require you to perform these maneuvers, doing so may result in
quicker calibration results.

The following is a list of sensors supported by the **static calibration** and
**dynamic calibration** DriveWorks APIs and tools.

@subsection dwx_calibration_overview_imu 1.1 IMU Calibration

DriveWorks provides a collection of APIs and tools for both dynamic and
static IMU calibration. In general, any IMU sensor supported by the @ref dwx_sal is
considered to be supported.

#### Static

For more information regarding static IMU Calibration, please refer to @ref dwx_imu_calibration_tool.

#### Dynamic

@ref calibration_usecase_imu covers in great detail how IMU self-calibration is
implemented and which driving maneuvers are beneficial for acceptance of an
accurate estimate.

Following is a list of sensors and DoFs that can be calibrated for IMU sensors
using the APIs as provided by the calibration engine, see
`dwCalibrationEngine_initializeIMU`.

These IMU sensors were tested and supported by both the static calibration tool
as well as the self-calibration API:

|    Sensor       |  Calibration support   | DW version|
|---------------- | ---------------------- | ----------|
|XSens MTi-G-710  |  roll,pitch,yaw        |   >= 2.0  |
|Continental SC13 |  roll,pitch,yaw        |   >= 3.0  |


@subsection dwx_calibration_overview_camera 1.2 Camera Calibration

DriveWorks provides support for the camera modules as listed in
`dwCameraType`. It also provides support for a custom camera through external
drivers. Calibration tools or APIs do not differentiate for specific camera
types, however they do depend on the availability of frames captured with these
cameras. They hence indirectly have a dependency on a working @ref dwx_sal.

#### Static Calibration and Camera Models

DriveWorks supports multiple mathematical models of the geometrical relationship
between pixels and optical rays, also known as intrinsic camera models, see @ref
cameramodel_group.

DriveWorks's static calibration tools support the f-theta
(`dwFThetaCameraConfig`) and pinhole (`dwPinholeCameraConfig`) camera models.
Estimated parameters of these models are also known as **intrinsic** calibration
parameters.

To additionally support mapping objects from camera space to the rig coordinate
system, all camera position and orientation parameters on the vehicle have to be
calibrated as well. These parameters are also known as the camera's
**extrinsic** calibration parameters.

Please refer to @ref dwx_camera_calibration_tools for the list of the tools
provided for static camera calibration. The step-by-step guide @ref
dwx_camera_calibration provides guidelines and best practices on how to successfully perform intrinsic as well
as extrinsic camera calibration. Static camera calibration can be performed on
any camera which is supported by the @ref dwx_sal.

#### Dynamic Calibration

Self-calibration is a method of estimating camera calibration parameters while
the vehicle performs regular driving maneuvers.

DriveWorks provides APIs, see @ref calibration_group, to implement
self-calibration in custom applications.

A collection of samples, for example @ref dwx_camera_calibration_sample,
demonstrates how the DriveWorks API can be used to calibrate recorded sessions.
An explanation of how self-calibration is implemented, as well as some
code-snippets, can be found at @ref calibration_usecase_features.

Following is a list of supported and verified sensors (cameras absent from the table below, but which are
listed in `dwCameraType` are not fully verified at this time):

|   Sensor   |   FOV   |  Orientation  | Dynamic calibration   | DW version   |
|----------- | --------| --------------| ----------------------| -------------|
|  AR0231    |  60deg  | front/rear    | roll,pitch,yaw,height |   >= 2.0     |
|  AR0231    |  60deg  | side/cross    | roll,pitch,yaw        |   >= 3.0*    |
|  AR0231    |  120deg | front/rear    | roll,pitch,yaw,height |   >= 2.0     |
|  AR0231    |  120deg | side/cross    | roll,pitch,yaw        |   >= 3.0*    |
|  AR0820    |  30deg  | front/rear    | pitch,yaw             |   >= 3.0     |
|  AR0820    |  30deg  | side/cross    |         n.a.          |     n.a.     |
|  AR0820    |  70deg  | front/rear    | roll,pitch,yaw,height |   >= 3.0     |
|  AR0820    |  70deg  | side/cross    | roll,pitch,yaw        |   >= 3.0*    |
|  AR0820    |  120deg | front/rear    | roll,pitch,yaw,height |   >= 3.0     |
|  AR0820    |  120deg | side/cross    | roll,pitch,yaw        |   >= 3.0*    |
|  IMX390    |  190deg | front/rear    | roll,pitch,yaw,height |   >= 3.2**   |
|  IMX390    |  190deg | side/cross    | roll,pitch,yaw        |   >= 3.2**   |

Notes:
 - **front/rear** indicate a camera mostly pointing forward or to the back, i.e.
   `yaw` in the ranges of (-30,30) and (150,-150) degrees.
 - **side** is a camera pointing to the sides, i.e. `yaw` is in the ranges of (120,60)
   and (-120,-60) degrees.
 - **cross** indicates a camera along the diagonal axis, i.e. `yaw` is in the ranges of
   (60,30), (-60,-30), (120,150) and (-120,-150) degrees.
 - (*): support is already provided from this version, however expecting
   inferior results
 - (**): expected support starting from this version

@subsection dwx_calibration_overview_lidar 1.3 Lidar Calibration

DriveWorks provides support for a variety of lidar sensors through it's @ref dwx_sal
interface, see @ref lidar_group.

#### Static

There are no tools provided to calibrate lidars statically yet.

#### Dynamic

APIs to perform dynamic lidar calibration can be found at @ref
calibration_group. See @ref calibration_usecase_lidar for a detailed explanation
of the algorithms to self-calibrate, as well as verification methodology of
lidar dynamic calibration.

Following is a list of supported and verified lidars for self-calibration:

|    Sensor       |  Calibration support   | DW version |
|---------------- | ---------------------- | ---------- |
| Velodyne HD32   | roll,pitch,yaw,height  |   >= 2.0   |
| Velodyne HD64   | roll,pitch,yaw,height  |   >= 2.0   |
| Velodyne VLS128 | roll,pitch,yaw,height  |   >= 2.0   |
| Ouster OS2-128  | roll,pitch,yaw,height  |   >= 3.2*  |
| Luminar H3      | roll,pitch,yaw,height  |   >= 3.2*  |

Notes:
 - (*): expected support starting from this version

@subsection dwx_calibration_overview_radar 1.4 Radar calibration

#### Static

There are no tools provided to calibrate radars statically yet.

#### Dynamic

DriveWorks provides APIs to perform radar self-calibration. See @ref
calibration_usecase_radar for a more detailed explanation of how
self-calibration of radars is implemented and verified.

Following is a list of supported and tested radars for self-calibration:

|    Sensor       |  Calibration support   | DW version|
|---------------- | ---------------------- | ----------|
| ARS430 (CAN)    | yaw, wheel-radii       |   >= 2.0  |