DriveWorks SDK Reference
3.5.78 Release
For Test and Development only

Frame Parsing Ingestion Tool

Description

This tool is available on the x86 Host System.

This is an executable which takes a binary sensor file as input, extracts sensor frame data and outputs the result to a ION/JSON file.

The tool currently supports Camera, CAN, GPS, IMU and Lidar binary file parsing. The tool parses CAN signals, GPS frames, IMU frames, Camera frames and Lidar packets.

Input

The input file must be a DriveWorks-supported binary sensor file: *.raw, *.lraw, *.xraw or *.bin, a *.mp4 file, or an index file outputted by Sensor Indexer Ingestion Tool. If the sensor file being parsed is a CAN sensor file, an input DBC tag is required as well. If the input is an index file, the executable will parse the timestamp list for each sensor frame and output them by frame index. The supported output format types are "ion-text", "ion-binary" and "json".

Output

The output ION/JSON file is filled with the serialized data of each sensor frame in the input file. For non-mp4 formats, the output of this tool is an intermediate ion/json output to be fed into the timesync_framedata tool for time synchronization. For mp4 videos, this will be the final ion/json output, and no time synchronization needs to be done. The output format for each parsed frame is described below.

Usage

cd install/tools/ingestion ./ingest_framedata –input=[path to input sensor file | path to input index file] –format=[ion-text|ion-binary|json] –output=[path to output ION/JSON file] [–dbc-tag=[input DBC tag for CAN recordings]]

DBC Tag

For CAN recordings, a DBC tag is required as well. The tag will be used to load the appropriate DBC file for interpreting the CAN signals in the parsed CAN messages. The DBC tag must be one of "audi", "dataspeed", "nav-config", "space-drive", "tsm-vmm", "vbox" or "default" (the general AV CAN Signals dbc file will be used for the latter).

Output Format

At the top of each output file, a struct containing metadata will be present:

Metadata
  • fileType : string, e.g. "lidar", "gps", etc.
  • numOfFrames : uint64_t, the number of Camera/GPS/IMU frames, CAN signals or Lidar packets in the file

Then, the rest of the file will contain multiple structs, with each struct being a CAN signal, Lidar packet or Camera/GPS/IMU frame.

CAN
  • timestamps : a list of timestamps in different time domains ordered by time conversion preference; see TimestampList Format below
  • payload : CAN signal data
    • message_index : uint32_t, index of the CAN message
    • signal_index : uint32_t, index of the signal within the message
    • signal_type : string, type of the signal, e.g. "bool", "float32"
    • signal_name : string
    • value : float64_t, raw value of the signal as a real number
    • unit : unit of the value, e.g. "m/s"
GPS
  • timestamps : a list of timestamps in different time domains ordered by time conversion preference; see TimestampList Format below
  • payload : GPS frame data
    • latitude : float64_t
    • longitude : float64_t
    • altitude : float64_t
    • course : float64_t
    • speed : float64_t
    • climb : float64_t
    • hdop : float64_t, horizontal dilution of precision
    • vdop : float64_t, vertical dilution of precision
IMU
  • timestamps : a list of timestamps in different time domains ordered by time conversion preference; see TimestampList Format below
  • payload : IMU frame data
    • orientation_[x] : float64_t, roll, pitch and yaw angle of the orientation in degrees
    • orientation_quaternion_[x] : float64_t, quaternion representation of the orientation
    • turn_rate_[x] : float64_t, roll, pitch and yaw angle turn rate in rad/s
    • acceleration_[x] : float64_t, acceleration in x, y and z directions in m/s^2
    • magnetometer_[x] : float64_t, measurement of the magnetometer unit in x, y and z directions in microteslas
    • heading : float64_t, heading of the IMU in respect to the ENU system in degrees
Video - Raw formats
  • timestamps : a list of timestamps in different time domains ordered by time conversion preference; see TimestampList Format below
  • payload : Camera frame data
    • frame_num : uint32_t, index of the frame
Video - MP4
  • timestamp : int64_t, the MP4 timestamp
  • payload : Camera frame data
    • frame_num : uint32_t, index of the frame
Lidar
  • packet_timestamps : a list of timestamps for the current packet in different time domains ordered by time conversion preference; see TimestampList Format below
  • frame_timestamps : timestamps of the spin's first packet ordered by time conversion preference
  • payload : Lidar packet data
    • packet_index : uint32_t, index of the packet within the spin
    • frame_index : uint32_t, index of the Lidar spin
    • azimuths_rad : float64_t[], the list azimuths of the current packet in radians
Index File

If the input is an .idx file generated by Sensor Indexer Ingestion Tool, the output will have the same format as Video.

TimestampList Format

Each timestamp list is a list of timestamps in different time domains, ordered by time conversion preference - the timesync tools will attemp to convert the first timestamp in the list to Host time domain first; if it fails, it will attempt to conver the next, etc. The last timestamp in the list will always be in Host time domain. Timesync tools will fallback to this one in case conversion from the other time domains in the list fails. Each timestamp is described as a pair in the output:

  • timestamp : int64_t, a timestamp value in the TimeDomain's unit
  • time_domain : uint8_t, { 0 : HOST, 1 : TSC, 2 : PTP, 3 : UTC, 4 : UTCTOH }