Main Content

adtfStreamReader

Stream reader for ADTF DAT file

    Description

    The adtfStreamReader object is an indexed selection of the data in an Automotive Data and Time-Triggered Framework (ADTF) DAT file, which you can use to read that data into the MATLAB® workspace. An adtfStreamReader object contains the indices and time stamps of the first and final data items from each stream selected from an adtfFileReader object. Each stream in the DAT file must contain sorted timestamps. This requirement applies to the data within a stream only, and not across multiple streams.

    Creation

    To create an adtfStreamReader object, use the select object function of the adtfFileReader object. You can read data from all the selected streams at once using the read object function, or read data items one-by-one sequentially using the readNext object function.

    adtfReader = adtfFileReader("sample_adtf.dat","sample_adtf.description");
    streamReader = select(adtfReader, TimeRange=[0, minutes(1)]);
    data = read(streamReader);

    Properties

    expand all

    This property is read-only.

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

    This property is read-only.

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

    This property is read-only.

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

    This property is read-only.

    Indices of the selected streams, specified as a vector of positive integers. The length of the vector is equal to the number of selected streams

    This property is read-only.

    Index of first data item for each stream in the selection, specified as a vector of positive integers. The length of the vector is equal to the number of streams in the selection.

    This property is read-only.

    Index of final data item for each stream in the selection, specified as a vector of positive integers. The length of the vector is equal to the number of streams in the selection.

    This property is read-only.

    Current offset from StartIndex, specified as a nonnegative scalar. This property indicates the current index offset of each stream, starting from the StartIndex value of that stream, when reading data sequentially using the readNext function. The hasNext function also uses this value to determine whether any streams in the selection have subsequent data items to read. The default value of 0 indicates that any sequential reading operation begins at the StartIndex value of each stream. You can reset this index to 0 using the reset function.

    This property is read-only.

    Timestamp of the first data item of each stream in the selection, specified as a duration scalar.

    Dependencies

    To assign this property value, you must specify the TimeRangename-value argument of the select function. Otherwise, the value is an empty duration array.

    This property is read-only.

    Timestamp of final data item of each stream in the selection, specified as a duration scalar.

    Dependencies

    To assign this property value, you must specify the TimeRangename-value argument of the select function. Otherwise, the value is an empty duration array.

    This property is read-only.

    Number of data items in each stream of the selection, specified as a vector of nonnegative integers. The length of the vector is equal to the number of streams in the selection.

    Object Functions

    readRead all data items from ADTF DAT file selection
    readNextRead next available data item from each stream of ADTF DAT file selection
    hasNextCheck if the ADTF DAT file selection has next data
    resetReset stream reader to first data item in ADTF DAT file selection

    Examples

    collapse all

    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

    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
        ___________    __________    _______________    _________    __________    _________
    
             1         {'rawcan'}    {'UNSUPPORTED'}      0 sec      14.805 sec       743   
             2         {'video' }    {'adtf/image' }      0 sec      14.799 sec       149   
    
    
    

    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/plaintype

      • adtf/audio

      • adtf/substreams

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

    Version History

    Introduced in R2022a