用于编码 glTF 2.0 文件的 Go 库-GLB下载网

用于高效、健壮地序列化/反序列化 glTF 2.0 的 Go 模块，这是一种免版税规范，用于应用程序高效传输和加载 3D 场景和模型，也称为“3D 的 JPEG”。

⭐ 主要特点

gltf。文档：惯用 glTF 数据模型
gltf。打开 / gltf。Save：和 [d]编码支持.glTF.glb
qmuntal/gltf/ext：内置可扩展性机制，开箱即用，主要扩展
qmuntal/gltf/modeler：用于读写访问器和缓冲区视图的友好包
qmuntal/gltf/binary：友好且高效的包，用于从缓冲区中读取和写入字节

📜 开始

数据模型

qmuntal/gltf实现整个 glTF 2.0 规范。顶层元素是 gltf.Document，它包含将 gltf 文档保存在内存中的所有信息：

// This document does not produce any valid glTF, it is just an example.
gltf.Document{
  Accessors: []*gltf.Accessor{
      {BufferView: gltf.Index(0), ComponentType: gltf.ComponentUshort, Type: gltf.AccessorScalar},
  },
  Asset: gltf.Asset{Version: "2.0", Generator: "qmuntal/gltf"},
  BufferViews: []*gltf.BufferView{
      {ByteLength: 72, ByteOffset: 0, Target: gltf.TargetElementArrayBuffer},
  },
  Buffers: []*gltf.Buffer{{ByteLength: 1033, URI: bufferData}},
  Meshes: []*gltf.Mesh{{
    Name: "Cube",
  }},
  Nodes: []*gltf.Node{{Name: "Cube", Mesh: gltf.Index(0)}},
  Scene:    gltf.Index(0),
  Scenes:   []*gltf.Scene{{Name: "Root Scene", Nodes: []int{0}}},
}

可选参数

所有默认值与 golang 类型零值不匹配的可选属性都被定义为指针。使用可选值时，请考虑以下准则：

如果所需值是默认值，则在编写 glTF 时不定义它们是安全的。
可以肯定的是，读取 glTF 时可选值不是 nil。
将值分配给可选属性时，使用以下实用程序函数可能会有所帮助：
- gltf.Index(1)
- gltf.Float(0.5)

阅读文档

一个 gltf。可以使用 gltf 从任何文档中解码文档。解码器：io.Reader

resp, _ := http.Get("https://example.com/static/foo.gltf")
var doc gltf.Document
gltf.NewDecoder(resp.Body).Decode(&doc)
fmt.Print(doc.Asset)

在使用文件系统时，使用 gltf 更方便。打开，因为它会自动管理相对的外部缓冲区：

doc, _ := gltf.Open("./foo.gltf")
fmt.Print(doc.Asset)

在这两种情况下，解码器都会根据文件的内容自动检测文件是 JSON/ASCII （gltf）还是二进制（glb）。

编写文档

一个 gltf。可以使用 gltf 将文档编码为任何文档。编码器：io.Writer

var buf bytes.Buffer
gltf.NewEncoder(&buf).Encode(&doc)
http.Post("http://example.com/upload", "model/gltf+binary", &buf)

默认输出一个二进制文件，以生成设置为 false 的 JSON/ASCII 文件：gltf.NewEncoderAsBinary

var buf bytes.Buffer
enc := gltf.NewEncoder(&buf)
enc.AsBinary = false
enc.Encode(&doc)
http.Post("http://example.com/upload", "model/gltf+json", &buf)

在使用文件系统时，使用 gltf 更方便。保存并 gltf。SaveBinary，因为它会自动管理相对的外部缓冲区：

gltf.Save(&doc, "./foo.gltf")
gltf.SaveBinary(&doc, "./foo.glb")

作缓冲区视图和访问器

包 gltf/modeler 定义了一个友好的 API 来读写访问器和缓冲区视图，抽象化了所有字节作工作和 glTF 规范的特质。

以下示例创建单个彩色三角形：

doc := gltf.NewDocument()
doc.Meshes = []*gltf.Mesh{{
    Name: "Pyramid",
    Primitives: []*gltf.Primitive{{
        Indices: gltf.Index(modeler.WriteIndices(doc, []uint16{0, 1, 2})),
        Attributes: gltf.PrimitiveAttributes{
          gltf.POSITION: modeler.WritePosition(doc, [][3]float32{{0, 0, 0}, {0, 10, 0}, {0, 0, 10}}),
          gltf.COLOR_0:  modeler.WriteColor(doc, [][3]uint8{{255, 0, 0}, {0, 255, 0}, {0, 0, 255}}),
        },
    }},
}}
doc.Nodes = []*gltf.Node{{Name: "Pyramid", Mesh: gltf.Index(0)}}
doc.Scenes[0].Nodes = append(doc.Scenes[0].Nodes, 0)
gltf.Save(doc, "./test.gltf")

数据交错

存储在单个 bufferView 中的属性数据可以存储为 Array-Of-Structures，这可能会在静态属性中产生渲染性能提升。使用 WritePrimitiveAttributes、WriteAccessorsInterled 和 WriteBufferViewInterleaved 方法，方便创建交错访问器和缓冲区视图，这是创建网格基元时最推荐的第一个方法：qmuntal/gltf/modeler

doc := gltf.NewDocument()
attrs, _ := modeler.WritePrimitiveAttributes(doc,
    modeler.PrimitiveAttribute{Name: gltf.POSITION, Data: [][3]float32{{0, 0, 0}, {0, 10, 0}, {0, 0, 10}}},
    modeler.PrimitiveAttribute{Name: gltf.COLOR_0, Data: [][3]uint8{{255, 0, 0}, {0, 255, 0}, {0, 0, 255}}},
)
doc.Meshes = []*gltf.Mesh{{
    Name: "Pyramid",
    Primitives: []*gltf.Primitive{{
        Indices: gltf.Index(modeler.WriteIndices(doc, []uint16{0, 1, 2})),
        Attributes: attrs,
    }},
}}
doc.Nodes = []*gltf.Node{{Name: "Pyramid", Mesh: gltf.Index(0)}}
doc.Scenes[0].Nodes = append(doc.Scenes[0].Nodes, 0)
gltf.Save(doc, "./test.gltf")

作字节

包 gltf/binary 定义了一个友好且高效的 API，用于从缓冲区读取和写入字节，从而抽象化所有字节作工作。这个包是非常低级别的，普通用户应该改用，因为它提供了另一个抽象级别，可以理解字节如何与其他实体相关联。gltf/modeler

这个包与 Go 包非常相似，主要区别在于它在 glTF 数据类型方面高度专业化，并且它只需要处理小端编码。binary

处理扩展

qmuntal/gltf旨在支持动态扩展。默认情况下，仅解码核心规范，扩展对象内的数据被存储，以便调用者可以解码它们或在保存文档时自动编码。json.RawMessage

一些官方扩展是在 ext.

要解码受支持的扩展之一，唯一需要的作是导入关联的包，这样扩展将不会存储为扩展包中定义的类型：json.RawMessage

import (
  "github.com/qmuntal/gltf"
  "github.com/qmuntal/gltf/ext/lightspunctual"
)

func main() {
  doc, _ := gltf.Open("./foo.gltf")
    if v, ok := doc.Extensions[lightspunctual.ExtensionName]; ok {
        for _, l := range v.(lightspunctual.Lights) {
            fmt.Print(l.Type)
        }
    }
}

无需调用内置扩展，因为这些扩展在初始化包时会自动注册。gltf.RegisterExtension

外部扩展

此列表是在其他模块中实现的已知扩展列表：

天龙-GO/GLTF/天龙

自定义扩展

要实现自定义扩展编码，请提供可以按照规范规定编码为 JSON 对象的。struct

要实现自定义扩展解码，请调用 gltf。RegisterExtension 在解码前至少进行一次，提供扩展的标识符和将 JSON 字节解码为所需字节的函数：struct

const ExtensionName = "FAKE_Extension"

type Foo struct {
    BufferView int          `json:"bufferView"`
    Attributes gltf.Attributes  `json:"attributes"`
}

func init() {
    gltf.RegisterExtension(ExtensionName, Unmarshal)
}

func Unmarshal(data []byte) (any, error) {
    foo := new(Foo)
    err := json.Unmarshal(data, foo)
    return foo, err
}

🙋 贡献

非常欢迎忍者地鼠的公关、问题和反馈。

关于项目

该库是 glTF 2.0 的完整实现，其明确目标是提供一个生产就绪、惯用且精心策划的 API 来执行任何类型的 glTF作。

实现与其他文件格式之间的转换以及提供创建和作 3D 几何体的机制超出了范围。

当前的 API 仍未被冻结，在达到 v1.0 之前可能会发生细微的变化。

如果您想报告问题或讨论功能，请使用问题跟踪器或。

Name
qmuntal 合并来自 qmuntal/nil-buffer 的拉取请求 #94 248c8f3 · 11 months ago
.github 域名	更新test.yml	last year
资产	改进自述文件	5 years ago
二元的	修复 castSlice	last year
内线	删除验证标记	last year
建模师	当 bufferView 和 sparse 为 nil 时，在 ReadAccessor 中返回非 nil 切片	11 months ago
测试数据	支持嵌入第一个缓冲区的二进制 GLTF	3 years ago
.gitignore 域名	初始提交	7 years ago
许可证	更改为 BSD 2 原因许可证	7 years ago
README.md	对所有非线数据使用 int 而不是 uint32	last year
bench_test.go	使用黑盒测试	last year
const.go	对所有非线数据使用 int 而不是 uint32	last year
const_strings.go	为所有 const 类型实现 String 方法	4 years ago
const_test.go	使用黑盒测试	last year
解码器.go	对所有非线数据使用 int 而不是 uint32	last year
decoder_test.go	对所有非线数据使用 int 而不是 uint32	last year
编码.go	删除验证标记	last year
encode_test.go	使用黑盒测试	last year
example_test.go	对所有非线数据使用 int 而不是 uint32	last year
export_test.go	使用黑盒测试	last year
gltf.go	删除验证标记	last year
gltf_test.go	对所有非线数据使用 int 而不是 uint32	last year
go.mod	支持包含“..”	last year
go.sum	删除验证器依赖项	6 years ago
数学.go	随处使用 float32	5 years ago
math_test.go	使用黑盒测试	last year