`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",
  "coordinateSystem": "Z_UP",
  "axisConvention": {
    "up": "+Z",
    "forward": "+Y",
    "handedness": "RIGHT_HANDED"
  },
  "sourceHash": "8d...",
  "objects": [{
    "id": "obj_main",
    "type": "voxel-volume",
    "gridSize": [128, 128, 128],
    "chunkSize": 16,
    "solidVoxelCount": 109690
  }],
  "cache": { "runtime": true }
}

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

coordinateSystem="Z_UP" 只声明上轴；要还原相机正面必须同时读取 axisConvention。VFP 1.3 Orientation Profile v1 规定 +Z 向上、+Y 向前、右手系，故 +X 向右。请优先使用 Vfp.axis_convention()：它会为历史缺失字段返回相同的确定默认值，并拒绝不完整的显式字段。

最小示例

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"])

if "THMB" in asset.section_tags():
    mime, width, height, png_bytes = asset.thumbnail()  # type: ignore[misc]
    print("缩略图:", mime, width, "x", height, len(png_bytes), "bytes")

用于安全的展示逻辑

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 资产展示。
`OSError`	`Vfp.parse()` 前后的文件被删除、无权限或底层读取失败。	检查路径、权限和外部存储状态。

与相邻 API 的选择

目标	应使用	不应只使用 `manifest()` 的原因
查询目录 tag	`section_tags()`	无需读取 JSON。
判断区段是否存在或读取目录长度	`section_tags()`、`entries()`	当前 SDK 没有 `inspect()` 汇总 API。
读取真实调色板	`palette()`	META 不是 PAL0 权威副本。
读取真实体素	`voxels()`	META 仅描述体素数量与网格。
确认 source hash	`validate()`	META 自身不构成可信证明。

注意事项

不要向返回字典写入业务状态再期待 asset 记住它；VFP 没有就地写回 API。
不要用 objects[0] 表示未来多对象格式的唯一对象；当前编译器写一个对象，但读取代码应保留数组语义。
不要把 META 中的缓存提示当作区段存在或可用的证明；使用 section_tags()、entries() 和 read_section("PRVW") 读取实际 CRC 校验过的载荷。

什么时候使用​

参数与返回值​

最小示例​

用于安全的展示逻辑​

异常​

与相邻 API 的选择​

注意事项​