calibration/engine/docs/usecase_vehicle.md

Go to the documentation of this file.

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

@page calibration_usecase_vehicle Vehicle Self-Calibration

@note SW Release Applicability: This tutorial is applicable to modules in both **NVIDIA DriveWorks** and **NVIDIA DRIVE Software** releases.

## Operating Principle

NVIDIA<sup>&reg;</sup> DriveWorks uses vehicle model to calibrate the steering system properities using vehicle odometery and vehicle egomotion measurement and predicted vehicle motion based on vehicle model.

### Steering Offset

Vehicle self-calibration supports vehicle steering offset self calibration. The steering offset is the difference between the actual steering and the measured steering angle, and it equals to the negative of the measured steering angle when the vehicle drive straight. The steering offset is calibrated by minimizing the predicted turn curvature based on model and curvature computed based on measurement data. To start the calibration process, the vehicle has to drive above 10 meter per seocnd, perform gradual lane change maneuvers.

![Normalized steering offset q3 (steering offset / wheelbase) (center histogram), and Understeer coefficient (left histogram)collected over a period of time](self_calib_vehicle.png)

## Requirements

### Initialization Requirements

- Nominal values on vehicle calibration
    - steering offset: 0 radian

### Runtime Calibration Dependencies

- IMU-based egomotion needs to be based on accurate IMU calibration and odometry properties

### Input Requirements

- Assumption: Vehicle performs the aforementioned maneuvers until calibration convergence.
- Vehicle egomotion: requirements can be found in the @ref egomotion_mainsection module
- Vehicle IO State: requirements can be found in the @ref vehicleio_mainsection VehicleIO

### Output Requirements

- Corrected steering offset: less than 0.8 degrees accuracy

## 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 normalized steering offset
q3 (q3=steering offset / wheelbase).
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_vehicle_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_initializeVehicle(...);    // depends on nominal calibration from rig configuration
    dwCalibrationEngine_startCalibration(...);     // runtime calibration dependencies need to be met

    while(true) // main loop
    {
        // get current vehicle IO state
        dwVehicleIO_getVehicleState(&state, ...); // requires vehicle io module

        // feed vehicle io state into self-calibration
        dwCalibrationEngine_addVehicleIOState(&state, ...);

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

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

    dwCalibrationEngine_stopCalibration(...);
```

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