Skip to content

Core API

The top level of frames2py exports the names below (its __all__). The kernel classes are also exported there; they are documented on the Kernels page. The other public modules are frames2py.kernels, frames2py.publish, frames2py.adapters.evt, frames2py.adapters.aedat4, frames2py.adapters.hdf5, frames2py.recorder, frames2py.viewer and frames2py.replay.

frames2py.Engine

Accumulates events from one producer and publishes snapshots for consumers.

ingest() does its work on the caller's thread and never waits for a consumer. Consumers call snapshot() whenever they like; snapshot() and stats take no lock. Publication happens only inside ingest() and stop(): there is no timer thread.

The first ingest() that doesn't raise makes its thread the producer for the Engine's lifetime, reset() included; ingest() from any other thread raises RuntimeError. start(), stop() and reset() may be called from any thread: they and ingest() take one lock, so each runs whole, never interleaved with another.

Raises RuntimeError on construction on a free-threaded build with the GIL disabled, unless that minor version has been verified (3.14).

Parameters:

Name Type Description Default
sensor_size tuple[int, int]

(width, height). Frames are (height, width[, channels]).

 required
kernel str | Kernel

A kernel instance, or "event_count", "polarity" or "time_surface".

 'event_count'
snapshot_interval_ms float

0 publishes on every ingest(). A positive interval publishes at most once per interval, on the first ingest() after it elapses. The first ingest() always publishes.

 16.0

stats property 

stats: EngineStats

Counters at the time of the call. Takes no lock.

ingest 

ingest(events: EventArray) -> None

Accumulate one call's events, then publish if the interval allows.

A no-op while stopped. Raises RuntimeError if called from a thread other than the producer's. Otherwise raises TypeError for a malformed array and ValueError if any event has t >= 2**63, in both cases before any state or statistic changes.

snapshot 

snapshot() -> Snapshot | None

The latest published snapshot, shared, not copied; or None before the first publication and after reset() until the next. Takes no lock.

start 

start() -> None

Resume ingestion after stop().

stop 

stop() -> None

Publish events accumulated since the last publication, if any, then make ingest() a no-op. The latest snapshot stays readable.

reset 

reset() -> None

Clear the kernel state, counters, watermark and published snapshot.

The snapshot sequence, uptime_ns and the producer thread carry on. The next ingest() publishes, as the first one does.

frames2py.Accumulator

Accumulates events through one kernel.

Synchronous and single-threaded: each call does its work on the caller's thread and returns. There is no publication; read() returns the current representation.

Parameters:

Name Type Description Default
sensor_size tuple[int, int]

(width, height). Frames are (height, width[, channels]).

 required
kernel str | Kernel

A kernel instance, or "event_count", "polarity" or "time_surface".

 required

watermark property 

watermark: int | None

The largest timestamp among accumulated in-bounds events, or None.

events_out_of_bounds property 

events_out_of_bounds: int

Events skipped by the bounds check since construction or reset().

accumulate 

accumulate(events: EventArray) -> None

Accumulate one call's events.

Raises TypeError for a malformed array and ValueError if any event has t >= 2**63, in both cases before anything changes. Out-of-bounds events are counted and otherwise ignored.

read 

read() -> NDArray[Any]

A copy of the current representation. Doesn't change any state.

reset 

reset() -> None

Clear the kernel state, the watermark and the out-of-bounds count.

frames2py.EVENT_DTYPE module-attribute 

EVENT_DTYPE: Final = np.dtype([('t', '<u8'), ('x', '<u2'), ('y', '<u2'), ('p', 'u1')])

One event: t µs, x column, y row, p polarity (0 is OFF, anything else ON). 13 bytes, little-endian, no padding.

frames2py.EngineStats dataclass

A frozen diagnostic view of an Engine's counters.

The fields are read one after another, not as one instant-consistent snapshot.

Attributes:

Name Type Description
events_ingested int

Events in accepted ingest() calls, out-of-bounds ones included.
events_out_of_bounds int

The subset of those rejected by the bounds check.
snapshots_published int

Publications since construction or the last reset().
uptime_ns int

Nanoseconds since the Engine was constructed. reset() doesn't change it.

frames2py.SnapshotMeta dataclass

Metadata published with each snapshot.

Attributes:

Name Type Description
watermark int | None

The largest timestamp among accumulated in-bounds events at publication, or None if none have been accumulated since construction or the last reset().
sequence int

Publication number. It increases with every publication for the Engine's lifetime, across reset().