evlib.datasets¶

Dataset base classes for event camera datasets.

class evlib.datasets.BlockAccessDataset¶

Map style dataset supporting random access by frame index.

PyTorch compatible contract: __getitem__ returns a sample dict for a given frame index, __len__ returns the frame count.

For low level event I/O (load_events, time_to_index, etc.), use the underlying class DataLoaderBase directly via the concrete dataset’s .loader property.

abstractmethod close()¶

Release resources (file handles, etc.).

Return type:: None

class evlib.datasets.EventDataset¶

ABC for any event data source.

Only resource management, no root/sequence attributes, since not all sources have them.

abstractmethod close()¶

Release resources (file handles, etc.).

Return type:: None

class evlib.datasets.IteratorAccessDataset¶

Iterable style dataset for streaming/online sources.

Subclasses must implement __iter__ and __next__, each yielding a dict with at least an ‘events’ key.

abstractmethod __next__()¶

Return the next sample dict, or raise class StopIteration.

Return type:: dict

reset()¶

Reset iteration to the beginning

The default implementation raises class NotImplementedError subclasses that support rewinding should override this.

Return type:: None

abstractmethod close()¶

Release resources (file handles, etc.).

Return type:: None

evlib.datasets.event_sample_collate(batch)¶

Collate event dataset samples.

Stacks "timestamp" and keeps other fields as Python lists. Preserves variable length events and None values.

Parameters:: batch (List[Dict[str, Any]])
Return type:: Dict[str, Any]

class evlib.datasets.MVSECDataset(root, sequence, camera='left', load_gt_flow=False, load_calibration=False, load_imu=False, load_odometry_npz=False, load_gt_odometry=False, load_gt_poses=False, load_gt_depth_raw=False, load_gt_depth_rect=False, load_gt_flow_hdf5=False, load_gt_blended=False, load_velodyne=False, event_load_mode='cached', image_load_mode='cached', cache_dir=None)¶

MVSEC dataset (block access / map style).

Thin wrapper around class MVSECDataLoader that adds a frame indexed __getitem__ / __len__ contract suitable for PyTorch DataLoader integration.

For custom access patterns (overlapping windows, multi-scale pyramids, arbitrary time slicing), use the attr loader directly

ds = MVSECDataset(root, “indoor_flying1”) loader = ds.loader events = loader.load_events(0, 10000) events = loader.get_events_by_time(t_start, t_end)

Or instantiate class MVSECDataLoader standalone, no Dataset needed.

Parameters:

root (str) – Directory containing the MVSEC files.
sequence (str) – Sequence name, e.g. “indoor_flying1”.
camera (str) – “left” or “right”.
load_gt_flow (LoadMode) – LoadMode for ground truth optical flow.
load_calibration (bool) – If True, load calibration maps.
load_imu (bool) – If True, cache IMU data.
load_odometry_npz (bool) – If True, cache odometry from NPZ.
load_gt_odometry (bool) – If True, cache LOAM odometry from gt HDF5.
load_gt_poses (bool) – If True, cache Cartographer poses from gt HDF5.
load_gt_depth_raw (LoadMode) – LoadMode for raw depth maps from gt HDF5.
load_gt_depth_rect (LoadMode) – LoadMode for rectified depth maps from gt HDF5.
load_gt_flow_hdf5 (LoadMode) – LoadMode for optical flow from gt HDF5.
load_gt_blended (LoadMode) – LoadMode for blended images from gt HDF5.
load_velodyne (LoadMode) – LoadMode for velodyne lidar from data HDF5.
event_load_mode (ResidentLoadMode) – "cached" or "lazy" for events.
image_load_mode (ResidentLoadMode) – "cached" or "lazy" for images.
cache_dir (Optional[str]) – Optional root directory for MVSEC sidecar caches.

IMAGE_SHAPE: Tuple[int, int] = (260, 346)¶

property loader: MVSECDataLoader¶: Underlying MVSECDataLoader.

property root: str¶

property sequence: str¶

property camera: str¶

close()¶

Release resources (file handles, etc.).

Return type:: None

load_events(start_index, end_index)¶

Load events in [start_index, end_index).

Parameters:

start_index (int)
end_index (int)

Return type:

RawEvents

property num_events: int¶: Total number of events.

time_to_index(t)¶

Find the last event strictly before time t.

Parameters:: t (float)
Return type:: int

index_to_time(index)¶

Return the timestamp of the event at index.

Parameters:: index (int)
Return type:: float

times_to_indices(timestamps)¶

Vectorized form of time_to_index().

Parameters:: timestamps (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])
Return type:: ndarray[Any, dtype[int64]]

indices_to_times(indices)¶

Vectorized form of index_to_time().

Parameters:: indices (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])
Return type:: ndarray[Any, dtype[float64]]

get_events_by_time(t_start, t_end)¶

Load events in [t_start, t_end).

Parameters:

t_start (float)
t_end (float)

Return type:

RawEvents

iter_events(num_events=None, time_window=None)¶

Yield RawEvents chunks.

Parameters:

num_events (int | None)
time_window (float | None)

Return type:

Iterator[RawEvents]

property has_gt_flow: bool¶: Whether ground truth optical flow is available.

load_optical_flow(t1, t2)¶

Load ground truth optical flow between two timestamps.

Parameters:

t1 (float)
t2 (float)

Return type:

ndarray[Any, dtype[float32]]

get_gt_timestamps(event_index)¶

Return the floor and ceil GT timestamps bracketing event_index.

Parameters:: event_index (int)
Return type:: Tuple[float | None, float | None]

gt_time_list()¶

Return all GT timestamps.

Return type:: ndarray[Any, dtype[float64]]

property frame_timestamps: ndarray[Any, dtype[float64]] | None¶: Grayscale frame timestamps from HDF5, or None if unavailable.

property frame_event_indices: ndarray[Any, dtype[int64]] | None¶: Event indices aligned to grayscale frames, or None if unavailable.

property event_load_mode: LoadingType¶: Configured event loading mode.

property image_load_mode: LoadingType¶: Configured image loading mode.

property has_images: bool¶: Whether grayscale images are available.

load_image(frame_index)¶

Load a single grayscale frame by index.

Parameters:: frame_index (int)
Return type:: ndarray[Any, dtype[uint8]] | None

property images: ndarray[Any, dtype[uint8]] | None¶: Cached grayscale image stack, or None if lazy/unavailable.

property num_frames: int¶: Number of grayscale frames.

find_nearest_frame_index(t)¶

Find the nearest grayscale frame to time t.

Parameters:: t (float)
Return type:: int

property has_calibration: bool¶: Whether calibration maps are available.

undistort_events(events)¶

Apply calibration rectification maps to events.

Parameters:: events (RawEvents)
Return type:: RawEvents

property has_imu: bool¶: Whether IMU data is available.

property imu_timestamps: ndarray[Any, dtype[float64]] | None¶: IMU timestamps, or None.

property imu_data: ndarray[Any, dtype[float64]] | None¶: Full IMU array (N, 6), or None.

load_imu(t_start, t_end)¶

Return IMU readings and timestamps in [t_start, t_end).

Parameters:

t_start (float)
t_end (float)

Return type:

Tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]] | None

property has_odometry_npz: bool¶: Whether odometry NPZ data is available.

property odometry_npz: MVSECOdometryData | None¶: MVSEC odometry data from NPZ, or None.

property has_gt_odometry: bool¶: Whether GT odometry (LOAM) is available.

property gt_odometry: ndarray[Any, dtype[float64]] | None¶: LOAM odometry SE(3) poses (N, 4, 4), or None.

property gt_odometry_timestamps: ndarray[Any, dtype[float64]] | None¶: LOAM odometry timestamps, or None.

property has_gt_pose: bool¶: Whether GT pose (Cartographer) is available.

property gt_pose: ndarray[Any, dtype[float64]] | None¶: Cartographer SE(3) poses (N, 4, 4), or None.

property gt_pose_timestamps: ndarray[Any, dtype[float64]] | None¶: Cartographer pose timestamps, or None.

load_nearest_pose(t, source='pose')¶

Return the nearest SE(3) pose (4, 4) to time t.

Parameters:

t (float)
source (str)

Return type:

ndarray[Any, dtype[float64]] | None

property has_gt_depth: bool¶: Whether GT depth maps are available.

property has_gt_depth_raw: bool¶: Whether raw GT depth maps are available.

property has_gt_depth_rect: bool¶: Whether rectified GT depth maps are available.

property gt_depth_raw_timestamps: ndarray[Any, dtype[float64]] | None¶: Raw depth timestamps, or None.

property gt_depth_timestamps: ndarray[Any, dtype[float64]] | None¶: Alias for raw depth timestamps.

property gt_depth_rect_timestamps: ndarray[Any, dtype[float64]] | None¶: Rectified depth timestamps, or None.

property depth_raw_images: ndarray[Any, dtype[float32]] | None¶: Cached raw depth image stack, or None if lazy/unavailable.

property num_gt_depth_raw_frames: int¶: Number of raw GT depth frames.

property num_gt_depth_rect_frames: int¶: Number of rectified GT depth frames.

property num_gt_depth_frames: int¶: Number of GT depth frames from the available depth source.

property depth_rect_images: ndarray[Any, dtype[float32]] | None¶: Cached rectified depth image stack, or None if lazy/unavailable.

load_depth(frame_index, rectified=False)¶

Load a single depth frame.

Parameters:

frame_index (int)
rectified (bool)

Return type:

ndarray[Any, dtype[float32]] | None

load_depth_raw(frame_index)¶

Load a single raw depth frame.

Parameters:: frame_index (int)
Return type:: ndarray[Any, dtype[float32]] | None

load_depth_rect(frame_index)¶

Load a single rectified depth frame.

Parameters:: frame_index (int)
Return type:: ndarray[Any, dtype[float32]] | None

property has_gt_blended: bool¶: Whether GT blended images are available.

property gt_blended_timestamps: ndarray[Any, dtype[float64]] | None¶: Blended image timestamps, or None.

property blended_images: ndarray[Any, dtype[uint8]] | None¶: Cached blended image stack, or None if lazy/unavailable.

load_blended_image(frame_index)¶

Load a single blended image.

Parameters:: frame_index (int)
Return type:: ndarray[Any, dtype[uint8]] | None

property has_gt_flow_hdf5: bool¶: Whether GT flow from HDF5 is available.

property flow_hdf5_frames: ndarray[Any, dtype[float64]] | None¶: Cached GT HDF5 flow stack, or None if lazy/unavailable.

property gt_flow_hdf5_timestamps: ndarray[Any, dtype[float64]] | None¶: GT HDF5 flow timestamps, or None.

load_flow_hdf5(frame_index)¶

Load a single flow field from gt HDF5.

Parameters:: frame_index (int)
Return type:: ndarray[Any, dtype[float64]] | None

property has_velodyne: bool¶: Whether velodyne lidar data is available.

property velodyne_timestamps: ndarray[Any, dtype[float64]] | None¶: Velodyne scan timestamps, or None.

property velodyne_scans: ndarray[Any, dtype[float32]] | None¶: Cached velodyne scan stack, or None if lazy/unavailable.

property num_velodyne_scans: int¶: Number of velodyne scans.

load_velodyne_scan(scan_index)¶

Load a single velodyne scan.

Parameters:: scan_index (int)
Return type:: ndarray[Any, dtype[float32]] | None

class evlib.datasets.MVSECIterator(root, sequence, **kwargs)¶

Streaming iterator over MVSEC frames.

Yields the same dicts as MVSECDataset.__getitem__(), frame by frame.

Parameters:

root (str) – Directory containing the MVSEC files.
sequence (str) – Sequence name.
**kwargs (Any) – Forwarded to class MVSECDataset.

property root: str¶

property sequence: str¶

property camera: str¶

__next__()¶

Return the next sample dict, or raise class StopIteration.

Return type:: dict

reset()¶

Reset iteration cursor to the beginning.

Return type:: None

close()¶

Release resources (file handles, etc.).

Return type:: None

evlib.datasets.mvsec_collate_fn(batch)¶

Collate event dataset samples.

Stacks "timestamp" and keeps other fields as Python lists. Preserves variable length events and None values.

Parameters:: batch (List[Dict[str, Any]])
Return type:: Dict[str, Any]

Modules

mvsec

MVSEC dataset loader.