undr.formats#

File formats supported by UNDR.

File types that are not listed here can still be included, downloaded, decompressed, and checked with UNDR. However, they are listed as “other files” and UNDR does not attempt to parse or load them.

To add a new file format, create and implement a derived class of undr.path.File (see for instance ApsFile) and add it to file_from_dict() and Switch.

Overview#

Classes#

ApsFile

A file that contains luminance (grey levels) frames.

DvsFile

A file that contains DVS (polarity) events.

ImuFile

A file that contains IMU events.

Switch

Calls specialized file handlers while iterating a dataset.

Functions#

file_from_dict

Creates a file object from a dictionary, typically loaded from an index file.

Attributes#

SendMessage

Callback channel for messages generated by a file handler during data iteration.

Module Contents#

class undr.formats.ApsFile#

Bases: undr.path.File

A file that contains luminance (grey levels) frames.

Active-pixel sensors (APS) describe, strictly speaking, any sensor with pixels that use MOSFET amplifiers. However, the term is commonly used to refer to the integrating pixels found in non-CCD conventional cameras. In the context of Neuromorphic Engineering, APS is used to describe DAVIS frames.

height: int#

Frame height (y direction) in pixels.

width: int#

Frame width (x direction) in pixels.

packets() → Iterable[numpy.ndarray]#

Iterates over the file data.

This function streams the file from the remote server if it is not available locally, and decompresses the file in memory if it is locally available but compressed.

Returns:

Iterator over the file’s data converted into numpy arrays with dtype undr.raw.aps_dtype().

Return type:

Iterable[numpy.ndarray]

word_size() → int#

The size of an entry in this file, in bytes.

This can be used to ensure that entries (events, frames…) are not split while reading. A decoded file’s size in bytes must be a multiple of the value returned by this function.

Returns:

Number of bytes used by each entry.

Return type:

int

class undr.formats.DvsFile#

Bases: undr.path.File

A file that contains DVS (polarity) events.

Dynamic Vision Sensor events, often called polarity events, contain a timestamp, pixel coordinates, and a polarity (ON or OFF) that indicates whether luminance increased or decreased.

height: int#

Frame height (y direction) in pixels.

width: int#

Frame width (x direction) in pixels.

packets() → Iterable[numpy.ndarray]#

Iterates over the file data.

This function streams the file from the remote server if it is not available locally, and decompresses the file in memory if it is locally available but compressed.

Returns:

Iterator over the file’s data converted into numpy arrays with dtype undr.raw.DVS_DTYPE.

Return type:

Iterable[numpy.ndarray]

word_size()#

The size of an entry in this file, in bytes.

This can be used to ensure that entries (events, frames…) are not split while reading. A decoded file’s size in bytes must be a multiple of the value returned by this function.

Returns:

Number of bytes used by each entry.

Return type:

int

class undr.formats.ImuFile#

Bases: undr.path.File

A file that contains IMU events.

Inertial Measurement Unit (IMU) events are produced by an accelerometer / gyroscope / magnetometer.

packets() → Iterable[numpy.ndarray]#

Iterates over the file data.

This function streams the file from the remote server if it is not available locally, and decompresses the file in memory if it is locally available but compressed.

Returns:

Iterator over the file’s data converted into numpy arrays with dtype undr.raw.IMU_DTYPE.

Return type:

Iterable[numpy.ndarray]

word_size()#

The size of an entry in this file, in bytes.

This can be used to ensure that entries (events, frames…) are not split while reading. A decoded file’s size in bytes must be a multiple of the value returned by this function.

Returns:

Number of bytes used by each entry.

Return type:

int

undr.formats.SendMessage#

Callback channel for messages generated by a file handler during data iteration.

class undr.formats.Switch#

Calls specialized file handlers while iterating a dataset.

If a handler is None, the corresponding files are ignored by the iterator.

Parameters:
handle_aps: Callable[[ApsFile, SendMessage], None] | None#
handle_dvs: Callable[[DvsFile, SendMessage], None] | None#
handle_imu: Callable[[ImuFile, SendMessage], None] | None#
handle_other: Callable[[undr.path.File, SendMessage], None] | None#
enabled_types() → set[Any]#

Lists the file types that have a non-None handler.

Returns:

The set of file classes that will be handled.

Return type:

set[Any]

handle_file(file: undr.path.File, send_message: SendMessage)#

Calls the specialized file handler for the file, if the handler is non-None.

Parameters:

  • file (path.File) – The file to process.

  • send_message (SendMessage) – Callback channel for messages.

Raises:

RuntimeError – if the file type is not supported by this function.

undr.formats.file_from_dict(data: dict[str, Any], parent: undr.path_directory.Directory) → undr.path.File#

Creates a file object from a dictionary, typically loaded from an index file.

Parameters:

  • data (dict[str, Any]) – Dictionary describing the file and its properties.

  • parent (path_directory.Directory) – Parent directory of the file, used to generate the file system path.

Raises:

RuntimeError – if the file type is not supported by this function.

Returns:

A specialized file object.

Return type:

path.File