Timestamp Shifting

In Prophesee event-based sensor, the timestamp temporal origin (the zero) is the time when the camera started streaming, not the time when a RAW file starts being recorded. Hence, timestamps in RAW files do not typically start at 0. For example, in the case of a raw stream encoded in EVT 3.0 format the first event can have any timestamp in the range [0, 16.77s].

Having an “initial hole” in the timestamp sequence does not bring any value and is not convenient. So the SDK offers an option to shift the timestamps while decoding and consider the timestamp is the first decoded event as the origin of time.

More specifically, after applying timestamp shifting, the timestamp of the first event may not necessarily be zero. This behavior depends on how the encoding format represents timestamp information.

For instance, in the EVT 3.0 format, timestamps are encoded using Time High (EVT_TIME_HIGH) and Time Low (EVT_TIME_HIGH) words. If we consider a stream where the first CD event has a timestamp of 152017. The mechanism identifies the preceding Time High and Time Low words in the stream, which might encode a base timestamp value of 152000. After applying the timestamp shifting mechanism, the first CD event would have its timestamp adjusted to 17 (the difference between 152017 and 152000).

By default, the timestamp shifting option is enabled in the SDK across our various APIs and applications. However, there are scenarios where disabling this feature can be beneficial, such as when performing fine-grained analysis of RAW files to preserve the original absolute timestamp values for precise data evaluation.

Configuration with SDK tools

Both metavision_file_info and metavision_file_to_csv perform timestamp shifting by default. However, they provide an option, --disable-timestamp-shifting (or its shortcut -d), to disable this feature as needed. This allows users to preserve the original, absolute timestamps in the output.

This option is demonstrated in the example below where we can see that:

  • when timestamp shifting is enabled (default behavior), the first timestamp is adjusted to 16

  • when timestamp shifting is disabled (with option --disable-timestamp-shifting), the original absolute timestamp of 2855312 is preserved

$ metavision_file_info -i industrial_fluid_flow.raw
====================================================================================================

Name                industrial_fluid_flow.raw
Path                /path/to/industrial_fluid_flow.raw
Duration            5s 635ms 895us
Integrator          Prophesee
Plugin name         hal_plugin_prophesee
Data encoding       EVT2
Camera generation   4.0
Camera systemID     26
Camera serial       00000996

====================================================================================================

Type of event       Number of events    First timestamp     Last timestamp      Average event rate
----------------------------------------------------------------------------------------------------
CD                  10572601            16                  5635895             1.9 Mev/s

$ metavision_file_info -i industrial_fluid_flow.raw --disable-timestamp-shifting
====================================================================================================

Name                industrial_fluid_flow.raw
Path                /path/to/industrial_fluid_flow.raw
Duration            8s 491ms 191us
Integrator          Prophesee
Plugin name         hal_plugin_prophesee
Data encoding       EVT2
Camera generation   4.0
Camera systemID     26
Camera serial       00000996

====================================================================================================

Type of event       Number of events    First timestamp     Last timestamp      Average event rate
----------------------------------------------------------------------------------------------------
CD                  10572601            2855312             8491191             1.2 Mev/s

Note

You can observe that both the duration and the average event rate output different values. This discrepancy is due to the initial “hole” without events at the beginning of the file, which is now taken into account in the computation of these values.

Configuring with the SDK API

By default in the SDK, the timestamp shifting option is enabled in our various API. In the following section, we describe how this option can be disabled if you want to get access to the “raw timestamp”.

Using HAL C++ API

When using HAL C++ API, to disable the timestamp shifting, you should leverage RawFileConfig:

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

Using SDK Stream C++ API

When using SDK Stream Camera class, to disable the timestamp shifting, you should leverage the FileConfigHints class:

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

Using SDK Core Python API

When using SDK Core EventsIterator class, to disable the timestamp shifting, you should call the function initiate_device with the argument do_time_shifting set to False:

from metavision_core.event_io.raw_reader import initiate_device
from metavision_core.event_io import EventsIterator

device = initiate_device(path=args.input_path,  do_time_shifting=False)
mv_iterator = EventsIterator.from_device(device=device)

Timestamp in other file formats

When RAW files are converted to other formats (HDF5, DAT or CSV) with our tools (e.g. File to HDF5 Converter, File to DAT Converter File to CSV Converter) we use the default API settings that apply the timestamp shifting, hence the timestamp in those files will be shifted.

  • For CSV, note that our Standalone decoder samples do not use the SDK API and write raw/absolute timestamps directly to the output CSV file. As a result, the CSV files produced by these samples will contain the same timestamps as those generated by C++ CSV Converter when using the --disable-timestamp-shifting option.

  • For HDF5, the offset mentioned in the HDF5 format section should not be confused with the timestamp shift. This offset is only related to the way the indexes are stored. Event data within HDF5 files are stored with shifted timestamps, and the shift value itself is not saved in the file.

  • For DAT files, since timestamps are already shifted during the conversion to the DAT format, the --disable-timestamp-shifting option in metavision_file_info has no effect.