khronosgroup / gltf-tutorials

glTF Tutorials

• The main glTF Tutorial.
• A tutorial about Physically Based Rendering (PBR) in glTF.
• A tutorial for Adding Material Extensions to glTF Models.
• A template for Building a glTF conversion tool based on Blender.

An online HTML version of these tutorials can be found at https://github.khronos.org/glTF-Tutorials/ .

Feedback

If there are any tutorials that you would like to see here, you can open a new issue to share your ideas, or add your suggestions to the Contributions to the glTF-Tutorials issue.

Contributing

If you want to contribute your own tutorial, you can do this in different ways:

You can open an issue to propose the new tutorial that you want to create. In this issue, you can discuss the intended topic, scope, and structure of the tutorial. This will allow you to gather early feedback, and maybe even find collaborators who would like to support you.

If you have already created a tutorial and want to make it available here, you can just open a pull request. The new tutorial should be in a subdirectory with a short, distinctive name that indicates the overall topic of the tutorial, in CamelCase or lowerCamelCase. Inside this directory, there should be a README.md file that serves as the entry point. Beyond that, you can structure your tutorial as you see fit: If it is a short tutorial, it could be fully contained in the README.md file. If you want to split it up into multiple sections, then you can create one markdown file for each section, and only put a Table Of Contents into the README.md file. You can also create further subdirectories, for example, a dedicated images directory for all the images that you want to inline.

The tutorials will be published here under the CC-BY 4.0 license.

gltf-tutorials's Issues

Structure of generic glTF tutorial

This issue is intended for discussing proposals regarding the structure of the chapters of the generic glTF tutorial in #1

The current structure of the chapters roughly corresponds to the "blocks" or "pages" of the https://github.com/javagl/gltfOverview/ .

But, for example, the section "Textures, Images, Samplers" does not really fit into gltfTutorial_005_MeshesTexturesImagesSamplers.md . Should there be a dedicated section for the (relatively complex and important) topic of meshes in glTF? Should the section about Textures simply be moved into gltfTutorial_006_MaterialsTechniquesProgramsShaders.md , or into a (short), dedicated section as well?

More generally: Should the chapters/sections be broken down, to be more fine-grained, or merged into larger ones? Should they have a more "hierarchical" structure? Should their order be changed?

implementing an algorithm for the simpleSkin model from this github

Hi,

I'm trying to implement an algorithm for the simpleSkin model: https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/SimpleSkin/glTF

so I started with storing the inverseBindMatrices ( 2 matrices ) in a 2 mat4, then calculating the local transform according to the tutorial which says M = T * R * S, so this the initial state. since we don't have an hierarchy of nodes here, the global transform would be the local transform? correct?

since we have animation, I have to change the local transform matrix every time when the rotation changes (since we only have rotation animation, the scale and translation will stay the same)? and then calculate the new local transform and then the global transform as mention in the tutorial? once I have the global transform, I have to calculate the global inverse transform.
after all that I have to send the u_jointMatrix to the vertex shader.

is this correct?
thanks

How can I stack multiple animations correctly, such as hands and feet?

I have several hands animations and several leg animations in glb file.
How do I properly stack several different animations?

SimpleSkin sample model doesn't match tutorial

The SimpleSkin tutorial model doesn't quite match some of the explanations and diagrams in skinning.

Specifically, the sample model places a translation on node index 1, which is actually joint 0, the parent joint. It places a rotation but not a translation on node 2, joint 1, which is the only child joint.

This means the parent joint is moved to Y + 1, and the child joint is co-located with the parent joint. The sample model still works, but only because the parent joint never moves, its only job is to hold its vertices in place.

Also, separate from the above, at some point we made the decision to zero out the first two lines of JOINTS_0 (to silence a validation warning about zero weights on non-zero joints), and some of the wording needs to be updated to reflect what happened there.

Clarify component order for quaternions in scene/node page

APIs/Tools vary in whether they put the w component of a quaternion is first or last. Under the rotation section, explicitly say that the order used by GLTF is x,y,z,w.

Animation in model without skeleton and bones

hi, I'm studying an interesting model and I don't understand how animation works in it, there is no skeleton and bones in it, but it moves. Do you have detailed documentation about this animation method?

-- thanks for help.

-- thanks for help.

Some phones don't draw models if indicesComponentType=5125-GL_UNSIGNED_INT. But they draw fine if indicesComponentType=5123-GL_UNSIGNED_SHORT. I think it may be related to the support on the phone OpenGLES3+. Or are there other reasons?

Some phones don't draw models if indicesComponentType=5125-GL_UNSIGNED_INT. But they draw fine if indicesComponentType=5123-GL_UNSIGNED_SHORT. I think it may be related to the support on the phone OpenGLES3+.
Or are there other reasons?

Accompanying code for the glTF tutorials

The tutorial in #1 is supposed to give and introduction to glTF, and to show the interrelations of the elements of a glTF asset.

When I started this, I thought that it could be nice to write this in the style of a "Tutorial for writing a minimalistic glTF renderer with JavaScript and WebGL". (This was somewhat ambitious, considering that I had never written any real JavaScript before). I tried to create such a renderer, while writing the tutorial, but it turned out to be harder than I anticipated. Nevertheless, in the initial (internal, non-published) drafts, the chapters also contained more actual code snippets, that I took from this renderer. But as a last step before the pull request, I moved most of this into the (currently unpublished) "Summary" section.

I assume that people who read such a tutorial expect some code that is at least close to something that they can copy, paste and use directly. This raises the question of how "Real Code®" could be combined with this tutorial.

Should the Real Code be shown in the "Summary" section? Or should there be dedicated tutorials for the implementations, considering that people migh want to implement renderers in JavaScript/Java/C++ using different libraries (three.js, assimp, ...) ?

I currently have a basic, "minimalistic" renderer in plain JavaScript+WebGL, which is not complete, but it properly renders the "Duck", at least. I think that something like this could be helpful as accompanying code for the tutorial. But due to my lack of JavaScript skills and experience, if this was supposed to be published, it would have to undergo a very critical review by a JavaScript expert. (My gut feeling is that there is waaay to much horrible, horrible JavaScript code out there, and I do not want to throw more on this pile...)

Cesium can not be displayed

Cesium can not be displayed，Can be displayed in threejs

how to use schema.json in gltf2.0

[featureIdTexture.schema.json.](https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_mesh_features)

for example in the document,it use shema.json to generate featureId for each vertex,i want to know waht software can do this ,can you give me more information @javagl

Question about keyframe compression

Is it possible to customize keyframe compression? I'm mostly interested by translations, which seem to be using half-precision floats when compressed. If I'm not mistaken, this would produce jittery animations when uncompressed translations base values are, for example, 1000.0 and change by orders of magnitude less, for example 0.001.

This is especially visible (given that my ozz-animation implementation is correct) in this scene: https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/VC

Most of the animated objects appear jittery, especially the helicopter.

buffers I don't know what it is

Hello!

"buffers" : [
{
"uri" : "data:application/octet-stream;base64,AAABAAIAAAAAAAAAAAAAAAAAAAAAAIA/AAAAAAAAAAAAAAAAAACAPwAAAAA=",
"byteLength" : 44
}
],

What's this uri ？ I don't know how to generate this binary through data.

Cannot replicate Skin glTF-Tutorial data contents

To get a grasp of the gltf format, I'm writing a simple loader that can load animation (vertex skinning) data. I follow the Skin glTF-Tutorial and use the same basic glTF asset and fail to extract some of the data contents from it.

The positions of the vertices and the indices of the triangles are OK.

inverseBindMatrices:

1.0   0.0   0.0   -0.5   
0.0   1.0   0.0   -1.0   
0.0   0.0   1.0    0.0   
0.0   0.0   0.0    1.0  

Instead of the pure -1.0 translation in the y direction. My extraction data matches min/max data from the "accessors":

{
    "bufferView" : 3,
    "byteOffset" : 0,
    "componentType" : 5126,
    "count" : 2,
    "type" : "MAT4",
    "max" : [ 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, -0.5, -1.0, 0.0, 1.0 ],
    "min" : [ 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, -0.5, -1.0, 0.0, 1.0 ]
}

How can I get an additional -0.5 translation in x? This doesn't align with the derivation with the inverse bind matrices.

"JOINTS_0":

0, 1, 0, 0
0, 0, 0, 0
0, 1, 0, 0
0, 0, 0, 0
0, 1, 0, 0
0, 0, 0, 0
0, 1, 0, 0
0, 0, 0, 0
0, 1, 0, 0
0, 0, 0, 0

"WEIGHTS_0" is the same.

The gltf asset loads and displays well in the online viewer.
skin.zip

Thank you!

how to calculate the global inverse transform

Hi,

it looks like I didn't understand how to find the global inverse transform and the global transform.
for this formula: jointMatrix(j) = globalTransformOfNodeThatTheMeshIsAttachedTo^-1 * globalTransformOfJointNode(j) * inverseBindMatrixForJoint(j); the inverseBindMatrix is okay because we can get it from the skin attribute through the accessor and then bufferView etc.. but how to calculate the global inverse transform and the global transform?

Calculating skin joint matrix - use mesh node transform?

The tutorial states[1]

The vertices have to be transformed with inverse of the global transform of the node that the mesh is attached to, because this transform is already done using the model-view-matrix, and thus has to be cancelled out from the skinning computation.

However, the spec states[2][3]:

Client implementations should apply only the transform of the skeleton root node to the skinned mesh while ignoring the transform of the skinned mesh node.

Should the tutorial be changed to reflect the language of the spec?

[1] https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_020_Skins.md
[2] https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#skins
[3] KhronosGroup/glTF#1195

Information about loading strategies for glTF assets

In response to KhronosGroup/glTF#755 (comment) , I created a gist summarizing the thoughts and discussions about (asynchronous) loading strategies for glTF: https://gist.github.com/javagl/bfde5cfab4240843120ed6eb38f4af87

This might become a section in the main tutorial. But since the tutorial until now is rather on a conceptual level, and not so much concerned with the implementation (say, of a viewer/renderer), this might also become a section of a (new?) tutorial that focuses on the implementation.

Hi, what is the right thing to do if JOINT_0 comes in a model in the format short 5123?

Hi, some models come with JOINT_0 in short 5123 format.
Please tell me how to process it correctly?

And another question, how to properly show a model without a skeleton and skin? Should I use a different shader or create a skin programmatically?

Add scene property to inlined glTF examples

The examples (for example, the minimal glTF file at https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_003_MinimalGltfFile.md ) are supposed to be minimal and complete files.

As of KhronosGroup/glTF-Sample-Models#242 , these examples should all have a default scene property. The examples from the tutorial should basically correspondond to the "simple sample models", and it should be possible to copy+paste+view these samples as standalone files.

gltf version

Hello,

Can it be made more clear which version of gltf 1.0 or 2.0 this tutorial targets? If both, does it consistently point out the differences when they arise?

Thank you!

glTF/GLB model size - is there any tool for checking it?

Hi guys, is there any tool, where I can check actual size (dimmensions) of glTF/GLB model?

Imagine that we got some 3D models of TV, we would like to use them for AR presentation, but before we would like to be sure, if dimmension of those models is correct.

Hope, that my question is clear.

Thank you in advance

Jan :)

gltfTutorial_020_Skins.md typo

gltfTutorial_020_Skins in section The skinning joints and weights says

except the first two vertices are influenced only by joint 0, and the last two vertices are influenced only by joint 1

But the bold part doesn't correspond to data shown:

’’’
Vertex 8: 0, 1, 0, 0,
Vertex 9: 0, 1, 0, 0,
’’’

Update links to point to the Khronos glTF registry

Links that pointed to the specification have to be updated, to no longer point to https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-scene but to https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html#reference-scene instead.

Hi, is there an example for OpenGL ES 3 using a normal map in glsl shaders to render gltf models? Could you point out a good link to explore?

Hi, is there an example for OpenGL ES 3 using a normal map in glsl shaders to render gltf models?
Could you point out a good link to explore?

can Mesh be used in several different Skins? should I provide for this when loading glb?

can Mesh be used in several different Skins? should I provide for this when loading glb?

Publish this repo as a website

GitHub has some new options: https://github.com/blog/2289-publishing-with-github-pages-now-as-easy-as-1-2-3

Looks like there are some custom theme options as well.

CC @Khronoswebmaster

Code

Is code available for these? I can't figure out the joint matrix calculation and would benefit from the code.

如何更改gltf模型中心点位置

如何更改gltf模型中心点位置？
实现效果：旋转模型时，围绕不同的中心点旋转

Contributions to the glTF-Tutorials repository

The main glTF tutorial explains the concepts of glTF, explaining the format itself, its features and its application cases. This tutorial does not cover implementation details. While it may be a good starting point as a general introduction, more focused tutorials may be added here.

Some examples:

• Explaining the best practices for using .gltf or .glb format. This is already discussed in KhronosGroup/glTF#1117 , and the results may be added here
• Tutorials on the implementation of PBR. This has already been started at https://github.com/moneimne/glTF-Tutorials/tree/master/PBR
• Examples showing how to use glTF in plain WebGL or any other graphics API (OpenGL, Direct3D, Vulkan...). This might eventually even be a tutorial on implementing a full glTF renderer
• Examples and usage patterns for glTF in rendering libraries like three.js, Babylon.js and others
• Translations of existing tutorials to other languages (?)
• ...

If you want to contribute a tutorial, feel free to open an issue so that its scope, goals and structure can be discussed, or open a pull request with your contributions.

List of open issues for the generic glTF tutorial

The generic glTF tutorial in #1 still has some open issues that I will list here, straight from my "TODO" list. (If appropriate, some of them might be pulled out into dedicated issues).

• Add the legalese statements for using the Khronos logos....
• Consider adding an overview for recommended OpenGL/WebGL tutorials in JavaScript/C++/Java...
• In gltfTutorial_002_BasicGltfStructure.md, mention embedded and binary glTF
• Make the formatting (backticking) consistent. Should it be "The mesh contains a mesh primitive", or "The mesh contains a meshPrimitive"? Which is considered more readable?
• Make the naming pattern for example JSON consistent. Right now, user-defined names are named like "exampleMesh". Should this be "mesh0", as this is usually written by the export tools?
• The section "Image data in images" in gltfTutorial_002_BasicGltfStructure.md mentioned the image formats, internalFormat etc. This should be explained in gltfTutorial_005_MeshesTexturesImagesSamplers.md! See also glTF issue 728
• In gltfTutorial_004_ScenesNodesCamerasAnimations.md, at "Animation samplers", mention that the interpolation there is LINEAR, and mention the other interpolation types. Particularly, mention SLERP with implementation notes for JavaScript/Java/C++...
• In gltfTutorial_006_MaterialsTechniquesProgramsShaders.md, mention the node property, and the "context awareness" of the semantics when no node is given (see https://github.com/KhronosGroup/glTF/tree/master/specification#semantics )
• In gltfTutorial_006_MaterialsTechniquesProgramsShaders.md, mention technique.states
• Consider some shameless self-promotion of https://javagl.github.io/GLConstantsTranslator/GLConstantsTranslator.html
• Consider adding more images:
  • For the "Local and global transforms" in gltfTutorial_004_ScenesNodesCamerasAnimations.md
  • For the buffer->bufferView->accessor structure in gltfTutorial_007_BuffersBufferViewsAccessors.md
  • ...
• Some images have to be improved: gltfStructure.pngshould say ".vert/.frag files" instead of ".glsl files". The technique.png looks a bit confusing.

For some points, it is not clear whether they should be described generically, in the tutorial, or whether they should be part of a dedicated section showing the "Implementation of a renderer" - for example:

• In gltfTutorial_006_MaterialsTechniquesProgramsShaders.md, there should be a link to the implementation section, showing how the "Techniqe parameter values" are eventually passed to OpenGL.
• In gltfTutorial_006_MaterialsTechniquesProgramsShaders.md, the "Implementation notes" for the program compilation are somewhat extensive, and would fit better into the implementation section
• In gltfTutorial_004_ScenesNodesCamerasAnimations.md, consider adding a summary "Playing the animations". However, such a section could better fit into the implementation section, which shows how the pieces of information are finally assembled into a renderer

does gltf support metadata， KV string map for example

I want store some metadata on a gltf, anyway i can store these data in it ?

Please rename default branch from 'master' to 'main' per Khronos policy

To repository owners: please rename the default branch of this repository from 'master' to 'main', using the Github renaming tool. This request is per policy set by the Khronos Promoters in May 2021, to follow Github community practice for respectful naming.

The Github renaming tool sets up URL redirections and retargets outstanding pull requests, so the impact on repository users is minimal. The most visible issue is that people with local repo clones will probably want to rename their clone's 'master' branch, following the popup instructions that will be seen when browsing the github repository after the change; or just delete 'master' and pull the new 'main', if it's purely a tracker with no local content.

You may wish to coordinate with @outofcontrol if you are doing auto-updates from this repository to another location, whether via push/pull mirroring or other mechanisms. The redirects setup by Github should accommodate most such uses transparently, but it's still good practice.

Based on experience with other KhronosGroup repositories which have undergone this renaming already, this is a reasonable approach:

• Agree on a date for the renaming within the Working Group or other owners of the repository, and document that date here.
  • Date can be adjusted to avoid interaction with major releases in flight.
• Provide notice to repository users outside Khronos, insofar as possible (adding a comment in the repo README with the switchover date is one way).
• Once the renaming is done, edit the new 'main' branch to replace hardwired references to 'master' with (preferably) 'default branch' or 'main'.
• Update the repo README to note the change.

If you have questions or issues about this, please raise them on Khronos internal gitlab 'khronos-general' issue 106 if possible. If not possible, you can @-tag me here.

While we will not force any WG into acting precipitously, this is our agreed policy. Please try to accommodate renaming relatively soon.

Note that this issue is automatically generated, due to the large number of KhronosGroup repositories it's being raised in.

Minor readability issue - image 18b

I was a little confused understanding the logic of animated morph targets..

https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_018_MorphTargets.md

The blend weight table logically reads left to right for the two morph targets.

Where image 18b shows the working calculation of the blended vertex (at t=1.25) it lists the second morph targets calculation (green) above the first morph target calculation (red)

It does so without showing any working for the effective blend weights themselves at t=1.25, which can be confusing for the reader if they expect to see the calculation written in morph target order.

I have a simple question

I know that the buffers are base64 that converted from some string.
But what the string is?the points?the matrixs?
Can you give me a detailed information?
thanks in advance.

Update and simplify the skinning section

The computation of the joint matrices at https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_020_Skins.md#the-joint-matrices is basically based on an older state of the specifiction, where some aspects of the skinning had not yet been clear (in general, and for me in particular).

Based on a discussion in KhronosGroup/glTF-Sample-Models#312 and what I have read in the issues that are linked from that, the globalTransformOfNodeThatTheMeshIsAttachedTo^-1 can be omitted. (Note that the current description is not wrong, it is just more complicated than it needs to be).

Some further verification will happen before that, and the https://github.com/javagl/gltfOverview will also have to be updated accordingly.

Comma mistakes in "A Simple Texture" tutorial

The glTF file published in "A Simple Texture" tutorial does not work because a comma is missing before the "images" list.

Moreover there is a comma after the "asset" dictionary that causes a parse error.

Where should joint matrices be stored?

in which class is it correct to store jointMatrices collections?
If I understood correctly, Skin is not suitable because each meshNode can have its own global transformations. Then should jointMatrices be stored for each Mesh or its Node to be passed to the shader?

is it possible to somehow determine in which units of measurement the model is located? Millimeters, centimeters, meters or inches?

is it possible to somehow determine in which units of measurement the model is located? Millimeters, centimeters, meters or inches?

Directory structure and naming scheme

A first part of a (generic) glTF tutorial is contained in #1 . One could consider adding a shortened version (as a "five minute tutorial", which could be nice), and others focussing on certain aspects or the implementation in different languages and environments.

So considering that several glTF tutorials should be collected here, what is the proposed directory structure and naming pattern for these tutorials?

Related: Should the generic tutorial stay in Markdown format, or should it be published as an HTML page? The latter could offer some better formatting and browsing capabilities (I'm thinking of something similar to https://open.gl/ here)

EDIT: Is there a proposed pattern for naming the files ("chapters") of the tutorial (regardless of whether it's Markdown or HTML) ? Currently, the chapters have "elaborate" names like gltfTutorial_004_ScenesNodesCamerasAnimations.md, which conveys information about the order and the contents, which can be handy, but makes a restructuring of the chapters really difficult (e.g. when a new chapter is added in-between...)

How should CUBICSPLINE Animation be exported?

There's very little in the documentation to show the right way to export intangents, outtangents and weights for CUBICSPLINE interpolation. I think this should be made much clearer