GLTI 选项与结果对象

from voxelkit import (
    GltiExportOptions,
    GltiExportResult,
    GltiExtractionResult,
)

这三个对象均为不可变 dataclass。它们不持有文件句柄或渲染器状态，可安全记录到任务日志；Path 字段在序列化为 JSON 前应转换为字符串。

GltiExportOptions

GltiExportOptions(
    include_video: bool = True,
    width: int = 1024,
    height: int = 1024,
    fps: int = 24,
    duration_seconds: float = 3.0,
    start_degrees: float = 315.0,
    embed_editable_vfp: bool = True,
)

字段	类型 / 默认值	说明
include_video	bool = True	为 True 且未传 video_path 时渲染并编码 H.264 转台。False 时输出静态 GLTI 容器。
width	int = 1024	转台帧宽。当前必须与 height 相等。
height	int = 1024	转台帧高。当前必须与 width 相等。
fps	int = 24	H.264 时间基准中的每秒帧数，必须大于零。
duration_seconds	float = 3.0	转台时长，必须大于零。
start_degrees	float = 315.0	首帧的转台偏航角，以度为单位。
embed_editable_vfp	bool = True	是否把输入 VFP 原样嵌入 GLB。关闭后是展示专用 GLTI，不能恢复编辑源。

frame_count()

options.frame_count() -> int

返回 round(fps * duration_seconds)，下限为 1。宽高不相等或 width、height、fps、duration_seconds 不为正时抛出 ValueError。

GltiExportResult

GltiExporter.export() 的返回值。

字段	类型	含义
output	Path	已写出的 GLTI MP4 路径。
glb_bytes	int	置入顶层 meta/idat 的 GLB 字节数。
vfp_sha256	str	输入 VFP 原始字节的 64 位十六进制 SHA-256。展示专用模式中仍返回该输入摘要，但文件不含 VFP。
has_video	bool	是否写入视频轨；include_video=False 的静态容器为 False。

GltiExtractionResult

GltiPackageReader.extract_to_vfp() 的返回值。

字段	类型	含义
output	Path	已验证且完整写出的 VFP 路径。
vfp_bytes	int	恢复的 VFP 原始字节数。
vfp_sha256	str	恢复 VFP 的 64 位十六进制 SHA-256，必须与 GLB 扩展声明一致。
source_hash	str	重新从 PAL0/VOX0 计算并验证后的权威 source hash。

vfp_sha256 用于确认交付字节未被替换；source_hash 用于确认可编辑体素与调色板的权威语义正确。两者不能互相替代。