跳到主要内容

Vfp.voxels()

asset.voxels() -> bytes

恢复所有权威 VOX0 chunk 为一个连续 RAW8 bytes 缓冲。它忽略 VBUF、PMSH、MSH0、RND0、ANM0 等可删除缓存，因此可用于编辑、转换和独立验证。

缓冲布局​

返回长度固定为 grid_size ** 3，x 轴连续最快：

offset = (z * grid_size + y) * grid_size + x
palette_index = voxels[offset]
值含义
0空体素。
1..len(asset.palette())对应 asset.palette()[value - 1] 的 PaletteEntry.index。

示例：读取一个体素​

from voxelkit import Vfp

asset = Vfp.parse("ship.vfp")
size = asset.inspect()["gridSize"]
buffer = asset.voxels()

def voxel_at(x: int, y: int, z: int) -> int:
    if not (0 <= x < size and 0 <= y < size and 0 <= z < size):
        raise IndexError("voxel coordinate outside grid")
    return buffer[(z * size + y) * size + x]

print(voxel_at(0, 0, 0))

示例：统计每种颜色​

from collections import Counter
from voxelkit import Vfp

asset = Vfp.parse("ship.vfp")
counts = Counter(asset.voxels())
for entry in asset.palette():
    print(entry.symbol, counts[entry.index])
print("empty", counts[0])

性能与所有权​

  • 方法会读取全部 VOX0，对每个 chunk 校验 CRC，按 codec 解码 RAW8 或 RLE8，并把局部体素拷贝到完整线性缓冲。
  • 返回的是新的不可变 bytes；多次调用可能重复分配。需要执行多种分析时，应把结果保存在局部变量中复用。
  • 128³ 网格约为 2 MiB RAW8；255³ 网格约为 15.8 MiB。不要在高频请求、Web handler 热路径或 UI 主线程反复调用。

异常​

VfpError 表示 VOX0 chunk 缺失、重复、排序/尺寸异常、RAW/RLE 长度不匹配、CRC 错误、引用不存在的 PAL0 index，或 META 的 solidVoxelCount 与恢复结果不一致。该方法恢复的是权威数据，但不单独比较 Header source hash；发布前请再调用 validate()。

何时选择其它 API​

目标建议 API
只显示实体体素数或网格inspect()，避免完整恢复。
只读取一个压缩 chunk 的原始存储字节read_section("VOX0", chunk_id=...)。
获取 PAL0 颜色palette()。
验证权威数据身份validate()。
导出为 JSON 或 VOXexport_json() / to_vox()，无需手写三重循环。