Quick Start¶
Get up and running with evlib in 5 minutes!
Basic Event Loading¶
import evlib
import polars as pl
# Load events from a text file (returns Polars LazyFrame)
events = evlib.load_events("data/slider_depth/events.txt")
df = events.collect() # Get DataFrame if needed
print(f"Loaded {len(df)} events")
# Access data columns
xs = df['x'].to_numpy()
ys = df['y'].to_numpy()
ts = df['t'].to_numpy()
ps = df['polarity'].to_numpy()
Event Filtering¶
The evlib.filtering module provides ready-made lazy filters. You can also write filters directly as Polars expressions; remember t is a Duration column.
import evlib
import evlib.filtering as evf
import polars as pl
events = evlib.load_events("data/slider_depth/events.txt")
# Time window filtering (t_start/t_end are in seconds)
filtered_events = evf.filter_by_time(events, t_start=0.0, t_end=1.0)
df = filtered_events.collect()
# Spatial bounds filtering
spatial_events = evf.filter_by_roi(events, x_min=100, x_max=500, y_min=100, y_max=300)
df = spatial_events.collect()
# Polarity filtering (slider_depth is text format, encoded 0/1: using 0 for negative here)
pos_events = evf.filter_by_polarity(events, polarity=1) # Positive events only
neg_events = evf.filter_by_polarity(events, polarity=0) # Negative events only
# Or write the same filters as Polars expressions directly:
expr_filtered = events.filter(
(pl.col('t').dt.total_microseconds() / 1_000_000).is_between(0.0, 1.0)
& pl.col('x').is_between(100, 500)
& (pl.col('polarity') == 1)
)
df = expr_filtered.collect()
Event Representations¶
import evlib
import evlib.representations as evr
events = evlib.load_events("data/slider_depth/events.txt")
# Voxel grid (Zhu et al. 2019 event volume)
voxel_df = evr.create_voxel_grid(events, height=480, width=640, n_time_bins=5)
print(f"Voxel grid entries: {len(voxel_df)}")
# Event frame (tonic to_frame semantics)
frame_df = evr.create_event_frame(events, height=480, width=640, n_time_bins=10)
print(f"Event frame entries: {len(frame_df)}")
# Stacked histogram (RVT-compatible)
hist_df = evr.create_stacked_histogram(
events, height=480, width=640, bins=10, window_duration_ms=50.0
)
print(f"Stacked histogram entries: {len(hist_df)}")
Event Visualization¶
import numpy as np
# Load events first
events = evlib.load_events("data/slider_depth/events.txt")
df = events.collect()
xs = df['x'].to_numpy()
ys = df['y'].to_numpy()
ts = df['t'].to_numpy()
ps = df['polarity'].to_numpy()
print(f"Loaded {len(df)} events for visualization")
print(f"Event data shape: x={xs.shape}, y={ys.shape}, t={ts.shape}, p={ps.shape}")
# Note: For actual plotting, install matplotlib and use:
# import matplotlib.pyplot as plt
# plt.scatter(xs[:10000], ys[:10000], c=ps[:10000], cmap='RdBu_r', s=0.1)
# plt.show()
Event Augmentation¶
import numpy as np
# Load events first
events = evlib.load_events("data/slider_depth/events.txt")
df = events.collect()
xs = df['x'].to_numpy()
ys = df['y'].to_numpy()
ps = df['polarity'].to_numpy()
# Spatial flip using numpy
xs_flipped = 640 - 1 - xs # Horizontal flip
ys_flipped = ys.copy()
ps_aug = ps.copy()
print(f"Original events: {len(xs)}")
print(f"Flipped coordinates: x_max={xs_flipped.max()}, x_min={xs_flipped.min()}")
# Note: For timestamp-based augmentation, handle the duration[μs] format properly
# or convert to numeric values first
Neural Network Models¶
E2VID and RVT models are available in Python via evlib.models (requires pip install evlib[torch]):
```python notest from evlib.models import E2VID, RVT
For RVT-compatible preprocessing, use `evlib.rvt.process_sequence(...)`, which offers four backends (`polars`, `rust`, `cuda`, `metal`).
## File Format Support
### Text Files
```python
# Standard format: t x y polarity
# 0.1 320 240 1
# 0.2 321 241 -1
events = evlib.load_events("data/slider_depth/events.txt")
df = events.collect()
xs, ys, ts, ps = df['x'].to_numpy(), df['y'].to_numpy(), df['t'].to_numpy(), df['polarity'].to_numpy()
HDF5 Files¶
import numpy as np
# Load events first
events = evlib.load_events("data/slider_depth/events.txt")
df = events.collect()
# Ensure correct dtypes for save function
xs = df['x'].to_numpy().astype(np.int64)
ys = df['y'].to_numpy().astype(np.int64)
ps = df['polarity'].to_numpy().astype(np.int64)
# Convert Duration timestamps to seconds (float64)
ts = df['t'].dt.total_seconds().to_numpy().astype(np.float64)
# Save events to HDF5 format
output_path = "quickstart_output.h5"
evlib.save_events_to_hdf5(xs, ys, ts, ps, output_path)
print(f"Successfully saved {len(xs)} events to HDF5 format")
# Note: For loading HDF5 files, use existing dataset files
# The save function uses internal type conversions for efficiency
# To continue working with the data, use the original DataFrame:
print(f"Working with {len(df)} events from original DataFrame")
Custom Column Mapping¶
# For files with different column order: x y polarity t
# Note: Column mapping not currently supported in this version
# Use standard format: t x y polarity
events = evlib.load_events("data/slider_depth/events.txt")
df = events.collect()
xs, ys, ts, ps = df['x'].to_numpy(), df['y'].to_numpy(), df['t'].to_numpy(), df['polarity'].to_numpy()
Performance Tips¶
When to Use evlib vs NumPy¶
SUCCESS: Use evlib for: - Large datasets (>100k events) - Complex event processing algorithms - Memory-efficient operations - Production event processing pipelines
SUCCESS: Use NumPy for: - Simple array operations - Small datasets (<10k events) - Rapid prototyping - Maximum single-operation speed
Example Performance Comparison¶
import time
import numpy as np
import evlib
# Large dataset example
events = evlib.load_events("data/slider_depth/events.txt") # 1M+ events
start = time.time()
df = events.collect()
load_time = time.time() - start
print(f"Data loading: {load_time:.3f}s for {len(df):,} events")
print(f"Loading rate: {len(df)/load_time:.0f} events/sec")
print(f"Event columns: {df.columns}")
Error Handling¶
import evlib
try:
events = evlib.load_events("nonexistent.txt")
except OSError as e:
print(f"File error: {e}")
# Example with valid file
try:
events = evlib.load_events("data/slider_depth/events.txt")
df = events.collect()
print(f"Successfully loaded {len(df)} events")
except OSError as e:
print(f"Error loading events: {e}")
File error: Failed to detect format: File not found: nonexistent.txt
Successfully loaded 1078541 events