跳到主要内容

Vfp.parse()

Vfp.parse(path: str | pathlib.Path) -> Vfp

打开现有 .vfp，读取 Header、末尾 Footer 和活动 DIR0，构造按需读取的 Vfp 实例。它不会在打开时解压全部 VOX0、读取缩略图或创建预览网格。

参数​

参数类型说明
pathstr 或 pathlib.Path现有常规文件路径。对象会保留规范化后的路径，后续所有 API 从该路径按需读取。

示例：先检查再读取​

from pathlib import Path
from voxelkit import Vfp

asset = Vfp.parse(Path("downloads/robot.vfp"))
print(asset.source_hash)
print(asset.section_tags())

inventory = asset.inspect()
if inventory["caches"]["hasThumbnail"]:
    asset.extract_thumbnail("cache/robot.png")

解析成功保证什么​

已检查未检查
magic、主/次版本、Header/Footer 一致性每个 payload CRC。
Footer 指向的活动目录范围和目录 CRCPAL0/VOX0 语义、实体体素数、source hash。
DIR0 记录大小、tag、codec、flags、offset/length 边界PMSH、RND0、ANM0 等缓存是否可由权威数据重建。

因此 parse() 适合快速发现“这是不是可识别的 VFP”，不适合建立信任边界。跨网络、用户上传、发布或转换前应调用 validate()。

生命周期​

Vfp 不会保持打开的文件描述符。每个读取方法自行打开需要的区段；因此可以安全地把实例在服务对象中保存，但调用之间不要移动、替换或原地改写同一路径的文件。

异常​

异常原因
OSError路径不存在、权限不足、文件在读取时消失。
VfpError文件太短、magic/版本错误、Footer/DIR0 不合法、目录 CRC 错误、区段越界、codec/flags/reserved 不符合 VFP 1.3。

相关 API​

  • 用 Vfp.compile() 或 Vfp.from_vox() 创建新资产并直接获得已打开对象。
  • 用 manifest() 查看 META；它会校验 META 本身的 CRC。
  • 用 validate() 进行权威完整校验。