evlab 0.1.0a1__py3-none-any.whl

evlab/__init__.py

@@ -0,0 +1,6 @@
+"""evlab: inspect, clean, convert, and benchmark event-camera data."""
+
+from .formats import EventData, from_arrays, load, save
+
+__version__ = "0.1.0a1"
+__all__ = ["EventData", "from_arrays", "load", "save", "__version__"]

evlab/cli.py

@@ -0,0 +1,204 @@
+"""evlab command line interface."""
+
+from __future__ import annotations
+
+import json
+
+import click
+import numpy as np
+
+from . import formats, metrics
+from .filters import FILTERS
+from .representations import voxel_grid
+from .synth import GENERATORS
+
+
+@click.group()
+@click.version_option(package_name="evlab")
+def main():
+    """Inspect, clean, convert, and benchmark event-camera data."""
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+def info(path, as_json):
+    """Summarize an event file (count, resolution, duration, rate)."""
+    data = formats.load(path)
+    stats = metrics.summary(data)
+    if as_json:
+        click.echo(json.dumps(stats, indent=2))
+        return
+    click.echo(f"{path}")
+    click.echo(f"  events      : {stats['num_events']:,}")
+    click.echo(f"  resolution  : {stats['width']} x {stats['height']}")
+    click.echo(f"  duration    : {stats['duration_s']:.3f} s")
+    click.echo(f"  event rate  : {stats['event_rate_hz']:,.0f} ev/s")
+    if stats["num_events"]:
+        click.echo(f"  polarity ON : {stats['polarity_balance']:.1%}")
+        click.echo(
+            f"  active px   : {stats['active_pixels']:,}"
+            f" ({stats['active_pixel_fraction']:.1%} of sensor)"
+        )
+
+
+@main.command()
+@click.argument("src", type=click.Path(exists=True, dir_okay=False))
+@click.argument("dst", type=click.Path(dir_okay=False))
+def convert(src, dst):
+    """Convert between event file formats (npz, csv, txt, aedat4-in)."""
+    data = formats.load(src)
+    formats.save(data, dst)
+    click.echo(f"wrote {len(data.events):,} events -> {dst}")
+
+
+@main.command()
+@click.argument("src", type=click.Path(exists=True, dir_okay=False))
+@click.argument("dst", type=click.Path(dir_okay=False))
+@click.option(
+    "--filter",
+    "filter_name",
+    type=click.Choice(sorted(FILTERS)),
+    default="baf",
+    show_default=True,
+    help="Denoising filter to apply.",
+)
+@click.option(
+    "--window",
+    type=int,
+    default=5000,
+    show_default=True,
+    help="Time window in microseconds (baf) / refractory period (refractory).",
+)
+def denoise(src, dst, filter_name, window):
+    """Denoise an event stream and write the result."""
+    data = formats.load(src)
+    if filter_name == "baf":
+        out = FILTERS[filter_name](data, time_window_us=window)
+    else:
+        out = FILTERS[filter_name](data, refractory_us=window)
+    formats.save(out, dst)
+    kept = metrics.retention(data, out)
+    click.echo(f"kept {len(out.events):,}/{len(data.events):,} events ({kept:.1%}) -> {dst}")
+
+
+@main.command()
+@click.argument("src", type=click.Path(exists=True, dir_okay=False))
+@click.argument("dst", type=click.Path(dir_okay=False))
+@click.option("--bins", type=int, default=10, show_default=True, help="Temporal bins.")
+def voxel(src, dst, bins):
+    """Build a (bins, H, W) voxel grid and save it as .npy."""
+    data = formats.load(src)
+    grid = voxel_grid(data, bins=bins)
+    np.save(dst, grid)
+    click.echo(f"voxel grid {grid.shape} (sum={grid.sum():+.1f}) -> {dst}")
+
+
+@main.command()
+@click.argument("src", type=click.Path(exists=True, dir_okay=False))
+@click.argument("dst", type=click.Path(dir_okay=False))
+@click.option(
+    "--mode",
+    type=click.Choice(["accumulate", "time-surface", "gif"]),
+    default="accumulate",
+    show_default=True,
+)
+@click.option(
+    "--window", type=float, default=33.0, show_default=True, help="Frame window in ms (gif mode)."
+)
+@click.option(
+    "--tau", type=float, default=30.0, show_default=True, help="Time-surface decay in ms."
+)
+def visualize(src, dst, mode, window, tau):
+    """Render events to a PNG (accumulate/time-surface) or GIF."""
+    from . import viz
+
+    data = formats.load(src)
+    if mode == "gif":
+        n = viz.render_gif(data, dst, window_ms=window)
+        click.echo(f"wrote {n} frames -> {dst}")
+    else:
+        viz.render_frame(data, mode, dst, tau_us=tau * 1000)
+        click.echo(f"wrote {mode} image -> {dst}")
+
+
+@main.command()
+@click.argument("dst", type=click.Path(dir_okay=False))
+@click.option(
+    "--pattern", type=click.Choice(sorted(GENERATORS)), default="moving-bar", show_default=True
+)
+@click.option("--resolution", default="240x240", show_default=True, help="WIDTHxHEIGHT.")
+@click.option("--duration", type=float, default=1.0, show_default=True, help="Seconds.")
+@click.option("--signal-rate", type=float, default=20000, show_default=True, help="Signal ev/s.")
+@click.option("--noise-rate", type=float, default=5000, show_default=True, help="Noise ev/s.")
+@click.option("--seed", type=int, default=0, show_default=True)
+def synth(dst, pattern, resolution, duration, signal_rate, noise_rate, seed):
+    """Generate a synthetic stream with ground-truth signal/noise labels."""
+    width, _, height = resolution.partition("x")
+    data = GENERATORS[pattern](
+        width=int(width),
+        height=int(height),
+        duration_us=int(duration * 1e6),
+        signal_rate_hz=signal_rate,
+        noise_rate_hz=noise_rate,
+        seed=seed,
+    )
+    formats.save(data, dst)
+    n_sig = int(data.meta["signal"].sum())
+    click.echo(f"wrote {len(data.events):,} events ({n_sig:,} signal) -> {dst}")
+
+
+@main.command("denoise-bench")
+@click.argument("src", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--filter", "filter_name", type=click.Choice(sorted(FILTERS)), default="baf", show_default=True
+)
+@click.option(
+    "--window",
+    type=int,
+    default=5000,
+    show_default=True,
+    help="Time window (baf) / refractory period, microseconds.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+def denoise_bench(src, filter_name, window, as_json):
+    """Score a denoising filter against a labeled stream (see `evlab synth`)."""
+    from .filters import MASKS
+
+    data = formats.load(src)
+    if filter_name == "baf":
+        mask = MASKS[filter_name](data, time_window_us=window)
+    else:
+        mask = MASKS[filter_name](data, refractory_us=window)
+    score = metrics.denoise_score(data, mask)
+    if as_json:
+        click.echo(json.dumps(score, indent=2))
+        return
+    click.echo(f"{filter_name} (window={window} us) on {src}")
+    click.echo(f"  precision     : {score['precision']:.1%}")
+    click.echo(f"  recall        : {score['recall']:.1%}")
+    click.echo(f"  f1            : {score['f1']:.3f}")
+    click.echo(f"  noise removed : {score['noise_removed']:.1%}")
+
+
+@main.command()
+@click.argument("reference", type=click.Path(exists=True, dir_okay=False))
+@click.argument("other", type=click.Path(exists=True, dir_okay=False))
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+def benchmark(reference, other, as_json):
+    """Compare two event streams (e.g. raw vs. denoised)."""
+    ref = formats.load(reference)
+    oth = formats.load(other)
+    result = metrics.compare(ref, oth)
+    if as_json:
+        click.echo(json.dumps(result, indent=2))
+        return
+    click.echo(f"retention        : {result['retention']:.1%}")
+    click.echo(f"event rate (ref) : {result['event_rate_ref_hz']:,.0f} ev/s")
+    click.echo(f"event rate (new) : {result['event_rate_other_hz']:,.0f} ev/s")
+    click.echo(f"structure (ref)  : {result['structure_ref']:.3f}")
+    click.echo(f"structure (new)  : {result['structure_other']:.3f}")
+
+
+if __name__ == "__main__":
+    main()

evlab/filters.py

@@ -0,0 +1,109 @@
+"""Event stream denoising filters.
+
+Each filter has a mask function (returns the boolean keep-mask, used by
+`evlab denoise-bench` to score against ground truth) and a public wrapper
+that applies it. Returned EventData shares no mutable state with the input;
+per-event metadata (like the ``signal`` labels) is subset alongside events.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .formats import EventData
+
+# Sentinel for "never fired": far in the past, but small enough that
+# `t - sentinel` cannot overflow int64 for microsecond timestamps.
+_NEVER = np.int64(np.iinfo(np.int64).min // 4)
+
+
+def _apply_mask(data: EventData, keep: np.ndarray) -> EventData:
+    meta = {}
+    for key, value in data.meta.items():
+        arr = np.asarray(value) if not np.isscalar(value) else None
+        if arr is not None and arr.shape[:1] == (len(data.events),):
+            meta[key] = arr[keep].copy()
+        else:
+            meta[key] = value
+    return EventData(data.events[keep].copy(), data.width, data.height, meta)
+
+
+def background_activity_mask(
+    data: EventData, time_window_us: int = 5000, neighborhood: int = 1
+) -> np.ndarray:
+    """Keep-mask for the nearest-neighbor / background-activity filter.
+
+    An event survives if at least one other event occurred within
+    ``time_window_us`` in its ``(2*neighborhood+1)^2 - 1`` spatial
+    neighborhood. This is the classic background-activity filter used by
+    DVS pipelines.
+    """
+    ev = data.events
+    keep = np.zeros(len(ev), dtype=bool)
+    if len(ev) == 0:
+        return keep
+
+    # last_seen[y, x] = timestamp of the most recent event at that pixel
+    last_seen = np.full(
+        (data.height + 2 * neighborhood, data.width + 2 * neighborhood), _NEVER, dtype=np.int64
+    )
+
+    xs = ev["x"].astype(np.int64) + neighborhood
+    ys = ev["y"].astype(np.int64) + neighborhood
+    ts = ev["t"]
+
+    n = neighborhood
+    for i in range(len(ev)):
+        x, y, t = xs[i], ys[i], ts[i]
+        window = last_seen[y - n : y + n + 1, x - n : x + n + 1]
+        # Exclude the center pixel: a pixel refiring alone is still noise.
+        center = window[n, n]
+        window[n, n] = _NEVER
+        keep[i] = bool((t - window <= time_window_us).any())
+        window[n, n] = center
+        last_seen[y, x] = t
+    return keep
+
+
+def background_activity_filter(
+    data: EventData, time_window_us: int = 5000, neighborhood: int = 1
+) -> EventData:
+    """Apply the background-activity filter (see `background_activity_mask`)."""
+    return _apply_mask(data, background_activity_mask(data, time_window_us, neighborhood))
+
+
+def refractory_mask(data: EventData, refractory_us: int = 1000) -> np.ndarray:
+    """Keep-mask dropping events within ``refractory_us`` of the previous
+    event at the same pixel (hot-pixel / oscillation suppression)."""
+    ev = data.events
+    keep = np.zeros(len(ev), dtype=bool)
+    if len(ev) == 0:
+        return keep
+
+    last_seen = np.full((data.height, data.width), _NEVER, dtype=np.int64)
+    xs = ev["x"].astype(np.intp)
+    ys = ev["y"].astype(np.intp)
+    ts = ev["t"]
+
+    for i in range(len(ev)):
+        x, y, t = xs[i], ys[i], ts[i]
+        keep[i] = (t - last_seen[y, x]) > refractory_us
+        if keep[i]:
+            last_seen[y, x] = t
+    return keep
+
+
+def refractory_filter(data: EventData, refractory_us: int = 1000) -> EventData:
+    """Apply the refractory filter (see `refractory_mask`)."""
+    return _apply_mask(data, refractory_mask(data, refractory_us))
+
+
+FILTERS = {
+    "baf": background_activity_filter,
+    "refractory": refractory_filter,
+}
+
+MASKS = {
+    "baf": background_activity_mask,
+    "refractory": refractory_mask,
+}

evlab/formats.py

@@ -0,0 +1,315 @@
+"""Canonical event representation and file format loaders/savers.
+
+The canonical in-memory representation is a numpy structured array with
+fields ``x`` (uint16), ``y`` (uint16), ``t`` (int64, microseconds), and
+``p`` (int8, polarity 0/1), sorted by ``t``, plus a metadata dict carrying
+at least ``width`` and ``height``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+import numpy as np
+
+EVENT_DTYPE = np.dtype([("x", "u2"), ("y", "u2"), ("t", "i8"), ("p", "i1")])
+
+
+@dataclass
+class EventData:
+    """Events plus sensor metadata."""
+
+    events: np.ndarray
+    width: int
+    height: int
+    meta: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.events.dtype != EVENT_DTYPE:
+            raise ValueError(f"events must have dtype {EVENT_DTYPE}, got {self.events.dtype}")
+
+    @property
+    def duration_us(self) -> int:
+        if len(self.events) == 0:
+            return 0
+        return int(self.events["t"][-1] - self.events["t"][0])
+
+    @property
+    def event_rate(self) -> float:
+        """Mean events per second over the recording."""
+        dur = self.duration_us
+        if dur == 0:
+            return 0.0
+        return len(self.events) / (dur / 1e6)
+
+
+def from_arrays(x, y, t, p, width: int | None = None, height: int | None = None) -> EventData:
+    """Build EventData from separate coordinate arrays (any numeric dtype)."""
+    x = np.asarray(x)
+    y = np.asarray(y)
+    t = np.asarray(t)
+    p = np.asarray(p)
+    if not (len(x) == len(y) == len(t) == len(p)):
+        raise ValueError("x, y, t, p must have equal lengths")
+
+    events = np.empty(len(x), dtype=EVENT_DTYPE)
+    events["x"] = x
+    events["y"] = y
+    events["t"] = t
+    # Normalize polarity: accept {0,1}, {-1,1}, or booleans.
+    p = p.astype(np.int8)
+    p[p < 0] = 0
+    events["p"] = p
+
+    order = np.argsort(events["t"], kind="stable")
+    events = events[order]
+
+    if width is None:
+        width = int(events["x"].max()) + 1 if len(events) else 0
+    if height is None:
+        height = int(events["y"].max()) + 1 if len(events) else 0
+    return EventData(events, width=width, height=height)
+
+
+# ---------------------------------------------------------------------------
+# npz
+# ---------------------------------------------------------------------------
+
+_NPZ_KEY_CANDIDATES = {
+    "x": ["x", "xs"],
+    "y": ["y", "ys"],
+    "t": ["t", "ts", "timestamp", "timestamps", "time"],
+    "p": ["p", "ps", "pol", "polarity", "polarities"],
+}
+
+
+def _resolve_npz_keys(available: set[str]) -> dict[str, str]:
+    resolved = {}
+    for canon, candidates in _NPZ_KEY_CANDIDATES.items():
+        for cand in candidates:
+            if cand in available:
+                resolved[canon] = cand
+                break
+        else:
+            raise KeyError(
+                f"could not find a key for '{canon}' in npz file "
+                f"(available: {sorted(available)}; accepted: {candidates})"
+            )
+    return resolved
+
+
+def load_npz(path: str) -> EventData:
+    with np.load(path) as data:
+        available = set(data.files)
+        if "events" in available and data["events"].dtype.names:
+            ev = data["events"]
+            width = int(data["width"]) if "width" in available else None
+            height = int(data["height"]) if "height" in available else None
+            out = from_arrays(ev["x"], ev["y"], ev["t"], ev["p"], width, height)
+        else:
+            keys = _resolve_npz_keys(available)
+            width = int(data["width"]) if "width" in available else None
+            height = int(data["height"]) if "height" in available else None
+            out = from_arrays(
+                data[keys["x"]], data[keys["y"]], data[keys["t"]], data[keys["p"]], width, height
+            )
+        # Ground-truth signal/noise labels (written by `evlab synth`). The
+        # events were saved t-sorted and from_arrays' stable sort is the
+        # identity on sorted input, so the mask stays aligned.
+        if "signal" in available:
+            out.meta["signal"] = data["signal"].astype(bool)
+        return out
+
+
+def save_npz(data: EventData, path: str) -> None:
+    extra = {}
+    if "signal" in data.meta:
+        extra["signal"] = np.asarray(data.meta["signal"], dtype=bool)
+    np.savez_compressed(
+        path, events=data.events, width=np.int64(data.width), height=np.int64(data.height), **extra
+    )
+
+
+# ---------------------------------------------------------------------------
+# csv / txt  (columns: t x y p, header optional, delimiter auto)
+# ---------------------------------------------------------------------------
+
+
+def load_csv(path: str, order: str = "txyp") -> EventData:
+    if sorted(order) != sorted("txyp"):
+        raise ValueError(f"order must be a permutation of 'txyp', got '{order}'")
+    arr = np.loadtxt(path, delimiter=None if path.endswith(".txt") else ",", ndmin=2)
+    if arr.shape[1] < 4:
+        raise ValueError(f"expected at least 4 columns (t x y p), got {arr.shape[1]}")
+    cols = {ch: arr[:, i] for i, ch in enumerate(order)}
+    return from_arrays(cols["x"], cols["y"], cols["t"], cols["p"])
+
+
+def save_csv(data: EventData, path: str) -> None:
+    ev = data.events
+    out = np.column_stack([ev["t"], ev["x"], ev["y"], ev["p"]])
+    np.savetxt(path, out, fmt="%d", delimiter="," if path.endswith(".csv") else " ")
+
+
+# ---------------------------------------------------------------------------
+# aedat4 (optional dependency)
+# ---------------------------------------------------------------------------
+
+
+def load_aedat4(path: str) -> EventData:
+    try:
+        import aedat  # type: ignore
+    except ImportError as e:
+        raise ImportError(
+            "reading .aedat4 requires the 'aedat' package: pip install evlab[aedat]"
+        ) from e
+
+    xs, ys, ts, ps = [], [], [], []
+    width = height = None
+    decoder = aedat.Decoder(path)
+    for packet in decoder:
+        if "events" in packet:
+            ev = packet["events"]
+            xs.append(ev["x"])
+            ys.append(ev["y"])
+            ts.append(ev["t"])
+            ps.append(ev["on"])
+    if not xs:
+        raise ValueError(f"no event packets found in {path}")
+    return from_arrays(
+        np.concatenate(xs),
+        np.concatenate(ys),
+        np.concatenate(ts),
+        np.concatenate(ps),
+        width,
+        height,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Prophesee legacy .dat (2D CD events)
+# ---------------------------------------------------------------------------
+
+
+def load_dat(path: str) -> EventData:
+    """Read a Prophesee legacy ``.dat`` file (2D CD events).
+
+    Layout: ASCII header lines starting with ``%``, then one byte event
+    type + one byte event size, then 8-byte records of little-endian
+    ``(uint32 t_us, uint32 addr)`` with ``x = addr & 0x3FFF``,
+    ``y = (addr >> 14) & 0x3FFF``, ``p = (addr >> 28) & 1``. The uint32
+    timestamp wraps every ~71 minutes; wraps are unwrapped monotonically.
+    """
+    width = height = None
+    with open(path, "rb") as f:
+        while True:
+            pos = f.tell()
+            line = f.readline()
+            if not line.startswith(b"%"):
+                f.seek(pos)
+                break
+            text = line[1:].strip().decode("ascii", errors="replace")
+            if text.lower().startswith("width"):
+                width = int(text.split()[-1])
+            elif text.lower().startswith("height"):
+                height = int(text.split()[-1])
+        header = f.read(2)
+        if len(header) < 2:
+            raise ValueError(f"truncated .dat file: {path}")
+        ev_size = header[1]
+        if ev_size != 8:
+            raise ValueError(f"unsupported .dat event size {ev_size} (expected 8): {path}")
+        raw = np.frombuffer(f.read(), dtype=np.dtype([("t", "<u4"), ("addr", "<u4")]))
+
+    t = raw["t"].astype(np.int64)
+    # Unwrap uint32 timestamp overflows.
+    wraps = np.cumsum(np.diff(t, prepend=t[:1]) < 0)
+    t += wraps * (np.int64(1) << 32)
+
+    addr = raw["addr"]
+    x = addr & 0x3FFF
+    y = (addr >> 14) & 0x3FFF
+    p = (addr >> 28) & 0x1
+    return from_arrays(x, y, t, p, width, height)
+
+
+# ---------------------------------------------------------------------------
+# ROS bags (optional dependency; dvs_msgs/prophesee-style EventArray topics)
+# ---------------------------------------------------------------------------
+
+
+def load_rosbag(path: str, topic: str | None = None) -> EventData:
+    """Extract events from a ROS1/ROS2 bag containing EventArray messages.
+
+    Requires the pure-python ``rosbags`` package (``pip install evlab[ros]``).
+    Reads every connection whose message type ends in ``EventArray``
+    (dvs_msgs, prophesee_event_msgs, ...), or only ``topic`` if given.
+    """
+    try:
+        from rosbags.highlevel import AnyReader
+    except ImportError as e:
+        raise ImportError(
+            "reading ROS bags requires the 'rosbags' package: pip install evlab[ros]"
+        ) from e
+    from pathlib import Path
+
+    xs, ys, ts, ps = [], [], [], []
+    width = height = None
+    with AnyReader([Path(path)]) as reader:
+        conns = [
+            c
+            for c in reader.connections
+            if c.msgtype.endswith("EventArray") and (topic is None or c.topic == topic)
+        ]
+        if not conns:
+            available = sorted({f"{c.topic} ({c.msgtype})" for c in reader.connections})
+            raise ValueError(f"no EventArray topic found in {path}; connections: {available}")
+        for conn, _timestamp, raw in reader.messages(connections=conns):
+            msg = reader.deserialize(raw, conn.msgtype)
+            if getattr(msg, "width", 0):
+                width, height = int(msg.width), int(msg.height)
+            for ev in msg.events:
+                xs.append(ev.x)
+                ys.append(ev.y)
+                ts.append(int(ev.ts.sec) * 1_000_000 + int(ev.ts.nanosec) // 1000)
+                ps.append(bool(ev.polarity))
+    if not xs:
+        raise ValueError(f"EventArray topic in {path} contained no events")
+    return from_arrays(np.array(xs), np.array(ys), np.array(ts), np.array(ps), width, height)
+
+
+# ---------------------------------------------------------------------------
+# dispatch
+# ---------------------------------------------------------------------------
+
+_LOADERS = {
+    ".npz": load_npz,
+    ".csv": load_csv,
+    ".txt": load_csv,
+    ".aedat4": load_aedat4,
+    ".dat": load_dat,
+    ".bag": load_rosbag,
+}
+
+_SAVERS = {
+    ".npz": save_npz,
+    ".csv": save_csv,
+    ".txt": save_csv,
+}
+
+
+def load(path: str) -> EventData:
+    """Load events from any supported file format (dispatched on extension)."""
+    ext = os.path.splitext(path)[1].lower()
+    if ext not in _LOADERS:
+        raise ValueError(f"unsupported input format '{ext}' (supported: {sorted(_LOADERS)})")
+    return _LOADERS[ext](path)
+
+
+def save(data: EventData, path: str) -> None:
+    """Save events to any supported output format (dispatched on extension)."""
+    ext = os.path.splitext(path)[1].lower()
+    if ext not in _SAVERS:
+        raise ValueError(f"unsupported output format '{ext}' (supported: {sorted(_SAVERS)})")
+    _SAVERS[ext](data, path)

evlab/metrics.py

@@ -0,0 +1,100 @@
+"""Metrics for comparing and characterizing event streams."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .formats import EventData
+
+
+def summary(data: EventData) -> dict:
+    """Basic stream statistics used by `evlab info`."""
+    ev = data.events
+    n = len(ev)
+    out = {
+        "num_events": n,
+        "width": data.width,
+        "height": data.height,
+        "duration_s": data.duration_us / 1e6,
+        "event_rate_hz": data.event_rate,
+    }
+    if n:
+        out["t_start_us"] = int(ev["t"][0])
+        out["t_end_us"] = int(ev["t"][-1])
+        out["polarity_balance"] = float(ev["p"].mean())
+        active = len(np.unique(ev["y"].astype(np.int64) * data.width + ev["x"]))
+        out["active_pixels"] = active
+        out["active_pixel_fraction"] = active / max(data.width * data.height, 1)
+    return out
+
+
+def retention(original: EventData, filtered: EventData) -> float:
+    """Fraction of events surviving a filter."""
+    if len(original.events) == 0:
+        return 1.0
+    return len(filtered.events) / len(original.events)
+
+
+def event_structural_ratio(data: EventData, patch: int = 8) -> float:
+    """Ratio of event mass in the densest patches vs. total (0..1).
+
+    A crude but dependency-free proxy for signal structure: real scenes
+    concentrate events on edges/objects; uniform sensor noise spreads them
+    evenly. Higher = more structured.
+    """
+    ev = data.events
+    if len(ev) == 0:
+        return 0.0
+    counts = np.zeros((data.height, data.width), dtype=np.int64)
+    np.add.at(counts, (ev["y"].astype(np.intp), ev["x"].astype(np.intp)), 1)
+
+    ph = max(data.height // patch, 1)
+    pw = max(data.width // patch, 1)
+    pooled = counts[: ph * patch, : pw * patch].reshape(ph, patch, pw, patch).sum(axis=(1, 3))
+    flat = np.sort(pooled.ravel())[::-1]
+    top = flat[: max(len(flat) // 10, 1)].sum()
+    return float(top / max(flat.sum(), 1))
+
+
+def denoise_score(data: EventData, keep_mask) -> dict:
+    """Score a denoising keep-mask against ground-truth labels.
+
+    Requires ``data.meta['signal']`` (boolean per-event array, True =
+    signal), as produced by `evlab.synth`. Positive class = signal kept.
+    """
+    import numpy as np
+
+    if "signal" not in data.meta:
+        raise ValueError("no ground-truth labels: data.meta['signal'] missing (see `evlab synth`)")
+    signal = np.asarray(data.meta["signal"], dtype=bool)
+    keep = np.asarray(keep_mask, dtype=bool)
+    if signal.shape != keep.shape:
+        raise ValueError(f"label/mask shape mismatch: {signal.shape} vs {keep.shape}")
+
+    tp = int((keep & signal).sum())
+    fp = int((keep & ~signal).sum())
+    fn = int((~keep & signal).sum())
+    n_noise = int((~signal).sum())
+    precision = tp / max(tp + fp, 1)
+    recall = tp / max(tp + fn, 1)
+    f1 = 2 * precision * recall / max(precision + recall, 1e-12)
+    return {
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+        "signal_events": int(signal.sum()),
+        "noise_events": n_noise,
+        "kept_events": int(keep.sum()),
+        "noise_removed": (n_noise - fp) / max(n_noise, 1),
+    }
+
+
+def compare(reference: EventData, other: EventData) -> dict:
+    """Metrics comparing two streams (e.g. clean vs denoised)."""
+    return {
+        "retention": retention(reference, other),
+        "event_rate_ref_hz": reference.event_rate,
+        "event_rate_other_hz": other.event_rate,
+        "structure_ref": event_structural_ratio(reference),
+        "structure_other": event_structural_ratio(other),
+    }

evlab/representations.py

@@ -0,0 +1,74 @@
+"""Dense representations of event streams (voxel grids, time surfaces, frames)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .formats import EventData
+
+
+def voxel_grid(data: EventData, bins: int = 10) -> np.ndarray:
+    """Accumulate events into a (bins, height, width) voxel grid.
+
+    Polarity is signed (+1/-1) and events are bilinearly distributed across
+    the two temporal bins they straddle, matching the common formulation
+    from Zhu et al. (EV-FlowNet) used by most learning pipelines.
+    """
+    ev = data.events
+    grid = np.zeros((bins, data.height, data.width), dtype=np.float32)
+    if len(ev) == 0:
+        return grid
+
+    t = ev["t"].astype(np.float64)
+    t0, t1 = t[0], t[-1]
+    denom = max(t1 - t0, 1.0)
+    # Scaled timestamp in [0, bins - 1]
+    tau = (t - t0) / denom * (bins - 1)
+    left = np.floor(tau).astype(np.int64)
+    right = np.minimum(left + 1, bins - 1)
+    w_right = tau - left
+    w_left = 1.0 - w_right
+
+    pol = ev["p"].astype(np.float32) * 2.0 - 1.0
+    ys = ev["y"].astype(np.intp)
+    xs = ev["x"].astype(np.intp)
+
+    np.add.at(grid, (left, ys, xs), (pol * w_left).astype(np.float32))
+    np.add.at(grid, (right, ys, xs), (pol * w_right).astype(np.float32))
+    return grid
+
+
+def time_surface(data: EventData, tau_us: float = 30000.0, at_t: int | None = None) -> np.ndarray:
+    """Exponentially-decayed time surface, one channel per polarity.
+
+    Returns a (2, height, width) float32 array where each pixel holds
+    ``exp(-(at_t - t_last) / tau_us)`` for the most recent event of that
+    polarity, or 0 if the pixel never fired.
+    """
+    ev = data.events
+    surface = np.zeros((2, data.height, data.width), dtype=np.float32)
+    if len(ev) == 0:
+        return surface
+
+    if at_t is None:
+        at_t = int(ev["t"][-1])
+
+    last = np.full((2, data.height, data.width), -np.inf, dtype=np.float64)
+    idx = (ev["p"].astype(np.intp), ev["y"].astype(np.intp), ev["x"].astype(np.intp))
+    # Later events overwrite earlier ones at the same pixel (events are t-sorted).
+    last[idx] = ev["t"].astype(np.float64)
+
+    fired = np.isfinite(last)
+    surface[fired] = np.exp(-(at_t - last[fired]) / tau_us).astype(np.float32)
+    return surface
+
+
+def accumulate_frame(data: EventData, clip: int = 3) -> np.ndarray:
+    """Signed event-count frame in [-clip, clip], shape (height, width)."""
+    ev = data.events
+    frame = np.zeros((data.height, data.width), dtype=np.int32)
+    if len(ev) == 0:
+        return frame
+    pol = ev["p"].astype(np.int32) * 2 - 1
+    np.add.at(frame, (ev["y"].astype(np.intp), ev["x"].astype(np.intp)), pol)
+    return np.clip(frame, -clip, clip)

evlab/synth.py

@@ -0,0 +1,62 @@
+"""Synthetic event streams with ground-truth signal/noise labels.
+
+Used by ``evlab synth`` and ``evlab denoise-bench`` to score denoising
+filters with known ground truth: real labeled denoising datasets are rare,
+and a controllable generator makes filter comparisons reproducible.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .formats import EventData, from_arrays
+
+
+def moving_bar(
+    width: int = 240,
+    height: int = 240,
+    duration_us: int = 1_000_000,
+    signal_rate_hz: float = 20_000.0,
+    noise_rate_hz: float = 5_000.0,
+    seed: int = 0,
+) -> EventData:
+    """A vertical bar sweeping left to right over uniform background noise.
+
+    Returns EventData whose ``meta['signal']`` is a boolean array marking
+    ground-truth signal events (True) vs. noise events (False), aligned
+    with the t-sorted event array.
+    """
+    rng = np.random.default_rng(seed)
+
+    n_sig = int(signal_rate_hz * duration_us / 1e6)
+    t_sig = np.sort(rng.integers(0, duration_us, n_sig))
+    # Bar leading edge moves across the full width over the recording.
+    edge = (t_sig / duration_us * (width - 4)).astype(np.int64)
+    x_sig = edge + rng.integers(0, 3, n_sig)
+    y_sig = rng.integers(0, height, n_sig)
+    # ON events at the leading edge, OFF at the trailing edge.
+    p_sig = (rng.random(n_sig) < 0.5).astype(np.int8)
+
+    n_noise = int(noise_rate_hz * duration_us / 1e6)
+    t_noise = rng.integers(0, duration_us, n_noise)
+    x_noise = rng.integers(0, width, n_noise)
+    y_noise = rng.integers(0, height, n_noise)
+    p_noise = rng.integers(0, 2, n_noise).astype(np.int8)
+
+    x = np.concatenate([x_sig, x_noise])
+    y = np.concatenate([y_sig, y_noise])
+    t = np.concatenate([t_sig, t_noise])
+    p = np.concatenate([p_sig, p_noise])
+    is_signal = np.concatenate([np.ones(n_sig, bool), np.zeros(n_noise, bool)])
+
+    # Sort everything by time with the same permutation from_arrays will
+    # apply (stable argsort), so the label mask stays aligned.
+    order = np.argsort(t, kind="stable")
+    data = from_arrays(x[order], y[order], t[order], p[order], width, height)
+    data.meta["signal"] = is_signal[order]
+    return data
+
+
+GENERATORS = {
+    "moving-bar": moving_bar,
+}

evlab/viz.py

@@ -0,0 +1,82 @@
+"""Rendering helpers (require the [viz] extra)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .formats import EventData
+from .representations import accumulate_frame, time_surface
+
+
+def _require_matplotlib():
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt  # noqa: F401
+
+        return matplotlib
+    except ImportError as e:
+        raise ImportError("visualization requires: pip install evlab[viz]") from e
+
+
+def render_frame(data: EventData, mode: str, out_path: str, **kwargs) -> None:
+    """Render a single image (PNG) of the stream in the given mode."""
+    _require_matplotlib()
+    import matplotlib.pyplot as plt
+
+    if mode == "accumulate":
+        img = accumulate_frame(data, clip=kwargs.get("clip", 3))
+        cmap, vmin, vmax = "RdBu_r", -abs(img).max() or 1, abs(img).max() or 1
+    elif mode == "time-surface":
+        surf = time_surface(data, tau_us=kwargs.get("tau_us", 30000.0))
+        img = surf[1] - surf[0]  # ON minus OFF
+        cmap, vmin, vmax = "RdBu_r", -1, 1
+    else:
+        raise ValueError(f"unknown mode '{mode}' (accumulate, time-surface)")
+
+    fig, ax = plt.subplots(figsize=(6, 6 * data.height / max(data.width, 1)))
+    ax.imshow(img, cmap=cmap, vmin=vmin, vmax=vmax, interpolation="nearest")
+    ax.set_axis_off()
+    fig.savefig(out_path, bbox_inches="tight", dpi=150)
+    plt.close(fig)
+
+
+def render_gif(
+    data: EventData, out_path: str, window_ms: float = 33.0, clip: int = 3, fps: int = 30
+) -> int:
+    """Render the stream as an animated GIF of accumulated frames.
+
+    Returns the number of frames written.
+    """
+    _require_matplotlib()
+    try:
+        from PIL import Image
+    except ImportError as e:
+        raise ImportError("GIF export requires: pip install evlab[viz]") from e
+
+    ev = data.events
+    if len(ev) == 0:
+        raise ValueError("cannot render an empty stream")
+
+    window_us = int(window_ms * 1000)
+    t0, t1 = int(ev["t"][0]), int(ev["t"][-1])
+    frames = []
+    for start in range(t0, t1 + 1, window_us):
+        mask = (ev["t"] >= start) & (ev["t"] < start + window_us)
+        chunk = EventData(ev[mask].copy(), data.width, data.height)
+        img = accumulate_frame(chunk, clip=clip).astype(np.float32)
+        # Map [-clip, clip] -> grayscale with ON=white, OFF=black on gray bg
+        norm = ((img + clip) / (2 * clip) * 255).astype(np.uint8)
+        frames.append(Image.fromarray(norm, mode="L"))
+
+    if not frames:
+        raise ValueError("no frames produced; try a larger --window")
+    frames[0].save(
+        out_path,
+        save_all=True,
+        append_images=frames[1:],
+        duration=int(1000 / fps),
+        loop=0,
+    )
+    return len(frames)

evlab-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: evlab
+Version: 0.1.0a1
+Summary: Inspect, clean, convert, and benchmark event-camera data from the command line
+Project-URL: Homepage, https://github.com/JPL11/evlab
+Project-URL: Issues, https://github.com/JPL11/evlab/issues
+Author-email: Jacky Li <jackydli95@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dvs,event-based-vision,event-camera,neuromorphic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: numpy>=1.24
+Provides-Extra: aedat
+Requires-Dist: aedat>=2.0; extra == 'aedat'
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: pillow>=10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: rosbags>=0.10; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: ros
+Requires-Dist: rosbags>=0.10; extra == 'ros'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Requires-Dist: pillow>=10.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# evlab
+
+**Inspect, clean, convert, and benchmark event-camera data from the command line.**
+
+Event-based vision has a preprocessing problem: every sensor and dataset ships a
+different container (AEDAT, ROS bags, CSV, NPZ, proprietary `.dat`), every paper
+wants a different representation (voxel grids, time surfaces, frames), and every
+pipeline reimplements the same denoising filters. `evlab` is the small, boring
+tool that handles that mess so you can get to the actual work.
+
+```bash
+pip install evlab[viz]
+
+evlab info recording.npz                 # what is this file?
+evlab convert events.aedat4 events.npz   # normalize the container
+evlab convert drive.dat events.npz       # Prophesee .dat works too
+evlab convert flight.bag events.npz      # ...and ROS bags (dvs_msgs)
+evlab denoise events.npz clean.npz --filter baf --window 5000
+evlab voxel clean.npz voxels.npy --bins 10
+evlab visualize clean.npz preview.gif --mode gif
+evlab benchmark events.npz clean.npz     # what did the filter do?
+```
+
+How good is a denoising filter, really? Generate a labeled stream and score it:
+
+```bash
+evlab synth labeled.npz --signal-rate 20000 --noise-rate 8000
+evlab denoise-bench labeled.npz --filter baf --window 3000
+#   precision     : 99.2%
+#   recall        : 37.8%
+#   f1            : 0.548
+#   noise removed : 99.2%
+```
+
+## Status
+
+Early alpha. Works and is tested: the canonical representation; loading
+NPZ/CSV/TXT, AEDAT4 (`[aedat]` extra), Prophesee legacy `.dat` (with
+timestamp-wrap handling), and ROS1/ROS2 bags with `EventArray` topics
+(`[ros]` extra); BAF/refractory denoising; voxel grids, time surfaces,
+accumulate frames; synthetic labeled streams and precision/recall filter
+scoring; and the eight CLI commands above. Planned next: Prophesee EVT3
+`.raw`, dataset-aware loaders (via [Tonic]), streaming via [Faery], and
+more filters (STCF, IE/YNoise) under `denoise-bench`.
+
+[Tonic]: https://github.com/neuromorphs/tonic
+[Faery]: https://github.com/aestream/faery
+
+## Python API
+
+```python
+import evlab
+
+data = evlab.load("recording.npz")          # EventData: (x, y, t, p) + sensor size
+print(data.event_rate)
+
+from evlab.filters import background_activity_filter
+clean = background_activity_filter(data, time_window_us=5000)
+
+from evlab.representations import voxel_grid
+grid = voxel_grid(clean, bins=10)            # (10, H, W) float32, ready for torch
+```
+
+## Design notes
+
+- One canonical in-memory format: a t-sorted structured numpy array
+  (`x: u2, y: u2, t: i8 (µs), p: i1`) plus sensor geometry. Every loader
+  normalizes into it; every filter/representation consumes it.
+- Zero heavy dependencies in the core (`numpy` + `click`). Visualization,
+  AEDAT support, and dataset loaders are opt-in extras.
+- Filters return copies; nothing mutates your data behind your back.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+ruff check src tests
+```
+
+## License
+
+MIT

evlab-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,13 @@
+evlab/__init__.py,sha256=_Pz8LvYm4R1rXPNGh0NL7b15jO42H5lRFwNBiRiQQdE,223
+evlab/cli.py,sha256=j6euP897eUiq6NbFdvTKgHsobCxPqYf4NLE4mZHL03k,7434
+evlab/filters.py,sha256=ayJfkPHMV7HzpOfnffqbTSEE63REZtuur95j7T9HlKU,3663
+evlab/formats.py,sha256=OYU6-04V7zKkRVfVxRKET7blf7iX5V3_37PODdQDusk,11204
+evlab/metrics.py,sha256=bsmNuoaTZp1PpQxcnh9XktzbFnyusAf1In_O9WYzFjM,3531
+evlab/representations.py,sha256=XyN8U_jMrJ6X0oZt9vkaPQJyl8vussOfLWkR4SusMNU,2652
+evlab/synth.py,sha256=zw6P6mzL1VIixrogRJ7aMd_w7NxuQRpFpOfC3IeHlqo,2212
+evlab/viz.py,sha256=73ZWECfh82a4XPTiCBXz-yQPyoKhZQuLGkqZXK_8MsE,2736
+evlab-0.1.0a1.dist-info/METADATA,sha256=9DFfWf_AYm_YDOHd54-TzGhUFlTK-NndWKIpmzGKSxA,4101
+evlab-0.1.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+evlab-0.1.0a1.dist-info/entry_points.txt,sha256=rKIuow3Nrfn2ulRiMZv3ng_tu-nv0TNwG6ziXZNBC9U,41
+evlab-0.1.0a1.dist-info/licenses/LICENSE,sha256=0fQlGFE3ScZzqnYgo-yrhRa6aj9CwMX6JUCZ2cZcV4I,1065
+evlab-0.1.0a1.dist-info/RECORD,,

evlab-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

evlab-0.1.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+evlab = evlab.cli:main

evlab-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacky Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.