Description:

gltflib 1.0.13

gltflib
Library for parsing, creating, and converting glTF 2.0 files in Python 3.6+.
Overview
This library is intended for working with glTF 2.0 at a fairly low level, meaning you are
responsible for managing the actual geometry data yourself. This library facilitates saving
this data into a properly formatted glTF/GLB file. It also helps with converting resources
inside a glTF/GLB file between external files or web URLs, data URLs, and embedded GLB
resources.
Installation
This library can be installed using pip:
pip install gltflib

Usage
The examples below illustrate how to use this library for a couple sample scenarios. The
example models come from the Khronos glTF-Sample-Models repository available here:
https://github.com/KhronosGroup/glTF-Sample-Models
Parsing a glTF 2.0 Model
To load a glTF 2.0 model:
from gltflib import GLTF

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

The GLTF.load static method supports loading both the JSON-based .gltf format, as well
as the binary .glb format. The type of the file will be determined based on the filename
extension. Alternatively, you can use GLTF.load_gltf(filename) or GLTF.load_glb(filename).
After loading, you can inspect the model structure by accessing the model property:
print(gltf.model)
# GLTFModel(extensions=None, extras=None, accessors=[Accessor(extensions=None, extras=None, name=None, bufferView=0, byteOffset=0, componentType=5123, ...

You can also inspect the various model properties:
print(gltf.model.buffers[0].uri)
# BoxTextured0.bin

A glTF 2.0 model may contain resources, such as vertex geometry or image textures. These
resources can be embedded as part of the model file, or (as with the above example) be
referenced as external file resources.
In either case, the resources are parsed alongside the model structure into the resources
property after loading a model:
print(gltf.resources)
# [FileResource(CesiumLogoFlat.png), FileResource(BoxTextured0.bin)]

Note that the actual content of these external file resources is not loaded by default
when loading a model. You can load the resource into memory in one of two ways. One way
is to call the load() method on the resource:
resource = gltf.resources[0]
resource.load() # Assumes resource is a FileResource

Another way is to pass the load_file_resources flag when calling GLTF.load():
gltf = GLTF.load(filename, load_file_resources=True)

In either case, now the file resource data can be accessed via the data property:
print(resource.data)
# b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?\x00\x00\x00\x00\x00\x00\...

Embedded resources in binary GLB files are also parsed into the resources list, but
they will be of type GLBResource instead of FileResource:
glb = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Binary/BoxTextured.glb')
print(glb.resources)
# [<gltflib.gltf_resource.GLBResource object at 0x7f03db7c1400>]

For embedded resources, the content is parsed into memory automatically. The binary data
can be accessed using the data property:
resource = glb.resources[0]
print(resource.data)
# b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?\x00\x00\x00\x00\x00\x00\...'

Exporting a glTF 2.0 Model
To export a model, call the GLTF.export() instance method in the GLTF class.
The example below creates a simple glTF 2.0 mode in memory (consisting of a single
triangle), then exports it as a glTF file named triangle.gltf (alongside with an
external file resource named vertices.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')

As with load, the export method infers the format based on the filename extension
(.gltf vs .glb). However, you can also call export_gltf or export_glb to manually
force the format.
In the above example, the export will produce two files: triangle.gltf and vertices.bin.
However, it is possible to bypass saving external file resources by setting the
save_file_resources flag to False when calling export:
gltf.export('triangle.gltf', save_file_resources=False)

To export the model as a binary GLB instead, simply change the extension when calling
export, or use export_glb:
gltf.export('triangle.glb')

Note that when exporting as a GLB, all resources will be embedded by default (even if
they were instantiated as a FileResource). This is generally the desired behavior when
saving as a GLB.
However, it is possible to force some or all resources to remain external when exporting
a GLB. To do so, you must call export_glb (instead of export), and setting either
embed_buffer_resources or embed_image_resources (or both) to False:
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)

In this case, you will also need to ensure that the associated buffers still have the
appropriate uri set in the model:
model = GLTFModel(
...,
buffers=[Buffer(byteLength=bytelen, uri='vertices.bin')],

The model will be exported as a binary GLB, but with external file resources. These
file resources will be saved by default when exporting the model. However, it is also
possible to bypass saving external file resources by setting the save_file_resources
to False when calling export_glb:
gltf.export_glb('triangle.glb', embed_buffer_resources=False, embed_image_resources=False,
save_file_resources=False)

Converting Between glTF and GLB
To convert a glTF model to GLB, simply load it and export it using the glb extension:
from gltflib import GLTF

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

This will automatically convert all external file resources to become embedded GLB
resources.
The reverse conversion is also possible, though with some caveats. Since a non-binary
glTF model may not have embedded binary data, the GLBResource must first be converted
to a different resource type. The section on Resources below goes into more details,
but here is a quick example where the GLBResource is first converted to a FileResource
with the filename BoxTextured.bin prior to exporting to glTF:
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')

Note that a GLB file typically contains a single binary GLB chunk that combines data
from multiple buffers (which are then consumed by multiple buffer views, images, and
accessors). Currently, when converting a GLB to glTF, the entire GLB chunk can be
converted to a resource of a different type, but the resource cannot be split out into
multiple resources (e.g., separate resource per buffer).
Resources
glTF and GLB models can refer to embedded or external resources (via the buffer or image
URIs, or in the case of GLB, by leaving the first buffer's URI undefined). These
resources are represented in this library using subclasses of the GLTFResource base
class. These resources will be parsed when loading a model, and must be properly
instantiated and added to the model prior to exporting.
There are 4 resource types that are supported by this library:

FileResource: File resources are resources that refer to a file path.
Base64Resource: Resources that are embedded directly in the glTF (or GLB) file
using a Base64-encoded data URI.
GLBResource: Used only by GLB files, this resource type represents the binary GLB
chunk that is embedded directly in the GLB file.
ExternalResource: External resources refer to external web URLs.

A reference to a particular resource can be obtained if its URI is known by
calling 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)

Alternatively, a list of all resources in a model can be obtained using the
resources list on the loaded model:
gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF/BoxTextured.gltf')
print(gltf.resources)
# [FileResource(CesiumLogoFlat.png), FileResource(BoxTextured0.bin)]

The GLTF class provides helper methods that can be used to convert a resource
from one type to another. Some of these methods require some additional information
to do the conversion; for instance, the filename when converting to a FileResource,
or the MIME type when converting to a Base64Resource.
The sections below go into more detail about each resource type, including their
caveats and limitations, as well as how to convert a given resource to that type.
File Resources
File resources are denoted using the FileResource class, and represent resources
that refer to a file path (generally a relative path, though absolute file paths are
also supported).
When loading a model, these resources are parsed by looking at the uri property on
buffers and images; however, their content is not automatically loaded unless the
load_file_resources flag is set to True when calling GLTF.load():
gltf = GLTF.load(filename, load_file_resources=True)

Alternatively, the load() method can be called on a FileResource instance to load
the data into memory:
resource = FileResource('triangleWithoutIndices.bin')
resource.load()

Once the file resource is loaded into memory, its content is accessible via the data
property:
print(resource.data)
# b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?\x00\x00\x00\x00\x00\x00\...

When exporting a model, file resources will be written to disk by default. However,
this can be bypassed by setting the save_file_resources flag False when calling
export:
gltf.export(filename, save_file_resources=False)

When creating a model instance manually, if the intention is to also save file
resources, then there must be a corresponding FileResource in the resources
list for every buffer or image that references a file path (otherwise, an error
will be raised when attempting to export):
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')

When instantiating a FileResource, if the content of the file is known, it can
be provided via the data constructor parameter:
resource = FileResource('buffer.bin', data=b'binary content here')

A resource of another type can be converted to a FileResource using the
convert_to_file_resource helper method on the GLTF class. This method
requires a filename as a parameter, and returns the converted FileResource
instance:
resource = gltf.resources[0]
file_resource = gltf.convert_to_file_resource(resource, 'BoxTextured.bin')

Note the file will not be created until the model is saved (with save_file_resources
flag set to True). Also, note that the resource to be converted must be
part of the resources list in the model (otherwise an error will be raised).
If the resource is already a FileResource and the filename matches, no action
is performed. If the filename is different, then the filename will be updated
on any buffers and images that reference it.
If the resource to be converted is a GLBResource or Base64Resource, it will be
un-embedded and converted to an external file resource, and any buffers that reference
the resource will be updated appropriately. Any embedded images that reference the
resource will be updated. If the image previously referenced a buffer view, it will
now reference a URI instead; the corresponding buffer view will be removed if no
other parts of the model refer to it. Further, after removing the buffer view, if
no other buffer views refer to the same buffer, then the buffer will be removed as
well.
If the resource to be converted is an ExternalResource, this method will raise an
error (accessing external resource data is not supported).
Base-64 (Data URI) Resources
glTF supports embedding a resource directly into a JSON-based glTF file (or a GLB
file, though it's not as common) using a
data URI.
In this scenario, the resource is defined as part of the URI itself, allowing the
model to be self-contained without necessarily using the GLB format:
{
...
"images": [
{
"uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAEDW..."
}
],
...
}

When loading such a model, a resource of type Base64Resource will be instantiated
and added to the model's resources list. The uri property of the resource will
contain the original data URI, while the data property can be used to access the
decoded binary data:
gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Embedded/BoxTextured.gltf')
logo = gltf.resources[1]
print(logo.data)
# b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?\x00\x00\x00\x00\x00\x00\...

To instantiate a Base64Resource, there are two options. One is to use the
constructor to pass in the binary data and MIME type (which defaults to
application/octet-stream if not provided):
resource = Base64Resource(b'sample binary data', mime_type='application/octet-stream')

The other way is to use the Base64Resource.from_uri factory method and pass
in the data URI:
resource = Base64Resource.from_uri('data:application/octet-stream;base64,c2FtcGxlIGJpbmFyeSBkYXRh')

To convert a resource of another type to a Base64Resource, use the
GLTF.convert_to_base64_resource helper method. This method accepts an optional
mime_type parameter if the MIME type of the original resource is known (defaults
to application/octet-stream if not provided):
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')

If the resource to be converted is already a Base64Resource, no action is performed.
If the resource is a FileResource, then it will be converted to a Base64Resource.
The data for the FileResource will be loaded from disk if not already loaded (which
may raise an IOError if the file does not exist).
If the resource is a GLBResource, it will be converted to a Base64Resource. The
GLB buffer will be replaced with a buffer with a data URI (or removed entirely if it
is only used by images). Any images that refer to the resource via a buffer view will
instead refer to the image directly via a data URI, and the corresponding buffer view
will be removed (if it is not also referenced elsewhere). Further, if no other buffer
views refer to the same buffer as the removed buffer view, then the buffer will be
removed entirely as well.
If the resource is an ExternalResource, this method will raise an error (accessing
external resource data is not supported).
GLB Resources
GLB Resources are resources that are embedded directly in a GLB file as binary
chunks. These resources can only be used with a GLB file (if saving to glTF, these
resources must first be converted to a different type).
There is generally one GLB chunk in a file (with the chunk type BIN), though it
is valid to have multiple GLB chunks if they have a different chunk type. This
library supports loading and saving these additional GLB chunks, though no
assumptions are made about their content.
A reference to the GLBResource corresponding to the primary GLB chunk (with the
chunk type BIN) can be obtained by calling get_glb_resource on a model
instance, and its data can be accessed via the data property:
gltf = GLTF.load('glTF-Sample-Models/2.0/BoxTextured/glTF-Binary/BoxTextured.glb')
glb_resource = gltf.get_glb_resource()
print(glb_resource.data)
# b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?\x00\x00\x00\x00\x00\x00\...

Additional GLB chunks can be referenced by calling get_glb_resource with a
resource_type parameter set to the chunk type:
my_custom_glb_resource = gltf.get_glb_resource(resource_type=123)

An individual resource of another type can be converted to a GLBResource using
the embed_resource helper method. This allows embedding a particular resource
while leaving others external when exporting to GLB (in this scenario, ensure
to use export_glb instead of export, and set both embed_buffer_resources
and embed_image_resources to False to prevent the other resources from also
being automatically embedded):
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)

However, the most common scenario is to embed all resources regardless of their
type, which happens automatically when calling export with a .glb extension
(or when calling export_glb with the default set of parameters).
Note that embedding an ExternalResource is not supported because its data is
not accessible (this library does not support loading resources from an external
web URL).
As explained in the other sections, converting a GLBResource to a resource of
another type (i.e., "un-embedding" a resource) will typically not only replace
the URIs on the corresponding buffers and images, but may also result in removing
the GLB buffer and buffer views entirely if they are not also referenced elsewhere.
External Resources
External resources (represented by the ExternalResource class) are resources
that have an external web URL. While this library is able to load models with
external web URLs, the resource itself will not be fetched. A resource of type
ExternalResource will be instantiated with the corresponding URI, but the
library will not perform any web requests to load the resource data. Likewise,
the library supports saving a model containing ExternalResource instances,
but again, no web requests will be performed.
A resource of another type can be converted to an ExternalResource using the
GLTF.convert_to_external_resource helper method, which accepts a URL:
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')

Again, since this library does not handle calling out to external resources,
this is strictly a bookkeeping operation. It is the responsibility of the caller
to ensure that the resource exists externally. Note when converting a resource
to an ExternalResource, the resource data becomes inaccessible.
If the resource is already an ExternalResource and the URI matches, no action
is performed. If the URI is different, then the URI will be updated on the resource
instance as well as on any corresponding buffers or images in the model.
If the resource is a FileResource or Base64Resource, then it will be converted
to an ExternalResource, and all buffers and images will be updated appropriately.
If the resource is a GLBResource, it will be converted to an ExternalResource.
The GLB buffer will be replaced with a buffer with a data URI (or removed entirely
if it is only used by images). Any images that refer to the resource via a buffer
view will instead refer to the image directly via a data URI, and the corresponding
buffer view will be removed (if it is not also referenced elsewhere). Further, if
no other buffer views refer to the same buffer as the removed buffer view, then the
buffer will be removed entirely as well.
Credits
This project is based on the pygltflib library by
dodgyville available here:
https://gitlab.com/dodgyville/pygltflib
Specifically, this project is based on a much earlier version of pygltflib at a
time when it didn't seem to be actively maintained. I used that library as a
starting point and added some features I needed for my own work. Since then, the
original pygltflib project has been revived, but our implementations have
diverged significantly. So now there are two :-)

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter