RAW File Format

Definition

RAW files store the output of the event camera without any decoding or processing. RAW sensor data can be stored using various encoding formats.

RAW files are written in binary little-endian.

RAW File Header

RAW file header contains ASCII information and metadata associated to the RAW file. It is a sequence of “keyword, value” pairs written line by line. More precisely, the file header is composed of text lines starting with “%” (0x25) followed by a space (0x20), a keyword, a space (0x20), a value and New Line NL / Line Feed (0x0A).

Here is an example of RAW file header:

% date 2020-09-14 14:18:29
% integrator_name Prophesee
% plugin_name hal_plugin_gen4_fx3
% serial_number 00001034
% evt 3.0
% firmware_version 3.2.3
% system_ID 26

Below, a table with common keyword, value pairs:

Keyword	Value	Mandatory
date	Recording date, format: YYY-MM-DD HH:MM:SS
integrator_name	Company name of the camera manufacturer	YES
plugin_name	HAL plugin used to generate the RAW file	YES
serial_number	Camera serial number	YES
evt	Version of the event encoding format
firmware_version	Camera firmware version. Camera Maker specific.
system_ID	System ID: Camera maker specific
width	Horizontal size of image sensor array.
height	Vertical size of image sensor array.

Note

For legacy RAW files that don’t have an integrator_name or a plugin_name in their header, we assume that this is a Prophesee file. In that case, the system_ID should be present as it will be used to deduce the plugin to use.

RAW File Event Data

RAW file event data is stored using either EVT 2.0 or EVT 3.0 encoding formats. Even if not available in the header metadata, the data encoding format of a RAW file can be figured out using metavision_file_info tool.

Reference decoder code is available in the samples below:

To decode data from EVT 2.0 RAW file, see EVT2 RAW File decoder sample

To decode data from EVT 3.0 RAW file, see EVT3 RAW File decoder sample

Reference encoder code is available for EVT 2.0 in the following sample:

To encode CSV format into EVT 2.0 data, see see EVT2 RAW File encoder sample

RAW File Processing

RAW files can be written and read by Metavision Studio and most of our Code Samples (if you don’t have any RAW file and no camera to produce one, you can use one from our Sample Recordings).

As shown in metavision_noise_filtering sample, it is possible process the events of a RAW file with an algorithm (e.g. ActivityNoiseFilterAlgorithm or TrailFilterAlgorithm) but you won’t be able to save the output directly in a RAW file. To do so, you will have to save the output in an intermediate format (e.g. CSV) and use our sample metavision_evt2_raw_file_encoder to generate a new RAW file based on EVT2 (We don’t provide any encoder for EVT3 format as its compressed nature makes it difficult to be re-created from an uncompressed CSV file).

Note

To apply a filter on a RAW file and re-encode it back to EVT2 RAW file in C++, you can follow those steps:

start from metavision_noise_filtering C++ sample
keep only the filter stage you want to use (or replace the existing ones with a new one)
remove the frame/display parts/stages
copy & paste the pipeline stage that writes CSV from the sample metavision_file_to_csv
use our sample metavision_evt2_raw_file_encoder to generate a new RAW file based on EVT2

In Python, similar steps can be followed. Start from metavision_noise_filtering Python sample and write filtered events in a CSV file as shown in the Python sample metavision_raw_to_csv to create a CSV file that you can then feed in metavision_evt2_raw_file_encoder.

RAW Index File

When reading a RAW file with the SDK, an index file named [raw_file_name].tmp_index is generated in the same folder. This index file stores metadata about where timestamps are located within the file to improve performances while seeking.

When you open a RAW file for the first time, this file is created. This operation can take more or less time depending on the size of the RAW file. But on next opening the same index file will be re-used. If you delete the index file, the SDK will re-create it next time, so you will lose some time, but it has no other impact.