GLTI 交付与恢复

GLTI 是面向交付的 ISO-BMFF / MP4 容器，而不是对 VFP 的替代。一个可编辑 GLTI 可以同时包含：

• 可在系统播放器中播放的 H.264 转台视频；
• 用于 3D 浏览的标准 GLB；
• GLB CHARACTECH_voxel_vfp 扩展引用的原始 VFP 字节。

其中 VFP 的 VOX0 与 PAL0 仍是唯一权威数据。GLB 和视频均可由 VFP 重新生成；恢复编辑工程时始终提取内嵌 VFP，而不从三角形网格或视频反推体素。

导出可编辑 GLTI

from voxelkit import GltiExporter, GltiExportOptions

result = GltiExporter.export(
    "model.vfp",
    "model.glti.mp4",
    options=GltiExportOptions(
        width=1024,
        height=1024,
        fps=24,
        duration_seconds=3.0,
    ),
)

print(result.output)
print(result.has_video, result.glb_bytes, result.vfp_sha256)

默认设置会离线渲染正方形 H.264 转台视频，并把输入 VFP 原样写入 GLB 扩展。视频渲染依赖系统 ffmpeg；若环境没有 ffmpeg，可以提供已有视频，或者导出不带视频轨的静态 GLTI。

# 使用业务侧已有的兼容 MP4，避免 SDK 再次编码。
GltiExporter.export("model.vfp", "model.glti.mp4", video_path="turntable.mp4")

# 只写 GLB 项和 VFP 项，不生成 H.264 视频。
GltiExporter.export(
    "model.vfp",
    "model-static.glti.mp4",
    options=GltiExportOptions(include_video=False),
)

导出展示专用文件

接收方只需要播放或浏览 3D 模型、且不应获得可编辑工程时，关闭编辑载荷：

from voxelkit import GltiExporter, GltiExportOptions

GltiExporter.export(
    "model.vfp",
    "presentation.glti.mp4",
    options=GltiExportOptions(embed_editable_vfp=False),
)

展示专用 GLTI 的 GLB 不含 CHARACTECH_voxel_vfp、VFP 字节或自定义 GLB 扩展。该模式不会加密视频或 GLB；它只是不交付编辑源。若需要访问控制、加密或许可校验，应在文件分发层单独实现。

从 GLTI 恢复 VFP

from voxelkit import GltiPackageReader

reader = GltiPackageReader()
result = reader.extract_to_vfp("model.glti.mp4", "restored.vfp")

print(result.output)
print(result.vfp_bytes, result.vfp_sha256, result.source_hash)

要在内存中继续处理，可直接取得字节：

vfp_bytes = reader.extract_vfp("model.glti.mp4")

读取器会验证 glti compatible brand、顶层 meta/idat 的 GLB、GLB v2 的 JSON/BIN 布局、扩展的长度和 SHA-256，并恢复 PAL0/VOX0 重新计算 source hash。任一校验失败都会抛出 ValueError 或 VFP 读取错误，输出文件不会被写出。

不能恢复的情况

下列输入会被拒绝：

• 普通 MP4 或不声明 glti brand 的文件；
• 没有顶层 meta/idat GLB 的容器；
• 没有 CHARACTECH_voxel_vfp 的展示专用 GLTI；
• 被截断、篡改或 SHA-256 不匹配的内嵌 VFP；
• 容器可读但 PAL0/VOX0/sourceHash 无法通过权威校验的 VFP。

这是一项刻意的可信边界。SDK 不会把 GLB 或视频体素化后当作“恢复成功”，因为那会丢失原始调色板索引、空体素、缓存和可编辑扩展。

选择交付模式

场景	建议
需要视频预览、3D 浏览和继续编辑	默认 GltiExportOptions()。
已经有审核通过的 MP4	传入 video_path，仍保留 GLB/VFP。
只需 3D + 编辑源，不需视频轨	include_video=False。
只需展示，不允许恢复工程	embed_editable_vfp=False。

参数细节见 GltiExporter、GltiPackageReader 和 GLTI 选项与结果对象。