跳到主要内容

Vfp.palette()

asset.palette() -> tuple[PaletteEntry, ...]

读取并解析权威 PAL0 区段，返回按 VFP palette index 排列的不可变条目元组。它是解释 voxels() 返回字节的唯一正确颜色映射。

返回条目​

属性类型范围说明
indexint1..255Voxel buffer 中的非零字节值。0 永远表示空体素，永远不出现在返回元组中。
symbolstrUTF-8，最长 8 字节原始 JSON/VOX 映射使用的调色板符号。
red / green / blueint0..255sRGB 八位颜色通道。

返回顺序保证满足 palette[position].index == position + 1。调用方不应把元组位置与 0-based voxel 值混用。

示例：将体素值变为 RGB​

from voxelkit import Vfp

asset = Vfp.parse("house.vfp")
palette = asset.palette()
voxels = asset.voxels()
size = asset.inspect()["gridSize"]

x, y, z = 10, 8, 4
value = voxels[(z * size + y) * size + x]

if value == 0:
    print("空体素")
else:
    color = palette[value - 1]
    print(color.symbol, (color.red, color.green, color.blue))

示例：构建 CSS/网页调色板​

from voxelkit import Vfp

asset = Vfp.parse("house.vfp")
css_colors = {
    entry.symbol: f"#{entry.red:02X}{entry.green:02X}{entry.blue:02X}"
    for entry in asset.palette()
}
print(css_colors)

symbol 在 VFP 中可为多字节 UTF-8；若需要导出 PixForge JSON，调用 export_json() 前仍会要求符号可无歧义表示为该 JSON 格式的单字符键。

校验与成本​

  • 此方法读取 PAL0 并校验该区段 CRC，不读取 VOX0、网格或预览缓存。
  • 它不重算 source hash；资产可信边界仍是 validate()。
  • 调色板最多 255 项，因而此调用的内存和 CPU 成本通常很小，适合列表和颜色选择器。

异常​

异常原因
VfpErrorPAL0 缺失、重复、CRC 错误、索引不连续、符号长度非法、记录截断或存在未知尾随字节。
OSError读取底层文件失败。

不要从 META 的颜色提示或 PRVW 材质反推调色板；它们都不是 PAL0 的权威替代。