evutils 0.3.10__tar.gz → 0.3.12__tar.gz

{evutils-0.3.10 → evutils-0.3.12}/.github/workflows/release.yaml

@@ -51,7 +51,7 @@ jobs:
           CIBW_ARCHS_MACOS: "x86_64 arm64"
 
       - name: Upload wheels
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist-${{ matrix.os }}
           path: wheelhouse/*.whl
@@ -75,7 +75,7 @@ jobs:
         run: pipx run build --sdist
 
       - name: Upload sdist
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist-sdist
           path: dist/*.tar.gz
@@ -140,4 +140,53 @@ jobs:
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
+
+  test_pypi_wheels:
+    name: Test PyPI Wheel (${{ matrix.os }}, Py ${{ matrix.python }})
+    needs: publish_pypi
+    runs-on: ${{ matrix.os }}
+    if: github.event_name == 'release'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, windows-latest, macos-14]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install evutils from PyPI
+        shell: bash
+        run: |
+          # Retry loop to wait for PyPI index to update with the new release
+          # GITHUB_REF_NAME contains the tag name (e.g. v1.0.0). We strip the 'v' for pip.
+          VERSION=${GITHUB_REF_NAME#v}
+          for i in {1..12}; do
+            uv pip install --system "evutils[test]==$VERSION" --no-cache && break
+            echo "Waiting for PyPI index..."
+            sleep 10
+          done
+
+      - name: Remove local source tree
+        shell: bash
+        run: |
+          # Remove local source so Python is forced to import from the installed PyPI wheel
+          rm -rf src/evutils
+
+      - name: Run tests against PyPI wheel
+        shell: bash
+        run: |
+          python -m pytest -s -v tests/

{evutils-0.3.10 → evutils-0.3.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: evutils
-Version: 0.3.10
+Version: 0.3.12
 Summary: Utilities for event-based vision
 Keywords: events,dvs,neuromorphic,vision,event-based
 Author-Email: Jakub Mandula <jakub.mandula@pbl.ee.ethz.ch>
@@ -30,25 +30,31 @@ Project-URL: Homepage, https://mandulaj.github.io/evutils/
 Requires-Python: >=3.10
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: opencv-python>=4.2
+Requires-Dist: numba>=0.57
+Provides-Extra: aedat
+Requires-Dist: lz4>=4.0; extra == "aedat"
+Requires-Dist: zstandard>=0.22; python_version < "3.14" and extra == "aedat"
 Provides-Extra: pandas
 Requires-Dist: pandas>=2.3.3; extra == "pandas"
-Provides-Extra: numba
-Requires-Dist: numba>=0.57; extra == "numba"
 Provides-Extra: torch
 Requires-Dist: torch>=2.0; extra == "torch"
 Provides-Extra: hdf5
 Requires-Dist: hdf5plugin==6.0.0; extra == "hdf5"
-Requires-Dist: h5py==3.16.0; extra == "hdf5"
+Requires-Dist: h5py>=3.16.0; extra == "hdf5"
 Provides-Extra: vis
 Requires-Dist: matplotlib>=3.1; extra == "vis"
+Requires-Dist: open3d>=0.19.0; python_version < "3.13" and extra == "vis"
 Requires-Dist: scipy>=1.15.3; extra == "vis"
 Requires-Dist: tqdm>=4.41; extra == "vis"
 Provides-Extra: test
 Requires-Dist: pytest>=9.0.2; extra == "test"
 Requires-Dist: pytest-benchmark>=5.2.3; extra == "test"
+Requires-Dist: zstandard>=0.22; python_version < "3.14" and extra == "test"
 Provides-Extra: compare
 Requires-Dist: expelliarmus>=1.1.0; extra == "compare"
-Requires-Dist: evlib; extra == "compare"
+Requires-Dist: evlib>=0.12.0; python_version >= "3.11" and extra == "compare"
+Requires-Dist: evlib>=0.8.0; python_version < "3.11" and extra == "compare"
+Requires-Dist: evt3>=0.3; extra == "compare"
 Provides-Extra: docs
 Requires-Dist: sphinx>=8.0.0; extra == "docs"
 Requires-Dist: sphinx-autoapi>=3.6.1; extra == "docs"
@@ -58,7 +64,7 @@ Requires-Dist: sphinx_book_theme>=1.0.0; extra == "docs"
 Requires-Dist: pydata_sphinx_theme>=0.19.0; extra == "docs"
 Requires-Dist: myst-parser>=4.0.0; extra == "docs"
 Provides-Extra: all
-Requires-Dist: evutils[hdf5,numba,pandas,torch,vis]; extra == "all"
+Requires-Dist: evutils[aedat,hdf5,pandas,torch,vis]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: evutils[all,docs,test]; extra == "dev"
 Description-Content-Type: text/markdown
@@ -68,7 +74,13 @@ Description-Content-Type: text/markdown
 [![Test](https://github.com/mandulaj/evutils/actions/workflows/test.yaml/badge.svg)](https://github.com/mandulaj/evutils/actions/workflows/test.yaml)
 
 ## Overview
-EV-Utils (``evutils``) is a performant collection of utilities for working with event-based vision data. Built with minimal dependencies, it relies on compiled C backed for speed while offering a clean, modular Python interface.
+EV-Utils (`evutils`) is a performant collection of utilities for working with event-based vision data. Built with minimal dependencies, it relies on a compiled C backend for speed while offering a clean, modular Python interface.
+
+### Core Philosophy
+* **Fast & Lightweight:** Highly optimized C parsers for zero-bottleneck data ingestion.
+* **Minimal Footprint:** Core features run entirely on NumPy and Numba.
+* **Lazy Loading:** All heavy integrations (PyTorch, Pandas, HDF5, Polars, etc.) are lazy-loaded. If you don't use them, you don't need them installed, and they won't slow down import times.
+* **Simple & Extensible:** Clean modular APIs.
 
 
 
@@ -79,14 +91,18 @@ This project draws inspiration from several excellent libraries in the event-bas
 * [event_utils](https://github.com/TimoStoff/event_utils)
 * [evlib](https://github.com/tallamjr/evlib)
 * [expelliarmus](https://github.com/open-neuromorphic/expelliarmus)
+* [event-vision-library](https://github.com/shiba24/event-vision-library)
+* [evt3](https://github.com/muthmann/evt3)
 * [openeb](https://github.com/prophesee-ai/openeb)
 
 
 ## Installation
-We recommend installing `evutils` using `uv`.
+We recommend installing `evutils` using `uv`. 
 ### From PyPi
 ```bash
-uv add evutils[all]
+uv add evutils # Basic library
+uv add evutils[all] # All groups (pandas, numba, torch, hdf5, etc..)
+uv add evutils[dev] # Dev group
 ```
 
 ### From Git
@@ -131,6 +147,20 @@ Wrappers for various dataset loaders -->
 
 The `io` module provides methods for reading and writing events into various event formats. It provides a simple `.read()` and `.write()` interface as well as more advanced interfaces using iterators and slicing.
 
+Supported formats (see the [formats documentation](https://mandulaj.github.io/evutils/formats.html) for details):
+
+| Format | Extensions | Read | Write | Notes |
+|---|---|:---:|:---:|---|
+| EVT3 / EVT2.1 / EVT2 (Prophesee RAW) | `.raw`, `.evt*` | ✅ | ✅ | native C decoder, external triggers |
+| DAT (Prophesee) | `.dat` | ✅ | ✅ | native C decoder |
+| AER (Prophesee) | `.aer` | ✅ | ✅ | timestamp generation selectable |
+| AEDAT 1.0 / 2.0 / 3.1 / 4.0 | `.aedat`, `.aedat4` | ✅ | 🚧 | AEDAT4 compression: `evutils[aedat]` |
+| HDF5 (DSEC/RVT layout) | `.h5`, `.hdf5` | ✅ | ✅ | `evutils[hdf5]`, ms-index random access |
+| HDF5 (Prophesee layout) | `.h5`, `.hdf5` | ✅ | 🚧 | ECF-compressed files need the ECF plugin |
+| NPZ | `.npz` | ✅ | ✅ | streaming, `np.load`-compatible |
+| CSV / TXT | `.csv`, `.txt` | ✅ | ✅ | `evutils[pandas]` |
+| BIN | `.bin` | 🚧 | 🚧 | planned |
+
 ```python
 from evutils.io import EventReader
 
@@ -187,25 +217,17 @@ uv run pytest benchmarks/ --benchmark-group-by=param:fmt    # compare libraries
 
 The benchmarks download a real Prophesee recording on first use. Optional cross-library comparisons run automatically once the libraries are installed (`uv pip install -e ".[compare]"`); OpenEB/Metavision is compared via the Docker image in `benchmarks/docker/`. See [`benchmarks/README.md`](benchmarks/README.md) for details.
 
-Decode/encode throughput on a 12th Gen Intel Core i7-1280P (millions of events per second, higher is better):
-
-**Read** (full-file decode)
-
-| Format | evutils | expelliarmus | evlib |
-| ------ | ------: | -----------: | ----: |
-| EVT2   |      91 |          105 |     5 |
-| EVT2.1 |      72 |            – |     – |
-| EVT3   |      53 |           41 |     5 |
-
-**Write** (evutils; expelliarmus/evlib are read-only for these formats)
 
-| Format | evutils |
-| ------ | ------: |
-| EVT2   |     146 |
-| EVT2.1 |     110 |
-| EVT3   |      74 |
 
-(`–` = format not supported by that library.)
+## & Roadmap
+We aim for universal event format support, prioritizing blazing fast read/write speeds, completeness, and extensibility. 
+- [x] Universal format support (`.raw`, `.evt2`, `.dat`, `.aedat4`, `.hdf5`, `.npz`, `.csv`, etc.)
+- [x] Full Read/Write parity where possible
+- [x] Chunked & Streaming access
+- [x] External trigger data parsing
+- [ ] **Random access / Timestamp indexing** (Big TODO for the future)
+- [ ] **Arbitrary input sources:** memory-mapped IO, pure in-memory streams, HTTP streams
+- [ ] **On-the-fly Compression wrappers:** passing file handles through `zstd` or `lz4` compression transparently before decoding
 
 
 ## Acknowledgements

{evutils-0.3.10 → evutils-0.3.12}/README.md

@@ -3,7 +3,13 @@
 [![Test](https://github.com/mandulaj/evutils/actions/workflows/test.yaml/badge.svg)](https://github.com/mandulaj/evutils/actions/workflows/test.yaml)
 
 ## Overview
-EV-Utils (``evutils``) is a performant collection of utilities for working with event-based vision data. Built with minimal dependencies, it relies on compiled C backed for speed while offering a clean, modular Python interface.
+EV-Utils (`evutils`) is a performant collection of utilities for working with event-based vision data. Built with minimal dependencies, it relies on a compiled C backend for speed while offering a clean, modular Python interface.
+
+### Core Philosophy
+* **Fast & Lightweight:** Highly optimized C parsers for zero-bottleneck data ingestion.
+* **Minimal Footprint:** Core features run entirely on NumPy and Numba.
+* **Lazy Loading:** All heavy integrations (PyTorch, Pandas, HDF5, Polars, etc.) are lazy-loaded. If you don't use them, you don't need them installed, and they won't slow down import times.
+* **Simple & Extensible:** Clean modular APIs.
 
 
 
@@ -14,14 +20,18 @@ This project draws inspiration from several excellent libraries in the event-bas
 * [event_utils](https://github.com/TimoStoff/event_utils)
 * [evlib](https://github.com/tallamjr/evlib)
 * [expelliarmus](https://github.com/open-neuromorphic/expelliarmus)
+* [event-vision-library](https://github.com/shiba24/event-vision-library)
+* [evt3](https://github.com/muthmann/evt3)
 * [openeb](https://github.com/prophesee-ai/openeb)
 
 
 ## Installation
-We recommend installing `evutils` using `uv`.
+We recommend installing `evutils` using `uv`. 
 ### From PyPi
 ```bash
-uv add evutils[all]
+uv add evutils # Basic library
+uv add evutils[all] # All groups (pandas, numba, torch, hdf5, etc..)
+uv add evutils[dev] # Dev group
 ```
 
 ### From Git
@@ -66,6 +76,20 @@ Wrappers for various dataset loaders -->
 
 The `io` module provides methods for reading and writing events into various event formats. It provides a simple `.read()` and `.write()` interface as well as more advanced interfaces using iterators and slicing.
 
+Supported formats (see the [formats documentation](https://mandulaj.github.io/evutils/formats.html) for details):
+
+| Format | Extensions | Read | Write | Notes |
+|---|---|:---:|:---:|---|
+| EVT3 / EVT2.1 / EVT2 (Prophesee RAW) | `.raw`, `.evt*` | ✅ | ✅ | native C decoder, external triggers |
+| DAT (Prophesee) | `.dat` | ✅ | ✅ | native C decoder |
+| AER (Prophesee) | `.aer` | ✅ | ✅ | timestamp generation selectable |
+| AEDAT 1.0 / 2.0 / 3.1 / 4.0 | `.aedat`, `.aedat4` | ✅ | 🚧 | AEDAT4 compression: `evutils[aedat]` |
+| HDF5 (DSEC/RVT layout) | `.h5`, `.hdf5` | ✅ | ✅ | `evutils[hdf5]`, ms-index random access |
+| HDF5 (Prophesee layout) | `.h5`, `.hdf5` | ✅ | 🚧 | ECF-compressed files need the ECF plugin |
+| NPZ | `.npz` | ✅ | ✅ | streaming, `np.load`-compatible |
+| CSV / TXT | `.csv`, `.txt` | ✅ | ✅ | `evutils[pandas]` |
+| BIN | `.bin` | 🚧 | 🚧 | planned |
+
 ```python
 from evutils.io import EventReader
 
@@ -122,25 +146,17 @@ uv run pytest benchmarks/ --benchmark-group-by=param:fmt    # compare libraries
 
 The benchmarks download a real Prophesee recording on first use. Optional cross-library comparisons run automatically once the libraries are installed (`uv pip install -e ".[compare]"`); OpenEB/Metavision is compared via the Docker image in `benchmarks/docker/`. See [`benchmarks/README.md`](benchmarks/README.md) for details.
 
-Decode/encode throughput on a 12th Gen Intel Core i7-1280P (millions of events per second, higher is better):
-
-**Read** (full-file decode)
-
-| Format | evutils | expelliarmus | evlib |
-| ------ | ------: | -----------: | ----: |
-| EVT2   |      91 |          105 |     5 |
-| EVT2.1 |      72 |            – |     – |
-| EVT3   |      53 |           41 |     5 |
-
-**Write** (evutils; expelliarmus/evlib are read-only for these formats)
 
-| Format | evutils |
-| ------ | ------: |
-| EVT2   |     146 |
-| EVT2.1 |     110 |
-| EVT3   |      74 |
 
-(`–` = format not supported by that library.)
+## & Roadmap
+We aim for universal event format support, prioritizing blazing fast read/write speeds, completeness, and extensibility. 
+- [x] Universal format support (`.raw`, `.evt2`, `.dat`, `.aedat4`, `.hdf5`, `.npz`, `.csv`, etc.)
+- [x] Full Read/Write parity where possible
+- [x] Chunked & Streaming access
+- [x] External trigger data parsing
+- [ ] **Random access / Timestamp indexing** (Big TODO for the future)
+- [ ] **Arbitrary input sources:** memory-mapped IO, pure in-memory streams, HTTP streams
+- [ ] **On-the-fly Compression wrappers:** passing file handles through `zstd` or `lz4` compression transparently before decoding
 
 
 ## Acknowledgements

evutils-0.3.12/benchmarks/README.md

@@ -0,0 +1,145 @@
+# Benchmarks
+
+Read/write throughput benchmarks for the native EVT2 / EVT2.1 / EVT3 codecs, plus optional comparisons against other event libraries.
+
+These benchmarks are **not** part of the normal test run (which uses `testpaths = ["tests"]`). They must be executed explicitly from the repository root.
+
+## Quick Start
+
+Run the default suite (evutils only, plus any installed comparison libraries):
+```bash
+pytest benchmarks/
+```
+
+Run specific benchmarks:
+```bash
+pytest benchmarks/test_read.py           # just reads
+pytest benchmarks/test_write.py          # just writes
+```
+
+## Benchmark Options
+
+### Datasets
+You can benchmark against two datasets using the `--dataset` flag. The necessary files are automatically downloaded and cached on first use.
+- `--dataset small` (default): A ~1GB memory footprint dataset (hand recordings).
+- `--dataset large`: A massive multi-GB dataset designed to test the streaming and chunking capabilities of the decoders.
+
+```bash
+pytest benchmarks/ --dataset large
+```
+
+### Filtering Readers
+The benchmark tests are fully parametrized by the reader name. You can effortlessly exclude specific third-party libraries using pytest's standard `-k` flag (for example, if they are slow or misbehaving on large datasets):
+
+```bash
+pytest benchmarks/ -k "not evlib" --dataset large
+pytest benchmarks/ -k "not evlib and not openeb"
+```
+
+## File Structure
+
+| File | What it benchmarks |
+|------|--------------------|
+| `test_read.py`          | `evutils` decode throughput on the full real recordings (evt2/evt21/evt3), asserts count vs reference |
+| `test_write.py`         | `evutils` encode throughput (payload = first 5M events of the real evt3 file) |
+| `test_formats.py`       | **uniform per-format read/write**: the same 5M real events transcoded into every format (EVT3/EVT2.1/EVT2, DAT, AER, NPZ, HDF5, CSV, AEDAT4), so numbers are comparable across formats; expelliarmus (DAT) and evlib (HDF5, AEDAT4) compared on the identical files |
+| `test_compare.py`       | third-party readers from `readers.py` on the full real recordings (auto-skip if not installed) |
+| `readers.py`            | adapter registry — one entry per external library |
+
+*Note: in `test_formats.py` AER is the one lossy transcode — the format has no timestamps and 9-bit coordinates, so the same events are written with coordinates masked to 0–511 (identical event count).*
+
+## Comparing Against Other Libraries
+
+Install the optional readers and run with grouping so every library lines up per format:
+
+```bash
+pip install evutils[compare]      # expelliarmus, evlib
+pytest benchmarks/ --benchmark-group-by=param:fmt --benchmark-columns=mean,ops
+```
+
+Each library reads inside a lazy import. If a library is uninstalled or broken, its benchmarks simply **skip**. To add another library, append a `Reader(...)` entry to `readers.py`.
+
+## Benchmark Comparison (Mean Time in Seconds)
+
+### Reading
+
+| Library | EVT2 | EVT21 | EVT3 |
+|---|---|---|---|
+| **evutils** | 0.138 s | 0.070 s | 0.292 s |
+| **evlib** | 4.410 s | N/A | 4.327 s |
+| **expelliarmus** | 0.128 s | N/A | 0.341 s |
+
+### Writing
+
+| Library | EVT2 | EVT21 | EVT3 |
+|---|---|---|---|
+| **evutils** | 0.013 s | 0.028 s | 0.041 s |
+| **expelliarmus** | 0.077 s | N/A | 0.097 s |
+
+**Hardware:** 12th Gen Intel(R) Core(TM) i7-1280P | **OS:** Linux 7.1.1-3-MANJARO | **Python:** 3.12.13
+
+*Lower is better. Generated dynamically by `scripts/generate_benchmark_table.py`.*
+
+> **Note**: `tonic` is intentionally not included. It has no standalone EVT reader and reads Prophesee data through `expelliarmus` internally, so benchmarking it would just re-measure `expelliarmus`.
+
+## OpenEB / Metavision (via Docker)
+
+OpenEB isn't on PyPI and is painful to build locally, so there's an image that builds it once. Both commands must be run **from the repo root** (the build context must be the whole project so `evutils` is copied in):
+
+```bash
+# Build the image (compiles OpenEB from source + installs evutils; slow, one-time)
+docker build -t evutils-openeb -f benchmarks/docker/Dockerfile.openeb .
+
+# Run the full suite (evutils + OpenEB), grouped per format
+docker run --rm evutils-openeb
+```
+
+The container's default command is `pytest benchmarks/ --benchmark-group-by=param:fmt`, so you get `evutils` and OpenEB side by side per format.
+
+### Useful Variations
+
+The recordings are **not** baked into the image (`.dockerignore` excludes the
+data and cache directories), so the fixture tries to download them on first
+use. If the container has no network access, mount the host's already-cached
+recordings and point `EVUTILS_BENCH_DATA` at them:
+
+```bash
+# after benchmarks have run at least once on the host:
+docker run --rm \
+  -v "$(pwd)/.pytest_cache/d/event_files:/data:ro" \
+  -e EVUTILS_BENCH_DATA=/data \
+  evutils-openeb
+```
+
+Alternatively, persist the container's own download across runs with a named
+volume (note the workdir is `/home/user/work`):
+
+```bash
+docker run --rm -v evutils-cache:/home/user/work/.pytest_cache evutils-openeb
+```
+
+Run only the OpenEB comparison (skip the `evutils` rows):
+
+```bash
+docker run --rm evutils-openeb \
+  pytest benchmarks/test_compare.py --benchmark-group-by=param:fmt -q
+```
+
+Drop into a shell to debug the build/run:
+
+```bash
+docker run --rm -it evutils-openeb bash
+```
+
+Build a different OpenEB release if the default fails to build:
+
+```bash
+docker build -t evutils-openeb --build-arg OPENEB_VERSION=5.0.0 \
+  -f benchmarks/docker/Dockerfile.openeb .
+```
+
+### Caveats
+
+- The image targets **OpenEB 5.x on Ubuntu 22.04**; OpenEB's apt dependencies and install layout drift between releases, so the `apt-get`/`PYTHONPATH` lines may need tweaking. The Dockerfile imports `metavision_core` at build time, so a broken OpenEB install fails during `docker build` rather than silently skipping at run time.
+- The first pass is slow: it compiles OpenEB (`-j$(nproc)`) and downloads the reference recording on first run.
+- A repo-root `.dockerignore` keeps the build context small (excludes `.venv`, `build/`, `.git`, `data/`, `*.raw`, etc.).

evutils-0.3.12/benchmarks/conftest.py

@@ -0,0 +1,171 @@
+"""Benchmark fixtures.
+
+``EventFile`` and ``real_event_files`` are duplicated from ``tests/conftest.py``
+on purpose: pytest only shares conftest fixtures downward, and ``benchmarks/``
+is a sibling of ``tests/``, so there is no clean way to reuse them without a
+repo-root conftest. Keep the two copies in sync.
+"""
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+from typing import Any, cast
+
+from evutils.io import EventReader
+
+sys.path.append(str(Path(__file__).parent.parent / "tests"))
+from conftest_utils import EventFile, download_and_extract_gdrive, load_event_files  # type: ignore
+
+#: Cap on how many events are held in memory for the write benchmarks. Large
+#: enough for a stable throughput measurement, small enough to stay light.
+N_REFERENCE = 5_000_000
+
+
+@pytest.fixture(scope='session')
+def real_event_files(request: Any, benchmark_dataset: str) -> dict[str, list[Any]]:
+    """Real Prophesee recordings (downloaded + cached on first use).
+
+    Returns ``{format: [EventFile(path, count)]}``.
+
+    Set ``EVUTILS_BENCH_DATA`` to a directory that already contains the
+    extracted recordings (+ JSON metadata) to skip the download entirely --
+    useful in offline environments such as the OpenEB benchmark container
+    (mount the host cache there).
+    """
+    import os
+    override = os.environ.get("EVUTILS_BENCH_DATA")
+    if override:
+        data_dir = Path(override)
+        if not data_dir.is_dir():
+            pytest.skip(f"EVUTILS_BENCH_DATA={override} is not a directory")
+        return cast(dict[str, list[Any]], load_event_files(data_dir))
+
+    if benchmark_dataset == "large":
+        temp_dir = request.config.cache.mkdir("event_files_huge")
+        file_id = "1QPuilR1VD0rKyhVOlu1Y-HtkO4ZBc2Cz"
+        
+        json_files = list(temp_dir.glob("*.json"))
+        if not json_files:
+            download_and_extract_gdrive(file_id, temp_dir, "huge.tar.zst")
+            
+        return cast(dict[str, list[Any]], load_event_files(temp_dir))
+    else:
+        temp_dir = request.config.cache.mkdir("event_files")
+        file_id = "1uhOsWbp2o3CktsHrFkzGCNFbx0bQLsct"
+        filenames = {
+            'evt3': "hand_evt3.raw",
+            'evt21': "hand_evt21.raw",
+            'evt2': "hand_evt2.raw",
+        }
+        paths = {fmt: temp_dir / name for fmt, name in filenames.items()}
+
+        for key, path in paths.items():
+            if not path.exists():
+                download_and_extract_gdrive(file_id, temp_dir, "hand.tar.zst")
+                break
+                
+        return cast(dict[str, list[Any]], load_event_files(temp_dir))
+
+
+@pytest.fixture(scope='session')
+def reference_events(real_event_files: dict[str, list[Any]]) -> Any:
+    """First ``N_REFERENCE`` events of the real EVT3 recording as an AoS array.
+
+    Decoded once and reused as the payload for every write benchmark, so the
+    write benchmarks measure encoding cost only (not decoding).
+    """
+    parts = []
+    total = 0
+    if 'evt3' not in real_event_files or not real_event_files['evt3']:
+        pytest.skip("No evt3 files available for reference events")
+    # Use the hand_evt3.raw file for reference events
+    ef = next((f for f in real_event_files['evt3'] if 'hand' in f.path.name), real_event_files['evt3'][0])
+    with EventReader(ef.path, n_events=1_000_000) as reader:
+        for chunk in reader:
+            parts.append(chunk.to_aos())
+            total += len(chunk)
+            if total >= N_REFERENCE:
+                break
+    return np.concatenate(parts)[:N_REFERENCE]
+
+
+def pytest_addoption(parser: Any) -> None:
+    parser.addoption(
+        "--rounds", action="store", default=4, type=int, help="Number of benchmark rounds"
+    )
+    parser.addoption(
+        "--dataset", action="store", default="small", choices=["small", "large"], 
+        help="Dataset size to use for benchmarks ('small' or 'large')"
+    )
+
+@pytest.fixture(scope="session")
+def benchmark_rounds(request: Any) -> int:
+    return int(request.config.getoption("--rounds"))
+
+@pytest.fixture(scope="session")
+def benchmark_dataset(request: Any) -> str:
+    return str(request.config.getoption("--dataset"))
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_benchmark_group_stats(config: Any, benchmarks: list[dict[str, Any]], group_by: str) -> Any:
+    """Guard against a pytest-benchmark crash with ``--benchmark-group-by=param:<name>``.
+
+    Benchmarks collected from non-parametrized tests have ``params = None``,
+    which the plugin's param-grouping code cannot handle (TypeError) -- and the
+    crash also swallows the whole error/summary report. Give such benchmarks an
+    explicit null param instead, so they group under ``<name>=None``.
+    """
+    if isinstance(group_by, str) and group_by.startswith("param:"):
+        names = group_by.split(":", 1)[1].split(",")
+        for bench in benchmarks:
+            if bench.get("params") is None:
+                bench["params"] = {}
+            for name in names:
+                bench["params"].setdefault(name, None)
+    yield
+
+
+@pytest.fixture(scope="session")
+def uniform_files(reference_events: Any, tmp_path_factory: Any) -> dict[str, Any]:
+    """The same ``N_REFERENCE`` real events transcoded into every format.
+
+    All per-format read/write benchmarks (benchmarks/test_formats.py) operate
+    on these files, so throughput numbers are comparable across formats: same
+    events, same count. AER is the one lossy exception -- it has no timestamps
+    and 9-bit coordinates, so its file carries the same events with coordinates
+    masked to 0..511 (the event count is identical).
+    """
+    from evutils.io import EventWriter
+
+    sys.path.append(str(Path(__file__).parent.parent / "tests"))
+    from aedat_synth import make_aedat4  # type: ignore
+
+    d = tmp_path_factory.mktemp("uniform")
+    ev = reference_events
+    files = {}
+
+    for fmt in ("evt3", "evt21", "evt2"):
+        files[fmt] = d / f"ref_{fmt}.raw"
+        with EventWriter(files[fmt], width=1280, height=720, format=fmt) as w:
+            w.write(ev)
+
+    for fmt, name in (("dat", "ref.dat"), ("npz", "ref.npz"),
+                      ("hdf5", "ref.h5"), ("csv", "ref.csv")):
+        files[fmt] = d / name
+        with EventWriter(files[fmt], width=1280, height=720) as w:
+            w.write(ev)
+
+    aer = ev.copy()
+    aer["x"] &= 0x1FF
+    aer["y"] &= 0x1FF
+    files["aer"] = d / "ref.aer"
+    with EventWriter(files["aer"]) as w:
+        w.write(aer)
+
+    files["aedat4"] = d / "ref.aedat4"
+    files["aedat4"].write_bytes(
+        make_aedat4(ev["t"], ev["x"], ev["y"], ev["p"], events_per_packet=65536)
+    )
+    return files

evutils-0.3.12/benchmarks/docker/Dockerfile.openeb

@@ -0,0 +1,56 @@
+# OpenEB (Metavision SDK, open-source edition) + evutils, for running the
+# comparison benchmarks against OpenEB's RawReader.
+#
+# OpenEB is not on PyPI and is fiddly to build; this image does it once.
+#
+# Build (from the repo root, so the whole project is the build context):
+#     docker build -t evutils-openeb -f benchmarks/docker/Dockerfile.openeb .
+#
+# Run the benchmarks (downloads the reference recordings on first run):
+#     docker run --rm evutils-openeb
+#
+# Tip: add a repo-root .dockerignore (.venv, build/, .git, *.raw, data/) to keep
+# the build context small.
+#
+# NOTE: OpenEB's exact apt dependencies and layout shift between releases. This
+# targets OpenEB 5.x on Ubuntu 22.04 -- bump OPENEB_VERSION / tweak deps if the
+# build fails.
+FROM registry.git.ee.ethz.ch/pbl/research/event-camera/docker/open-eb-docker/openeb_base:latest
+
+ARG USERNAME=user
+ARG PASSWORD=password
+ARG USER_ID=1000
+ARG GROUP_ID=1000
+
+# Validate that all required arguments are set
+RUN : \
+  && if [ -z "$USERNAME" ]; then echo "ERROR: USERNAME is not set."; exit 1; fi \
+  && if [ -z "$PASSWORD" ]; then echo "ERROR: PASSWORD is not set."; exit 1; fi \
+  && if [ -z "$USER_ID" ]; then echo "ERROR: USER_ID is not set."; exit 1; fi \
+  && if [ -z "$GROUP_ID" ]; then echo "ERROR: GROUP_ID is not set."; exit 1; fi
+
+RUN groupadd -g ${GROUP_ID} ${USERNAME} && useradd -u ${USER_ID} -g ${GROUP_ID} -ms /bin/bash ${USERNAME} && usermod -aG sudo ${USERNAME} && echo "${USERNAME}:${PASSWORD}" | chpasswd
+
+USER ${USERNAME}
+RUN echo "source /openeb/build/utils/scripts/setup_env.sh" >> /home/${USERNAME}/.bashrc
+
+WORKDIR /home/${USERNAME}/work
+COPY . /home/${USERNAME}/work
+
+
+
+# 2. Omit --python 3.12 so it defaults to the system Python (3.10) to match OpenEB
+RUN uv venv --system-site-packages
+RUN uv pip install --no-cache-dir -e ".[test,compare]"
+
+ENV PATH="/home/${USERNAME}/work/.venv/bin:$PATH"
+
+# 3. Source the OpenEB setup script directly during the RUN step
+RUN . /openeb/build/utils/scripts/setup_env.sh && \
+    python3 -c "from metavision_core.event_io import RawReader; print('OpenEB OK')"
+
+# 4. Use an ENTRYPOINT script to ensure OpenEB vars are loaded for ANY command you run
+ENTRYPOINT ["/bin/bash", "-c", "source /openeb/build/utils/scripts/setup_env.sh && exec \"$@\"", "--"]
+
+CMD ["pytest", "benchmarks/", "--benchmark-group-by=param:fmt", \
+     "--benchmark-columns=mean,ops", "-q"]