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

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.

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.

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.

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

Evidence On Disk

Repo Shape

• 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.