glTF Transform

In a standard glTF file, properties like meshes, materials, and nodes are stored in top-level JSON arrays and linked via integer indices. This is efficient for loading but difficult to edit manually.

glTF Transform preserves the conceptual model of these root-level arrays but replaces index-based pointers with a managed graph of references. Instead of working with indices, you interact with objects directly. The library manages the internal graph structure, ensuring that when you pass an object to a property, the relationship is automatically tracked.

Key behaviors:

• Fluidity: Positions in root-level arrays are not fixed until the file is exported. You can add, move, or remove objects without manually recalculating indices.
• Automatic Tracking: Objects can identify their users. For example, a Mesh can list all Node instances that reference it using .listParents().
• Lifecycle Management: To remove all uses of a Property, use .detach() or .dispose(). Note that detached but non-disposed properties may still be exported, though they will lack references from a Scene.

// Find an existing Mesh named 'Cog'.
const mesh = doc.getRoot()
  .listMeshes()
  .find((mesh) => mesh.getName() === 'Cog');

// Instantiate a copy of the 'Cog' mesh at a new node, 'CogInstance1'.
const cogNode = doc.createNode('CogInstance1')
  .setMesh(mesh);

// Add the Node to a Scene.
doc.listScenes()[0]
  .addChild(cogNode);

// List all references to the 'Cog' mesh.
mesh.listParents(); // → [cogNode, ...]

Transforms are operations that apply a modification to a Document. They are executed using the Document.transform() method, which accepts one or more transform functions as arguments. This allows you to chain multiple modifications (like welding, quantizing, or deduplicating) in a single call. You can also implement custom transforms by creating a function that accepts a Document and modifies it.

import { NodeIO } from '@gltf-transform/core';
import { KHRONOS_EXTENSIONS } from '@gltf-transform/extensions';
import { weld, quantize, dedup } from '@gltf-transform/functions';

const io = new NodeIO().registerExtensions(KHRONOS_EXTENSIONS);
const document = await io.read('input.glb');

// Apply multiple transforms at once
await document.transform(
	weld(),
	quantize(),
	dedup(),

	// Custom transform.
	backfaceCulling({cull: true}),
);

// Custom transform implementation example: enable/disable backface culling.
function backfaceCulling(options) {
  return (document) => {
    for (const material of document.getRoot().listMaterials()) {
      material.setDoubleSided(!options.cull);
    }
  };
}

await io.write('output.glb', document);

@gltf-transform/view creates three.js objects from a glTF Transform Document and maintains a real-time link between them. As you modify the Document via the glTF Transform API, the three.js scene graph updates automatically.

This provides a lossless workflow for editor-like web applications. Unlike THREE.GLTFExporter, features not supported by three.js are preserved in the underlying Document even if they are not rendered in the preview.

Key Workflow

1. Load: Use WebIO to read a glTF file into a Document.
2. Initialize View: Create a DocumentView from the Document.
3. Bind to Scene: Use documentView.view(sceneDef) to convert a glTF Transform Scene (or other elements) into three.js objects (like THREE.Group) and add them to your three.js scene.
4. Edit: Modify the Document properties; the three.js scene will update automatically.

Memory Management

DocumentView tracks reference counts and disposes of WebGL resources (textures, geometry, materials) when the underlying glTF Transform properties are disposed.

To manually free up GPU memory by disposing of unused resources, call documentView.gc(). Resources are re-allocated automatically if they are needed again later.

import { Scene, WebGLRenderer, PerspectiveCamera } from 'three';
import { WebIO } from '@gltf-transform/core';
import { KHRONOS_EXTENSIONS } from '@gltf-transform/extensions';
import { DocumentView } from '@gltf-transform/view';

// Set up three.js scene.
const scene = new Scene();
// ...

// Load glTF Document.
const io = new WebIO().registerExtensions(KHRONOS_EXTENSIONS);
const document = await io.read('path/to/input.glb');
const documentView = new DocumentView(document);

// Add glTF content to the scene (just once).
const sceneDef = document.getRoot().getDefaultScene(); // glTF Transform Scene
const group = documentView.view(sceneDef); // THREE.Group
scene.add(group);

// Render.
function animate () {
	requestAnimationFrame(animate);
	renderer.render(scene, camera);
}

// When glTF Document is edited, scene updates automatically.
const materialDef = document.getRoot().listMaterials()
	.find((mat) => mat.getName() === 'MyMaterial');
buttonEl.addEventListener('click', () => {
	materialDef.setBaseColorHex(0xFF0000);
});

In glTF, binary data (like vertex positions) is tightly packed into buffers, where Accessors and BufferViews define byte offsets. Manually editing this data is difficult because changing one value can shift the offsets for everything else.

glTF Transform simplifies this by isolating the typed arrays during editing. You can resize or delete data in an Accessor without manually updating byte offsets or other BufferViews. The library handles the complex task of recalculating these offsets and generating appropriate BufferViews during the export process.

Key Abstractions:

• Accessor: Represents the typed array of data. It has a reference to a Buffer, but this is primarily used by the exporter to determine data placement.
• BufferView: This concept is abstracted away from the user. glTF Transform automatically creates interleaved BufferViews for each mesh at export and generates additional views for remaining data.
• Grouping: You can assign Accessors to specific Buffer instances to group data, which enables lazy-loading in supported clients.

To define data that attaches to glTF objects, extend ExtensionProperty. Use init() to define the extensionName, propertyType, and parentTypes (the glTF types this property can be attached to). Use getDefaults() to define initial values.

Properties use methods like .get(), .set(), .addRef(), and .removeRef() (from the property-graph package) to manage data and resource references. This ensures the extension's usage of resources is tracked by the core engine.

Example structure:

class Emitter extends ExtensionProperty {
	static EXTENSION_NAME = 'ACME_particle_emitter';

	init() {
		this.extensionName = 'ACME_particle_emitter';
		this.propertyType = 'Emitter';
		this.parentTypes = [PropertyType.NODE];
	}

	getDefaults() {
		return Object.assign(super.getDefaults(), {
			minVelocity: [1, 1, 1],
			maxVelocity: [10, 10, 10],
			meshes: []
		});
	}

	// minVelocity
	getMinVelocity() {
		return this.get('minVelocity');
	}
	setMinVelocity(velocity) {
		return this.set('minVelocity', velocity);
	}

	// maxVelocity
	getMaxVelocity() {
		return this.get('maxVelocity');
	}
	setMaxVelocity(velocity) {
		return this.set('maxVelocity', velocity);
	}

	// meshes
	listMeshes() {
		return this.listRefs('meshes');
	}
	addMesh(mesh) {
		return this.addRef('meshes', mesh);
	}
	removeMesh(mesh) {
		return this.removeRef('meshes', mesh);
	}
}