sqzc3d API 参考

适用于 sqzc3d v0.4.x（ABI SQZC3D_ABI_VERSION=4）。

头文件

  • include/sqzc3d.h: public C API

  • include/sqzc3d_types.h: shared scalar and status types

  • include/sqzc3d_easy.h: lightweight C++ convenience helpers

初始化 helpers

API

用途

sqzc3d_default_open_opt(sqzc3d_open_opt_t*)

以安全默认值填充 sqzc3d_open_opt_t。

sqzc3d_default_build_opt(sqzc3d_build_opt_t*)

以安全默认值填充 sqzc3d_build_opt_t。

sqzc3d_apply_preset_stream_frame_all(sqzc3d_build_opt_t*)

streaming 全帧 points 读取的 preset。

sqzc3d_apply_preset_stream_frame_sel(sqzc3d_build_opt_t*)

streaming 且显式点选择的 preset。

sqzc3d_apply_preset_window_analysis(sqzc3d_build_opt_t*)

window analysis preset（带 residual gate 默认值）。

sqzc3d_apply_preset_interpolation_ready(sqzc3d_build_opt_t*)

interpolation 友好的 window 读取 preset。

sqzc3d_default_bundle_load_opt(sqzc3d_bundle_load_opt_t*)

以安全默认值填充 bundle-load options。

sqzc3d_default_error_detail(sqzc3d_error_detail_t*)

以零/默认填充 error-detail struct。

sqzc3d_version()

返回语义版本字符串。

sqzc3d_abi_version()

返回 ABI 版本整数。

默认行为备注：

  • Option structs 必须设置 struct_size == sizeof(struct)；请用 sqzc3d_default_*_opt(...) 初始化。

  • sqzc3d_default_build_opt(...) 默认会 materialize analogs（analog_enable = sqzc3d_ANALOG_EN_ON）。

  • sqzc3d_build_opt_t::target_unit 可将 materialized 的 chunk->points_xyz 转成 mm、cm、m 或 km；NULL/空字符串表示保持 source units。

  • 当 analog_enable = sqzc3d_ANALOG_EN_AUTO 时，sqzc3d_build_chunks 会强制 analog_size_soft_limit_bytes （默认 500 MiB），若预计 analog payload 超过该限制则以 sqzc3d_STATUS_INVALID_ARGUMENT 失败。

生命周期

API

用途

sqzc3d_open_file

从文件路径打开 C3D。

sqzc3d_open_memory

从内存 buffer 打开 C3D。

sqzc3d_close_dec

释放 decoder handle。

sqzc3d_last_error / sqzc3d_last_error_detail

获取最近一次 API 错误文本或结构化详情。

备注：

  • sqzc3d_open_memory 会把输入 bytes 复制到 decoder 自己持有的内存源中读取。 调用返回后，caller 可以释放或修改原始 buffer；这不是 zero-copy borrowed-buffer API。

  • Decoder 与 chunk handle 内部不做同步。同一个 handle 应一次只在一个线程中使用；如需并发调用， 由 caller 在外层加锁。

  • sqzc3d_last_error(NULL) 与 sqzc3d_last_error_detail(NULL, ...) 会返回当前线程的最近一次错误。 这对 sqzc3d_open_file / sqzc3d_open_memory 在返回 decoder handle 之前就失败的情况非常有用。

在 SQZC3D_WITH_EZC3D=OFF 时，sqzc3d_open_file、sqzc3d_open_memory、sqzc3d_build_chunks 会返回 sqzc3d_STATUS_NOT_IMPLEMENTED；以 sqzc3d_get_features() 为准。

Chunk 构建与查询

API

用途

sqzc3d_build_chunks

将指定 frame/point/analog 范围解析并 materialize 为一个 chunk 对象。

sqzc3d_free_chunk

释放 chunk 资源。

sqzc3d_chunk_num_frames / sqzc3d_chunk_num_points / sqzc3d_chunk_num_scalar

获取 chunk shape。

sqzc3d_chunk_point_indices_total

可选的 chunk-local -> source-total point index 映射（若可用）。

sqzc3d_chunk_meta_tree_json

可选的 meta_tree 快照（UTF-8 JSON；若可用）。

sqzc3d_chunk_time_axis

可选的时间轴元数据（源 first/last frame、采样率、窗口起点）。

sqzc3d_point_indices_for_labels / sqzc3d_analog_indices_for_labels

labels -> indices 映射。

sqzc3d_points_view_frames / sqzc3d_points_view_points / sqzc3d_points_view_frame_points

按 frame、index list 或 selected frame+points 构建 points views。

sqzc3d_analogs_view_samples / sqzc3d_analogs_view_channels

按 sample range 或 channel list 构建 analog views。

Chunk point payload：

  • chunk->points_xyz：frame-major [T][P][3]；若设置 target_unit，这里已经完成单位转换。

  • chunk->points_valid：frame-major [T][P]。

  • chunk->points_residual：frame-major [T][P]；raw decoded residual，保持 source point units。

  • chunk->residual_nscalar：residual 可用时为 T * P。

  • 单位元数据：point_units_per_meter、target_units_per_meter、residual_units_per_meter、 point_units_source。

Residual validity policy：

  • 默认 sqzc3d_VALID_POLICY_FINITE_XYZ 只按 finite xyz 判定 valid。

  • sqzc3d_VALID_POLICY_FINITE_XYZ_AND_RESIDUAL_GATE 会额外应用 residual_gate_mm。

  • residual_gate_mm 永远以 millimeters 表示；sqzc3d 内部会换算到 residual source units 后比较。

  • points_residual 始终可读，不受 valid policy 影响，也不会随 target_unit 缩放。

View lifetime：

  • sqzc3d_points_view_t 借用 sqzc3d_chunk_t 的 point storage；view 不可超过 source chunk 生命周期。

  • 非连续 point view 还会借用 caller 传入的 point_indices 数组。

  • sqzc3d_analogs_view_t 对 chunk analog storage 和 caller 传入的 channel_indices 数组遵循同样规则。

Bundle 持久化

API

用途

sqzc3d_export_bundle

写出 meta.json + data.bin 或 single-file bundle。

sqzc3d_load_bundle

从持久化 bundle 加载为 chunk。

sqzc3d_load_bundle_with_options

带 strict flag 的严格加载变体。

Type-group metadata and default layout

  • chunk->type_group_names: group names（长度 chunk->n_type_groups）。

  • chunk->type_group_starts: prefix-sum offsets，长度 n_type_groups + 1。

  • chunk->type_group_indices: flattened group indices，位于 chunk-local point index space [0..n_points)； indices[type_group_starts[i]..type_group_starts[i+1]) 是 type_group_names[i] 对应的 indices（索引到 chunk->point_labels）。

  • Optional：sqzc3d_chunk_point_indices_total() 在可用时提供 chunk-local -> source-total 映射。

在 v0.x 中，默认 points layout 固定为：

  • points_layout = sqzc3d_POINTS_LAYOUT_FRAME_MAJOR

  • points_pack = sqzc3d_POINTS_PACK_AOS_XYZ_VALID

  • 默认 easy 层契约：PointWindow 为 frame-major，AoS XYZ；valid 与 residual 为 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]

  • v0.x 默认 analog layout 为 channel-major (C, N)：

    • analog_shape = [n_analogs][n_frames*n_analog_by_frame]（contiguous）

    • analog_stride = [n_frames*n_analog_by_frame, 1]

特性与能力

API

用途

sqzc3d_get_features

读取运行时可用性 bits。

在实践中，这通常是第一步调用：在进入 feature-gated 路径之前，用它来判断当前 build 是否启用了 C3D 解析与 analog APIs。

Easy API

include/sqzc3d_easy.h 中的 header-only helpers：

  • sqzc3d::MakeFrameWindowBuildOpt / sqzc3d::ReadPointsWindow

    • 以选定的 preset 构建一个带 window 的 frame-range chunk。

  • sqzc3d::ReadPointsWindowByLabels

    • 基于 labels 的 windowing。

  • sqzc3d::FrameMajorPointsView

    • 将 chunk 指针转换为 frame-major AoS view，shape 为 [frame][point][xyz]。

  • sqzc3d::AnalogSamplesView

    • 将 chunk 指针转换为 analog view，采用 channel-major (C, N) 布局。

  • sqzc3d::FrameMajorAnalogViewTCS

    • 在底层 (C, N) 存储之上提供非连续（strided）的 frame-major view (T, C, S)。

  • sqzc3d::PointIndicesFromTypeGroups

    • 将 type-group names 转换为一个扁平的 chunk-local point index list。

    • 默认过滤语义：缺失 TYPE_GROUPS 元数据 => no-op（all points）；group name 缺失 => 空集。

  • sqzc3d::PointIndicesFromTypeGroupsStrict

    • 严格变体，显式报错（返回 sqzc3d_STATUS_*）。

  • sqzc3d::ChunkQuery / sqzc3d::ChunkRecipe

    • 最小 AND-only 的 chunk-local filtering helpers（Query 绑定 chunk；Recipe 可复用）。

  • sqzc3d::ReorderFrameMajorToPointMajor

    • 供需要 point-major layout 的消费者使用的 reorder helper。

状态码与枚举

  • 返回码为来自 sqzc3d_types.h 的 C-style ints：

    • sqzc3d_STATUS_SUCCESS

    • sqzc3d_STATUS_INVALID_ARGUMENT

    • sqzc3d_STATUS_DIMENSION_MISMATCH

    • sqzc3d_STATUS_NOT_IMPLEMENTED

    • sqzc3d_STATUS_INTERNAL_ERROR

  • 重要的 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

备注

  • API 与 C89 兼容（C++ 可通过 extern "C" 使用）。

  • 所有非 const out-parameters 都要求 caller 提供可写内存。

  • 由本库分配的资源必须使用对应的 free APIs 释放。

  • public residual payload 已提供为 raw source-unit decoded residual；camera mask 还不是 public payload。

Python API

Python bindings 基于 pybind11。

Python 高层导出：

  • sqzc3d.version()

  • sqzc3d.abi_version()

  • sqzc3d.features()

  • sqzc3d.read(...) -> sqzc3d.View（easy 层）

  • sqzc3d.View（easy 层）

  • sqzc3d.Recipe（sqzc3d.ChunkRecipe 的 alias）

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

推荐大多数用户从这里开始。

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

选择器语义（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；若可用；bundle 会保留；从 C3D 提取需要 SQZC3D_WITH_EZC3D=ON）

  • Advanced escape hatch：

    • view._chunk（pybind Chunk；indices/masks 等被视作 advanced）

Notes：

  • easy 层按设计为 labels-only。若你已有 indices，请使用 core API 并直接 slice 数组。

Decoder：

  • Decoder(path, label_norm=sqzc3d.SQZC3D_LABEL_NORM_EXACT)

  • Decoder.read(start_frame=0, frame_count=-1, points=None, analogs=None, analog_range=None, target_unit="")

  • Decoder.close()

  • Decoder.source_path（只读）

  • Decoder.closed（只读 bool）

Chunk：

  • chunk.points(selector=None, copy=True) -> (values, valid)

  • chunk.residual(selector=None, copy=True) -> residual

  • chunk.analogs(selector=None, layout="CN", copy=True) -> (values, valid)

    • layout="tcs" 会返回一个非连续的 frame-major view (T, C, S)（底层仍为 channel-major 存储）。

  • chunk.meta（dict）

  • chunk.meta_tree（dict：若可用；bundle 会保留；open_memory 也应可用）

  • chunk.source_path（只读）

Python payload 语义：

  • points values：float64，默认 frame-major shape (T, P, 3)，valid mask (T, P) dtype uint8。

  • residual values：float64，默认 frame-major shape (T, P)，source point units。

  • analogs values：

    • layout="CN" 默认：(C, N)，其中 N = n_frames * n_analog_by_frame

    • layout="tcs"：(T, C, S) non-contiguous view helper

  • selector：

    • None 表示 all

    • [] 表示 empty

    • int 或 list/tuple[int] 为 index selection

    • str 或 list/tuple[str] 为 label selection

  • 非连续选择需要 copy=True；copy=False 当前会抛 RuntimeError，以避免隐藏的转换。