跳到主要内容

Vfp.manifest()

asset.manifest() -> dict[str, object]

读取 VFP 中唯一的 META 区段，将 UTF-8 JSON 解码为一个新的 Python 字典。它回答“这个资产声称自己是什么、由谁编译、包含哪些缓存”，不负责证明这些声明真实。

什么时候使用​

  • 在文件列表显示网格尺寸、实体体素数、缩略图可用性或编译器信息。
  • 在导入前判断是否值得读取 THMB、PRVW 或进入预览缓存路径。
  • 记录可读的模型元信息到日志。

如果要在保存、发布、转换前确认资产没有被篡改，使用 asset.validate()；它会恢复权威 PAL0/VOX0 并重算 source hash。

参数与返回值​

此方法没有参数。

返回值类型所有权说明
META 对象dict[str, object]调用方拥有的新字典修改返回值不会回写 .vfp，也不会改变同一 asset 后续调用的结果。

典型 VFP 1.3 META 片段：

{
  "format": "Voxel Format Package",
  "formatVersion": { "major": 1, "minor": 3 },
  "generator": "voxelkit 0.10.0",
  "coordinateSystem": "Z_UP",
  "sourceHash": "8d...",
  "objects": [{
    "id": "obj_main",
    "type": "voxel-volume",
    "gridSize": [128, 128, 128],
    "chunkSize": 16,
    "solidVoxelCount": 109690
  }],
  "cache": {
    "previewGlb": false,
    "thumbnail": { "format": "PNG", "width": 256, "height": 256, "background": "transparent" }
  }
}

字段会随格式小版本和编译选项扩展。业务代码必须把未知字段视为可忽略，不能假设 cache、thumbnail、generator 或特定对象 ID 一定存在。

最小示例​

from voxelkit import Vfp

asset = Vfp.parse("assets/house.vfp")
meta = asset.manifest()

first_object = meta["objects"][0]
grid_size = first_object["gridSize"]
print("网格:", grid_size[0], "x", grid_size[1], "x", grid_size[2])
print("实体体素:", first_object["solidVoxelCount"])
print("声明的 source hash:", meta["sourceHash"])

thumbnail = meta.get("cache", {}).get("thumbnail")
if thumbnail:
    print("缩略图:", thumbnail["width"], "x", thumbnail["height"])

用于安全的展示逻辑​

META 中的 sourceHash 是声明值。下面的写法会在展示后再确认权威体素，适合导入工作流：

from voxelkit import Vfp, VfpError

asset = Vfp.parse("incoming/model.vfp")
meta = asset.manifest()

try:
    report = asset.validate()
except VfpError as error:
    raise RuntimeError("文件元信息可读，但权威体素校验失败") from error

assert report["sourceHash"] == meta["sourceHash"]
print("已验证:", report["solidVoxelCount"], "个体素")

validate() 会比 manifest() 明显更慢，因为它需要读取所有权威 chunk；不要为了仅显示文件名和网格尺寸而在列表页对每个文件都执行完整验证。

异常​

异常发生条件处理方式
VfpError缺少 META、META 区段重复、区段 CRC 错误、不是 UTF-8 或 JSON 根不是对象。拒绝将该文件作为正常 VFP 资产展示。
OSErrorVfp.parse() 前后的文件被删除、无权限或底层读取失败。检查路径、权限和外部存储状态。

与相邻 API 的选择​

目标应使用不应只使用 manifest() 的原因
查询目录 tagsection_tags()无需读取 JSON。
判断缓存和区段字节统计inspect()返回专门的库存汇总。
读取真实调色板palette()META 不是 PAL0 权威副本。
读取真实体素voxels()META 仅描述体素数量与网格。
确认 source hashvalidate()META 自身不构成可信证明。

注意事项​

  • 不要向返回字典写入业务状态再期待 asset 记住它；VFP 没有就地写回 API。
  • 不要用 objects[0] 表示未来多对象格式的唯一对象；当前编译器写一个对象，但读取代码应保留数组语义。
  • 不要把 META 中 cache.previewGlb=true 当作 PRVW 可直接使用的证明；提取时仍要调用 extract_glb()，它会校验 CRC 和 GLB 结构。