跳到主要内容

GltiPackageReader

GltiPackageReader 读取 VoxelKit 的可编辑 GLTI。它只接受内嵌原始 VFP 的文件，不做 GLB 网格或视频的反体素化。

from voxelkit import GltiPackageReader

reader = GltiPackageReader()

extract_vfp()​

reader.extract_vfp(
    source: bytes | bytearray | memoryview | str | pathlib.Path,
) -> bytes

在内存中提取并验证原始 VFP。

参数类型说明
sourcebytes | bytearray | memoryview | str | Path完整 GLTI 字节，或 GLTI 文件路径。str 会按文件路径处理，不接受 URL。

返回值是 GLB 扩展中原样保存的 VFP 字节。方法不写文件，适合随后交给上传、对象存储或其他内存 API。

extract_to_vfp()​

reader.extract_to_vfp(
    source: bytes | bytearray | memoryview | str | pathlib.Path,
    output_path: str | pathlib.Path,
) -> GltiExtractionResult

提取、验证并写出 VFP。output_path 的父目录不存在时会自动创建；同名目标会被覆盖。验证在写入前完成，因此失败时不会得到部分恢复的文件。

result = reader.extract_to_vfp("incoming.glti.mp4", "assets/recovered.vfp")
print(result.output)
print(result.vfp_bytes, result.vfp_sha256, result.source_hash)

返回对象字段见 GLTI 选项与结果对象。

验证序列​

每次提取都会完成以下检查：

  1. ISO-BMFF 首项为 ftyp，compatible brands 含 glti；
  2. 顶层 meta 内存在 idat GLB 项；
  3. GLB 是长度一致的 v2 JSON + BIN 双区段结构；
  4. CHARACTECH_voxel_vfp 使用 vfp-raw，其 bufferView、长度和范围正确；
  5. 内嵌 VFP 的 SHA-256 与 GLB 扩展一致；
  6. VFP 的 PAL0、VOX0 与 sourceHash 能重新通过权威校验。

该顺序同时阻止“容器看似可读、实际编辑源已被替换”的情况。

异常与边界​

ValueError 表示 GLTI/GLB 布局、扩展声明、长度、哈希或权威 VFP 不可信；OSError 表示文件读取或写入失败。

展示专用 GLTI 会抛出 ValueError，错误文本包含 presentation-only。这是预期行为：该模式明确没有内嵌 VFP，SDK 不会尝试从 H.264 或标准 GLB 制造近似 VFP。

对于大型资产，读取器需要在内存中持有 GLTI、内嵌 VFP 和解码后的权威体素数据。服务端应限制上传尺寸、在工作线程执行恢复，并在成功后尽快释放输入字节。