# 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。

```python
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"])
```

严格性：

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

导出（core API）：

```python
import sqzc3d as sq

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

## C API

Export：

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

Load：

```c
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(...)` 进行诊断。