Library for parsing, creating, and converting glTF 2.0 files in Python 3.6+.
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.
This library can be installed using pip:
pip install gltflib
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
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\...'
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)
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).
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 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).
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 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 (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, 'https://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.
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 :-)