evlab 0.1.0a1__tar.gz

evlab-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e .[dev]
+      - name: Lint
+        run: |
+          ruff check src tests
+          ruff format --check src tests
+      - name: Test
+        run: pytest -v

evlab-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

evlab-0.1.0a1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

evlab-0.1.0a1/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.

evlab-0.1.0a1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,83 @@
+# 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/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "evlab"
+version = "0.1.0a1"
+description = "Inspect, clean, convert, and benchmark event-camera data from the command line"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Jacky Li", email = "jackydli95@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+    "click>=8.1",
+]
+keywords = ["event-camera", "neuromorphic", "dvs", "event-based-vision"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+
+[project.optional-dependencies]
+viz = ["matplotlib>=3.7", "pillow>=10.0"]
+aedat = ["aedat>=2.0"]
+ros = ["rosbags>=0.10"]
+dev = ["pytest>=7.0", "ruff>=0.4", "matplotlib>=3.7", "pillow>=10.0", "rosbags>=0.10"]
+
+[project.scripts]
+evlab = "evlab.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/JPL11/evlab"
+Issues = "https://github.com/JPL11/evlab/issues"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

evlab-0.1.0a1/src/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-0.1.0a1/src/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-0.1.0a1/src/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,
+}