跳到主要内容

GltiExporter

GltiExporter 将一个已存在的 VFP 打包为 GLTI MP4。它从 VFP 的权威数据和 PMSH 构建标准 GLB，并按选项生成或复用 H.264 视频。默认将输入 VFP 原样嵌入 GLB，因而可由 GltiPackageReader 无损恢复。

from voxelkit import GltiExporter

export()​

GltiExporter.export(
    vfp_path: str | pathlib.Path,
    output_path: str | pathlib.Path,
    *,
    video_path: str | pathlib.Path | None = None,
    options: GltiExportOptions | None = None,
) -> GltiExportResult

该方法是静态方法，不需要创建 GltiExporter 实例。

参数类型默认值说明
vfp_pathstr | Path必填输入 VFP。必须能被 Vfp.parse() 读取，并包含用于导出预览网格的 PMSH。
output_pathstr | Path必填输出 GLTI MP4 路径。父目录不存在时自动创建；同名文件会被覆盖。
video_pathstr | Path | NoneNone已有兼容 MP4。提供后直接复用其视频容器，不触发 SDK 转台渲染。
optionsGltiExportOptions | NoneNone输出视频与编辑源策略。省略时采用默认的 1024² / 24fps / 3秒 可编辑导出。

默认行为​

当 video_path 与 options.include_video=False 均未设置时，SDK 会：

  1. 从 VFP 的 PMSH 和调色板重建标准 GLB；
  2. 将原始 VFP 嵌入 GLB 的 CHARACTECH_voxel_vfp 扩展；
  3. 离线渲染指定帧数的转台图像；
  4. 使用本机 ffmpeg 编码 H.264；
  5. 写出带 glti compatible brand、视频轨和顶层 meta/idat GLB 项的 MP4。

embed_editable_vfp=False 会跳过第 2 步，输出仍可播放/浏览，但不能恢复为 VFP。

返回值​

返回 GltiExportResult：

  • output：实际写出的 Path；
  • glb_bytes：嵌入 GLB 的字节数；
  • vfp_sha256：输入 VFP 原始字节的 SHA-256；
  • has_video：是否包含视频轨。静态 include_video=False 输出为 False。

异常​

异常条件
FileNotFoundError / OSError输入、输出或提供的视频文件无法访问。
VfpError / ValueErrorVFP 结构、PMSH、调色板或选项不符合要求。
RuntimeError没有 ffmpeg，或转台渲染/H.264 编码子进程失败。

示例：默认可编辑交付​

from voxelkit import GltiExporter

delivery = GltiExporter.export("house.vfp", "house.glti.mp4")
assert delivery.has_video
print(delivery.output, delivery.vfp_sha256)

示例：固定演示帧数​

from voxelkit import GltiExporter, GltiExportOptions

options = GltiExportOptions(width=768, height=768, fps=30, duration_seconds=2.0)
assert options.frame_count() == 60
GltiExporter.export("house.vfp", "house-60f.glti.mp4", options=options)

更多工作流和恢复语义见 GLTI 交付与恢复。