evutils 0.3.0__tar.gz

evutils-0.3.0/.github/workflows/release.yaml

@@ -0,0 +1,83 @@
+name: Release & Publish Docs
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write      # Required for modern PyPI publishing and GitHub Pages deployment
+  pages: write         # Required for GitHub Pages deployment
+
+jobs:
+  build-and-publish-pypi:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build tools
+        run: uv pip install --system build cibuildwheel
+
+      - name: Build source distribution (sdist)
+        run: python -m build --sdist
+
+      - name: Build compiled wheels (cibuildwheel)
+        run: python -m cibuildwheel --output-dir dist
+        env:
+          CIBW_SKIP: "cp36-* cp37-* cp38-* cp39-* pp* *musllinux*"
+          CIBW_BUILD_FRONTEND: "build[uv]"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+  build-and-publish-docs:
+    name: Build & Publish Sphinx Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install package and docs dependencies
+        # uv compiles the C extension locally and installs dependencies instantly
+        run: uv pip install --system .[docs]
+
+      - name: Build Sphinx HTML
+        run: |
+          cd docs
+          make html
+
+      - name: Setup GitHub Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/build/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,35 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+      - feature/*
+      - fix/*
+  pull_request:
+    branches:
+      - main
+      - feature/*
+      - fix/*
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Download submoduels
+        run: git submodule update --init --recursive
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install Pytests and any other packages
+        run: pip install pytest
+      - name: Install package
+        run: pip install .
+      - name: Run Tests
+        run: pytest -s -v

evutils-0.3.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__
+build
+*.egg-info
+_version.py
+data
+models
+
+# Event types
+*.csv
+*.h5
+*.raw
+*.bias
+*.dat
+*.txt
+*.tmp_index
+*.prof
+*.svg
+*.data
+*.png
+*.jpg
+
+*.json
+
+test.py
+*.ipynb

evutils-0.3.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vis/rpg_e2vid"]
+	path = src/evutils/vis/reconstructor/rpg_e2vid
+	url = https://github.com/mandulaj/rpg_e2vid.git

evutils-0.3.0/CMakeLists.txt

@@ -0,0 +1,53 @@
+cmake_minimum_required(VERSION 3.18)
+project(evutils_native LANGUAGES C)
+
+# --- Standard / flags -------------------------------------------------------
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
+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")
+
+add_library(evutils_native SHARED ${EVUTILS_SOURCES})
+
+target_include_directories(evutils_native
+    PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/csrc/include")
+
+set_target_properties(evutils_native PROPERTIES
+    OUTPUT_NAME "evutils_native"
+    # Export all symbols on Windows without needing __declspec annotations.
+    # (For a curated public ABI later, switch to an explicit export macro.)
+    WINDOWS_EXPORT_ALL_SYMBOLS ON)
+
+if(MSVC)
+  target_compile_options(evutils_native PRIVATE /O2 /W3)
+else()
+  target_compile_options(evutils_native PRIVATE
+      -O3 -Wall -Wextra
+      $<$<CONFIG:Debug>:-O0 -g>)
+endif()
+
+# --- Install ----------------------------------------------------------------
+# When built through scikit-build-core (i.e. via `uv build` / pip), drop the
+# shared library *inside* the python package directory in the wheel, so the
+# ctypes loader finds it next to evutils/__init__.py.
+if(DEFINED SKBUILD_PROJECT_NAME)
+  install(TARGETS evutils_native
+          LIBRARY DESTINATION "${SKBUILD_PROJECT_NAME}"
+          RUNTIME DESTINATION "${SKBUILD_PROJECT_NAME}")
+else()
+  # Standalone `cmake --build build` leaves the .so in build/ where the
+  # loader's dev-mode search also looks.
+  install(TARGETS evutils_native
+          LIBRARY DESTINATION lib
+          RUNTIME DESTINATION bin)
+endif()

evutils-0.3.0/LICENSE

@@ -0,0 +1,19 @@
+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.

evutils-0.3.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.1
+Name: evutils
+Version: 0.3.0
+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.
+Requires-Python: >=3.10
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: tqdm>=4.41
+Requires-Dist: matplotlib>=3.1
+Requires-Dist: opencv-python>=4.2
+Requires-Dist: numba>=0.57
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: pandas>=2.3.3
+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: test
+Requires-Dist: pytest>=9.0.2; extra == "test"
+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: dev
+Requires-Dist: evutils[docs,hdf5,test,torch]; extra == "dev"
+Description-Content-Type: text/markdown
+
+EV Utils
+========
+
+EV-utils is a collection of utilities for working event based data inspired by the [event_utils](https://github.com/TimoStoff/event_utils) library. This library aims at being camera independent (yet also supporting specific camera vendors) with minimal dependencies but also performent. The library is divided into severla modules some of which can be used without installing all the dependencies. These include:
+
+```
+└── augment - Event augmentations
+└── dataset - Wrappers for various dataset loaders
+└── events 
+└── io
+    ├── reader 
+    └── writer
+└── random
+└── torch
+└── types
+└── vis
+    ├── histogram
+    └── reconstructor
+```
+
+
+## Installation
+
+### From Git
+```bash
+git clone --recurse-submodules git@git.ee.ethz.ch:pbl/research/event-camera/evutils.git
+
+cd evutils
+pip install . 
+pip install -e . # Use this to install an editable version of the package
+```
+
+## Quick API overview 
+
+### `augment`
+
+Event augmentations
+
+### `dataset`
+
+Wrappers for various dataset loaders
+
+### `io`
+
+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.reader import EventReader_RAW
+
+
+ev_file = EventReader_RAW("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.
+
+You need to download the pretrained weights:
+```bash
+wget "http://rpg.ifi.uzh.ch/data/E2VID/models/E2VID_lightweight.pth.tar" -O models/E2VID_lightweight.pth.tar
+```
+
+
+```python
+from evutils.vis.reconstructor import RPG_Reconstructor
+
+reconstructor = RPG_Reconstructor(1280, 720)
+
+img = reconstructor.gen_frame(events)
+
+```
+
+## Running tests
+
+You can run tests on using the pytest utility:
+```bash
+pytest -s
+```
+
+
+## Acknowledgements
+
+Thanks to all the contributors for supporting this project:
+
+* Elia Franc
+* Jakub Mandula

evutils-0.3.0/README.md

@@ -0,0 +1,102 @@
+EV Utils
+========
+
+EV-utils is a collection of utilities for working event based data inspired by the [event_utils](https://github.com/TimoStoff/event_utils) library. This library aims at being camera independent (yet also supporting specific camera vendors) with minimal dependencies but also performent. The library is divided into severla modules some of which can be used without installing all the dependencies. These include:
+
+```
+└── augment - Event augmentations
+└── dataset - Wrappers for various dataset loaders
+└── events 
+└── io
+    ├── reader 
+    └── writer
+└── random
+└── torch
+└── types
+└── vis
+    ├── histogram
+    └── reconstructor
+```
+
+
+## Installation
+
+### From Git
+```bash
+git clone --recurse-submodules git@git.ee.ethz.ch:pbl/research/event-camera/evutils.git
+
+cd evutils
+pip install . 
+pip install -e . # Use this to install an editable version of the package
+```
+
+## Quick API overview 
+
+### `augment`
+
+Event augmentations
+
+### `dataset`
+
+Wrappers for various dataset loaders
+
+### `io`
+
+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.reader import EventReader_RAW
+
+
+ev_file = EventReader_RAW("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.
+
+You need to download the pretrained weights:
+```bash
+wget "http://rpg.ifi.uzh.ch/data/E2VID/models/E2VID_lightweight.pth.tar" -O models/E2VID_lightweight.pth.tar
+```
+
+
+```python
+from evutils.vis.reconstructor import RPG_Reconstructor
+
+reconstructor = RPG_Reconstructor(1280, 720)
+
+img = reconstructor.gen_frame(events)
+
+```
+
+## Running tests
+
+You can run tests on using the pytest utility:
+```bash
+pytest -s
+```
+
+
+## Acknowledgements
+
+Thanks to all the contributors for supporting this project:
+
+* Elia Franc
+* Jakub Mandula

evutils-0.3.0/csrc/evutils.c

@@ -0,0 +1,24 @@
+#include "evutils/evutils.h"
+
+#ifndef EVUTILS_VERSION
+#define EVUTILS_VERSION "0.0.1"
+#endif
+
+const char *evutils_version(void) {
+    return EVUTILS_VERSION;
+}
+
+size_t evutils_debug_fill_soa(event_buffer_soa_t *buf, uint64_t t0) {
+    if (!buf || !buf->t || !buf->x || !buf->y || !buf->p) {
+        return 0;
+    }
+    const size_t n = buf->capacity;
+    for (size_t i = 0; i < n; ++i) {
+        buf->t[i] = t0 + (uint64_t)i;
+        buf->x[i] = (uint16_t)(i % 640u);
+        buf->y[i] = (uint16_t)(i % 480u);
+        buf->p[i] = (uint8_t)(i & 1u);
+    }
+    buf->size = n;
+    return n;
+}

evutils-0.3.0/csrc/include/evutils/evt3.h

@@ -0,0 +1,69 @@
+/* evutils — EVT3 parser public interface.
+ *
+ * This declares the EVT3 ABI exactly as your parser already exposes it, plus
+ * three small lifecycle functions for the opaque parser state. Python never
+ * needs to know the layout of evt3_state_t — it only holds the pointer.
+ *
+ * ACTION REQUIRED in evt3.c: implement the three lifecycle functions below.
+ * They are thin wrappers around whatever you already do to zero-initialise
+ * your state struct, e.g.:
+ *
+ *     struct evt3_state_s { uint64_t ts; uint16_t y, vecbase_x; uint8_t vecbase_p; ... };
+ *     evt3_state_t *EVT3_state_create(void) { return calloc(1, sizeof(evt3_state_t)); }
+ *     void EVT3_state_reset(evt3_state_t *s) { memset(s, 0, sizeof(*s)); }
+ *     void EVT3_state_destroy(evt3_state_t *s) { free(s); }
+ */
+#ifndef EVUTILS_EVT3_H
+#define EVUTILS_EVT3_H
+
+#include "evutils/types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Returned by the chunk parsers to tell the caller why parsing stopped.
+ * NOTE: these values are a placeholder. If your evt3.c already defines this
+ * enum, delete this copy and include yours — but keep the Python side
+ * (_native.py) in sync with whatever the real values are. */
+typedef enum evt3_parse_status_e {
+    EVT3_STATUS_OK               = 0, /* reached end of input cleanly        */
+    EVT3_STATUS_INPUT_EXHAUSTED  = 1, /* ran out of input mid-group (carry)  */
+    EVT3_STATUS_OUTPUT_FULL      = 2, /* event/trigger buffer hit capacity   */
+    EVT3_STATUS_ERROR            = 3  /* malformed stream                    */
+} evt3_parse_status_t;
+
+/* Opaque parser state. Definition lives in evt3.c. */
+typedef struct evt3_state_s evt3_state_t;
+
+evt3_state_t *EVT3_state_create(void);
+void          EVT3_state_reset(evt3_state_t *state);
+void          EVT3_state_destroy(evt3_state_t *state);
+
+typedef struct evt3_input_buffer_s {
+    const uint16_t *begin;
+    const uint16_t *end;
+} evt3_input_buffer_t;
+
+typedef struct evt3_parser_result_s {
+    const uint16_t     *current;
+    evt3_parse_status_t status;
+} evt3_parser_result_t;
+
+evt3_parser_result_t EVT3_parse_chunk(
+    evt3_state_t            *state,
+    const evt3_input_buffer_t *input_buffer,
+    event_buffer_t          *event_buffer,
+    trigger_buffer_t        *trigger_buffer);
+
+evt3_parser_result_t EVT3_parse_chunk_soa(
+    evt3_state_t            *state,
+    const evt3_input_buffer_t *input_buffer,
+    event_buffer_soa_t      *event_buffer,
+    trigger_buffer_t        *trigger_buffer);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* EVUTILS_EVT3_H */

evutils-0.3.0/csrc/include/evutils/evutils.h

@@ -0,0 +1,30 @@
+/* evutils — library-level entry points.
+ *
+ * Small surface that does not belong to any one format: a version string and
+ * a debug probe used by the test suite to validate the Python <-> C SoA
+ * buffer hand-off without depending on a real parser being linked in yet.
+ */
+#ifndef EVUTILS_H
+#define EVUTILS_H
+
+#include "evutils/types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Returns a static, NUL-terminated version string. */
+const char *evutils_version(void);
+
+/* DEBUG ONLY. Fills `buf` with `buf->capacity` synthetic events:
+ *   t[i] = t0 + i,  x[i] = i % 640,  y[i] = i % 480,  p[i] = i & 1
+ * Sets buf->size and returns the number written. Lets the Python test
+ * confirm that numpy-allocated columns are written in place by C.
+ * Returns 0 if any column pointer is NULL. */
+size_t evutils_debug_fill_soa(event_buffer_soa_t *buf, uint64_t t0);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* EVUTILS_H */

evutils-0.3.0/csrc/include/evutils/types.h

@@ -0,0 +1,81 @@
+/* evutils — shared event/trigger/buffer types.
+ *
+ * This is the single source of truth for the C ABI that the Python ctypes
+ * layer mirrors (see src/evutils/_native.py). If you change a struct here,
+ * update the matching ctypes.Structure there.
+ *
+ * Layout notes (these matter for the Python bindings):
+ *   - event32_t is 12 bytes: t@0 (4), x@4 (2), y@6 (2), p@8 (1), + 3 pad.
+ *     The AoS numpy dtype must therefore use itemsize=12, not 9.
+ *   - The SoA buffer uses uint64 timestamps; the AoS event_t uses uint32.
+ *     (See the note in README about reconciling 32- vs 64-bit time.)
+ */
+#ifndef EVUTILS_TYPES_H
+#define EVUTILS_TYPES_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct event32_s {
+    uint32_t t;
+    uint16_t x;
+    uint16_t y;
+    uint8_t  p;
+} event32_t;
+
+typedef struct event64_s {
+    uint64_t t;
+    uint16_t x;
+    uint16_t y;
+    uint8_t  p;
+} event64_t;
+
+typedef event32_t event_t;
+
+typedef struct trigger64_s {
+    uint64_t t;
+    uint8_t  id;
+    uint8_t  p;
+} trigger64_t;
+
+typedef struct trigger32_s {
+    uint32_t t;
+    uint8_t  id;
+    uint8_t  p;
+} trigger32_t;
+
+typedef trigger32_t trigger_t;
+
+/* Struct-of-arrays event buffer (preferred for the numpy path: one dtype per
+ * column, no struct padding to reconcile). */
+typedef struct event_buffer_soa_s {
+    uint64_t *t;
+    uint16_t *x;
+    uint16_t *y;
+    uint8_t  *p;
+    size_t capacity;
+    size_t size;
+} event_buffer_soa_t;
+
+/* Array-of-structs event buffer. */
+typedef struct event_buffer_s {
+    event_t *events;
+    size_t capacity;
+    size_t size;
+} event_buffer_t;
+
+typedef struct trigger_buffer_s {
+    trigger_t *triggers;
+    size_t capacity;
+    size_t size;
+} trigger_buffer_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* EVUTILS_TYPES_H */