gltflib

用于在 Python 中解析、创建和转换 glTF 2.0 文件的库。

该库旨在以相当低的级别使用 glTF 2.0，这意味着您是 负责自己管理实际的几何数据。该库有助于保存 将此数据转换为格式正确的 glTF/GLB 文件。它还有助于转换资源 在外部文件或 Web URL、数据 URL 和嵌入式 GLB 之间的 glTF/GLB 文件中 资源。

可以使用 pip 安装此库：

pip install gltflib

以下示例演示了如何将此库用于几个示例方案。这 示例模型来自 Khronos glTF-Sample-Models 存储库，此处提供：

https://github.com/KhronosGroup/glTF-Sample-Models

要加载 glTF 2.0 模型：

from gltflib import GLTF

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF/BoxTextured.gltf')

静态方法还支持加载基于 JSON 的格式 作为二进制格式。文件类型将根据文件名确定 外延。或者，您可以使用 或 。GLTF.load.gltf.glbGLTF.load_gltf(filename)GLTF.load_glb(filename)

加载后，您可以通过访问属性来检查模型结构：model

print(gltf.model)
# GLTFModel(extensions=None, extras=None, accessors=[Accessor(extensions=None, extras=None, name=None, bufferView=0, byteOffset=0, componentType=5123, ...

您还可以检查各种模型属性：

print(gltf.model.buffers[0].uri)
# BoxTextured0.bin

glTF 2.0 模型可能包含资源，例如顶点几何体或图像纹理。这些 资源可以作为模型文件的一部分嵌入，或者（如上面的示例）是 作为外部文件资源引用。

无论哪种情况，在加载模型后，资源都会与模型结构一起解析到属性中：resources

print(gltf.resources)
# [FileResource(CesiumLogoFlat.png), FileResource(BoxTextured0.bin)]

请注意，默认情况下不会加载这些外部文件资源的实际内容 加载模型时。可以通过以下两种方式之一将资源加载到内存中。单程 是调用资源上的方法：load()

resource = gltf.resources[0]
resource.load()     # Assumes resource is a FileResource

另一种方法是在调用时传递标志：load_file_resourcesGLTF.load()

gltf = GLTF.load(filename, load_file_resources=True)

无论哪种情况，现在都可以通过以下属性访问文件资源数据：data

print(resource.data)
# b'x00x00x00x00x00x00x00x00x00x00x80?x00x00x00x00x00x00...

二进制 GLB 文件中的嵌入资源也会解析到列表中，但是 它们将是类型而不是 ：resourcesGLBResourceFileResource

glb = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Binary/BoxTextured.glb')
print(glb.resources)
# [<gltflib.gltf_resource.GLBResource object at 0x7f03db7c1400>]

对于嵌入式资源，内容会自动解析到内存中。二进制数据 可以使用以下属性访问：data

resource = glb.resources[0]
print(resource.data)
# b'x00x00x00x00x00x00x00x00x00x00x80?x00x00x00x00x00x00...'

若要导出模型，请调用类中的实例方法。GLTF.export()GLTF

下面的示例在内存中创建一个简单的 glTF 2.0 模式（由单个 三角形），然后将其导出为名为 （与 名为 ： 外部文件资源 ：triangle.gltfvertices.bin

import struct
import operator
from gltflib import (
    GLTF, GLTFModel, Asset, Scene, Node, Mesh, Primitive, Attributes, Buffer, BufferView, Accessor, AccessorType,
    BufferTarget, ComponentType, GLBResource, FileResource)

vertices = [
    (-4774424.719997984, 4163079.2597148907, 671001.6353722484),
    (-4748098.650098154, 4163079.259714891, 837217.8990777463),
    (-4689289.5292739635, 4246272.966707474, 742710.4976137652)
]

vertex_bytearray = bytearray()
for vertex in vertices:
    for value in vertex:
        vertex_bytearray.extend(struct.pack('f', value))
bytelen = len(vertex_bytearray)
mins = [min([operator.itemgetter(i)(vertex) for vertex in vertices]) for i in range(3)]
maxs = [max([operator.itemgetter(i)(vertex) for vertex in vertices]) for i in range(3)]
model = GLTFModel(
    asset=Asset(version='2.0'),
    scenes=[Scene(nodes=[0])],
    nodes=[Node(mesh=0)],
    meshes=[Mesh(primitives=[Primitive(attributes=Attributes(POSITION=0))])],
    buffers=[Buffer(byteLength=bytelen, uri='vertices.bin')],
    bufferViews=[BufferView(buffer=0, byteOffset=0, byteLength=bytelen, target=BufferTarget.ARRAY_BUFFER.value)],
    accessors=[Accessor(bufferView=0, byteOffset=0, componentType=ComponentType.FLOAT.value, count=len(vertices),
                        type=AccessorType.VEC3.value, min=mins, max=maxs)]
)

resource = FileResource('vertices.bin', data=vertex_bytearray)
gltf = GLTF(model=model, resources=[resource])
gltf.export('triangle.gltf')

与 一样，该方法根据文件扩展名推断格式 （ 与 ）。但是，您也可以手动调用或 强制格式化。loadexport.gltf.glbexport_gltfexport_glb

在上面的示例中，导出将生成两个文件：和 。 但是，可以通过在调用时将标志设置为 来绕过保存外部文件资源：triangle.gltfvertices.binsave_file_resourcesFalseexport

gltf.export('triangle.gltf', save_file_resources=False)

要将模型导出为二进制 GLB，只需在调用 时更改扩展名，或使用：exportexport_glb

gltf.export('triangle.glb')

请注意，当导出为 GLB 时，默认情况下将嵌入所有资源（即使 它们被实例化为 ）。这通常是在以下情况下所期望的行为 保存为 GLB。FileResource

但是，导出时可以强制部分或全部资源保持在外部 GLB。为此，您必须调用 （而不是 ），并将 one or （或 both ） 设置为 ：export_glbexportembed_buffer_resourcesembed_image_resourcesFalse

resource = FileResource('vertices.bin', data=vertex_bytearray)
gltf = GLTF(model=model, resources=[resource])
gltf.export_glb('triangle.glb', embed_buffer_resources=False, embed_image_resources=False)

在这种情况下，您还需要确保关联的缓冲区仍具有 模型中的适当集：uri

model = GLTFModel(
    ...,
    buffers=[Buffer(byteLength=bytelen, uri='vertices.bin')],

该模型将导出为二进制 GLB，但具有外部文件资源。这些 导出模型时，默认情况下将保存文件资源。然而，它也是 可以通过在调用时将 设置为 来绕过保存外部文件资源：save_file_resourcesFalseexport_glb

gltf.export_glb('triangle.glb', embed_buffer_resources=False, embed_image_resources=False,
                save_file_resources=False)

要将 glTF 模型转换为 GLB，只需加载它并使用扩展导出它：glb

from gltflib import GLTF

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF/BoxTextured.gltf')
gltf.export('BoxTextured.glb')

这将自动将所有外部文件资源转换为嵌入式 GLB 资源。

反向转换也是可能的，但有一些注意事项。由于非二元性别 glTF模型可能没有嵌入的二进制数据，必须先转换 设置为不同的资源类型。下面关于资源的部分将详细介绍 但这里有一个快速示例，在导出到 glTF 之前，首先将 转换为具有文件名的 a：GLBResourceGLBResourceFileResourceBoxTextured.bin

from gltflib import GLTF

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Binary/BoxTextured.glb')
glb_resource = gltf.get_glb_resource()
gltf.convert_to_file_resource(glb_resource, 'BoxTextured.bin')
gltf.export('BoxTextured.gltf')

请注意，GLB 文件通常包含一个组合数据的二进制 GLB 块 来自多个缓冲区（然后由多个缓冲区视图、图像和 访问器）。目前，将 GLB 转换为 glTF 时，整个 GLB 块可以 转换为不同类型的资源，但该资源不能拆分为 多个资源（例如，每个缓冲区单独的资源）。

glTF 和 GLB 模型可以引用嵌入式或外部资源（通过缓冲区或图像 URI，或者在 GLB 的情况下，通过保留第一个缓冲区的 URI 未定义）。这些 资源在此库中使用 base 的子类表示 类。加载模型时将解析这些资源，并且必须正确 在导出之前实例化并添加到模型中。GLTFResource

此库支持 4 种资源类型：

• FileResource：文件资源是引用文件路径的资源。
• Base64Resource：直接嵌入在 glTF（或 GLB）文件中的资源 使用 Base64 编码的数据 URI。
• GLBResource：仅由 GLB 文件使用，此资源类型表示二进制 GLB 直接嵌入在 GLB 文件中的块。
• ExternalResource：外部资源是指外部 Web URL。

如果特定资源的 URI 由 叫：get_resource

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF/BoxTextured.gltf')
logo = gltf.get_resource('CesiumLogoFlat.png')
print(logo)
# FileResource(CesiumLogoFlat.png)

或者，可以使用加载模型上的列表获取模型中所有资源的列表：resources

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF/BoxTextured.gltf')
print(gltf.resources)
# [FileResource(CesiumLogoFlat.png), FileResource(BoxTextured0.bin)]

该类提供了可用于转换资源的帮助程序方法 从一种类型到另一种类型。其中一些方法需要一些额外的信息 进行转换;例如，将文件名转换为 ， 或转换为 .GLTFFileResourceBase64Resource

以下部分详细介绍了每种资源类型，包括其 注意事项和限制，以及如何将给定资源转换为该类型。

文件资源使用类表示，并表示资源 引用文件路径（通常是相对路径，尽管绝对文件路径是 也支持）。FileResource

加载模型时，通过查看 缓冲区和图像;但是，除非在调用 ： 时将标志设置为 ：uriload_file_resourcesTrueGLTF.load()

gltf = GLTF.load(filename, load_file_resources=True)

或者，可以在实例上调用该方法进行加载 数据进入内存：load()FileResource

resource = FileResource('triangleWithoutIndices.bin')
resource.load()

将文件资源加载到内存中后，可以通过以下属性访问其内容：data

print(resource.data)
# b'x00x00x00x00x00x00x00x00x00x00x80?x00x00x00x00x00x00...

导出模型时，默认情况下，文件资源将写入磁盘。然而 这可以通过在调用时设置标志来绕过：save_file_resourcesFalseexport

gltf.export(filename, save_file_resources=False)

手动创建模型实例时，如果还打算保存文件 resources，则引用文件路径的每个缓冲区或图像的列表中必须有一个对应的（否则，错误 在尝试导出时会引发）：FileResourceresources

resource = FileResource('buffer.bin')
model = GLTFModel(asset=Asset(version='2.0'), buffers=[Buffer(uri='buffer.bin', byteLength=18)])
gltf = GLTF(model=model, resources=[resource])
gltf.export('model.gltf')

实例化 时，如果文件的内容已知，则可以 通过构造函数参数提供：FileResourcedata

resource = FileResource('buffer.bin', data=b'binary content here')

可以将另一种类型的资源转换为 GLTF 类上的 using helper 方法。这种方法 需要一个文件名作为参数，并返回转换后的实例：FileResourceconvert_to_file_resourceFileResource

resource = gltf.resources[0]
file_resource = gltf.convert_to_file_resource(resource, 'BoxTextured.bin')

请注意，在保存模型之前，不会创建该文件（标志设置为 ）。另外，请注意，要转换的资源必须是 模型中列表的一部分（否则会引发错误）。save_file_resourcesTrueresources

如果资源已经是 a 并且文件名匹配，则不执行任何作执行。如果文件名不同，则文件名将更新在引用它的任何缓冲区和图像上。FileResource

如果要转换的资源是 或 ，它将是un嵌入并转换为外部文件资源，并且引用的任何缓冲区资源将得到适当更新。任何引用的嵌入图像资源将被更新。如果图像之前引用了缓冲区视图，它将现在引用一个 URI;如果没有，则相应的缓冲区视图将被删除模型的其他部分引用它。此外，删除缓冲区视图后，如果没有其他缓冲区视图引用同一缓冲区，则缓冲区将被删除为 井。GLBResourceBase64Resource

如果要转换的资源是 ，此方法将引发错误（不支持访问外部资源数据）。ExternalResource

glTF 支持使用数据 URI 将资源直接嵌入到基于 JSON 的 glTF 文件（或 GLB文件，尽管它并不常见）中。在这种情况下，资源被定义为 URI 本身的一部分，允许模型是独立的，而不必使用 GLB 格式：

{
  ...
  "images": [
    {
      "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAEDW..."
    }
  ],
  ...
}

加载此类模型时，将实例化类型为的资源 并添加到模型列表中。资源的属性将 包含原始数据 URI，而该属性可用于访问 解码后的二进制数据：Base64Resourceresourcesuridata

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Embedded/BoxTextured.gltf')
logo = gltf.resources[1]
print(logo.data)
# b'x00x00x00x00x00x00x00x00x00x00x80?x00x00x00x00x00x00...

要实例化 ，有两个选项。一种是使用 构造函数以传入二进制数据和 MIME 类型（如果未提供，则默认为）：Base64Resourceapplication/octet-stream

resource = Base64Resource(b'sample binary data', mime_type='application/octet-stream')

另一种方式是使用工厂方法并传递 在数据 URI 中：Base64Resource.from_uri

resource = Base64Resource.from_uri('data:application/octet-stream;base64,c2FtcGxlIGJpbmFyeSBkYXRh')

要将另一种类型的资源转换为 ，请使用 helper 方法。如果原始资源的 MIME 类型已知，则此方法接受可选参数（默认值 如果未提供，则为 ）：Base64ResourceGLTF.convert_to_base64_resourcemime_typeapplication/octet-stream

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF/BoxTextured.gltf')
logo = gltf.get_resource('CesiumLogoFlat.png')
gltf.convert_to_base64_resource(logo, 'image/png')
gltf.export('BoxTexturedBase64.gltf')

如果要转换的资源已经是 ，则不执行任何作。Base64Resource

如果资源是 ，则它将转换为 . 如果尚未加载，则将从磁盘加载 （ 如果文件不存在，可能会引发 a）。FileResourceBase64ResourceFileResourceIOError

如果资源是 ，它将转换为 .这 GLB 缓冲区将替换为带有数据 URI 的缓冲区（如果它 仅供图像使用）。任何通过缓冲区视图引用资源的图像都将 而是通过数据 URI 直接引用图像，以及相应的缓冲区视图 将被删除（如果其他地方没有引用）。此外，如果没有其他缓冲区 视图引用与删除的缓冲区视图相同的缓冲区，则缓冲区将是 也完全删除了。GLBResourceBase64Resource

如果资源是 ，此方法将引发错误（访问 不支持外部资源数据）。ExternalResource

GLB 资源是作为二进制文件直接嵌入到 GLB 文件中的资源 块。这些资源只能与 GLB 文件一起使用（如果保存到 glTF，这些 资源必须首先转换为其他类型）。

一个文件中通常有一个 GLB 块（块类型为 ），尽管它 如果具有多个 GLB 块具有不同的块类型，则它们是有效的。这 库支持加载和保存这些额外的 GLB 块，但没有 对其内容做出假设。BIN

对主 GLB 块对应的引用（使用 chunk 类型）可以通过调用模型来获得 实例，其数据可以通过属性访问：GLBResourceBINget_glb_resourcedata

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Binary/BoxTextured.glb')
glb_resource = gltf.get_glb_resource()
print(glb_resource.data)
# b'x00x00x00x00x00x00x00x00x00x00x80?x00x00x00x00x00x00...

可以通过调用将参数设置为块类型来引用其他 GLB 块：get_glb_resourceresource_type

my_custom_glb_resource = gltf.get_glb_resource(resource_type=123)

另一种类型的单个资源可以转换为 helper 方法。这允许嵌入特定资源 同时在导出到 GLB 时将其他内容留在外部（在这种情况下，请确保 使用 代替 ，并设置 和 to 以防止其他资源也 被自动嵌入）：GLBResourceembed_resourceexport_glbexportembed_buffer_resourcesembed_image_resourcesFalse

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Binary/BoxTextured.glb')
logo = gltf.get_resource('CesiumLogoFlat.png')
gltf.embed_resource(logo)
gltf.export_glb('BoxTexturedPartial.glb', embed_buffer_resources=False, embed_image_resources=False)

但是，最常见的情况是嵌入所有资源，无论其类型如何，这在使用扩展调用时自动发生（或使用默认参数集调用时）。export.glbexport_glb

请注意，不支持嵌入 an，因为它的数据是不可访问的（此库不支持从外部加载资源Web URL）。ExternalResource

如其他部分所述，将 a 转换为另一种类型（即“取消嵌入”资源）通常不仅会替换相应缓冲区和图像上的 URI，而且还可能导致删除GLB 缓冲区和缓冲区视图（如果它们没有在其他地方也被引用）。GLBResource

外部资源（由类表示）是资源 具有外部 Web URL 的 URL。虽然这个库能够加载模型 外部 Web URL，则不会获取资源本身。类型的资源将使用相应的 URI 进行实例化，但 库将不会执行任何 Web 请求来加载资源数据。同样 该库支持保存包含实例的模型， 但同样，不会执行任何 Web 请求。ExternalResourceExternalResourceExternalResource

另一种类型的资源可以转换为使用辅助方法，该方法接受 URL：ExternalResourceGLTF.convert_to_external_resource

gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF/BoxTextured.gltf')
logo = gltf.get_resource('CesiumLogoFlat.png')
gltf.convert_to_external_resource(logo, 'http://www.example.com/image.png')
gltf.export('BoxTexturedExternal.gltf')

同样，由于此库不处理对外部资源的调用， 这严格来说是一种簿记作。这是来电者的责任 以确保资源存在于外部。转换资源时的注意事项 到 ，资源数据将变得无法访问。ExternalResource

如果资源已经是 并且 URI 匹配，则不执行任何作 被执行。如果 URI 不同，则将在资源上更新 URI 实例以及模型中任何相应的缓冲区或图像上。ExternalResource

如果资源是 或 ，则它将被转换 设置为 ，所有缓冲区和图像都将得到适当的更新。FileResourceBase64ResourceExternalResource

如果资源是 ，它将转换为 . GLB 缓冲区将替换为具有数据 URI 的缓冲区（或完全删除 如果它仅由图像使用）。通过缓冲区引用资源的任何图像 view 将直接通过数据 URI 引用图像，而相应的 buffer 视图将被删除（如果它没有在其他地方引用）。此外，如果 没有其他缓冲区视图引用与删除的缓冲区视图相同的缓冲区，则 缓冲区也将被完全删除。GLBResourceExternalResource

该项目基于 Luke Miller 的图书馆：https://gitlab.com/dodgyville/pygltflibpygltflib

具体来说，这个项目基于一个更早的版本 at 它似乎没有得到积极维护的时候。卢卡斯·肖福德 （Lukas Shawford） 将该库用作 起点，并添加了他自己工作所需的一些功能。从那时起， 原来的项目已经恢复，但这个实现已经 出现了显着分歧。所以现在有两个 ：-）pygltflibpygltflib