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 made of two parts:

  • Header written in ASCII

  • Event data written in binary little or big-endian (depending on the sensor configuration, little-endian by default)

RAW File Header

RAW file header contains 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).

There is one special keyword: end without value that is used to mark the end of the header so that the code used to parse the header can know that after this keyword data will be found. This keyword is optional though as the parser will decide data begins as soon as a line does not start with “% ” (i.e the character ‘%’ followed by ‘ ‘).

Here is an example of RAW file header obtained with an EVK4 on Metavision SDK 4.0:

% camera_integrator_name Prophesee
% date 2023-03-29 16:37:46
% evt 3.0
% format EVT3;height=720;width=1280
% generation 4.2
% geometry 1280x720
% integrator_name Prophesee
% plugin_integrator_name Prophesee
% plugin_name hal_plugin_imx636_evk4
% sensor_generation 4.2
% serial_number 00ca0009
% system_ID 49
% end

Below, a table with common keyword/value pairs:

Keyword

Value

date

Recording date, format: YYYY-MM-DD HH:MM:SS

camera_integrator_name

Company name of the camera integrator

plugin_integrator_name

Company name of the plugin integrator

plugin_name

HAL plugin used to generate the RAW file

serial_number

Camera serial number

format

Encoding format version & size of sensor array

format: EVTn;height=y;width=x

system_ID

Camera System ID

end

No Value. Used to specify end of header

With the current version of Prophesee camera plugin, to be able to read a RAW file, the keyword format is favored as it contains both the encoding format (required to decode the data) and the geometry of the sensor (required when displaying events as frames).

Setting both keywords camera_integrator_name and plugin_integrator_name to the value Prophesee will allow Prophesee plugin to use the system_ID field to infer information on the stream that might be missing from the header (i.e. if the % format value is missing).

The other keywords (e.g. serial_number) are optional and currently only used to provide information to the I_HW_Identification class.

Note

There are multiple related/synonyms keyword in the example shown above (integrator_name and camera_integrator_name, or evt and format etc.). Those keywords are present for backward compatibility of the recordings, i.e. to allow previous versions of Metavision SDK to read RAW files.

RAW File Event Data

RAW file event data is stored using EVT 2.0, EVT 2.1 or EVT 3.0 encoding formats which is specified in the format keyword in the header. As described in the Selecting Data Formats section, you can choose which encoding format to use via Metavision Studio or the SDK API.

On some versions of RAW files, the format might be absent from the header. In that case, the data encoding format of the RAW file can be figured out using metavision_file_info tool.

Reference decoder code is available for EVT2 and EVT3 in the samples below:

Reference encoder code is available for EVT2 in the following sample:

RAW File Usage

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:

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_file_to_csv to create a CSV file that you can then feed in metavision_evt2_raw_file_encoder.

Another option to process event data is to convert the RAW file into an HDF5 event file and then process the HDF5 event file. In that case, it is possible to save the processed data in an HDF5 event file.

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. However, you need to ensure that you have write access on the path where you open the RAW file. Otherwise, you will get in the terminal a message similar to the following:

[HAL][ERROR] Failed to build index for input RAW file raw_file_name.raw

It is possible to specify that a RAW file should not be indexed when opening it:

  • when using HAL API, you should leverage RawFileConfig:

    Metavision::RawFileConfig config;
config.build_index_ = false;
device = DeviceDiscovery::open_raw_file(file_path, config);

  • when using SDK Driver, you should leverage FileConfigHints:

    Metavision::FileConfigHints config;
config.set("index", false);
camera = Metavision::Camera::from_file(file_path, config);