adtfFileReader

Read stream information from ADTF DAT file

Since R2022a

Description

An adtfFileReader object reads the stream information associated with the various sensors in an Automotive Data and Time-Triggered Framework (ADTF) DAT file. ADTF is a framework developed by Elektrobit, to develop, visualize, test and validate advanced driver assistance systems (ADAS) and automated driving functions. DAT files contain data from various sensors, such as lidars and cameras as well as other automotive data.

To select messages of a specific type to read from an adtfFileReader object, use the select object function.

adtfFileReader supports reading both 2.0 and 3.0 versions of ADTF DAT files. Each stream in the DAT file must contain sorted chunk timestamps. This requirement applies to the data within a stream only, and not across multiple streams.

Creation

Syntax

adtfReader = adtfFileReader(dataFileName)

adtfReader = adtfFileReader(dataFileName,descriptionFileName)

adtfReader = adtfFileReader(dataFileName,pluginDirectoryPath)

adtfReader = adtfFileReader(dataFileName,descriptionFileName,pluginDirectoryPath)

Description

adtfReader = adtfFileReader(dataFileName) creates an adtfFileReader object, adtfReader, that reads stream information from the specified ADTF DAT file.

adtfReader = adtfFileReader(dataFileName,descriptionFileName) specifies a description file, descriptionFileName, that defines the structure of the streams in the ADTF DAT file.

adtfReader = adtfFileReader(dataFileName,pluginDirectoryPath) specifies a directory, pluginDirectoryPath, that contains plugins to use when reading information from the ADTF DAT file. Plugins are operating system specific, compiled object files that help in reading DAT files.

adtfReader = adtfFileReader(dataFileName,descriptionFileName,pluginDirectoryPath) specifies the plugin directory and the description file to read data from the ADTF DAT file.

Input Arguments

dataFileName — ADTF DAT file name

string scalar | character vector

ADTF DAT file name, specified as a string scalar or character vector.

descriptionFileName — Description file name

string scalar | character vector

Description file name, specified as a string scalar or character vector. Description files have the extension as XML or DESCRIPTION.

pluginDirectoryPath — Absolute path to ADTF plugin directory

string scalar | character vector

Absolute path to ADTF plugin directory, specified as a string scalar or character vector. The object uses only the plugin files within the specified directory that have the .adtffileplugin extension.

Properties

DataFileName — Absolute path to ADTF DAT file

string scalar

This property is read-only.

Absolute path to the ADTF DAT file to read, specified as a string scalar.

DescriptionFileName — Absolute path to description file

string scalar

This property is read-only.

Absolute path to the description file, specified as a string scalar.

PluginDirectory — Absolute path to ADTF plugin directory

string scalar

This property is read-only.

Absolute path to ADTF plugin directory, specified as a string scalar.

StreamCount — Number of streams in DAT file

positive integer

This property is read-only.

Number of streams in DAT file, specified as a positive integer.

StreamInfo — Summary of all streams in the DAT file

structure

This property is read-only.

Summary of all streams in the DAT file, specified as a structure.

Object Functions

select

Create reader for selected subset of ADTF DAT file data

Examples

Extract Video Stream From ADTF DAT File

This example shows how to extract and visualize a video stream, stored in an ADTF DAT file. It also shows how to write the video stream into a video file.

Download the sample video DAT file.

downloadURL  = 'https://ssd.mathworks.com/supportfiles/driving/data/sample_can_video_dat.zip';
dataFolder   = fullfile(tempdir, 'adtf-video', filesep); 
options      = weboptions('Timeout', Inf);
zipFileName  = [dataFolder, 'sample_can_video_dat.zip'];
folderExists = exist(dataFolder, 'dir');

% Create a folder in a temporary directory to save the downloaded file.
if ~folderExists  
    mkdir(dataFolder); 
    disp('Downloading sample_can_video_dat.zip (9.74 MB)...') 
    websave(zipFileName, downloadURL, options); 
    
    % Extract contents of the downloaded file.
    disp('Extracting sample_can_video_dat.zip...') 
    unzip(zipFileName, dataFolder); 
end

Downloading sample_can_video_dat.zip (9.74 MB)...

Extracting sample_can_video_dat.zip...

Create the ADTF File Reader object.

datFileName = fullfile(dataFolder,"sample_can_video.dat");
fileReader  = adtfFileReader(datFileName) 

fileReader = 
              DataFileName: "C:\Users\latriwal\AppData\Local\Temp\adtf-video\sample_can_video.dat"
       DescriptionFileName: ""
           PluginDirectory: ""
               StreamCount: 2
                StreamInfo: 

    StreamIndex    StreamName      StreamType      StartTime     EndTime      ItemCount    SubstreamInfo
    ___________    __________    ______________    _________    __________    _________    _____________

         1         {'rawcan'}    {'UNRESOLVED'}      0 sec      14.805 sec       743       {0×1 struct} 
         2         {'video' }    {'adtf/image'}      0 sec      14.799 sec       149       {0×1 struct} 

From the StreamInfo property, note that the index of the video stream is 2. Use the select function of the adtfFileReader object, to select the video stream for reading. The returned adtfStreamReader object has all the information about the selection.

streamReader = select(fileReader,2) 

streamReader = 
  adtfStreamReader with properties:

           DataFileName: "C:\Users\latriwal\AppData\Local\Temp\adtf-video\sample_can_video.dat"
    DescriptionFileName: ""
        PluginDirectory: ""
            StreamIndex: 2
             StartIndex: 1
               EndIndex: 149
     CurrentIndexOffset: 0
              StartTime: [0×0 duration]
                EndTime: [0×0 duration]
              DataCount: 149

Note that the value of CurrentIndexOffset is 0. This signifies that the next readNext call will return the first item.

Preview the first image frame from the stream.

firstFrame = readNext(streamReader);
imshow(firstFrame.Data.Item)

Before creating a video, use the reset function to start reading from the first frame. This resets the value of CurrentIndexOffset to 0.

reset(streamReader);
fprintf("CurrentIndexOffset = %d\n",streamReader.CurrentIndexOffset)

CurrentIndexOffset = 0

Create a VideoWriter object that you can use to write image frames to a video file. Specify a frame rate of 1 frame per second.

videoWriterObj = VideoWriter("example_video.avi"); 
videoWriterObj.FrameRate = 1; 
open(videoWriterObj); 

Using the streamReader object, iterate over the data items in the selection one-by-one. The hasNext function determines if there is an item left to read as we are incrementally reading the file. readNext returns the data item which is basically a structure containing the data and the associated timestamp. In every iteration, extract the image frame and write it to the video file.

while streamReader.hasNext()
    streamData = streamReader.readNext(); 
    imageFrame = streamData.Data.Item; 
    frame      = im2frame(streamData.Data.Item, gray); 
    writeVideo(videoWriterObj, frame); 
end 

Alternatively, you can read all the image frames at once, using the read function, and iterate over it later.

allData = read(streamReader)

allData = struct with fields:
    StreamIndex: 2
           Data: [149×1 struct]

Close the connection with the video file.

close(videoWriterObj);
close all

Visualize the output file example_video.avi using Video Viewer.

implay("example_video.avi") 

Limitations

• Reading DAT files on Mac platforms is not supported.

• Reading these stream types is not supported:

  • adtf/anonymous

  • adtf/audio

• For reading adtf/video_compressed stream type, only JPEG compression format is supported.

Version History

Introduced in R2022a