Metadata-Version: 2.4
Name: mfc-codec
Version: 0.3.29
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Summary: Mirror Fractal Codec — lossless compression for neuromorphic event camera data
Keywords: event-camera,dvs,neuromorphic,compression,lossless
Author-email: Aleksei Solonskii <info@mirrorfractal.com>
License: LicenseRef-Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Demo, https://codec.mirrorfractal.com
Project-URL: Homepage, https://codec.mirrorfractal.com
Project-URL: Issues, https://github.com/MirrorFractal/codec/issues
Project-URL: Repository, https://github.com/MirrorFractal/codec

# Mirror Fractal Codec

Lossless compression for neuromorphic event-camera data (DVS/ATIS).

**1.51 bits/event** · **47.6x compression** · **0.55 ms per N-MNIST sample**.

*Patent Pending — US Provisional #64/034,974*

## Install

```bash
pip install mfc-codec
```

Pre-built wheels for CPython 3.11 on Linux (manylinux_2_34 x86_64), macOS (arm64), and Windows (amd64).

## Quick start

```python
import mfc

events = mfc.load_nmnist("sample.bin")
compressed, stats = mfc.compress(events, width=34, height=34, t_bits=16, xy_bits=8)
print(f"{stats.compression_ratio:.1f}x, {stats.bits_per_event:.2f} bpe")

decoded = mfc.decompress(compressed)
assert events == decoded   # bit-exact, lossless
```

## Results

### N-MNIST (60,000 real samples, 34×34 sensor)

| Digit | Samples | Avg events | Ratio | bpe | Encode |
|-------|---------|------------|-------|-----|--------|
| Total | 60,000  | 4,172      | 47.6× | 1.51 | 0.55 ms |

### High-resolution synthetic

| Config    | Events | Raw       | Compressed | Ratio  | Encode |
|-----------|--------|-----------|------------|--------|--------|
| DVS128 500K | 500K | 4,395 KB  | 3.9 KB     | 1,117× | 4.9 ms |
| VGA 2M      | 2M   | 17,578 KB | 20.0 KB    | 878×   | 36.9 ms |
| HD 1M       | 1M   | 8,789 KB  | 8.5 KB     | 1,040× | 58.2 ms |

## Supported dataset formats

N-MNIST `.bin` · AEDAT 2.0 `.aedat` · DSEC HDF5 (Blosc/LZ4/zstd) · `.npy` · `.evb` · CSV · `.dat`/`.raw`

## Links

- **Live demo** — https://codec.mirrorfractal.com
- **Public repository (docs, examples, issues)** — https://github.com/MirrorFractal/codec
- **Paper / Zenodo deposit** — DOI: [10.5281/zenodo.19704064](https://doi.org/10.5281/zenodo.19704064)

## Citation

```bibtex
@software{mfc_codec_2026,
  author = {Solonskii, Aleksei},
  title  = {Mirror Fractal Codec: Lossless Compression for Neuromorphic Event Camera Streams},
  year   = {2026},
  doi    = {10.5281/zenodo.19704064},
  url    = {https://codec.mirrorfractal.com}
}
```

## License

Proprietary — all rights reserved. Patent Pending US 64/034,974.

Contact: info@mirrorfractal.com

