Skip to content

Adapters API

Each adapter module's public API (its __all__) is one function, open(), which returns a Reader. Other names visible in the modules with dir(), Reader included, are not part of the public API and may change; Reader is documented here because every open() returns one. See Adapters for how they behave. In the signatures, PathArg is str | os.PathLike[str]: a string or a pathlib.Path; Size is tuple[int, int], a (width, height) pair.

frames2py.adapters.evt.open 

open(path: PathArg, *, sensor_size: tuple[int, int] | None = None, batch_size: int | None = None) -> Reader

Open an EVT 2.0 or 3.0 RAW file for one pass over its CD events.

Parameters:

Name Type Description Default
path PathArg

The .raw file.

 required
sensor_size tuple[int, int] | None

(width, height); required if the header has no geometry.

 None
batch_size int | None

Events per yielded array (the last may have fewer), or None for the decoder's own boundaries.

 None

Raises:

Type Description
FileNotFoundError

path doesn't exist.
OSError

path is a directory or can't be read.
ValueError

the header is malformed, its version is not EVT 2.0 or 3.0, it has no geometry and no sensor_size was given, or sensor_size conflicts with it.

frames2py.adapters.aedat4.open 

open(path: PathArg, *, sensor_size: tuple[int, int] | None = None, batch_size: int | None = None) -> Reader

Open an AEDAT 4.0 file for one pass over its first event stream.

Parameters:

Name Type Description Default
path PathArg

The .aedat4 file.

 required
sensor_size tuple[int, int] | None

(width, height); required if the stream has no resolution.

 None
batch_size int | None

Events per yielded array (the last may have fewer), or None for the file's own packets.

 None

Raises:

Type Description
ImportError

dv-processing is not installed (frames2py[aedat4]).
FileNotFoundError

path doesn't exist.
OSError

path is a directory or can't be read.
ValueError

dv-processing can't read the file, it has no event stream, the stream has no resolution and no sensor_size was given, or sensor_size conflicts with it.

frames2py.adapters.hdf5.open 

open(path: PathArg, *, group: str, t_offset: int | str | None = None, sensor_size: tuple[int, int] | None = None, batch_size: int | None = None) -> Reader

Open an HDF5 file for one pass over the events in group.

Parameters:

Name Type Description Default
path PathArg

The HDF5 file.

 required
group str

Path of the group holding the t, x, y and p datasets.

 required
t_offset int | str | None

Microseconds added to every t: an int, or the path of a scalar integer dataset in the file. None adds nothing.

 None
sensor_size tuple[int, int] | None

(width, height), reported as reader.sensor_size.

 None
batch_size int | None

Events per yielded array (the last may have fewer), or None for steps of 1,048,576 events.

 None

Raises:

Type Description
ImportError

h5py or hdf5plugin is not installed (frames2py[hdf5]).
FileNotFoundError

path doesn't exist.
OSError

path is a directory or can't be read.
TypeError

group is not a str, or t_offset not an int, str or None.
ValueError

the file isn't HDF5, the group or its datasets don't follow the schema, the group declares a frames2py_format_version other than 1, the t_offset dataset isn't a scalar integer, or a dataset's mandatory filter isn't available.

Reader

Iterate once over a recording's events.

Iteration yields 1-D, C-contiguous EVENT_DTYPE arrays in source order. With batch_size=None each array follows the decoder's own boundaries; with batch_size=N every array has N events except the last. No array is empty.

Each array is new or a view of a new array; no two share memory, and none shares memory with the file or the backend.

A second iter() raises RuntimeError. Iterating a closed reader, or calling next() on its iterator after close(), raises ValueError.

sensor_size property 

sensor_size: Size | None

(width, height), from the source or the explicit sensor_size.

close 

close() -> None

Release the file or decoder. Closing twice is a no-op.