跳到主要内容

转换与缓存重建

导出开放 JSON​

from voxelkit import Vfp

asset = Vfp.parse("model.vfp")
asset.validate()
result = asset.export_json("model.json")
print(result["gridSize"], result["paletteCount"])

导出的 JSON 使用 VoxelKit / PixForge 体素表示：grid_size、colors 与 data[z][y][x]。若 PAL0 符号 无法无歧义映射为该开放 JSON，SDK 会拒绝导出，而不是猜测颜色或覆盖体素。

导出 MagicaVoxel VOX​

asset.to_vox("model.vox")

导出使用单模型 MagicaVoxel Profile。VFP 是立方网格，导出的 .vox 也只表示一个体素对象；图层、动画、 场景树等未来扩展不应被假定能映射到当前 Profile。

从权威数据重建缓存​

rebuilt = asset.rebuild_caches(
    "model-rebuilt.vfp",
    include_preview=True,
    include_runtime_caches=True,
    include_render_cache=False,
    include_animation_cache=True,
    include_thumbnail=True,
    thumbnail_size=512,
    thumbnail_background="transparent",
)

重建会创建新文件，不会覆盖输入 VFP。SDK 先恢复并校验 VOX0/PAL0/sourceHash，随后重新生成派生区段， 旧的 MSH0、VBUF、PMSH、RND0、ANM0、PRVW 与 THMB 不会被信任或复制。

参数默认值说明
include_previewNoneNone 时沿用输入是否已有 PRVW。
include_runtime_cachesTrue生成运行时基础缓存。
include_render_cacheFalse是否生成可选 RND0。
include_animation_cacheTrue是否生成 ANM0。
include_thumbnailNoneNone 时沿用输入是否已有 THMB。
thumbnail_size256重新生成缩略图的边长。
thumbnail_backgroundtransparent缩略图背景。

如权威 VOX0/PAL0 与 source hash 不匹配，重建会失败。这是有意的安全边界，不应通过跳过校验规避。