flywave/gltf

Go 语言实现的 glTF 2.0 读写库，含 GLB 二进制格式、数据量化/解量化、 索引式 Draco 与 meshopt 压缩、高斯泼溅、3D Tiles 结构化元数据等 25 个扩展包，由 flywave 独立维护。

本项目为独立维护的修改版，不是任何上游仓库的 fork，无上游跟踪关系。 依据 BSD-2-Clause 许可，基础部分源码的原始版权声明保留于 LICENSE 文件。

包结构

包	说明
gltf（根包）	glTF 2.0 文档模型、JSON/GLB 编解码、结构校验
binary	缓冲区二进制读写（支持交错步长、全部 glTF 组件/类型组合）
modeler	几何数据便捷读写（索引、位置、颜色、法线等）
ext/*	KHR/厂商扩展实现

快速开始

// 读取
doc, err := gltf.Open("model.glb")

// 写入 GLB
err = gltf.SaveBinary(doc, "out.glb")

// 写入 .gltf（外部 buffer 落盘）
err = gltf.Save(doc, "out.gltf")

// 结构校验（枚举、引用完整性、必填字段）
if err := doc.Validate(); err != nil { ... }

使用 modeler 构建网格

doc := gltf.NewDocument()
idx := modeler.WriteIndices(doc, []uint16{0, 1, 2})
pos := modeler.WritePosition(doc, [][3]float32{{0, 0, 0}, {1, 0, 0}, {0, 1, 0}})
prim := &gltf.Primitive{Indices: gltf.Index(idx), Attributes: gltf.Attribute{gltf.POSITION: pos}}
doc.Meshes = append(doc.Meshes, &gltf.Mesh{Primitives: []*gltf.Primitive{prim}})

安全与健壮性

• 解码恶意/损坏文档时各读取 API 返回错误而非 panic。
• 写入前可调用 doc.Validate() 提前发现结构问题（枚举、范围、 引用完整性、extensionsRequired 声明）。
• 编码器阻断 buffer URI 路径穿越；GLB 块长度与声明严格一致。
• 全库附带安全审计（见 AUDIT_REPORT.md）与逐项修复记录 （见 FIXES.md）及 12 个回归测试文件。

注意事项

• go.mod 使用指向同级目录的 replace（go-meshopt、go-draco），克隆后需 将这两个仓库放到相邻目录才能构建。
• 量化扩展使用 FLYWAVE_mesh_quantization 私有名（payload 与 KHR_mesh_quantization 官方语义不同），读取时兼容旧名称。