evutils 0.3.0__tar.gz → 0.3.6__tar.gz

evutils-0.3.6/.dockerignore

@@ -0,0 +1,15 @@
+# Keep the Docker build context small (used by benchmarks/docker/Dockerfile.openeb).
+.venv
+build
+.git
+.github
+data
+*.raw
+.benchmarks
+.pytest_cache
+__pycache__
+*.pyc
+docs
+dist
+*.prof
+*.svg

{evutils-0.3.0 → evutils-0.3.6}/.github/workflows/release.yaml

@@ -15,10 +15,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v8.2.0 
         with:
           enable-cache: true
 
@@ -49,15 +49,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v8.2.0 
         with:
           enable-cache: true
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.10"
 
@@ -71,10 +71,10 @@ jobs:
           make html
 
       - name: Setup GitHub Pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@v6
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: 'docs/build/html'
 

evutils-0.3.6/.github/workflows/test.yaml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  push:
+    branches: [main, feature/*, fix/*]
+  pull_request:
+    branches: [main, feature/*, fix/*]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0   # pin to a full version — see note below
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+
+      - name: Install the project
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest -s -v

evutils-0.3.6/.gitignore

@@ -0,0 +1,55 @@
+# Python build artifacts
+__pycache__
+build
+*.egg-info
+*.pyd
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+
+# C build artifacts
+*.so
+*.o
+*.obj
+*.dylib
+
+# Data and models
+data
+models
+
+# Venvs
+.venv/
+venv/
+env
+
+# Event types
+*.csv
+*.h5
+*.raw
+*.bias
+*.dat
+*.txt
+*.tmp_index
+*.svg
+*.data
+*.png
+*.jpg
+
+# Profiling
+*.prof
+*.old
+
+*.json
+
+# Miscellaneous
+test.py
+*.ipynb
+
+# IDE and OS
+.vscode
+.idea
+.DS_Store
+
+

{evutils-0.3.0 → evutils-0.3.6}/CMakeLists.txt

@@ -12,8 +12,6 @@ endif()
 
 # --- Sources ----------------------------------------------------------------
 # Compile every .c under csrc/. CONFIGURE_DEPENDS re-globs when files are
-# added/removed so dropping in evt3.c / evt2.c / ... needs no edit here.
-# (If you prefer an explicit list for reproducibility, replace this glob.)
 file(GLOB EVUTILS_SOURCES CONFIGURE_DEPENDS
      "${CMAKE_CURRENT_SOURCE_DIR}/csrc/*.c")
 

evutils-0.3.6/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.1
+Name: evutils
+Version: 0.3.6
+Summary: Utilities for event-based vision
+Keywords: events,dvs,neuromorphic,vision,event-based
+Author-Email: Jakub Mandula <jakub.mandula@pbl.ee.ethz.ch>
+License: Copyright (c) 2024 Jakub Mandula
+         
+         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.
+Project-URL: Source Code, https://github.com/mandulaj/evutils
+Project-URL: Documentation, https://mandulaj.github.io/evutils/
+Project-URL: Bug Tracker, https://github.com/mandulaj/evutils/issues
+Project-URL: Homepage, https://mandulaj.github.io/evutils/
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: opencv-python>=4.2
+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"
+Provides-Extra: vis
+Requires-Dist: matplotlib>=3.1; 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"
+Provides-Extra: compare
+Requires-Dist: expelliarmus>=1.1.0; extra == "compare"
+Requires-Dist: evlib; extra == "compare"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0.0; extra == "docs"
+Requires-Dist: sphinx-autoapi>=3.6.1; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=3.0.1; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3.1.0; extra == "docs"
+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"
+Provides-Extra: dev
+Requires-Dist: evutils[all,docs,test]; extra == "dev"
+Description-Content-Type: text/markdown
+
+# <a href="https://mandulaj.github.io/evutils"><img src="https://mandulaj.github.io/evutils/_static/event_hexagon_broken.webp" alt="evutils_logo" width="50" align="top" style="background-color: #fff0;"></a> EV-Utils
+[![PyPI Version](https://img.shields.io/pypi/v/evutils)](https://pypi.org/project/evutils/)
+[![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.
+
+
+
+### Inspirations & Related Work 
+This project draws inspiration from several excellent libraries in the event-based vision ecosystem and attempts to fill in their shortcomings:
+
+* [Tonic](https://github.com/neuromorphs/tonic)
+* [event_utils](https://github.com/TimoStoff/event_utils)
+* [evlib](https://github.com/tallamjr/evlib)
+* [expelliarmus](https://github.com/open-neuromorphic/expelliarmus)
+* [openeb](https://github.com/prophesee-ai/openeb)
+
+
+## Installation
+We recommend installing `evutils` using `uv`.
+### From PyPi
+```bash
+uv add evutils[all]
+```
+
+### From Git
+```bash
+git clone --recurse-submodules https://github.com/mandulaj/evutils.git
+cd evutils
+
+uv pip install -e ".[dev]"
+```
+
+Note: You can also install specific optional dependency groups like `uv add evutils[torch,hdf5]`.
+
+## Architecture
+The library is divided into several discrete modules. Many can be used independently without installing the full suite of dependencies:
+
+```
+└── augment     - Event augmentations
+└── dataset     - Wrappers for various dataset loaders
+└── events      - Core event handling logic
+└── io          - Event reading and writing interfaces
+    ├── reader 
+    └── writer
+└── random      - Random event generation and noise injection
+└── torch       - PyTorch integration (requires evutils[torch])
+└── types       - Standard types for representing Events in NumPy arrays
+└── vis         - Visualization methods
+    ├── histogram
+    └── reconstructor
+```
+
+### Quick API overview 
+
+<!-- ### `augment`
+
+Event augmentations
+
+### `dataset`
+
+Wrappers for various dataset loaders -->
+
+#### `io`: Reading and Writing Events
+
+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.
+
+```python
+from evutils.io import EventReader
+
+
+ev_file = EventReader("raw_file.raw", delta_t=10e3)
+
+events = ev_file.read()
+
+```
+
+#### `utils`
+
+Various utility functions
+
+#### `random`
+
+Generating random events and adding noise to event recordings
+
+#### `types`
+
+This provides several standard types for representing Events in numpy arrays
+
+
+#### `vis`
+
+The `vis` moduels provides several methods for visualizing the events (for example as histograms), but also provides a streamlined interface for more complex visualization techneques, such as using the [E2Vid](https://github.com/uzh-rpg/rpg_e2vid) reconstructor.
+
+
+```python
+from evutils.vis.reconstructor import RPG_Reconstructor
+
+reconstructor = RPG_Reconstructor(1280, 720)
+
+img = reconstructor.gen_frame(events)
+
+```
+
+## Running tests
+
+Tests are managed via `pytest`. If you installed the package with the `[dev]` or `[test]` flag, you can run them via:
+```bash
+uv run pytest -s
+```
+
+
+## [Benchmarks](benchmarks/README.md)
+
+Read/write throughput benchmarks (using [pytest-benchmark](https://pytest-benchmark.readthedocs.io)) live in `benchmarks/` and are kept out of the normal test run. Run them explicitly:
+
+```bash
+uv run pytest benchmarks/                                   # evutils only
+uv run pytest benchmarks/ --benchmark-group-by=param:fmt    # compare libraries per format
+```
+
+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.)
+
+
+## Acknowledgements
+
+Thanks to all the contributors for supporting this project:
+
+* Elia Franc
+* Jakub Mandula
+
+
+## Cite
+```bibtex
+@PhDThesis{2024mandula_evutils,
+  author        = {Jakub Mandula},
+  title         = {EV-Utils: collection of utilities for working with event-based vision data},
+  school        = {Dept. of Information Technology and Electrical Engineering, ETH Zurich},
+  year          = 2024
+}
+```

evutils-0.3.6/README.md

@@ -0,0 +1,162 @@
+# <a href="https://mandulaj.github.io/evutils"><img src="https://mandulaj.github.io/evutils/_static/event_hexagon_broken.webp" alt="evutils_logo" width="50" align="top" style="background-color: #fff0;"></a> EV-Utils
+[![PyPI Version](https://img.shields.io/pypi/v/evutils)](https://pypi.org/project/evutils/)
+[![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.
+
+
+
+### Inspirations & Related Work 
+This project draws inspiration from several excellent libraries in the event-based vision ecosystem and attempts to fill in their shortcomings:
+
+* [Tonic](https://github.com/neuromorphs/tonic)
+* [event_utils](https://github.com/TimoStoff/event_utils)
+* [evlib](https://github.com/tallamjr/evlib)
+* [expelliarmus](https://github.com/open-neuromorphic/expelliarmus)
+* [openeb](https://github.com/prophesee-ai/openeb)
+
+
+## Installation
+We recommend installing `evutils` using `uv`.
+### From PyPi
+```bash
+uv add evutils[all]
+```
+
+### From Git
+```bash
+git clone --recurse-submodules https://github.com/mandulaj/evutils.git
+cd evutils
+
+uv pip install -e ".[dev]"
+```
+
+Note: You can also install specific optional dependency groups like `uv add evutils[torch,hdf5]`.
+
+## Architecture
+The library is divided into several discrete modules. Many can be used independently without installing the full suite of dependencies:
+
+```
+└── augment     - Event augmentations
+└── dataset     - Wrappers for various dataset loaders
+└── events      - Core event handling logic
+└── io          - Event reading and writing interfaces
+    ├── reader 
+    └── writer
+└── random      - Random event generation and noise injection
+└── torch       - PyTorch integration (requires evutils[torch])
+└── types       - Standard types for representing Events in NumPy arrays
+└── vis         - Visualization methods
+    ├── histogram
+    └── reconstructor
+```
+
+### Quick API overview 
+
+<!-- ### `augment`
+
+Event augmentations
+
+### `dataset`
+
+Wrappers for various dataset loaders -->
+
+#### `io`: Reading and Writing Events
+
+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.
+
+```python
+from evutils.io import EventReader
+
+
+ev_file = EventReader("raw_file.raw", delta_t=10e3)
+
+events = ev_file.read()
+
+```
+
+#### `utils`
+
+Various utility functions
+
+#### `random`
+
+Generating random events and adding noise to event recordings
+
+#### `types`
+
+This provides several standard types for representing Events in numpy arrays
+
+
+#### `vis`
+
+The `vis` moduels provides several methods for visualizing the events (for example as histograms), but also provides a streamlined interface for more complex visualization techneques, such as using the [E2Vid](https://github.com/uzh-rpg/rpg_e2vid) reconstructor.
+
+
+```python
+from evutils.vis.reconstructor import RPG_Reconstructor
+
+reconstructor = RPG_Reconstructor(1280, 720)
+
+img = reconstructor.gen_frame(events)
+
+```
+
+## Running tests
+
+Tests are managed via `pytest`. If you installed the package with the `[dev]` or `[test]` flag, you can run them via:
+```bash
+uv run pytest -s
+```
+
+
+## [Benchmarks](benchmarks/README.md)
+
+Read/write throughput benchmarks (using [pytest-benchmark](https://pytest-benchmark.readthedocs.io)) live in `benchmarks/` and are kept out of the normal test run. Run them explicitly:
+
+```bash
+uv run pytest benchmarks/                                   # evutils only
+uv run pytest benchmarks/ --benchmark-group-by=param:fmt    # compare libraries per format
+```
+
+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.)
+
+
+## Acknowledgements
+
+Thanks to all the contributors for supporting this project:
+
+* Elia Franc
+* Jakub Mandula
+
+
+## Cite
+```bibtex
+@PhDThesis{2024mandula_evutils,
+  author        = {Jakub Mandula},
+  title         = {EV-Utils: collection of utilities for working with event-based vision data},
+  school        = {Dept. of Information Technology and Electrical Engineering, ETH Zurich},
+  year          = 2024
+}
+```

evutils-0.3.6/benchmarks/README.md

@@ -0,0 +1,102 @@
+# Benchmarks
+
+Read/write throughput benchmarks for the native EVT2 / EVT2.1 / EVT3 codecs,
+plus optional comparisons against other event libraries.
+
+They are **not** part of the normal test run (`testpaths = ["tests"]`); run them
+explicitly:
+
+```bash
+pytest benchmarks/                       # evutils only (+ any installed compare libs)
+pytest benchmarks/test_read.py           # just reads
+pytest benchmarks/test_write.py          # just writes
+```
+
+Fixtures (`test_events`, `real_event_files`) are shared with the test suite from
+the repo-root `conftest.py`. `real_event_files` downloads the reference
+recordings to the pytest cache on first use.
+
+## Files
+
+| file | what it benchmarks |
+|------|--------------------|
+| `test_read.py`    | evutils decode throughput (evt2/evt21/evt3), asserts count vs reference |
+| `test_write.py`   | evutils encode throughput (payload = first 5M events of the real evt3 file) |
+| `test_compare.py` | third-party readers from `readers.py` (auto-skip if not installed) |
+| `readers.py`      | adapter registry — one entry per external library |
+
+## 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, so an uninstalled (or broken) library
+just **skips**. To add another library, append a `Reader(...)` to `readers.py`.
+
+> tonic is intentionally not included: it has no standalone EVT reader and reads
+> Prophesee data through `expelliarmus` internally, so it would just re-measure
+> expelliarmus (already benchmarked).
+
+## 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 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
+
+Persist the downloaded recording across runs (otherwise `--rm` discards the
+pytest cache and it re-downloads every time):
+
+```bash
+docker run --rm -v evutils-cache:/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`, ...).