DriveWorks SDK Reference
4.0.0 Release
For Test and Development only

Rig File Format

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-name=SF3325,interface=csi-a,link=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

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

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.

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.

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]
}

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],
}

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® 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

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

nominalSensor2Rig: nominalSensor2Rig transformation

correction_rig_T: correction_rig_T transformation

correction_sensor_R_FLU: correction_sensor_R_FLU transformation

nominalSensor2Rig_FLU: nominalSensor2Rig_FLU transformation

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.

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, Vehicle IO Sample, and Vehicle IO Plugin sample.