squeezc3d documentation

squeezc3d, aka sqzc3d, is a high-performance C3D loading library. The goal is simple: read C3D into predictable arrays (points/analogs) with clear semantics.

30-second summary

  • If you just want arrays for analysis or simulation, start with Python Easy: sqzc3d.read(...).

  • You get arrays plus explicit *_valid masks, so missing samples are not a guessing game.

  • You can select by labels, read windows, and keep behavior stable across native and WASM.

  • If you worry about “will my data silently change?”, read user_guide_correctness_compatibility and run verify.py stress.

It is designed around practical ezc3d-based workflows:

  • ezc3d has mature parsing and parameter tree support, but in batch / large-file / WASM settings, object graph construction, copying, and layout normalization can be expensive.

  • Downstream code often still needs consistent selection, validity, units, and marker-set / type-groups semantics.

Mini glossary

Term

Plain meaning

read -> View

the easy “just give me arrays” API.

Decoder -> Chunk

the core API when you want full control over selection and layouts.

materialize

read once, allocate arrays, then slice fast.

*_valid

per-sample “usable / not usable” masks.

selector

picking markers/channels by labels or indices.

Where to start

  • If you use Python: start with getting_started_python, then user_guide_python_easy.

  • If you use C/C++: start with getting_started_c, then build.

  • If you want confidence before switching from ezc3d: read user_guide_correctness_compatibility and run verify.py stress.

Key results in squeezc3d:

  • Chunk-first: materialize into a compact chunk and get contiguous arrays, NumPy-friendly.

  • Clear contracts: fixed layout, explicit valid masks, unambiguous selector/index-space rules, and well-defined defaults for type-groups and units.

  • Application-facing API: Python read -> View stays small; Core Decoder/Chunk and C/C++ APIs remain available for precise control.

  • Optional modes: streaming reads and .sqzc3d bundles for low-memory, browser, and cached-load workflows.

Getting started

User guide

Correctness & Compatibility

Benchmarks

API reference