Metadata-Version: 2.4
Name: evlib
Version: 0.9.0
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Dist: numpy>=1.24.0
Requires-Dist: h5py>=3.8.0 ; sys_platform != 'win32'
Requires-Dist: hdf5plugin>=5.1.0 ; sys_platform != 'win32'
Requires-Dist: polars>=1.30.0
Requires-Dist: pyarrow>=21.0.0
Requires-Dist: pandera[polars]>=0.18.0
Requires-Dist: evlib[dev,duckdb,plot,jupyter,torch,pytorch] ; extra == 'all'
Requires-Dist: codecov ; extra == 'dev'
Requires-Dist: maturin ; extra == 'dev'
Requires-Dist: mike>=2.0.0 ; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5.0 ; extra == 'dev'
Requires-Dist: mkdocs-jupyter>=0.24.0 ; extra == 'dev'
Requires-Dist: mkdocs-material[imaging]>=9.5.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
Requires-Dist: pygments>=2.18.0 ; extra == 'dev'
Requires-Dist: nbmake ; extra == 'dev'
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-benchmark ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pytest-markdown-docs>=0.9.0 ; extra == 'dev'
Requires-Dist: pytest-xdist ; extra == 'dev'
Requires-Dist: tqdm>=4.67.1 ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: duckdb>=1.3.2 ; extra == 'duckdb'
Requires-Dist: jupyter>=1.0.0 ; extra == 'jupyter'
Requires-Dist: matplotlib>=3.7.0 ; extra == 'plot'
Requires-Dist: opencv-python>=4.8.0 ; extra == 'plot'
Requires-Dist: seaborn>=0.13.2 ; extra == 'plot'
Requires-Dist: torch>=2.0.0 ; extra == 'pytorch'
Requires-Dist: torch>=2.0.0 ; extra == 'torch'
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: duckdb
Provides-Extra: jupyter
Provides-Extra: plot
Provides-Extra: pytorch
Provides-Extra: torch
License-File: LICENSE.md
Summary: Python bindings for event camera utilities
Home-Page: https://github.com/tallamjr/evlib
Author-email: Tarek Allam <t.allam.jr@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<table align="center">
  <tr>
    <td>
      <img src="./docs/evlogo.png" width="70" alt="evlib logo" />
    </td>
    <td>
      <h1 style="margin: 0;">
        <code>evlib</code>: Event Camera Data Processing Library
      </h1>
    </td>
  </tr>
</table>

<div style="text-align: center;" align="center">

[![PyPI Version](https://img.shields.io/pypi/v/evlib.svg)](https://pypi.org/project/evlib/)
[![Python Versions](https://img.shields.io/pypi/pyversions/evlib.svg)](https://pypi.org/project/evlib/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://tallamjr.github.io/evlib/)
[![Python](https://github.com/tallamjr/evlib/actions/workflows/pytest.yml/badge.svg)](https://github.com/tallamjr/evlib/actions/workflows/pytest.yml)
[![Rust](https://github.com/tallamjr/evlib/actions/workflows/rust.yml/badge.svg)](https://github.com/tallamjr/evlib/actions/workflows/rust.yml)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue)](https://github.com/tallamjr/evlib)
[![License](https://img.shields.io/github/license/tallamjr/evlib)](https://github.com/tallamjr/evlib/blob/master/LICENSE.md)

</div>

An event camera processing library with a Rust backend and Python bindings,
designed for scalable data processing with real-world event camera datasets.

### Architecture

evlib keeps a thin Rust core and does all DataFrame work in Polars from Python:

- **Rust** (`evlib._evlib`) handles only what cannot be expressed as DataFrame
  operations: binary format parsing (EVT2/EVT3/EVT2.1, AEDAT, AER, HDF5 with the
  ECF codec), construction of the Polars frame from decoded primitives, and the
  dense scatter-add that builds RVT stacked-histogram representations.
- **Python Polars** handles all processing: loading filters, filtering
  (`evlib.filtering`), and representations (`evlib.representations`, `evlib.rvt`).
  Every query is a lazy Polars `LazyFrame` collected with a selectable engine, so
  the same code runs on the CPU streaming engine today and on the GPU via
  cudf-polars (`collect(engine="gpu")`) where CUDA is available.

`evlib.load_events` returns a `LazyFrame` and applies any time, spatial, or
polarity filters as Polars expressions, so loading and filtering fuse into one
GPU-collectable query.

**Full documentation:** <https://tallamjr.github.io/evlib/>

<!-- mtoc-start -->

- [Quick Start](#quick-start)
  - [What are Event Cameras?](#what-are-event-cameras)
  - [Basic Usage](#basic-usage)
- [Installation](#installation)
- [Documentation](#documentation)
- [Examples](#examples)
- [Development](#development)
- [Community & Support](#community--support)
- [License](#license)

<!-- mtoc-end -->

## Quick Start

![xkcd](https://imgs.xkcd.com/comics/the_best_camera.png)

### What are Event Cameras?

Event cameras (also called neuromorphic or dynamic vision sensors) operate
asynchronously: each pixel independently reports brightness changes as they
occur, rather than sampling frames at a fixed rate.

Each **event** is represented as a 4-tuple:

$$e = (x, y, t, p)$$

Where:

- $x, y \in \mathbb{N}$: Pixel coordinates
- $t \in \mathbb{R}^+$: Timestamp (microsecond precision)
- $p \in \{-1, +1\}$ or $\{0, 1\}$: Polarity (brightness change direction)

An event fires when the logarithmic brightness change exceeds a threshold:

$$\log(L(x,y,t)) - \log(L(x,y,t_{\text{last}})) > \pm C$$

where $C$ is the contrast threshold. This yields microsecond temporal
resolution, 120 dB+ dynamic range, and data sparsity proportional to scene
motion.

For a deeper introduction, see the
[user guide](https://tallamjr.github.io/evlib/user-guide/loading-data/).

<p align="center">
  <img src="./wasm/wasm-sim.png" width="480" height="320" alt="event data visualisation">
</p>

### Basic Usage

```python
import evlib

# Automatic format detection — returns a Polars LazyFrame
events = evlib.load_events("data/prophesee/samples/evt2/80_balls.raw")

df = events.collect(engine="streaming")
print(f"Loaded {len(df):,} events")
print(f"Resolution: {df['x'].max()} x {df['y'].max()}")
print(f"Duration:   {df['t'].max() - df['t'].min()}")
```

Chain Polars expressions for efficient filtering and representation extraction:

```python notest
import evlib
import evlib.representations as evr
import polars as pl

events = evlib.load_events("data/prophesee/samples/hdf5/pedestrians.hdf5")

# Temporal + spatial + polarity filtering, lazily
filtered = events.filter(
    (pl.col("t").dt.total_microseconds() / 1_000_000).is_between(0.1, 0.5)
    & pl.col("x").is_between(100, 500)
    & (pl.col("polarity") == 1)
)

# Produce a stacked histogram ready for an RVT-style model
hist = evr.create_stacked_histogram(
    filtered.collect(),
    height=180, width=240,
    bins=5, window_duration_ms=50.0,
)
```

See the [representations guide](https://tallamjr.github.io/evlib/user-guide/representations/)
for voxel grids, time surfaces, and mixed density stacks.

## Installation

```bash
# Basic install
pip install evlib

# With PyTorch integration
pip install evlib[pytorch]
```

From source (requires Rust nightly and `maturin`):

```bash
git clone https://github.com/tallamjr/evlib.git
cd evlib
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
maturin develop                    # default minimal build
maturin develop --features hdf5    # opt-in HDF5 support (Linux/macOS)
```

HDF5 is opt-in on Linux/macOS and unavailable on Windows — use `h5py` directly
for HDF5 I/O on Windows. Full details and platform-specific notes live in
the [installation guide](https://tallamjr.github.io/evlib/getting-started/installation/).

## Documentation

Complete documentation is published at <https://tallamjr.github.io/evlib/>:

- [Quick Start](https://tallamjr.github.io/evlib/getting-started/quickstart/)
- [Loading Data](https://tallamjr.github.io/evlib/user-guide/loading-data/) — formats, polarity encoding, streaming
- [Event Representations](https://tallamjr.github.io/evlib/user-guide/representations/)
- [Polars Preprocessing](https://tallamjr.github.io/evlib/user-guide/polars-preprocessing/)
- [Performance Guide](https://tallamjr.github.io/evlib/getting-started/performance/) — benchmarks, memory monitoring, troubleshooting
- [API Reference](https://tallamjr.github.io/evlib/api/core/)
- [Platform Support](https://tallamjr.github.io/evlib/platform-support/windows/)

## Examples

Runnable examples live in [`examples/`](./examples):

```bash
python examples/simple_example.py
python examples/filtering_demo.py
python examples/stacked_histogram_demo.py

# Jupyter notebooks
pytest --nbmake examples/
```

Benchmarks and performance scripts live in [`benches/`](./benches).

## Development

```bash
# Tests
pytest                        # Python
cargo test                    # Rust
pytest --markdown-docs docs/  # doc examples

# Formatting / linting
black python/ tests/ examples/
cargo fmt
ruff check python/ tests/
cargo clippy -- -D warnings
```

See [CONTRIBUTING](./docs/development/contributing.md) and the
[architecture overview](./docs/development/architecture.md) for design details.

## Community & Support

- [**Issues**](https://github.com/tallamjr/evlib/issues): Report bugs and request features

![xkcd](https://imgs.xkcd.com/comics/infrastructures.png)

## License

MIT License — see [LICENSE.md](LICENSE.md) for details.

