Bundles

30 秒版本：

bundle 是 sqzc3d 的缓存格式，用来“下次更快加载”。
推荐使用单文件 bundle：*.sqzc3d。
sqzc3d.read(...) 会自动识别 bundle；strict 与 best-effort 行为可选。
bundle 会保存关键元数据（包括 meta_tree 参数树、时间轴字段、residual payload 与单位元数据），因此你用 bundle 也能读取像 FORCE_PLATFORM 这类参数。

形象化：把“解码后的两张表”装进一个缓存箱，下次直接开箱，不必再从头解码。

sqzc3d 支持把 materialize 后的 chunk 持久化为一个紧凑的 “bundle” 格式，用于快速重新加载。

支持两种 bundle 布局：

目录 bundle（legacy）：目录内包含 meta.json + data.bin
单文件 bundle（推荐）：*.sqzc3d

Python

Easy 入口 sqzc3d.read(...) 会自动识别 bundles：

若 source 是目录，则加载目录 bundle。
若 source 以 .sqzc3d 结尾（大小写不敏感），则加载单文件 bundle。
否则将其视作 C3D path/buffer 并 materialize 出 chunk。

import sqzc3d as sq

v = sq.read("trial.sqzc3d")     # 加载单文件 bundle
v = sq.read("bundle_dir/")      # 加载目录 bundle
v = sq.read("trial.c3d")        # 从 C3D materialize

print(v.meta["n_frames"], v.meta["n_points"])

严格性：

v = sq.read("trial.sqzc3d", bundle_strict=True)   # 默认
v = sq.read("trial.sqzc3d", bundle_strict=False)  # best-effort（尽量加载）

导出（core API）：

import sqzc3d as sq

v = sq.read("trial.c3d")
sq.export_bundle("trial.sqzc3d", v._chunk)   # 也可以传目录路径，例如 "bundle_dir/"

C API

Export：

// Writes <out_dir>/meta.json and <out_dir>/data.bin.
int st = sqzc3d_export_bundle(out_dir, chunk);

Load：

sqzc3d_chunk_t* chunk = NULL;
int st = sqzc3d_load_bundle(bundle_path_or_dir, &chunk);

备注：

bundle 会加载成 sqzc3d_chunk_t*，因此可复用相同的 view/query/free APIs。
新 bundle 使用 schema version 4，包含 points_residual 与单位元数据。
loader 仍接受 schema version 3 的旧 bundle；这类 legacy bundle 的 points_residual == NULL，单位元数据未知。
bundle 元数据（meta.json）会记录 sqzc3d_version 与 sqzc3d_abi_version，便于诊断版本兼容性问题。
bundle 可能包含额外元数据；若出现不匹配，可使用 chunk->reason / sqzc3d_last_error_detail(...) 进行诊断。