Opening an Event File

In Metavision SDK, events can be stored in various file formats:

The different modules of the SDK can read the following formats:

  • HAL C++ and Python API can read RAW files

  • SDK Stream C++ and Python API can read RAW, DAT and HDF5 files

  • SDK Core Python API can read RAW, DAT and HDF5 files

As demonstrated in the following sections, once a file is opened with the SDK, a device or a camera object is created. This object functions similarly to the one obtained when connecting to a live camera. While sensor-specific facilities such as biases, ROI, and ERC are not applicable to files, these objects still provide access to all the powerful streaming and decoding features of the SDK.

See also

For an overview of the HAL facilities available for both cameras and files, refer to:

Using HAL C++ API

A RAW file can be opened using the function Metavision::DeviceDiscovery::open_raw_file():

device = Metavision::DeviceDiscovery::open_raw_file(raw_file_path);

Once the device is available, you can stream events as you would do from a camera. You can refer to the page Reading Events from a device for more details. If you want to start from an example, on how to stream events from a file with HAL API in C++, you can check out the sample metavision_hal_showcase

Using HAL Python API

The HAL Python API is a binding of the C++ API so the usage is similar:

device = DeviceDiscovery.open_raw_file(raw_file_path)

A simple example demonstrating how to discover and open a RAW file with this HAL Python API can be found in the metavision_hal_get_started sample.

Using SDK Stream C++ API

An event file (RAW, HDF5 or DAT) can be opened with the function Metavision::Camera::from_file:

camera = Metavision::Camera::from_file(event_file_path)

Once the camera is available, you can stream events from your file as you would do from a actual camera. You can refer to the page Reading Events from a device for more details. Alternatively, you can check our tutorial Get Started using C++ that shows how to read events both from cameras and event files.

Using SDK Stream Python API

The SDK Stream Python API is a binding of the SDK Stream C++ API so the usage is similar:

camera = Camera.from_file(event_file_path)

To see this Camera class in action, see our Python Get started guide or the metavision_camera_stream_slicer Python sample.

Using SDK Core Python API

In addition to the SDK Stream Python class Camera mentioned in the previous sections, the SDK also provides another class for opening cameras: EventsIterator.

The EventsIterator class was developed prior to the binding of the C++ Camera class and has therefore been widely used in various samples and tutorials. While newer implementations may favor the Camera class for its streamlined interface, the EventsIterator remains a robust and well-documented choice for accessing event-based data.

To us this API, the following statement will open an event file (RAW, HDF5 or DAT):

mv_iterator = EventsIterator(event_file_path)

To see the EventsIterator class in action, you can check the list of code samples and pick one that is leveraging it.

Going Further

To learn how to retrieve the event stream, refer to the following guide: Reading Events from a Device.