zpe-mocap 0.1.1

Zero-label structural motion search and compression. ZPE-MoCap deterministic codec/search package.

ZPE-Mocap

---

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
Compression ratio range	15.22×–22.98×	results.json
Clip count	10 (walk, run, hop, combat, swim, calisthenics)	summary.md
Corpus	CMU MoCap database via cgspeed BVH conversion (2010)	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
Corpus	24 scanned BVH files, 24 clips used	results.json
Relevance target	Same source clip across held-out non-overlapping windows	summary.md
Recall@1	0.125000 (3.0× random baseline of 0.042)	results.json
Recall@5	0.416667	summary.md
Recall@10	0.583333	summary.md
Mean reciprocal rank	0.277189	summary.md
Median rank	6.0	summary.md
Latency p50	0.826 ms	results.json
Latency p95	0.869 ms	summary.md
Latency p99	1.191 ms	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
ACL (Animation Compression Library)	19.15×	medium	same 10 synthetic clips	acl_direct_comparator_table.json

ACL reference: 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

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:

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 before turning any artifact in this repo into a broader playback or commercial claim.