https://github.com/zer0pa/zpe-ink
ZPE-Ink V0.0: DETERMINISTIC DIGITAL INK CODEC: .zpink Streams | Stroke Compression | 5x+ vs Float32 | Rust | WASM | Swift | C# Cross-Runtime
https://github.com/zer0pa/zpe-ink
apple-pencil artificial-intelligence codec compression computational-physics creative-coding cross-platform csharp digital-ink digital-writing handwriting-recognition human-computer-interaction lossless-compression machine-learning python rust stylus swift touch webassembly
Last synced: 3 months ago
JSON representation
ZPE-Ink V0.0: DETERMINISTIC DIGITAL INK CODEC: .zpink Streams | Stroke Compression | 5x+ vs Float32 | Rust | WASM | Swift | C# Cross-Runtime
- Host: GitHub
- URL: https://github.com/zer0pa/zpe-ink
- Owner: Zer0pa
- License: other
- Created: 2026-03-09T13:32:09.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-24T21:33:51.000Z (3 months ago)
- Last Synced: 2026-04-24T22:37:14.998Z (3 months ago)
- Topics: apple-pencil, artificial-intelligence, codec, compression, computational-physics, creative-coding, cross-platform, csharp, digital-ink, digital-writing, handwriting-recognition, human-computer-interaction, lossless-compression, machine-learning, python, rust, stylus, swift, touch, webassembly
- Language: Python
- Homepage: https://www.zer0pa.ai
- Size: 5.93 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# ZPE-Ink
ZPE-Ink is an always-in-beta `.zpink` digital-ink codec — one of 17 independent encoding products in the Zer0pa portfolio. Every claim in this README is anchored to a committed proof artifact or CI test in this repository.
License: see `LICENSE`.
## What This Is
ZPE-Ink encodes and decodes deterministic `.zpink` stroke packets in Python, with 0.0 Hausdorff error on all measured datasets and bit-exact roundtrip fidelity backed by committed benchmark artifacts. The public proof surface covers:
- lossless encode/decode roundtrip for generated stroke fixtures
- CRC and truncated-payload rejection
- optional pressure, tilt, and azimuth channel handling
- static binding-contract consistency across the Python, PyO3, WASM, Swift, and C# surfaces
The committed public benchmark artifacts are in `proofs/` and their compression-ratio results are surfaced below. CI does not rerun those external corpora; the benchmark rows are static committed artifacts.
## Encoding Contract
| Claim | Proof artifact | CI test |
|---|---|---|
| `.zpink` lossless roundtrip is bit-exact for generated fixtures | `proofs/logs/20260321_technical_alignment_pytest.txt` | `code/tests/test_codec_roundtrip.py::test_lossless_roundtrip_bit_exact` |
| Corrupted or truncated payloads are rejected | `proofs/logs/20260321_technical_alignment_pytest.txt` | `code/tests/test_codec_roundtrip.py::test_crc_tamper_detection`, `code/tests/test_codec_roundtrip.py::test_reject_truncated_payload` |
| zero-valued optional channels can be omitted without changing decoded strokes | `proofs/logs/20260321_technical_alignment_pytest.txt` | `code/tests/test_codec_roundtrip.py::test_zero_optional_channels_are_omitted_by_default` |
| binding headers and package version are contract-consistent | `proofs/logs/20260321_technical_alignment_binding_contracts.json` | `code/tests/test_binding_contracts.py::test_repo_binding_contracts_pass` |
| CLI demo and roundtrip entry points execute | `proofs/logs/20260321_technical_alignment_wheel_install.txt` | `code/tests/test_cli.py` |
## Public Benchmark Results
These rows are committed static artifacts. The codec ran `encode → decode → verify` on each dataset using the repo-local lossless path. CI does not rerun these external corpora; results are bounded to the sample sizes shown.
| Dataset | Samples | Compression ratio | Max Hausdorff (px) | Roundtrip fidelity | Proof artifact |
|---|---:|---:|---:|---|---|
| UJI Pen Characters | 1,364 | **1.6111×** | 0.0 | exact | `proofs/reruns/phase3_public_benchmarks/phase3_public_benchmarks.json` |
| CROHME (ICFHR package) | 90 | **1.4360×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| DigiLeTs | 180 | **1.0891×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| MathWriting excerpt | 70 | **1.1870×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| QuickDraw (cat) | 256 | **1.0181×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| IAM On-Line | — | — | — | skipped: registration-gated | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| UNIPEN | — | — | — | skipped: host unavailable | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
Baseline: raw little-endian float32 x/y pairs per point. Hausdorff = 0.0 on all measured datasets means decoded coordinates match the source integers exactly.
**Zero-channel suppression improvement (committed):** auto-suppressing zero tilt/azimuth streams raised CROHME mean compression from 1.52× to 1.76× (max 3.34×) and MathWriting mean from 1.06× to 1.15×. This change is captured in `proofs/artifacts/mathwriting_analysis/comparison.json` and exercised by `code/tests/test_codec_roundtrip.py::test_zero_optional_channels_are_omitted_by_default`.
Encode latency on the measured corpora: median 0.02–0.10 ms/stroke (single-core Python, macOS; QuickDraw low end 0.026 ms/stroke, MathWriting high end 0.099 ms/stroke). Source: `proofs/artifacts/public_benchmarks/dataset_matrix.json` (`median_ms_per_stroke` field).
These results do not constitute a hard-corpus pass, release-readiness claim, or competitive superiority claim. See `proofs/artifacts/public_benchmarks/README.md` for full methodology notes.
## Commercial Readiness
| Field | Value |
|---|---|
| Verdict | `STAGED` |
| Posture | No release-readiness or hard-corpus authority claim is made. Public benchmark rows are lossless-path results against raw float32 baseline only; no named external codec comparison is claimed. |
| Release validation | `proofs/release_validation/README.md` |
## What We Do Not Claim
- No claim of release readiness
- No claim of blind-clone closure
- No claim of hard-corpus pass
- No claim of general digital-ink dominance
- No claim that the public benchmark rows close release readiness or hard-corpus authority
- No claim that local binding-contract checks prove full runtime parity for every downstream environment
- No claim that committed compression ratios on the above datasets constitute superiority over general-purpose codecs on those corpora
## Quick Start
Development install:
```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e './code[dev]'
python -m pytest code/tests -q
python -m zpe_ink demo
python -m zpe_ink verify-roundtrip
```
Package build:
```bash
python -m build
```
## Repository Links
| Field | Value |
|---|---|
| Repository | `https://github.com/Zer0pa/ZPE-Ink` |
| Issues | `https://github.com/Zer0pa/ZPE-Ink/issues` |
| License | SAL v7.0 — see `LICENSE` |
| Contact | `architects@zer0pa.ai` |