读取 VFP 文件
VoxelKit Reader 是 Voxel Format Package（VFP）1.3 的只读 Python SDK。它的任务很明确：安全打开一个 VFP 文件、读取权威体素数据、验证完整性，并导出为其他消费端可用的格式。它不承担模型编辑、缓存构建或 VFP 编译职责。
适用场景
- 资产库在列表页显示网格大小、文件体积与是否内嵌 GLB 预览。
- 服务端在接收用户上传的 VFP 后执行完整性校验。
- 离线任务把可信 VFP 导出为 PixForge JSON 或 MagicaVoxel VOX。
- Web 服务提取已经存在的 GLB 预览，而不在请求时生成网格。
最小读取流程
from vfp_reader import VfpError, VfpReader
try:
reader = VfpReader.open("assets/robot.vfp")
info = reader.inspect()
report = reader.validate_source()
except VfpError as error:
raise RuntimeError(f"拒绝损坏或不兼容的模型：{error}") from error
print(info["gridSize"])
print(report["solidVoxelCount"])
open() 验证 VFP 容器、Footer 和目录；inspect() 不展开体素；validate_source() 才读取 PAL0、全部 VOX0 并重算 sourceHash。生产代码应在任何依赖模型内容的操作前调用后者。
公开能力
| 需求 | API 或命令 | 是否读取完整体素 |
|---|---|---|
| 快速显示文件信息 | inspect() / info | 否 |
| 读取描述信息 | manifest() | 否 |
| 读取颜色定义 | palette() | 否 |
| 恢复线性体素缓冲 | voxels() | 是 |
| 验证权威数据 | validate_source() / verify-source | 是 |
| 导出 JSON | export_json() / to-json | 是 |
| 导出 VOX | to_vox() / to-vox | 是 |
| 提取现有预览 | extract_glb() / extract-glb | 否，仅 PRVW |
必须理解的边界
VFP 的权威数据是 PAL0 和 VOX0。PMSH、RND0、ANM0、VBUF 与 PRVW 都是可选派生内容。Reader 可以报告或提取其中某些内容，但不会以缓存替代权威数据，也不会根据缓存“补全”损坏的模型。
本仓库只提供读取端能力。JSON/VOX 到 VFP 的编译、VFP 写入、缓存重建、贪心网格、ArkGraphics Geometry 创建和编辑器交互，均属于 VoxelKit Compiler 或上层应用。