# Materialize 与 Streaming

`sqzc3d` 支持两种访问模型，它们都能得到一致的语义（layout/validity/units），差异在于资源与交付形态：

30 秒版本：

- Materialize：一次性读入并产出数组。大多数用户默认就用它。
- Streaming：保持文件打开，按需读到你提供的 buffer。只有在内存很紧或 I/O 很特殊时才需要。

形象化：Materialize 像把整张表读进来；Streaming 像需要哪几行就读哪几行。

## Materialize：一次性内存化为 `Chunk`

Materialize 的特点：

- 解析 C3D payload。
- 分配紧凑的连续数组。
- 返回一个 `Chunk`，包含：
  - `points_xyz`: `(T, P, 3)` `float64`（frame-major）
  - `points_valid`: `(T, P)` `uint8`
  - 可选的 `analogs`: `(C, N)` `float64`（channel-major）

这适合大多数分析/仿真场景：加载一次，后续反复切片/计算都很快。

Python easy 层（`read -> View`）与 C API（`sqzc3d_build_chunks`）走的都是这条路径。

## Streaming：只保留头信息，按需读入用户缓冲区

Streaming 的特点：

- 解析 header + parameters + labels。
- 保持文件打开。
- 按需从文件读取 frames/windows/trajectories。

该模式通过 `include/sqzc3d_c3d_stream.h` 中的 C++ API 暴露。

典型用例（更偏“工程约束”而不是“更好用”）：

- 极端内存受限环境。
- 虚拟文件系统（例如浏览器 WASM file APIs）。
- 只需要读取小窗口/少量帧，不想把全量数据放进内存。

## 如何选择

- 优先用 Materialize：语义最直观、数组最友好、也更符合 Python 用户心智。
- 需要极低内存或特殊 I/O 才用 Streaming：你需要自己管理输出 buffer，并显式选择读取的窗口。

Units：

- 默认情况下，Streaming 返回 raw point units（见 Units）；如果下游需要某个单位，可显式请求缩放。