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 RAW file, an HDF5 event file or a DAT file.

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_ext_trigger_events(): Returns a copy of 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) 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,
real-time. (otherwise this is a speed-up over) –

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,
true. (this function will return) –

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 a camera.

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 to 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 0us.
use_external_triggers (Channel List) – list of channels of external trigger to be activated (only relevant for a live camera). On most systems, only one (MAIN) channel can be enabled.

Returns

a HAL Device.

Return type

device

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

RawReader loads events from a RAW file or a camera

When reading a file, RawReader allows to read the 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 (Channel 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=10000000)

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 explicitly 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.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.

class metavision_core.event_io.event_frame_iterator.EventFrameReader(input_path): Reads a raw file of either DIFF3D or HISTO3D

class metavision_core.event_io.event_frame_iterator.EventFrameIterator(input_path)

Iterates over a raw file of either DIFF3D or HISTO3D

get_frame_type(): Returns the frame type. Will be either ‘DIFF3D’ or ‘HISTO3D’

get_size()

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

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

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