khronosgroup/gltf-blender-io

Blender glTF 2.0 importer and exporter

Blender glTF 2.0 Importer and Exporter

Documentation

Blender Version	Documentation
4.1	https://docs.blender.org/manual/en/4.1/addons/import_export/scene_gltf2.html
4.2 beta	https://docs.blender.org/manual/en/4.2/addons/import_export/scene_gltf2.html
dev	https://docs.blender.org/manual/en/dev/addons/import_export/scene_gltf2.html

Notes:

• 4.1 is the current stable release. Check the blender-v4.1-release branch (and 4.1.x tag)
• 4.2 will be the next stable release. Check the blender-v4.2-release branch.
• 2.80 - 4.0 are previous stable releases.
• 3.6.x is the current Blender LTS release. Check the blender-v3.6-release branch (and 3.6.x tag)
• main branch of this addon is mirrored in Blender Addons main, that will become Blender 4.3.

Legacy 2.79 Support

The final version of this addon with legacy support for Blender 2.79 is available on the 2.79 Release Page.

Blender 2.80 and higher bundle this addon in the main Blender install package, so no 3rd-party install is required.

Credits

Developed by UX3D, Scurest and Julien Duroure, with support from the Khronos Group, Mozilla, and Airbus Defense & Space.

Introduction

Official Khronos Group Blender glTF 2.0 importer and exporter.

This project contains all features from the previous exporter, and all future development will happen on this repository. In addition, this repository contains a Blender importer, with common Python code shared between exporter and importer for round-trip workflows. New features are included or under development, but usage and menu functionality remain the same.

The shared codebase is organized into common (Blender-independent) and Blender-specific packages:

Package organisation

This structure allows common code to be reused by third-party Python packages working with the glTF 2.0 format.

Import & export process

The main importer and exporter interface is the Python glTF scene representation. Blender scene data is first extracted and converted into this scene description. This glTF scene description is exported to the final JSON glTF file. Any compression of mesh, animation, or texture data happens here. For import, glTF data is parsed and written into the Python glTF scene description. Any decompression is executed in this step. Using the imported glTF scene tree, the Blender internal scene representation is generated from this information.

Installation

The Khronos glTF 2.0 importer and exporter is enabled by default in Blender 2.8 and higher. To reinstall it — for example, when testing recent or upcoming changes — copy the addons/io_scene_gltf2 folder into the scripts/addons_core/ directory of the Blender installation, then enable it under the Add-ons tab. For additional development documentation, see Debugging.

Debugging

• Debug with PyCharm NOTE: If you are using Blender 2.80+, you need the updated debugger script
• Debug with VSCode

Continuous Integration Tests

Several companies, individuals, and glTF community members contribute to Blender glTF I/O. Functionality is added and bugs are fixed regularly. Because hobbyists and professionals using Blender glTF I/O rely on its stability for their daily work, continuous integration tests are enabled. After each commit or pull request, the following tests are run:

• Export Blender scene and validate using the glTF validator
• Round trip import-export and comparison of glTF validator results

These quality-assurance checks improve the reliability of Blender glTF I/O.

Running the Tests Locally

To run the tests locally, your system should have a blender executable in the path that launches the desired version of Blender.

The latest version of Yarn should also be installed.

Then, in the tests folder of this repository, run yarn install, followed by yarn run test.

Main branch

The main branch was renamed on 2023 January, 12th. If you need to update your local repository, you can use the following documentation

Some Technical documentation

Want to fix some bugs or add some enhancement? You will find some technical overview of this addon here

gltf-blender-io's Issues

Blender 2.8 conversion and integration

• Separate 2.79 and 2.80 code
• Implement 2.80 code
• Integrate into 2.80 repository

Importer: Replace dictionaries with arrays and only use the json containers

At the moment, we do have the data duplicated.

From our point of view, the additional dictionaries are not required. Instead - if really the indices are required - we should add accessors, which do calculate these.

Importer: Import meshes to appear smooth depending on normal

This is the future! Thank you for the awesome work you are doing!

This is the future!

It's not spam I just wanted to tell you, all contributors thank you for building this addon. It feels great to use Blender with a single addon to manage import and export from it to GLTF/GLB.

Thank you again for the awesome work you are doing!

I hope to see all planned features implemented to get ready for more great content exported from blender 2.8 to GLTF!

Riccardo.

Morph target Normals export issue

Hi,
I've noticed a weird behavior when playing with Shape Keys.

When I create a shape, edit it, add a key shape (or several), edit it, then export the gltf file, the base gltf mesh normals data will be those of the last edited shape.
Morph shape normals will be relative to this one.

However, if I select the original shape "Basis", go in edit mode, and recompute normals, then exporting the gltf will generate the expected behavior with correct normals on both the base mesh and morph shapes.

Here is a simple example, a 3*3 grid. Basic shape is flat, first key shape corners are pull up/down

Rendering the normal buffer in my engine : (Left : export before recomputing normal on basis shape, Right, after recomputing)

Morph coefficient at 0%

Morph coefficient at 100%

M.

Check with blender for unit of light intensity

verify blender cycles is actually using lumen instead of watts (as specified in documentation)

Request for bone length to be exported

Bones have a concept of length in Blender, which currently is not exported. This is useful, particularly when trying to load another object in-game at a location relative to the end of a bone. You can parent an object to a bone in Blender, and it is rendered in Blender relative to the end of the bone. But there is no way to get it in the correct place after it has been exported without the offset along the length of the bone.

To get the data I needed in-engine I simply added the following to gltf2_generate.py at line 1913 in generate_nodes()

node['length'] = blender_bone.length

Exporter: Avoid to export invalid JSON format

AFAIK the * .gltf file should be in JSON format:
https://github.com/KhronosGroup/glTF/tree/master/specification/2.0
»The format combines an easily parseable JSON scene description with one or more binary files representing geometry, animations, and other rich data. Binary data is stored in such a way that it can be loaded directly into GPU buffers without additional parsing or other manipulation.«

The JSON specification doesn't allow NaN as a value or number: https://json.org/

Exporting values as NaN breaks reading the glft file with the standard JSON parsers.
I couldn't trigger such a case with the blender-exporter[2] myself, but others claim that it happens
godotengine/godot#21668
and try to push workarounds for the JSON parsers in the importer software.

In the attachment, only the first test-cube is validated by the JSON parser as correct.
In the blender-importer [1], the second one stops with python TypeError: list indexes must be integers or slices, not float, the third one loads without an error, which is in my opinion a mistake.

test-NaN.zip

I have created an issue only here, but it affects both
[1] https://github.com/julienduroure/gltf2-blender-importer
[2] https://github.com/KhronosGroup/glTF-Blender-Exporter

Empty nodes exported when camera or lights are disabled

With the camera or lights disabled, the exporter still writes empty nodes in their place:

SmoothMorph.zip

Preferably these nodes would be ignored, if they have no children, so that it's possible to export simple models containing only a single node.

Export world settings

Hi and first of all: thanks for your great work on the GLTF standard and on this addon in particular. You're doing a fantastic job :).

Now my question / feature request: It would be great if you could somehow export the world settings / node tree of a scene and especially support HDR lighting. By chance, do you know Verge3D? I am think they are using big parts of your code in their product, but are having some pretty good enhancements, like exporting the mentioned world settings.

Cheers
-Sebastian

Increased vertex counts when mesh has UVs

Okay so I have:

vertices.

After export:

28k

Can't export custom normals (use_auto_smooth)

I'm using two addons to manually change the normals for my model. When I export, it doesn't get saved out. Is the exported checking if auto smooth is turned on and that the custom data is there being used?

Data should be stored in "Custom Split Normals Data" datablock.

I can upload a sample file if you need it.

Exporter: Exporting results in .test.png files

Hey again!

Image Texture nodes with JPG images as sources for the Principled BSDF node in Blender for some reason result in the export also having foo.jpg.test.png files in the output directory.

Multiple UV Layouts

Hi there,

I'd like to have multpile UV-Layouts on my models (one for tiling and one for baking stuff) and I'm fine with not having factors for the mapping as a node in blender but still I need to pick which uv-layout applies for what texture-map.

Here are my nodes:

However, if I use any online-viewer or even the gltf-importer from three-js, only the baking-UV-Layout is used for everything.

If I edit the gltf-file created I can see both layouts and switch them, if I edit TEXCOORD manually but I think it is not intended to work that way. The ao-map gets ignored anyways, but this may be a viewer-issue.

My question is, what is the proper way to deal with multiple UV-Layouts in the blender-exporter?

Here is my .blend-file if someone cares.
Monkey.blend.zip

Thanks!
Goetz

Broken morph target animation

From @mrdoob in #52 —

---

Seems like the materials no longer export with the latest version of the exporter 😕

alligator.blend.zip

alligator_old.gltf.zip

alligator_new.gltf.zip

Incorrect armature scale and hierarchy

I have this armature in blender. I've scaled it down as it was too big and reset the transforms.

When I export as a DAE file this is the result:

which is correct. Notice the red line on the left indicates a non-scaled box for size, and the box to the right is the same box just attached to the skeleton.
Also notice on the far right, the hierarchy from the DAE file matches blender.

Now this is the exported GLB. Notice the red line on the left indicates the non-scaled box which is correct. The box to the right is the same box attached to the skeleton - see it is way bigger. This is the size I would expect from the character before I scaled and applied the transform.
Also notice the far right, the hierarchy from the GLB is really weird broken up into multiple skeletons.

Here is my blender file with exported DAE and GLB files for debugging
Stip.zip

Importer: Use filename of imported image for name of Image Texture

Having the filename in the properties field later allows a smoother round trip.

Importer: Disable all non-glTF parameters in Principled BSDF node

Set clear coat and other parameters that they do not have any effect.

Exporter freezes when exporting with animation

I have a model I downloaded and re-rigged myself and have been testing with Babylon.js. It is a mostly vertex-painted model with the solidify modifier to add the cartoon outline effect.

It exports and loads fine, armature and all, in Babylon.js. without animations.

So I added a simple Head Turn animation for starters. Nothing too fancy.

I tried the latest version of Kupoman's gltf exporter as of today and it exports without error but the animations are incorrect - the head distorts instead of turns, and the character doesn't turn her head a full 90 degrees each direction.

In the older version of this exporter (latest from October 2 2017), it exports without error and seems to animate properly, but many other bones seem to be displaced and there are black artifacts everywhere.

In the latest version of this exporter, however, it exports fine without animations but the moment I check [export skinning] it will never finish exporting. Blender stops responding and I'm forced to close it.

Oddly enough, the older version of the exporter manages a smaller gltf (5MB) than the newest one (10MB). Is this supposed to happen?

Here is the file for reference:

GwenSimp - w_head_turn.zip

Exporter should reuse animation sampler's input when they are the same

Consider (again) this model
simple.zip
And the resulted exported file
SimpleAnimPose.zip
It's been exported checking the "force sample animation" option.
In the animations/samplers section you can see that each input points to a different accessor. If you look at those accessors, they look similar, but each one points toward a different bufferView. Those buffer views, in turn, points to the same buffer, but with a different byteOffset each time, meaning that the data is duplicated in the bin file too.
If I check the data when loading the files it is strictly identical from one input to another.

This is perfectly valid in a spec point of view, so that's not really a bug, but maybe an enhancement. It would greatly reduce the files size if this data was reused.

Importer: Mesh instance management

Currently, meshes are duplicated

Exporting Action changes bind pose of armature to first frame

Trying to export a character with a walking cycle. Problem is that when I export with an action that is active, the mesh's armature resting post changes to the first frame of the animation. This is not the desired result. I need the armature to stay at its default rotation/positions so that I can then setup my own bind pose data for my skeleton animator. If I disable the action, then the armature exports correctly but then the action animation doesn't get exported. This makes it very difficult to use the format to make a game.

Here's my test file.
bendy_v1_0_1b.zip

New folder structure

I think the folder structure proposed in README.md looks fairly close to right. How about renaming "generic" to "io"? I think that would more clearly communicate that it is the serialization/deserialization code, and can be used independently. Then:

• io_scene_gltf2
  • blender
    • common
    • export
    • import
  • io
    • ...

I leave the subfolders under io/ blank because I think feature-related classes/files (similar to https://github.com/julienduroure/gltf2-blender-importer/tree/master/io_scene_gltf2_importer) may be wanted, but I don't have my mind made up on this.

Importer: fps

Currently, no checks are done on fps, that can lead to incorrect animations.
2 possibilities:

• Add a warning when calculated fps in animation doesn't match to scene fps
• Automatically change scene fps, based on gltf file fps

I think we don't have to change fps automatically. My choice goes to warning user only

Importer: Packing of images should be optional

Optimizing and bug fixing (cont.)

• Adapt same code style

Align copyright in source code

see https://github.com/KhronosGroup/glTF-Blender-IO/blob/master/LICENSE.txt

Merge glTF 2.0 importer and exporter

• Code base merged
• Separte exporter code
• Separte importer code
• Create / use common classes and functions

Rotation animation not playing as expected

I am trying to animate a spinning windmill. 2 key frames: one at Euler X 0° and one at Euler X 360°. It does a full rotation in blender as expected, but upon export the animation doesn't move because 0° apparently equals 360°. If I use a value of 359°, the animation moves by -1° instead of +359°. I didn't have this issue with an older version of the exporter, before multiple animations were implemented.

Include exporter version in 'generator' string.

Will likely be helpful down the road if assets include the version of the exporter used. I.e. replace Khronos Blender glTF 2.0 exporter with Khronos Blender glTF 2.0 exporter (<version>), where <version> is either a commit hash or semver version.

Animation export/import ?

Do you plan on adding animation (skeletal, non-skeletal) export/import to your add-on?

If so, could you please make it in non-convoluted way (without a need in using NLA Editor) with support of multiple Actions ?

Thanks beforehand

Exporter: KHR extensions, add hooks for Vendor extensions

• KHR_lights_punctual
• KHR_materials_unlit
• KHR_texture_transform
• Refactor to have hooks/callbacks

Remove option for Z=Up export?

A recent PR (KhronosGroup/glTF-Blender-Exporter#130) contributed this, I just wanted to check that this should be supported? In other words, should we have options that are technically invalid according to the spec, and/or should it be named something other than Convert Z up to Y up?

Exporter: Component type exported as a float

Hey,

Noticed the .gltf generated by today's master results in componentTypes with a .0 at the end. While practically an integer, smells of a possible future bug. ;)

Correct creating morph animation

Hello have any guides for creating morph animation in blender because, when i create animation not work.

I get this errors
ANIMATION_SAMPLER_INPUT_ACCESSOR_TOO_FEW_ELEMENTS | Animation sampler output accessor with 'CUBICSPLINE' interpolation must have at least 2 elements. Got 1.

when enable animation checkbox in gltf viewer i not show animated objects.

attach example model

j70_2_0.zip

Importer: Add helper node for camera and lights

Because of different coordinate system, a helper node is required.

Recommend, that there is an import option, where one can optionally resolve the orientation of the coordinate system.
Keep in mind, that this should be optional, as any possible animation on this node causes a domino effect of data conversions.

Separate Blender dependent from Blender independent Python code

For the exporter, in a first step, split up files and move Blender independent code in the io folder structure.
Please keep functionality and do only minor refactoring.

Exporter: Animation missing.

Basic example attached; animations are not included on export:

CubeAction.zip

Model exported with 5 identical skins.

This one is more tricky and I couldn't dig out a proper lead...
Consider this model
Jaime.zip
It has a fairly complex rig. When I export it I get this files. (note that it's exported with default settings except that selected only is checked, with the mesh selected, export skinning, force sample application is checked, Bake skinning application is checked).
gltf.zip
There are 5 identical skins exported. (there should be one.) And only the last one is actually references by the mesh node.
I can't figure out where it comes from.

Importer: checks

Some checks must be added:

• check Asset gltf version
• check glb total size, and each glb chunk

Optimizing and bug fixing

• Finalize sharing of common code base
• Optimize image merge name creation

"Correction_*" should be name of inserted parent, not the functional node.

When exporting cameras or lights, we have to inject a Correction_ node as discussed elsewhere (KhronosGroup/glTF-Blender-Exporter#265, KhronosGroup/glTF-Blender-Exporter#113). However, I think we could make this less confusing for users by putting the prefix on the wrapper, not on the node that references the camera or light. Current behavior:

Since the user knows they've created a light named "Spot", it would be nice if searching for the node named "Spot" in the loaded model would give them a light. This makes the wrapper less awkward, I think.

GLTF is generated with zero weight vertices

Taking the discussion back from here. I'm generating this gtlf with blender+exporter and some of the branches of the generated tree cannot be displayed in babylon.js.

They pointed out that some of the vertices are being exported with wights all in 0 that is not compliant with GLTF standard.

Is this correct? Should I do something in modelling time to avoid this issue?

thanks!

ACCESSOR_NON_UNIT error in validator

I'm exporting a blender scene using the latest add on in master and then opening it in https://gltf-viewer.donmccurdy.com/ and I get the error

Cannot read property 'joints' of undefined

The model has an armature and some animations. I'm attaching the gltf and the blender file. Thanks!

broken_model.zip

Driven shape keys don't export

I have a figure that was exported from Makehuman. It has drivers which allow a facial expression to be set as a single operation. When you do this, all the corresponding facial bones and shape keys are supposed to take up the correct positions.

It's possible to animate the expressions, but the results don't export properly. The 'Bake skinning constraints' option seems to cover driven bones as well as bones with constraints (these are of course slightly different things in Blender). Unfortunately it doesn't seem to work with shape keys. If they have a driver attached, they export as zero for the whole animation range.

I'll attach a file with a simplified test case. When you run the animation in Blender, you should see the object bend (driven skeletal animation) and open it's 'mouth' (driven shape key). If you export it with the default options, you will see neither, which is presumably the correct behaviour. If you export it with 'Bake skinning constraints' the object will bend but the shape key will do nothing.

test2.blend.gz

Importer: Parent armature with blender style

Parent mesh to armature --> This is way it's done in Blender, using armature modifier
We need to parent correctly, keeping offset

Exporter: Use Principled BSDF / Deprecate custom glTF node groups

Principled BSDF export

• Scalars and vectors
• Extract channels and merge image functionality
• Images, textures and samplers
  • Normal
  • Emissive
  • Base Color
  • Metallic
  • Roughness

Importer: Material / vertex color duplication

A same material can have difference vertex color multiplicator (stored at primitive level).
Currently, only 1 material is created, and used for all objects/meshes.
--> Need to check vertex in order to know if a new material must be created

Empty Samplers node

The Blender glTF exporter writes a file with the samplers node empty. This causes any text on a texture to render highly aliased in some viewers, particularly the Microsoft Mixed Reality desktop viewer.

Other exporerts, such as Substance Painter, export a glTF file with correct data to render text smooth:
"magFilter": 9729,
"minFilter": 9985,
"wrapS": 10497,
"wrapT": 10497

When the above lines are manually edited into the glTF file, the text renders with a smooth linear filter.
Can we have the option to include this samplers info in the Blender glTF exporter?

glb-files.zip

Exporting only selected objects doesn't quite work for lights

I've opened the 04_lights.blend scene from glTF-Blender-Exporter repo. I've selected only one light in the scene and then tried to export it. In the exporter options I have both "Export selected only" and "Export KHR_lights" checked.

The output gltf file doesn't have all the information about the light I selected:

04_lights.txt

When I unckeck "Export selected only" it seems to work fine. But of course it exports all lights.

PS: Posting the same issue here as well because I'm not sure what's the difference between this repo and glTF-Blender-Exporter. Previously created issue here: KhronosGroup/glTF-Blender-Exporter#304