Metadata-Version: 2.4
Name: zpe-mocap
Version: 0.1.1
Summary: Zero-label structural motion search and compression. ZPE-MoCap deterministic codec/search package.
Author-email: "Zer0pa (Pty) Ltd" <architects@zer0pa.ai>
License-Expression: LicenseRef-Zer0pa-SAL-7.0
Project-URL: Homepage, https://github.com/Zer0pa/ZPE-Mocap
Project-URL: Documentation, https://github.com/Zer0pa/ZPE-Mocap#readme
Project-URL: Issues, https://github.com/Zer0pa/ZPE-Mocap/issues
Project-URL: Repository, https://github.com/Zer0pa/ZPE-Mocap
Keywords: motion-capture,skeletal-motion,bvh,motion-retrieval,motion-search,deterministic-codec
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: cmu
Requires-Dist: bvhio; extra == "cmu"
Provides-Extra: gates
Requires-Dist: comet_ml>=3.43; extra == "gates"
Requires-Dist: zstandard>=0.22; extra == "gates"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

<h1 align="center">ZPE-Mocap</h1>

<p align="center">
  <img src=".github/assets/readme/zpe-masthead.gif" alt="ZPE-Mocap Masthead" width="100%">
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-SAL%20v7.0-e5e7eb?labelColor=111111" alt="License: SAL v7.0"></a>
  <a href="code/README.md"><img src="https://img.shields.io/badge/python-reference%20implementation-e5e7eb?labelColor=111111" alt="Python reference implementation"></a>
  <a href="proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md"><img src="https://img.shields.io/badge/current%20authority-CMU%20retrieval-e5e7eb?labelColor=111111" alt="Current authority: CMU retrieval"></a>
  <a href="docs/LEGAL_BOUNDARIES.md"><img src="https://img.shields.io/badge/lane%20boundaries-retrieval%20not%20playback-e5e7eb?labelColor=111111" alt="Lane boundaries: retrieval, not playback"></a>
</p>

---

## What This Is

ZPE-Mocap is a deterministic motion fingerprinting and retrieval codec for skeletal motion data — one lane in Zer0pa's 17-lane ZPE encoding portfolio. The design target is compact, indexable motion fingerprints from BVH archives, not playback-grade reconstruction. Encoding is lossy by design; retrieval fidelity is the primary proof surface.

**Headline result (CI-anchored, real data):** mean 18.77× compression vs raw BVH float32 on 10 real CMU corpus clips. A synthetic-fixture ACL comparator (57.03× ZPE-Mocap vs 19.15× ACL medium, 10 synthetic clips, not CI-gated) sets an orientation ceiling but is not the aggregate claim. Both are documented in full below with scope boundaries.

The committed front door covers: canonical walk fixture integrity, suffix-index retrieval stability, edge-case decode coverage, and the 10-clip CMU fixture manifest.

## CI-Verified Surface

| Surface | Backing artifact | CI path |
|--------|------------------|---------|
| Canonical walk payload is byte-stable. | `code/tests/fixtures/canonical_walk.json`, `code/tests/fixtures/canonical_walk_compressed.bin` | `code/tests/test_roundtrip.py::test_canonical_walk_payload_matches_committed_binary` |
| Canonical walk roundtrip remains numerically stable against the committed fixture. | `code/tests/fixtures/canonical_walk_roundtrip.json` | `code/tests/test_roundtrip.py::test_canonical_walk_roundtrip_matches_committed_json` |
| Exact retrieval over the committed compressed walk fixture remains stable. | `code/tests/fixtures/canonical_walk.json`, `code/tests/fixtures/canonical_walk_compressed.bin` | `code/tests/test_search.py::test_retrieves_exact`, `code/tests/test_search.py::test_queries_compressed_library` |
| Search ranking and retrieval metric primitives used by the CMU benchmark remain covered. | `code/zpe_mocap/search.py`, `code/zpe_mocap/metrics.py`, `code/scripts/benchmark_cmu_retrieval.py` | `code/tests/test_search.py`, `code/tests/test_metrics.py` |
| The committed CMU fixture manifest remains fixed to the 10 checked-in BVH clips. | `code/fixtures/cmu/manifest.json`, `code/fixtures/cmu/bvh/*.bvh` | `code/tests/test_cmu_offline.py::test_manifest_matches_committed_fixture_set` |

## CMU Corpus Compression

**Primary compression authority.** Ratios measured against real CMU mocap data (10 fixture clips, cgspeed MotionBuilder-friendly BVH conversion, 2010). Basis: raw BVH float32 bytes. Reconstruction fidelity (MPJPE) is not a design target and is not claimed here.

| Field | Value | Proof |
|-------|-------|-------|
| Mean compression ratio vs raw BVH float32 | **18.77×** | [`results.json`](proofs/artifacts/2026-04-14_cmu_corpus_benchmark/results.json) |
| Compression ratio range | 15.22×–22.98× | [`results.json`](proofs/artifacts/2026-04-14_cmu_corpus_benchmark/results.json) |
| Clip count | 10 (walk, run, hop, combat, swim, calisthenics) | [`summary.md`](proofs/artifacts/2026-04-14_cmu_corpus_benchmark/summary.md) |
| Corpus | CMU MoCap database via cgspeed BVH conversion (2010) | [`results.json`](proofs/artifacts/2026-04-14_cmu_corpus_benchmark/results.json) |

## CMU Retrieval Benchmark

The current retrieval authority is the 2026-04-24 CMU held-out-window benchmark. Scope: same-source clip retrieval across non-overlapping windows, not playback-grade reconstruction and not semantic action retrieval.

| Field | Value | Proof |
|-------|-------|-------|
| Verdict | PASS for retrieval/indexing scope | [`summary.md`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md) |
| Corpus | 24 scanned BVH files, 24 clips used | [`results.json`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/results.json) |
| Relevance target | Same source clip across held-out non-overlapping windows | [`summary.md`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md) |
| Recall@1 | 0.125000 (3.0× random baseline of 0.042) | [`results.json`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/results.json) |
| Recall@5 | 0.416667 | [`summary.md`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md) |
| Recall@10 | 0.583333 | [`summary.md`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md) |
| Mean reciprocal rank | 0.277189 | [`summary.md`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md) |
| Median rank | 6.0 | [`summary.md`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md) |
| Latency p50 | 0.826 ms | [`results.json`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/results.json) |
| Latency p95 | 0.869 ms | [`summary.md`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md) |
| Latency p99 | 1.191 ms | [`results.json`](proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/results.json) |

## ACL Direct Compression Comparator

**Secondary comparator — synthetic fixture, not CI-gated.** This comparator runs on 10 synthetic clips (wave 1 fixture), not CMU real data. ZPE-Mocap is a fingerprinting codec (lossy by design) while ACL targets playback-grade reconstruction. The comparison is compression-ratio-only and does not imply equivalent reconstruction quality. Do not treat this as the aggregate compression claim — that is the 18.77× CMU figure above.

| Codec | Mean ratio vs raw BVH float32 | ACL level | Corpus | Proof |
|-------|-------------------------------|-----------|--------|-------|
| ZPE-Mocap | 57.03× | n/a (fingerprinting) | 10 synthetic clips | [`acl_direct_comparator_table.json`](proofs/artifacts/2026-02-20_zpe_mocap_wave1/acl_direct_comparator_table.json) |
| ACL (Animation Compression Library) | 19.15× | medium | same 10 synthetic clips | [`acl_direct_comparator_table.json`](proofs/artifacts/2026-02-20_zpe_mocap_wave1/acl_direct_comparator_table.json) |

ACL reference: [github.com/nfrechette/acl](https://github.com/nfrechette/acl). ACL binary was built locally from source and run directly; the ratio is measured against the same raw BVH float32 baseline. This result is not CI-gated and is bounded to the wave 1 synthetic fixture.

## Tests and Verification

| Code | Check | Verdict |
|------|-------|---------|
| T_01 | Canonical walk payload matches committed binary fixture | PASS |
| T_02 | Canonical walk roundtrip matches committed JSON fixture within numerical tolerance | PASS |
| T_03 | Synthetic encode/decode threshold smoke path | PASS |
| T_04 | Suffix-index exact retrieval remains stable | PASS |
| T_05 | Retrieval metric helpers used by the CMU benchmark remain stable | PASS |
| T_06 | CMU fixture manifest remains fixed to the committed 10-clip set | PASS |
| T_07 | Decode edge cases preserve expected shapes and fps | PASS |

## Evidence On Disk

| Path | State |
|------|-------|
| `proofs/artifacts/2026-04-14_cmu_corpus_benchmark/results.json` | PRESENT |
| `proofs/artifacts/2026-04-14_cmu_corpus_benchmark/summary.md` | PRESENT |
| `proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/results.json` | PRESENT |
| `proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/summary.md` | PRESENT |
| `proofs/artifacts/2026-02-20_zpe_mocap_wave1/mocap_compression_benchmark.json` | PRESENT |
| `proofs/artifacts/2026-02-20_zpe_mocap_wave1/mocap_joint_fidelity.json` | PRESENT |
| `proofs/artifacts/2026-02-20_zpe_mocap_wave1/mocap_search_eval.json` | PRESENT |
| `proofs/artifacts/2026-02-20_zpe_mocap_wave1/mocap_query_latency.json` | PRESENT |
| `proofs/artifacts/2026-02-20_zpe_mocap_wave1/acl_direct_comparator_table.json` | PRESENT |

## Repo Shape

| Field | Value |
|-------|-------|
| Evidence Bundles | 3 |
| Modality Lanes | 1 |
| CI Front Door | fixture-backed encode/decode, retrieval, and metric-helper checks |

- `code/`: Python reference implementation and repo-local tests.
- `proofs/artifacts/2026-02-20_zpe_mocap_wave1/`: historical synthetic ceiling bundle.
- `proofs/artifacts/2026-04-14_cmu_corpus_benchmark/`: checked-in CMU fixture benchmark bundle.
- `proofs/artifacts/2026-04-24_cmu_retrieval_benchmark/`: current CMU retrieval authority bundle.
- `docs/`: architecture and legal-boundary notes.
- `proofs/logs/`, `proofs/source_refs/`: lineage and source-reference material.

## Quick Start

```bash
git clone https://github.com/Zer0pa/ZPE-Mocap.git
cd ZPE-Mocap
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ./code
python -m unittest discover -s code/tests -v
```

Smoke check:

```bash
python - <<'PY'
from zpe_mocap.codec import decode_zpmoc, encode_clip
from zpe_mocap.synthetic import generate_clip

clip = generate_clip(
    clip_id="readme_smoke",
    label="walk",
    frames=120,
    fps=60,
    seed=20260220,
    noise_scale=0.0002,
)
enc = encode_clip(clip, seed=20260220)
dec = decode_zpmoc(enc.payload)
print(enc.compression_ratio, dec.clip_id)
PY
```

The checked-in benchmark bundles under `proofs/artifacts/` remain available for manual inspection. Promoted metrics above are bounded to retrieval/indexing scope. Read [docs/LEGAL_BOUNDARIES.md](docs/LEGAL_BOUNDARIES.md) before turning any artifact in this repo into a broader playback or commercial claim.
