src/dw/calibration/engine/docs/usecase_imu.md

Go to the documentation of this file.

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

@page calibration_usecase_imu IMU Self-Calibration

## IMU Calibration - Operating Principle

IMU calibration involves the estimation of the three angles aligning the IMU coordinate frame to the vehicle coordinate frame: roll, pitch, and yaw. All three angles are crucial to correctly estimate and predict the vehicle's pose when egomotion is used in `::DW_EGOMOTION_IMU_ODOMETRY` mode (for more details, see @ref egomotion_mainsection). The three angles are computed by processing the data sensed by the linear accelerometer and the gyroscope sensors embedded in the IMU device. Common driving maneuvers must be performed in order to excite the accelerometer and the gyroscope sensors along their three axes in order to make all three angles to be estimated observable.

### IMU Roll

In order to calibrate the IMU roll, the vehicle must perform several turns. Turns are automatically detected by the magnitude of the gyroscope excitation. In order to mitigate the influence of sensor noise, the gyroscope data is smoothed prior to processing. Roll corresponding to the gyroscope rotation is sampled into a histogram, mode of which, defines the estimated roll angle.

### IMU Pitch and Yaw

The pitch and yaw of the IMU are computed by using the linear accelerometer. In order to identify a forward acceleration, episodes of starts from static conditions, e.g, restarting at a traffic light or in a traffic jam, are automatically detected. In order to mitigate the influence of sensor noise, the accelerometer data is smoothed prior to processing. Employing the same histogram voting scheme as before, the pitch and yaw calibration angles are estimated in a robust way (see histograms below).

![Up estimation histograms (left) and forward estimation histograms (right) of an IMU calibration, collected over a period of time](self_calib_imu.png)

## Requirements

### Initialization Requirements

- Nominal values on IMU calibration
    - Orientation(roll/pitch/yaw): roll less than 10 degree error, pitch and yaw less than 5 degree error
    - Position(x/y/z): not used

### Runtime Calibration Dependencies

- None

### Input Requirements

- Assumption: Vehicle performs the aforementioned maneuvers until calibration convergence.
- Speed measurements: Must be provided as part of dwVehicleIOState, see @ref vehicleio_mainsection for details

### Output Requirements

- Corrected roll/pitch/yaw value: less than 0.4 degrees accuracy
- Time to correction: 11 minutes

## Cross-validation KPI

Several hours of data are used to produce a reference calibration value for cross-validation.
Then, short periods of data are evaluated for whether they can recover the same values.
For example, the graph below shows precision/recall curves of IMU self-calibration.
Precision indicates that an accepted calibration is within a fixed precision threshold
from the reference calibration, and recall indicates the ratio of accepted calibrations
in the given amount of time.

![](self_calib_imu_kpi.png)

## Workflow

The following code snippet shows the general structure of a program that performs IMU self-calibration

```{.cpp}
    dwCalibrationEngine_initialize(...);       // depends on sensor from rig configuration module
    dwCalibrationEngine_initializeIMU(...);    // depends on nominal calibration from rig configuration
    dwCalibrationEngine_startCalibration(...); // runtime calibration dependencies need to be met

    while(true) // main loop
    {
        // get current IMU frame
        dwSensorIMU_readFrame(&imuFrame, ...); // requires IMU module

        // feed IMU frame into self-calibration
        dwCalibrationEngine_addIMUFrame(&imuFrame, ...);

        // Update vehicle state from CAN
        dwSensorCAN_readMessage(&canMsg, ...);
        dwVehicleIO_consumeCANFrame(&canMsg, ...);

        // get current vehicle state
        dwVehicleIO_getVehicleState(&vehicleState, ...);

        // pass on vehicle state to self-calibration
        dwCalibrationEngine_addVehicleIOState(&vehicleState, ...);

        // retrieve calibration status
        dwCalibrationEngine_getCalibrationStatus(...);

        // retrieve self-calibration results
        dwCalibrationEngine_getSensorToRigTransformation(...);
    }

    dwCalibrationEngine_stopCalibration(...);
```

This workflow is demonstrated in the following sample: @ref dwx_imu_calibration_sample