Skip to main content

GLTFLoader

Parses a glTF file. Can load both the .glb (binary) and .gltf (application/json) file format variants.

A glTF file contains a hierarchical scenegraph description that can be used to instantiate corresponding hierarcy of actual Scenegraph related classes in most WebGL libraries.

LoaderCharacteristic
File Extensions.glb, .gltf
File TypeBinary, JSON, Linked Assets
File FormatglTF v2, GLTF v1 *
Data FormatScenegraph
Supported APIsload, parse
SubloadersDracoLoader, ImageLoader

* From Website shields.io, the GLTFLoader offers optional, best-effort support for converting older glTF v1 files to glTF v2 format (options.gltf.normalize: true). This conversion has a number of limitations and the parsed data structure may be only partially converted to glTF v2, causing issues to show up later e.g. when attempting to render the scenegraphs.

Usage

import {load} from '@loaders.gl/core';
import {GLTFLoader} from '@loaders.gl/gltf';
const gltf = await load(url, GLTFLoader);

To decompress Draco-compressed meshes:

import {load} from '@loaders.gl/core';
import {GLTFLoader} from '@loaders.gl/gltf';
import {DracoLoader} from '@loaders.gl/draco';
const gltf = load(url, GLTFLoader, {DracoLoader, decompress: true});

Overview

The GLTFLoader aims to take care of as much processing as possible, while remaining framework-independent.

The GLTF Loader returns an object with a json field containing the glTF Scenegraph. In its basic mode, the GLTFLoader does not modify the loaded JSON in any way. Instead, the results of additional processing are placed in parallel top-level fields such as buffers and images. This ensures that applications that want to work with the standard glTF data structure can do so.

Optionally, the loaded gltf can be "post processed", which lightly annotates and transforms the loaded JSON structure to make it easier to use. Refer to postProcessGLTF for details.

In addition, certain glTF extensions, in particular Draco mesh encoding, can be fully or partially processed during loading. When possible (and extension processing is enabled), such extensions will be resolved/decompressed and replaced with standards conformant representations. See glTF Extensions for more information.

Note: while supported, synchronous parsing of glTF (e.g. using parseSync()) has significant limitations. When parsed asynchronously (using await parse() or await load()), the following additional capabilities are enabled:

  • linked binary resource URI:s will be loaded and resolved (assuming a valid base url is available).
  • base64 encoded binary URI:s inside the JSON payload will be decoded.
  • linked image URI:s can be loaded and decoded.
  • Draco meshes can be decoded asynchronously on worker threads (in parallel!).

Options

OptionTypeDefaultDescription
gltf.loadBuffersBooleanfalseFetch any referenced binary buffer files (and decode base64 encoded URIS).
gltf.loadImagesBooleanfalseLoad any referenced image files (and decode base64 encoded URIS).
gltf.decompressMeshesBooleantrueDecompress Draco compressed meshes (if DracoLoader available).
gltf.postProcessBooleantruePerform additional post processing on the loaded glTF data.
gltf.normalizeBooleanfalseOptional, best-effort attempt at converting glTF v1 files to glTF2 format.

Remarks:

  • The gltf.postProcess option activates additional post processing that transforms parts of JSON structure in the loaded glTF data, to make glTF data easier use in applications and WebGL libraries (e.g replacing indices with links to the indexed objects). However, the data structure returned by the GLTFLoader will no longer be fully glTF compatible.

Data Format

With Post Processing

When the GLTFLoader is called with gltf.postProcess option set to true (the default),the parsed JSON chunk will be returned, and post processing will have been performed, which will link data from binary buffers into the parsed JSON structure using non-standard fields, and also modify the data in other ways to make it easier to use.

At the top level, this will look like a standard glTF JSON structure:

{
scenes: [...],
scene: ...,
nodes: [...],
...
}

However, the objects inside these arrays will have been pre-processed to simplify usage. For details on changes and extra fields added to the various glTF objects, see post processing.

Without Post Processing

By setting gltf.postProcess to false, an unprocessed glTF/GLB data structure will be returned, with binary buffers provided as an ArrayBuffer array.

{
// The base URI used to load this glTF, if any. For resolving relative uris to linked resources.
baseUri: String,

// JSON Chunk
json: Object, // Containse the parsed glTF JSON or the parsed GLB JSON chunk

// Length and indices of this array will match `json.buffers`
// The GLB bin chunk, if present, will be found in buffer 0.
// Additional glTF json `buffers` are fetched and base64 decoded from the JSON uri:s.
buffers: [{
arrayBuffer: ArrayBuffer,
byteOffset: Number,
byteLength: Number
}],

// Images can optionally be loaded and decoded, they will be stored here
// Length and indices of this array will match `json.buffers`
images: Image[],

// GLBLoader output, if this was a GLB encoded glTF
_glb?: Object
}
FieldTypeDefaultDescription
baseUriString``length of GLB (e.g. embedded in larger binary block)
jsonObject{}Parsed JSON from the JSON chunk
buffersObject[][]The version number
buffers[\*].arrayBufferArrayBuffernullThe binary chunk
buffers[\*].byteOffsetNumbernulloffset of buffer (embedded in larger binary block)
buffers[\*].byteLengthArrayBuffernulllength of buffer (embedded in larger binary block)
_glb?ObjectN/AThe output of the GLBLoader if the parsed file was GLB formatted