rig/docs/usecase0.md

Go to the documentation of this file.

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

@page rigconfiguration_usecase0 Rig File Format

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

A rig file contains two major fields to define sensors and vehicles, that is,

    {
        "rig": {
            "sensors": [ { sensor I }, { sensor II }, ... ],
            "vehicle": { vehicle }
        },
        "version":
    }

# Sensor Field

Each sensor field provides information on each sensor and can be categorized into two types: camera field and non-camera field.

## 1. Camera Field

Each camera field is an array that describes each specific camera in the sensor suite. The following code snippet shows how the camera field is structured,

    {
        "name": "camera:front:center:60fov",
        "nominalSensor2Rig": {
            "quaternion": [
                0.0,
                0.0,
                0.0,
                1.0
            ],
            "t": [
                0.0,
                0.0,
                0.0
            ]
        },
        "parameter": "camera-type=ar0231-rccb-bae-sf3325,camera-group=a,camera-count=1,camera-mask=0001,siblingIndex=0,output-format=raw+yuv,fifo-size=1,warn-per-frame=0",
        "properties": {
            "Model": "ftheta",
            "bw-poly": "0.0 0.000545421498827636 -1.6216719633103e-10 -4.64720492990289e-12 2.85224527762934e-16",
            "cx": "960",
            "cy": "604",
            "height": "1208",
            "width": "1920",
            "car-mask": "camera:front:center:60fov.pgm"
        },
        "protocol": "camera.gmsl",
        "sensor2Rig": {
            "quaternion": [
                0.0,
                0.0,
                0.0,
                1.0
            ],
            "t": [
                0.0,
                0.0,
                0.0
            ]
        },
        "car-mask": {
            "data/rle16-base64": "//8BjoABAQAA3QEBBQAA2gEBBwAA2AEBC...",
            "resolution": [
                 480,
                 302
            ]
    }

**name**: *camera* : *front* | *rear* : *left* | *center* | *right* : *60fov* | *120fov*

**parameter**: [camera parameters](@ref dwx_sensor_enum_sample)

**properties**: Properties are stored in name=value pairs and implement properties which are specific for a certain sensor in a generic way. A camera can specify calibration parameters, e.g. the intrinsic parameters, in here.

**properties->Model**: *ftheta* | *ocam* | *pinhole*

This determines the supported optical camera models, which defines the mapping between optical rays and pixel coordinates. Each model has a separate set of parameters `dwFThetaCameraConfig`, `dwOCamCameraConfig`, `dwPinholeCameraConfig`.

**car-mask**: The `car-mask` *property* specifies a (optional) binary image file (currently `.pgm` images are supported) representing a binary mask of the ego-car in the camera image, separating it from the scene. Also, (optional) serialized car mask images are supported, which are represented by a serialization of the binary car mask images in the `car-mask` *field*. A `car-mask` image file property will be converted into a `car-mask` field on rig file serialization, and `car-mask` image file properties always have precedence over serialized car masks (to be able to update them). Car masks are important for, e.g., accurate self-calibration of the given camera.

**protocol**: For camera sensors, protocol must be *camera.gmsl*

<a name="sensor2Rig"></a>
**sensor2Rig**:

This is the sensor to rig transformation for a camera, and can be represented in two forms,

1.

    {
        "quaternion": [q_x, q_y, q_z, q_w],
        "t": [t_x, t_y, t_z]
    }


2.

    {
        "roll-pitch-yaw": [roll, pitch, yaw],
        "t": [t_x, t_y, t_z]
    }

This transformation relates the camera and the rig coordinate system to each other, i.e. translation in meters and roll-pitch-yaw in degrees. For example, the origin in camera coordinate system is the position of the camera in rig coordinates. The self-calibration might remove this field, and substitute it with *correction_rig_T* and *correction_sensor_R_FLU* transformations after the calibration.

<a name="nominalSensor2Rig"></a>
**nominalSensor2Rig**:

This is the nominal sensor to rig transformation for a camera, and can be represented in two forms,

1.

    {
        "quaternion": [q_x, q_y, q_z, q_w],
        "t": [t_x, t_y, t_z]
    }

2.

    {
        "roll-pitch-yaw": [roll, pitch, yaw],
        "t": [t_x, t_y, t_z]
    }

This transformation differs from *sensor2rig* transformation in that it represents a static reference transformation from factory calibration and/or mechanical drawings, whereas *sensor2rig* can change over time.

<a name="correction_rig_T"></a>
**correction_rig_T**:

This shows the corrections in the translation with respect to the *nominalSensor2Rig* transformation, which is estimated and added to the rig file by the self-calibration. The self-calibration saves the translation updates only as,

    {
        "t": [t_x, t_y, t_z]
    }

<a name="correction_sensor_R_FLU"></a>
**correction_sensor_R_FLU**:

This shows the corrections in the rotation with respect to the *nominalSensor2Rig* transformation, which is estimated and added to the rig file by the self-calibration. The self-calibration saves the rotation updates only as,

    {
        "roll-pitch-yaw": [roll, pitch, yaw],
    }

<a name="nominalSensor2Rig_FLU"></a>
**nominalSensor2Rig_FLU**:

During the self-calibration, *nominalSensor2Rig* transformation is renamed and saved as *nominalSensor2Rig_FLU* without any change in the values as,

    {
        "roll-pitch-yaw": [roll, pitch, yaw],
        "t": [t_x, t_y, t_z]
    }

@note To summarize the self-calibration changes in the rig files,
- Rig files before self-calibration: *sensor2Rig* + *nominalSensor2Rig*
- Rig files after self-calibration: *correction_sensor_R_FLU* + *correction_rig_T* + *nominalSensor2Rig_FLU*

## 2. Non-Camera Field

NVIDIA<sup>&reg;</sup> DriveWorks currently supports the following non-camera sensors:
- CAN
- GPS
- IMU
- Lidar
- Radar

The following code snippet shows an example for the IMU sensor field,

    {
        "name": "imu:xsens",
        "nominalSensor2Rig": {
            "quaternion": [
                0.0,
                0.0,
                0.0,
                1.0
            ],
            "t": [
                0.0,
                0.0,
                0.0
            ]
        },
        "parameter": "device=/dev/ttyUSBXSENS,baudrate=230400,time-smoothing=true",
        "properties": null,
        "protocol": "imu.xsens",
        "sensor2Rig": {
            "quaternion": [
                0.0,
                0.0,
                0.0,
                1.0
            ],
            "t": [
                0.0,
                0.0,
                0.0
            ]
        }
    }

The following code snippet shows an example for the GPS sensor field,

    {
        "name": "gps:xsens",
        "correction_rig_T": [
            0.0,
            0.0,
            0.0
        ],
        "correction_sensor_R_FLU": {
            "roll-pitch-yaw": [
                0.0,
                0.0,
                0.0
            ]
        },
        "nominalSensor2Rig_FLU": {
            "roll-pitch-yaw": [
                0.0,
                0.0,
                0.0
            ],
            "t": [
                0.0,
                0.0,
                0.0
            ]
        },
        "parameter": "file=device=/dev/ttyUSBXSENS,baudrate=230400",
        "properties": null,
        "protocol": "gps.xsens"
    }

**name**: *can* | *gps* | *imu* | *lidar* | *radar*

**parameter**: [sensor parameters](@ref dwx_sensor_enum_sample)

**properties**:

Properties are stored in name=value pairs and implement properties which are specific for a certain sensor in a generic way. For example, an IMU might store bias values there, etc.

**protocol**:

- CAN: *can.socket* | *can.aurix*
- GPS: *gps.uart*   | *gps.xsens*
- IMU: *imu.uart*   | *imu.xsens*
- Lidar: *lidar.socket*
- Radar: *radar.socket*

**sensor2Rig**: [sensor2Rig transformation](#sensor2Rig)

**nominalSensor2Rig**: [nominalSensor2Rig transformation](#nominalSensor2Rig)

**correction_rig_T**: [correction_rig_T transformation](#correction_rig_T)

**correction_sensor_R_FLU**: [correction_sensor_R_FLU transformation](#correction_sensor_R_FLU)

**nominalSensor2Rig_FLU**: [nominalSensor2Rig_FLU transformation](#nominalSensor2Rig_FLU)

# Vehicle Field

The following rig snippet shows the vehicle field structure,

    {
        "vehicle": {
            "valid": true,
            "value": {
                "axleFront": {
                    "corneringStiffness": 0.0,
                    "position": 0.0,
                    "track": 0.0,
                    "wheelRadiusLeft": 0.0,
                    "wheelRadiusRight": 0.0
                },
                "axleRear": {
                    "corneringStiffness": 0.0,
                    "position": 0.0,
                    "track": 0.0,
                    "wheelRadiusLeft": 0.0,
                    "wheelRadiusRight": 0.0
                },
                "body": {
                    "boundingBoxPosition": [0.0, 0.0, 0.0],
                    "centerOfMass": [0.0, 0.0, 0.0],
                    "height": 0.0,
                    "inertia": [0.0, 0.0, 0.0],
                    "length": 0.0,
                    "mass": 0.0,
                    "width": 0.0
                },
                "powertrain": {
                    "brakeActuatorTimeConstant": 0.0,
                    "effectiveMass": 0.0,
                    "throttleActuatorTimeConstant": 0.0,
                    "torqueLUT": {
                        "throttlePedalInput": "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                        "throttleSpeedInput": "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                        "throttleTorqueOutput": [
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                            "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0"
                        ],
                        "brakePedalInput": "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0",
                        "brakeTorqueOutput": "0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0"
                    }
                },
                "steering": {
                    "driveByWireTimeConstant": 0.0,
                    "driveByWireTimeDelay": 0.0,
                    "maxSteeringWheelAngle": 0.0,
                    "steeringWheelToSteeringMap": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
                },
                "suspension": {
                    "pitchDampingRatio": 0.0,
                    "pitchNaturalFrequency": 0.0
                },
                "hasCabin": false,
                "numTrailers": 0
            }
        }
    }

For the full implementation refer to `dwVehicleGeneric`

# Vehicle IO Field

Vehicle IO field describes Drive-By-Wire interface of a vehicle.

    "vehicleio": [
        {
            "type": "custom",
            "parent-sensor": "can:vehicle",
            "dbc-file": "AutonomousVehicleCANSignals.dbc"
        }
    ],
    "sensors": [
        {
            "name": "can:vehicle",
            "parameter": "device=can0",
            "protocol": "can.socket",
            "properties": null,
            "nominalSensor2Rig": { "quaternion": [ 0.0, 0.0, 0.0, 1.0 ], "t": [ 0.0, 0.0, 0.0 ] },
            "sensor2Rig": { "quaternion": [ 0.0, 0.0, 0.0, 1.0 ], "t": [ 0.0, 0.0, 0.0 ] }
        }
    ],

**type**: [Type of a Drive-By-Wire interface.](@ref vehicleio_mainsection)

**parent-sensor**: Name of a sensor that is used to communicate with Drive-By-Wire hardware.

**dbc-file**: A DBC file for Vehicle IO drivers that require one.

For more information, please refer to
[Vehicle IO Documentation](@ref vehicleio_mainsection),
[Vehicle IO Sample](@ref dwx_vehicleio_sample), and
[Vehicle IO Plugin sample](@ref dwx_vehicleio_plugin_sample).