读取、校验与提取

from voxelkit import Vfp

asset = Vfp.parse("model.vfp")
print(asset.source_hash, asset.generation, asset.section_tags())
print(asset.manifest()["coordinateSystem"])  # Z_UP
print(asset.axis_convention())
report = asset.validate()
voxels = asset.voxels()
palette = asset.palette()

parse() 只验证容器/目录；跨网络或进入转换前必须 validate()。voxels() 恢复完整 x-fastest 体素；read_section(tag, chunk_id=-1) 读取并 CRC 校验一个存储 Payload。

axis_convention() 返回 {"up":"+Z","forward":"+Y","handedness":"RIGHT_HANDED"}。它比直接检查 coordinateSystem 更适合相机、转台和跨引擎变换：Z_UP 本身并不能确定前方。对于没有 axisConvention 的早期 VFP 1.3，SDK 使用该同一默认值；显式但不完整的约定会抛出 VfpError，不会擅自镜像模型。

if "PRVW" in asset.section_tags():
    open("preview.glb", "wb").write(asset.read_section("PRVW"))

thumb = asset.thumbnail()
if thumb:
    _, _, _, png = thumb
    open("thumbnail.png", "wb").write(png)

thumbnail() 还验证 THMB 的 PNG 结构并在不存在时返回 None。读取 PRVW 时调用方应按自己的 GLB 安全策略解析；SDK 没有 extract_glb()/extract_thumbnail() 写文件方法。