Data layout

This page documents the default array layouts used by sqzc3d materialization.

The goal is predictable shape and memory order for downstream code.

Quick summary:

  • Points: (T, P, 3) plus a matching (T, P) points_valid.

  • Analogs: (C, N) plus a matching (C, N) analogs_valid by default.

  • layout="tcs" is a view helper; layout="CN" is contiguous storage.

Mental model: sqzc3d returns “tables”, and it tells you the table shape and memory order up front.

Points

Points are marker trajectories.

Materialized points contract:

  • Layout: frame-major

  • Pack: AoS XYZ with a separate valid mask

In Python, the default Chunk.points(...) returns:

  • points: shape (T, P, 3), dtype float64

  • points_valid: shape (T, P), dtype uint8

import sqzc3d as sq

v = sq.read("trial.c3d")
points = v.points
valid = v.points_valid

# Example: filter out invalid samples for one point.
p = v.point["LANK"]                 # (T, 3)
pv = v.point_valid["LANK"]          # (T,)
p_clean = p[pv != 0]

In the C API, sqzc3d_points_view_frames(...) exposes the same memory as a view:

  • view.points_xyz: (T, P, 3) frame-major, contiguous

  • view.points_valid: (T, P) contiguous

Analogs

Analogs are time-series channels (e.g. ground reaction force, EMG).

Materialized analogs are channel-major by default:

  • Layout: (C, N) where N = T * S

  • S = n_analog_by_frame (subframes per frame)

In Python:

import sqzc3d

dec = sqzc3d.Decoder("trial.c3d")
chunk = dec.read()
dec.close()

values_cn, valid_cn = chunk.analogs(layout="CN")     # (C, N)
values_tcs, valid_tcs = chunk.analogs(layout="tcs")  # (T, C, S) (strided view helper)

Notes:

  • layout="CN" is contiguous.

  • layout="tcs" is a strided view over the underlying (C, N) storage. It is convenient for frame-based logic.

Copies vs views

sqzc3d avoids implicit gathers/copies:

  • Contiguous selections can return a view (copy=False).

  • Non-contiguous selections require copy=True.

This makes performance costs explicit and keeps memory behavior predictable.