Crate eventcv_core 

eventcv-core

The Rust core of EventCV — “OpenCV for event-based vision”.

Everything is built around EventStream, a struct-of-arrays container of events (xs, ys, ts, ps columns plus sensor size and timestamp scale). Streams are constructed only through EventStreamBuilder, which drops out-of-bounds events.

The crate is organised into focused modules:

• io — readers/writers for .npz, .txt, .bag, .h5, .aedat, .dat, plus the io::load extension dispatcher and lazy io::SliceSource indexing for large files.
• representation — event → dense tensor (representation::Representation, e.g. voxel grids and time surfaces).
• transform — chainable event-domain geometry/temporal/polarity ops on streams.
• camera — intrinsics and undistort.
• features, flow, cluster — corner detection, optical flow, connected components.
• filter, image, viz — hot-pixel filtering, frame-domain resize, colormapped export.

The hdf5 feature (off by default to keep cargo test fast) enables the .h5/.hdf5 reader by building libhdf5 from source.

Modules

camera

Pinhole camera intrinsics with Brown–Conrady (radial + tangential) distortion — the model event-camera calibrations ship (e.g. EV-IMO calib.txt = fx fy cx cy k1 k2 p1 p2). Used by EventStream::undistort to rectify event coordinates.

cluster

Connected-component labelling on event frames — a simple clustering / segmentation step over a dense EventFrame (e.g. a count or binary image). A pixel is foreground when any of its channels is non-zero; a flood fill assigns each maximal 4- or 8-connected foreground blob a distinct label 1..=k, with background 0. Returns a single-channel u64 “labels” frame.

features

Event feature detection (OpenCV features2d analogue). Both detectors maintain a per-polarity Surface of Active Events (SAE — the latest timestamp seen at each pixel) and return a new EventStream holding only the events that sit on a moving corner, so detection chains like a denoising filter. Both assume events arrive in ascending time order (what the readers produce); call EventStream::sort_by_time first if a stream might be unordered.

filter

Denoising filters — drop noise events from the sparse EventStream (OpenCV imgproc/photo analogue). Each filter keeps (x, y, p, t) unchanged and only removes events, returning a new stream so calls chain. The polarity filter lives with the transforms (EventStream::filter_polarity).

flow

Optical flow (OpenCV video analogue). Lucas-Kanade on the time surface: the Surface of Active Events T(x, y) (the latest event time at each pixel, in milliseconds) is a local ramp whose gradient encodes edge velocity — an edge moving with pixel velocity v satisfies ∇T · v = 1. We fit one constant v per pixel over a window by least squares, exactly like image Lucas-Kanade, and return a two-channel (flow_x, flow_y) EventFrame in pixels per millisecond. Where the window holds only a single edge the structure tensor is rank-deficient (the aperture problem), so we fall back to normal flow along the gradient; genuinely flat, event-free windows stay zero. Flow is emitted only at pixels that saw an event. Assumes ascending time order.

image

io

representation

transform

Event-domain geometry and stream algebra — OpenCV-style transforms that operate on the sparse EventStream itself (not a dense frame), preserving per-event timestamps. Every op returns a new stream so calls chain. Coordinates are remapped and rounded — there is no pixel interpolation — and out-of-bounds events are dropped (downscale therefore lets several events share a pixel, which is lossless: representations handle the collisions).

viz

Frame → pixels rendering: the shared 2-D visualisation path used by PNG export and the interactive viewer’s image representations. Most EventFrames reduce to a per-pixel scalar field (signed for polarity/voxel/time-surface reprs, unsigned for count/binary), which a Colormap turns into RGB. Two kinds have their own RGB path: Tencode (already an RGB encoding) and Flow (Middlebury colour coding — direction → hue, speed → saturation).

Structs

Event

EventStream

A stream of events stored column-wise (struct-of-arrays). Columns compress and transform far better than interleaved rows, and timestamps use i64 (µs) so real multi-second recordings fit. See TASKS.md §3.

EventStreamBuilder

Builds an EventStream one event at a time, dropping events outside the sensor. The single construction path shared by readers and (future) transforms.