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 really easy to manipulate

Classes

For simple use cases you can also use the following 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 or a RAW file.

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

duration_s

Indicating the total duration of the file in seconds.

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

A class to write CD events in DAT binary files:

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

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.count_events(filename)

Returns the number of events in a DAT file.

Args :

filename (string): Path to a DAT file.