ZPE-Mocap

---

What This Is

ZPE-Mocap is a motion fingerprint index for archive search and deduplication, not a playback codec. It produces compact, indexable fingerprints from skeletal BVH motion data so operators of large mocap archives can locate, dedupe, and retrieve clips by content. Encoding is lossy by design; retrieval fidelity and index latency are the primary proof surfaces. The lane is one of 17 in Zer0pa's ZPE portfolio.

Honest top-line (CI-anchored, real data): mean 18.77× compression vs raw BVH float32 on 10 real CMU corpus clips, with retrieval Recall@1 0.125, Recall@10 0.583, and p50 query latency 0.826 ms — the actual product story for an archive-search index. A separate ACL synthetic comparator is documented in section 5 with its scope boundaries explicitly drawn (non-CI-gated, non-commensurable: fingerprint extraction vs playback codec); it is orientation material, not the aggregate claim.

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 — honest headline. 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 for a fingerprint index and is not claimed here. The 18.77× mean is the figure that travels with this lane.

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

Synthetic comparison (non-CI-gated, non-commensurable: fingerprint extraction vs playback codec). This comparator runs on 10 synthetic clips (wave 1 fixture), not CMU real data. ZPE-Mocap extracts a lossy fingerprint sized for retrieval; ACL targets playback-grade reconstruction. The two systems are not commensurable on a single ratio number — a fingerprint index and a playback codec are doing different jobs — and this benchmark is not gated by CI. Reported here for orientation only; do not treat the 57.03× figure as the lane's compression claim. The aggregate, CI-gated claim 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.

Upcoming Workstreams

This section captures the active lane priorities — what the next agent or contributor picks up, and what investors should expect. Cadence is continuous, not milestoned.

• CMU benchmark scale-up (10 → 100+ clips) — Active Engineering. Pure data-ingestion work; closes proof-surface gap to a buyer-evaluable corpus.
• Recall@1 lift via fingerprint primitives — Research-Deferred — Investigation Underway. Current 0.125 needs lift to 0.25+ for archive-search buyers; learned-embedding head, metric-learning fine-tune, or alternative distance function under investigation.