`sqzc3d` API reference

Applies to sqzc3d v0.4.x (ABI SQZC3D_ABI_VERSION=4).

Headers

include/sqzc3d.h: public C API
include/sqzc3d_types.h: shared scalar and status types
include/sqzc3d_easy.h: lightweight C++ convenience helpers

Initialization helpers

API	Purpose
`sqzc3d_default_open_opt(sqzc3d_open_opt_t*)`	Fill `sqzc3d_open_opt_t` with safe defaults.
`sqzc3d_default_build_opt(sqzc3d_build_opt_t*)`	Fill `sqzc3d_build_opt_t` with safe defaults.
`sqzc3d_apply_preset_stream_frame_all(sqzc3d_build_opt_t*)`	Preset for streaming full-frame point reads.
`sqzc3d_apply_preset_stream_frame_sel(sqzc3d_build_opt_t*)`	Preset for streaming with explicit user point selection.
`sqzc3d_apply_preset_window_analysis(sqzc3d_build_opt_t*)`	Preset for window analysis with residual gate default.
`sqzc3d_apply_preset_interpolation_ready(sqzc3d_build_opt_t*)`	Preset for interpolation-friendly window reads.
`sqzc3d_default_bundle_load_opt(sqzc3d_bundle_load_opt_t*)`	Fill bundle-load options with safe defaults.
`sqzc3d_default_error_detail(sqzc3d_error_detail_t*)`	Fill an error-detail struct with zeros/defaults.
`sqzc3d_version()`	Return the semantic version string.
`sqzc3d_abi_version()`	Return the ABI version integer.

Default behavior notes:

Option structs must set struct_size == sizeof(struct); use sqzc3d_default_*_opt(...) to initialize.
sqzc3d_default_build_opt(...) materializes analogs by default (analog_enable = sqzc3d_ANALOG_EN_ON).
sqzc3d_build_opt_t::target_unit optionally converts materialized chunk->points_xyz to mm, cm, m, or km. NULL/empty keeps source units.
When analog_enable = sqzc3d_ANALOG_EN_AUTO, sqzc3d_build_chunks enforces analog_size_soft_limit_bytes (default 500 MiB) and fails with sqzc3d_STATUS_INVALID_ARGUMENT if the projected analog payload exceeds the limit.

Life-cycle

API	Purpose
`sqzc3d_open_file`	Open C3D from file path.
`sqzc3d_open_memory`	Open C3D from memory buffer.
`sqzc3d_close_dec`	Release decoder handle.
`sqzc3d_last_error` / `sqzc3d_last_error_detail`	Retrieve last API error text or structured detail.

Notes:

sqzc3d_open_memory copies the input bytes into decoder-owned memory and reads from that memory source. The caller may release or mutate the input buffer after the call returns. This is not a zero-copy borrowed-buffer API.
Decoder and chunk handles are not internally synchronized. Use a given handle from one thread at a time, or guard concurrent API calls with external synchronization.
sqzc3d_last_error(NULL) and sqzc3d_last_error_detail(NULL, ...) report the last error on the current thread. This is useful when sqzc3d_open_file / sqzc3d_open_memory fails before returning a decoder handle.

In SQZC3D_WITH_EZC3D=OFF, sqzc3d_open_file, sqzc3d_open_memory, sqzc3d_build_chunks return sqzc3d_STATUS_NOT_IMPLEMENTED and keep sqzc3d_get_features() authoritative.

Chunk building and query

API	Purpose
`sqzc3d_build_chunks`	Parse selected frame/point/analog ranges into a chunk object.
`sqzc3d_free_chunk`	Release chunk resources.
`sqzc3d_chunk_num_frames` / `sqzc3d_chunk_num_points` / `sqzc3d_chunk_num_scalar`	Access chunk shape.
`sqzc3d_chunk_point_indices_total`	Optional chunk-local -> source-total point index mapping (when available).
`sqzc3d_chunk_meta_tree_json`	Optional `meta_tree` snapshot as UTF-8 JSON (when available).
`sqzc3d_chunk_time_axis`	Optional time-axis metadata (source first/last frame, rates, window origins).
`sqzc3d_point_indices_for_labels` / `sqzc3d_analog_indices_for_labels`	Map labels to indices.
`sqzc3d_points_view_frames` / `sqzc3d_points_view_points` / `sqzc3d_points_view_frame_points`	Build point views by frame, index list, or selected frame+points.
`sqzc3d_analogs_view_samples` / `sqzc3d_analogs_view_channels`	Build analog views by sample range or channel list.

Chunk point payload:

chunk->points_xyz: frame-major [T][P][3]; converted by target_unit when requested.
chunk->points_valid: frame-major [T][P].
chunk->points_residual: frame-major [T][P]; raw decoded residual in source point units.
chunk->residual_nscalar: T * P when residual storage is available.
Unit metadata: point_units_per_meter, target_units_per_meter, residual_units_per_meter, and point_units_source.

Residual validity policy:

Default sqzc3d_VALID_POLICY_FINITE_XYZ marks points valid from finite xyz only.
sqzc3d_VALID_POLICY_FINITE_XYZ_AND_RESIDUAL_GATE additionally applies residual_gate_mm.
residual_gate_mm is always expressed in millimeters; sqzc3d converts the threshold to residual source units before comparing.
points_residual remains readable regardless of valid policy and is never scaled by target_unit.

View lifetime:

sqzc3d_points_view_t borrows sqzc3d_chunk_t storage; the view must not outlive the source chunk.
Non-contiguous point views also borrow the caller-provided point_indices array.
sqzc3d_analogs_view_t follows the same rule for chunk analog storage and caller-provided channel_indices.

Bundle persistence

API	Purpose
`sqzc3d_export_bundle`	Write `meta.json` + `data.bin` or single-file bundle.
`sqzc3d_load_bundle`	Load persisted bundle into chunk.
`sqzc3d_load_bundle_with_options`	Strict-load variant with strict flag.

Type-group metadata and default layout

chunk->type_group_names: group names (length chunk->n_type_groups).
chunk->type_group_starts: prefix-sum offsets length n_type_groups + 1.
chunk->type_group_indices: flattened group indices in the chunk-local point index space [0..n_points); indices[type_group_starts[i]..type_group_starts[i+1]) are indices into chunk->point_labels for type_group_names[i].
Optional: sqzc3d_chunk_point_indices_total() provides a chunk-local -> source-total mapping when available.

In v0.x the default points layout is fixed:

points_layout = sqzc3d_POINTS_LAYOUT_FRAME_MAJOR
points_pack = sqzc3d_POINTS_PACK_AOS_XYZ_VALID
Default easy layer contracts: PointWindow is frame-major, AoS XYZ; valid and residual are frame-major [T][K].
- points_xyz_shape = [n_frames][n_points][3] (contiguous)
- points_xyz_stride = [n_points*3, 3, 1]
- points_valid_shape = [n_frames][n_points] (contiguous)
- points_valid_stride = [n_points, 1]
- points_residual_shape = [n_frames][n_points] (contiguous)
- points_residual_stride = [n_points, 1]
Default analog layout in v0.x is channel-major (C, N):
- analog_shape = [n_analogs][n_frames*n_analog_by_frame] (contiguous)
- analog_stride = [n_frames*n_analog_by_frame, 1]

Feature and capability

API	Purpose
`sqzc3d_get_features`	Read runtime availability bits.

In practice this is the first call to decide whether C3D parsing and analog APIs are enabled before invoking feature-gated paths.

Easy API

Header-only helpers in include/sqzc3d_easy.h:

sqzc3d::MakeFrameWindowBuildOpt / sqzc3d::ReadPointsWindow
- Build a windowed frame-range chunk with a chosen preset.
sqzc3d::ReadPointsWindowByLabels
- Label-driven windowing.
sqzc3d::FrameMajorPointsView
- Convert chunk pointer to frame-major AoS view with [frame][point][xyz] shape.
sqzc3d::AnalogSamplesView
- Convert chunk pointer to analog view with channel-major (C, N) layout.
sqzc3d::FrameMajorAnalogViewTCS
- Provide a non-contiguous (strided) frame-major view (T, C, S) over the underlying (C, N) storage.
sqzc3d::PointIndicesFromTypeGroups
- Convert type-group names to a flat chunk-local point index list.
- Default filter semantics: missing TYPE_GROUPS metadata => no-op (all points); missing group name => empty set.
sqzc3d::PointIndicesFromTypeGroupsStrict
- Strict variant with explicit error signaling (returns a sqzc3d_STATUS_* code).
sqzc3d::ChunkQuery / sqzc3d::ChunkRecipe
- Minimal AND-only chunk-local filtering helpers (bound to a chunk; recipes are reusable).
sqzc3d::ReorderFrameMajorToPointMajor
- Reorder helper for consumers requiring point-major layout.

Status and enums

Return codes are C-style ints from sqzc3d_types.h:
- sqzc3d_STATUS_SUCCESS
- sqzc3d_STATUS_INVALID_ARGUMENT
- sqzc3d_STATUS_DIMENSION_MISMATCH
- sqzc3d_STATUS_NOT_IMPLEMENTED
- sqzc3d_STATUS_INTERNAL_ERROR
Important enum families:
- input type: sqzc3d_FILE, sqzc3d_MEMORY
- selection mode: indices/labels/all
- read policy: AUTO, DENSE, SPARSE
- valid policy: sqzc3d_VALID_POLICY_FINITE_XYZ, sqzc3d_VALID_POLICY_FINITE_XYZ_AND_RESIDUAL_GATE

Notes

API is C89-compatible (extern "C" available for C++).
All non-const out-parameters are expected writable by caller.
Resources allocated by this library must be released with corresponding free APIs above.
Public residual payload is available as raw source-unit decoded residual. Camera masks are not yet public payload.

Python API

Python bindings are implemented via pybind11.

High-level Python exports:

sqzc3d.version()
sqzc3d.abi_version()
sqzc3d.features()
sqzc3d.read(...) -> sqzc3d.View (easy layer)
sqzc3d.View (easy layer)
sqzc3d.Recipe (alias of sqzc3d.ChunkRecipe)
sqzc3d.Decoder
sqzc3d.Chunk
sqzc3d.ChunkQuery / sqzc3d.ChunkRecipe (AND-only chunk-local filtering)
sqzc3d.type_group_indices(chunk, group_names, strict=False)
sqzc3d.load_bundle(path: str, strict: bool = True)
sqzc3d.export_bundle(out_dir: str, chunk: sqzc3d.Chunk)

Easy layer

Recommended for most users.

read:

sqzc3d.read(source, *, start_frame=0, frame_count=-1, points=None, analogs=None, analog_range=None, label_norm=..., recipe=None, target_unit=None) -> View

Selector semantics (Python):

None = default (ALL)
[] = empty selection

View:

Selection state (labels-first):
- view.point_labels (None | list[str])
- view.analog_labels (None | list[str])
- view.type_groups (list[str])
Data (properties):
- view.points / view.points_valid
- view.points_residual
- view.analogs / view.analogs_valid
Label accessors:
- view.point["LANK"] / view.point_valid["LANK"]
- view.point_residual["LANK"]
- view.analog["EMG1"] / view.analog_valid["EMG1"]
Metadata:
- view.meta (flat dict)
- view.meta_tree (EZ parameter tree when available; preserved in bundles; SQZC3D_WITH_EZC3D=ON is required to extract it from C3D)
Advanced escape hatch:
- view._chunk (pybind Chunk; indices/masks/etc are considered advanced)