常见问题与排障

为什么 extract_thumbnail() 失败？

文件可能没有 THMB，或缩略图区段损坏。先查看：

from voxelkit import Vfp
asset = Vfp.parse("model.vfp")
print(asset.inspect()["caches"])

若 thumbnail 为 False，使用 rebuild_caches(..., include_thumbnail=True) 输出新文件，或重新编译时保持 thumbnail=True。不要用缺失 THMB 判断 VOX0 是否损坏。

为什么 extract_glb() 失败？

PRVW 是可选预览。以 preview=False 编译的文件不包含它；重新编译或重建时设置 include_preview=True。

为什么 rebuild_caches() 拒绝执行？

它会重新计算 VOX0/PAL0 的 source hash。若与 Header/META 不一致，代表权威数据存在不一致或损坏，SDK 会 拒绝在此基础上生成可信缓存。保存原文件，记录错误，再从原始 JSON / VOX 重新编译。

为什么 VOX 文件无法导入？

当前仅支持一个模型的 MAIN/SIZE/XYZI[/RGBA] Profile。PACK、nTRN、nGRP、nSHP 等场景结构会被拒绝， 因为压平会丢失对象与变换语义。请在 MagicaVoxel 中导出单个模型。

为什么透明缩略图在某些界面看起来是黑色？

默认 THMB 为透明 RGBA PNG。宿主若不正确合成 alpha，可能显示为黑色。调用方应在 UI 中合成背景，或编译时传入 thumbnail_background="#F5F7FA" 等明确颜色。