读取、校验与提取

打开与检查

from voxelkit import Vfp

asset = Vfp.parse("model.vfp")
print(asset.source_hash)
print(asset.generation)
print(asset.section_tags())
print(asset.inspect())

parse() 读取 Header、Footer 与目录；它不会替你把所有区段预先展开。inspect() 适合资产列表、日志和 诊断，它返回网格尺寸、文件大小、区段库存和缓存是否存在。

校验与权威数据

report = asset.validate()
manifest = asset.manifest()
voxels = asset.voxels()
palette = asset.palette()

API	返回值	适合场景
validate()	校验报告字典	导入前、发布前、可信资产处理。
manifest()	META JSON 字典	名称、网格、缓存提示等轻量信息。
voxels()	bytes	恢复完整线性 VOX0 体素缓冲。
palette()	PAL0 条目元组	获取每个非空 palette index 的颜色与符号。
read_section(tag, chunk_id=-1)	bytes	读取一个已 CRC 校验的原始区段。

对于编辑、导出或安全判断，应先执行 validate()，再读取 voxels()；不要以 THMB、PRVW 或网格缓存 作为模型真实内容。

提取缩略图 THMB

asset.extract_thumbnail("thumbnail.png")

# 也可以在内存中交给任意 PNG 解码器
png_bytes = asset.read_section("THMB")

extract_thumbnail(output_path) 会检查唯一全局 THMB、CRC 与 PNG 签名，然后原样写出 PNG。若文件没有 缩略图，方法抛出 VfpError；可在重新编译时启用 thumbnail=True。

提取 GLB 预览 PRVW

asset.extract_glb("preview.glb")

该调用不重新网格化，而是导出编译阶段已有的 GLB。若 PRVW 缺失，需要使用 preview=True 重新编译，或 用 rebuild_caches() 生成新文件。

错误处理

from voxelkit import Vfp, VfpError

try:
    asset = Vfp.parse("incoming.vfp")
    asset.validate()
    asset.extract_thumbnail("incoming.png")
except VfpError as error:
    print(f"VFP 无法使用：{error}")

VfpError 用于格式、完整性、区段缺失和不支持的互操作输入。文件读写失败还可能由系统抛出 OSError。