Event I/O

This module contains several options for loading events. RAW files are direct dump from the camera whereas DAT files are simple binaries representation of events, that are bigger on disk but easier to manipulate.

Classes

For simple use cases you can also use the following EventsIterator class directly for both RAW or DAT files. It has a reduced set of features compared to RawReader and DatReader below but runs faster.

class metavision_core.event_io.EventsIterator(input_path, start_ts=0, mode='delta_t', delta_t=10000, n_events=10000, max_duration=None, relative_timestamps=False, **kwargs)

EventsIterator is a small convenience class to iterate through either a camera, a DAT file, a RAW file or a H5 file containing events.

Note that, as every Python iterator, you can consume an EventsIterator only once.

reader

class handling the file or camera.

delta_t

Duration of served event slice in us.

Type

int

max_duration

If not None, maximal duration of the iteration in us.

Type

int

end_ts

If max_duration is not None, last timestamp to consider.

Type

int

relative_timestamps

Whether the timestamp of served events are relative to the current reader timestamp, or since the beginning of the recording.

Type

boolean

Parameters
  • input_path (str) – Path to the file to read. If path is an empty string or a camera serial number it will try to open that camera instead.

  • start_ts (int) – First timestamp to consider (in us). If mode is “delta_t” or “mixed”, start_ts must be a multiple of delta_t, otherwise a ValueError is thrown.

  • mode (string) – Load by timeslice or number of events. Either “delta_t”, “n_events” or “mixed”, where mixed uses both delta_t and n_events and chooses the first met criterion.

  • delta_t (int) – Duration of served event slice in us.

  • n_events (int) – Number of events in the timeslice.

  • max_duration (int) – If not None, maximal duration of the iteration in us.

  • relative_timestamps (boolean) – Whether the timestamp of served events are relative to the current reader timestamp, or since the beginning of the recording.

  • **kwargs – Arbitrary keyword arguments passed to the underlying RawReaderBase or EventDatReader.

Examples

>>> for ev in EventsIterator("beautiful_record.raw", delta_t=1000000, max_duration=1e6*60):
>>>     print("Rate : {:.2f}Mev/s".format(ev.size * 1e-6))
classmethod from_device(device, start_ts=0, n_events=10000, delta_t=50000, mode='delta_t', max_duration=None, relative_timestamps=False, **kwargs)

Alternate way of constructing an EventsIterator from an already initialized HAL device.

Note that it is not recommended to leave a device in the global scope, so either create the HAL device in a function or, delete explicitly afterwards. In some cameras this could result in an undefined behaviour.

Parameters
  • device (device) – Hal device object initialized independently.

  • start_ts (int) – First timestamp to consider.

  • mode (string) – Load by timeslice or number of events. Either “delta_t” or “n_events”

  • delta_t (int) – Duration of served event slice in us.

  • n_events (int) – Number of events in the timeslice.

  • max_duration (int) – If not None, maximal duration of the iteration in us.

  • relative_timestamps (boolean) – Whether the timestamp of served events are relative to the current reader timestamp, or since the beginning of the recording.

  • **kwargs – Arbitrary keyword arguments passed to the underlying RawReaderBase.

Examples

>>> from metavision_core.event_io.raw_reader import initiate_device
>>> device = initiate_device(path=args.input_path)
>>> # call any methods on device
>>> mv_it = EventsIterator.from_device(device=device)
>>> del device  # do not leave the device variable in the global scope
get_size()

Function returning the size of the imager which produced the events.

Returns

Tuple of int (height, width) which might be (None, None)

class metavision_core.event_io.LiveReplayEventsIterator(events_iterator, replay_factor=1.0)

LiveReplayEventsIterator allows replaying a record in “live” (“real-time”) condition or at a speed-up (or slow-motion) factor of real-time.

Parameters
  • events_iterator (EventsIterator) – event iterator

  • replay_factor (float) – if greater than 1.0 we replay with slow-motion,

  • this is a speed-up over real-time. (otherwise) –

metavision_core.event_io.is_live_camera(input_path)

Checks if input_path is a live camera

Parameters
  • input_path (str) – path to the file to read. if path is an empty string or a camera serial number,

  • function will return true. (this) –

class metavision_core.event_io.AdaptiveRateEventsIterator(input_path, thr_var_per_event=0.0005, downsampling_factor=2)

AdaptiveRateEventsIterator is small convenience class to iterate through a recording

It will produce reasonably sharp slices of events of variable time duration and variable number of events, depending on the content of the stream itself.

Internally, it uses a compation of variance per event as a criterion for the sharpness of the current slice of events. An additional criterion is the proportion of active pixels containing both positive and negative events.

Parameters
  • input_path (str) – Path to the file to read

  • thr_var_per_event (float) – minimum variance per pixel value to reach before considering splitting the slice.

  • downsampling_factor (int) – performs a downsampling of the input before computing the statistics. Original coordinates will be multiplied by 2**(-downsampling_factor)

Examples

>>> for events in AdaptiveRateEventsIterator("beautiful_record.raw"):
>>>     assert events.size > 0
>>>     start_ts = events[0]["t"]
>>>     end_ts = events[-1]["t"]
>>>     print("frame: {} -> {}   delta_t: {}   fps: {}   nb_ev: {}".format(start_ts, end_ts,
                                                                           end_ts - start_ts,
                                                                           1e6 / (end_ts - start_ts),
                                                                           events.size))
metavision_core.event_io.raw_reader.initiate_device(path, do_time_shifting=True, use_external_triggers=[])

Constructs a device either from a file if the path ends with RAW or with the camera serial number.

This device can be used in conjunction with RawReader.from_device or EventsIterator.from_device to create a RawReader or an EventsIterator with a customized HAL device.

Parameters
  • path (str) – either path do a RAW file (having a .raw or .RAW extension) or a camera serial number. leave blank to take the first available camera.

  • do_time_shifting (bool) – in case of a file, makes the timestamps start close to 0mus.

  • use_external_triggers (int List) – list of integer values corresponding to the channels of external trigger to be activated (only relevant for a live camera).

Returns

a HAL Device.

Return type

device

class metavision_core.event_io.RawReader(record_base, max_events=100000000, do_time_shifting=True, device=None, initiate_device=True, use_external_triggers=[])

RawReader loads events from a RAW file.

RawReader allows to read a file of events while maintaining a position of the cursor. Further manipulations like advancing the cursor in time are possible.

path

Path to the file being read. If path is an empty string or a camera serial number it will try to open that camera instead.

Type

string

current_time

Indicating the position of the cursor in the file in us.

Type

int

do_time_shifting

If True the origin of time is a few us from the first events. Otherwise it is when the camera was started.

Type

bool

Parameters
  • record_base (string) – Path to the record being read.

  • do_time_shifting (bool) – If True the origin of time is a few us from the first events. Otherwise it is when the camera was started.

  • use_external_triggers (int List) – list of integer values corresponding to the channels of external trigger to be activated (only relevant for a live camera).

clear_ext_trigger_events()

Deletes previously stored external trigger events

current_event_index()

Returns the number of event already loaded

classmethod from_device(device, max_events=100000000)

Alternate way of constructing an RawReader from an already initialized HAL device.

Note that it is not recommended to leave a device in the global scope, so either create the HAL device in a function or, delete explicitely afterwards. In some cameras this could result in an undefined behaviour.

Parameters

device (device) – Hal device object initialized independently.

Examples

>>> device = initiate_device(path=args.input_path)
>>> # call any methods on device
>>> reader = RawReader.from_device(device=device)
>>> del device  # do not leave the device variable in the global scope
get_ext_trigger_events()

Returns all external trigger events that have been loaded until now in the record

get_size()

Function returning the size of the imager which produced the events.

Returns

Tuple of int (height, width)

is_done()

Indicates if all events have been already read.

load_delta_t(delta_t)

Loads all the events contained in the next delta_t microseconds.

Parameters

delta_t (int) – Interval of time in us since last loading, within which events are loaded

Returns

structured numpy array containing the events.

Return type

events (numpy array)

load_mixed(n_events, delta_t)

Loads batch of n events or delta_t microseconds, whichever comes first.

Parameters
  • n_events (int) – Maximum number of events that will be loaded.

  • delta_t (int) – Maximum allowed slice duration (in us).

Returns

structured numpy array containing the events.

Return type

events (numpy array)

Note that current time will be incremented to reach the timestamp of the first event not loaded yet unless the maximal time slice duration is reached in which case current time will be increased by delta_t instead.

load_n_events(n_events)

Loads a batch of n_events events.

Parameters

n_events (int) – Number of events to load

Returns

structured numpy array containing the events.

Return type

events (numpy array)

reset()

Resets at beginning of file.

seek_event(n_events)

Advance n_events into the RAW file. The decoded events are dropped.

Parameters

n_events (int) – number of events to skip.

seek_time(final_time)

seeks into the RAW file until current_time >= final_time.

Parameters

final_time (int) – Timestamp in us at which the search stops.

class metavision_core.event_io.EventDatReader(event_file)

EventDatReader class to read DAT long files. DAT files are a binary format with events stored with polarity, x and y casted into a uint32 and timestamp on another uint32. This format still exists in many of our datasets, so this file is used to support it.

path

Path to the file being read

Type

string

current_time

Indicating the position of the cursor in the file in us

Type

int

duration_s

Indicating the total duration of the file in seconds

Type

int

Parameters

event_file (str) – file containing events

class metavision_core.event_io.EventNpyReader(event_file)

EventNpyReader class to read NPY long files.

path

Path to the file being read

Type

string

current_time

Indicating the position of the cursor in the file in us

Type

int

duration_s

Indicating the total duration of the file in seconds

Type

int

Parameters

event_file (str) – file containing events

class metavision_core.event_io.EventBboxNpyReader(event_file)

EventBboxNpyReader class to read NPY long files.

path

Path to the file being read

Type

string

current_time

Indicating the position of the cursor in the file in us

Type

int

duration_s

Indicating the total duration of the file in seconds

Type

int

Parameters

event_file (str) – file containing events

class metavision_core.event_io.DatWriter(filename, height=240, width=320)

Convenience class used to write Event2D to a DAT file.

The constructor writes the header for a DAT file.

Parameters
  • filename (string) – Path to the destination file

  • height (int) – Imager height in pixels

  • width (int) – Imager width in pixels

Examples

>>> f = DatWriter("my_file_td.dat", height=480, width=640)
>>> f.write(np.array([(3788, 283, 116, 0), (3791, 271, 158, 1)],
                     dtype=[('t', '<u4'), ('x', '<u2'), ('y', '<u2'), ('p', 'u1')]))
>>> f.close()
write(events)

Writes events of fields x,y,p,t into the file. Only Event2D events are supported

Parameters

events (numpy array) – Events to write

class metavision_core.event_io.event_bufferizer.FixedTimeBuffer(delta_t)

Fixed Time Bufferizer Sends data once delta_t is accumulated Otherwise Sends None. :param delta_t: time trigger :type delta_t: int

class metavision_core.event_io.event_bufferizer.FixedCountBuffer(max_count)

Fixed Count Buffer Sends data once max_count events are accumulated :param max_count: count trigger :type max_count: int

class metavision_core.event_io.H5EventsWriter(out_name, height, width, compression_backend='zlib')

Compresses & Writes Event Packets as they are read

Parameters
  • out_name (str) – destination path

  • height (int) – height of recording

  • width (int) – width of recording

  • compression_backend (str) – compression api to be called, defaults to zlib.

  • you can try to use zstandard which is faster at writing. (If) –

write(events)

Writes event buffer into a compressed packet

Parameters

events (ndarray) – events of type EventCD

class metavision_core.event_io.H5EventsReader(path)

Reads & Seeks into a h5 file of compressed event packets.

Parameters

src_name (str) – input path

class metavision_core.event_io.meta_event_producer.MetaEventBufferProducer(event_producer, mode='delta_t', delta_t=10000, n_events=10000, start_ts=0, relative_timestamps=False)

Resamples an event producer to stream by N events or DT duration.

Parameters
  • event_producer (object) – any object that streams numpy buffer of EventCD

  • mode (str) – “delta_t”, “n_events” or “mixed” trigger ways

  • delta_t (int) – fixed duration

  • n_events (int) – fixed count

  • start_ts (int) – start time

  • relative_timestamps (bool) – retrieve events with first time of buffer substracted

get_size()

Resolution of the sensor that produced the events.

seek_time(ts)

seek in time, depends on event producer’s seek implementation.

Defines some tools to handle events, mimicking dat_tools.py. In particular :

-> defines functions to read events from binary .npy files using numpy

metavision_core.event_io.npy_tools.parse_header(fhandle)

Parses the header of a .npy file

Parameters

fhandle (file) – File handle to a DAT file.

Returns

int position of the file cursor after the header int type of event int size of event in bytes size (height, width) tuple of int or None

metavision_core.event_io.npy_tools.stream_events(file_handle, buffer, dtype, ev_count=- 1)

Streams data from opened file_handle

Args :

file_handle: File object, needs to be opened. buffer (events numpy array): Pre-allocated buffer to fill with events. dtype (numpy dtype): Expected fields. ev_count (int): Number of events.

Functions

metavision_core.event_io.load_events(filename, ev_count=- 1, ev_start=0)

Loads event data from files.

Args :

path (string): Path to a DAT file. event_count (int): Number of events to load. (all events in the file we be loaded if set to the default -1). ev_start (int): Index of the first event.

Returns :

a numpy array behaving like a dictionary containing the fields ts, x, y, p

metavision_core.event_io.dat_tools.stream_events(file_handle, buffer, dtype, ev_count=- 1)

Streams data from opened file_handle. Args :

file_handle: file object, needs to be opened. buffer (events numpy array): Pre-allocated buffer to fill with events dtype (numpy dtype): expected fields ev_count (int): Number of events

metavision_core.event_io.npy_tools.stream_events(file_handle, buffer, dtype, ev_count=- 1)

Streams data from opened file_handle

Args :

file_handle: File object, needs to be opened. buffer (events numpy array): Pre-allocated buffer to fill with events. dtype (numpy dtype): Expected fields. ev_count (int): Number of events.

metavision_core.event_io.count_events(filename)

Returns the number of events in a DAT file.

Args :

filename (string): Path to a DAT file.

metavision_core.event_io.dat_tools.parse_header(f)

Parses the header of a DAT file and put the file cursor at the beginning of the binary data part.

Parameters

f (file) – File handle to a DAT file.

Returns

int position of the file cursor after the header int type of event int size of event in bytes size (height, width) tuple of int or None

metavision_core.event_io.npy_tools.parse_header(fhandle)

Parses the header of a .npy file

Parameters

fhandle (file) – File handle to a DAT file.

Returns

int position of the file cursor after the header int type of event int size of event in bytes size (height, width) tuple of int or None