Centers the Scene at the origin, or above/below it. Transformations from animation, skinning, and morph targets are not taken into account.
Example:
await document.transform(center({pivot: 'below'}));
Vertex color colorspace correction. The glTF format requires vertex colors to be stored as linear values, and this function provides a way to correct vertex colors that are (incorrectly) sRGB.
Constructs a plan for processing vertex streams, based on unique index:attribute[] groups. Where different indices are used with the same attributes, we'll end up splitting the primitives to not share attributes, which appears to be consistent with the Meshopt implementation.
Removes duplicate Accessor, Mesh, Texture, and Material properties. Partially based on a gist by mattdesl. Only accessors in mesh primitives, morph targets, and animation samplers are processed.
Example:
document.getRoot().listMeshes(); // → [Mesh, Mesh, Mesh]
await document.transform(dedup({propertyTypes: [PropertyType.MESH]}));
document.getRoot().listMeshes(); // → [Mesh]
Dequantize Primitives, removing KHR_mesh_quantization
if present. Dequantization will increase the size of the mesh on disk and in memory, but may be
necessary for compatibility with applications that don't support quantization.
Applies Draco compression using KHR_draco_mesh_compression. This type of compression can reduce the size of triangle geometry.
This function is a thin wrapper around the DracoMeshCompression extension itself.
Returns bitmask of all TextureChannels used by the
given texture. Determination is based only on the role of the textures, e.g.
a texture used for the occlusionTexture will have (at least) a red channel.
See listTextureChannels for an array alternative.
Example:
const mask = getTextureChannelMask(document, texture);
if (mask & TextureChannel.R) {
console.log('texture red channel used');
}
Inspects the contents of a glTF file and returns a JSON report.
Creates GPU instances (with EXT_mesh_gpu_instancing) for shared Mesh references. No
options are currently implemented for this function.
Returns a list of TextureChannels used by the given
texture. Determination is based only on the role of the textures, e.g.
a texture used for the occlusionTexture will have (at least) a red channel
in use. See getTextureChannelMask for bitmask alternative.
Example:
const channels = listTextureChannels(document, texture);
if (channels.includes(TextureChannel.R)) {
console.log('texture red channel used');
}
Lists all TextureInfo definitions associated with a given Texture.
Example:
// Find TextureInfo instances associated with the texture.
const results = listTextureInfo(document, texture);
// Find which UV sets (TEXCOORD_0, TEXCOORD_1, ...) are required.
const texCoords = results.map((info) => info.getTexCoord());
// → [0, 0, 1]
Returns names of all texture slots using the given texture.
Example:
const slots = listTextureSlots(document, texture);
// → ['occlusionTexture', 'metallicRoughnesTexture']
Applies Meshopt compression using EXT_meshopt_compression. This type of compression can reduce the size of point, line, and triangle geometry, morph targets, and animation data.
This function is a thin wrapper around reorder, quantize, and MeshoptCompression, and exposes relatively few configuration options. To access more options (like quantization bits) direct use of the underlying functions is recommended.
Example:
import { MeshoptEncoder } from 'meshoptimizer';
import { reorder } from '@gltf-transform/functions';
await MeshoptEncoder.ready;
await document.transform(
reorder({encoder: MeshoptEncoder, level: 'medium'})
);
Convert Materials from spec/gloss PBR workflow to metal/rough PBR workflow,
removing KHR_materials_pbrSpecularGlossiness and adding KHR_materials_ior and
KHR_materials_specular. The metal/rough PBR workflow is preferred for most use cases,
and is a prerequisite for other advanced PBR extensions provided by glTF.
No options are currently implemented for this function.
Optimizes JPEG images by default, optionally converting PNG textures to JPEG.
Requires @squoosh/lib, and currently works only in Node.js
environments. Support for encoding in web browsers may be available pending
GoogleChromeLabs/squoosh#1084.
Example:
import { cpus } from 'os';
import * as squoosh from '@squoosh/lib';
import { mozjpeg } from '@gltf-transform/functions';
await document.transform(
mozjpeg({ squoosh, jobs: cpus().length })
);
Generates flat vertex normals for mesh primitives.
Example:
import { normals } from '@gltf-transform/functions';
await document.transform(normals({overwrite: true}));
Optimizes PNG images by default, optionally converting JPEG textures to PNG.
Requires @squoosh/lib, and currently works only in Node.js
environments. Support for encoding in web browsers may be available pending
GoogleChromeLabs/squoosh#1084.
Example:
import { cpus } from 'os';
import * as squoosh from '@squoosh/lib';
import { oxipng } from '@gltf-transform/functions';
await document.transform(
oxipng({ squoosh, jobs: cpus().length })
);
Partitions the binary payload of a glTF file so separate mesh or animation data is in separate
.bin Buffers. This technique may be useful for engines that support lazy-loading
specific binary resources as needed over the application lifecycle.
Example:
document.getRoot().listBuffers(); // → [Buffer]
await document.transform(partition({meshes: true}));
document.getRoot().listBuffers(); // → [Buffer, Buffer, ...]
Removes properties from the file if they are not referenced by a Scene. Commonly helpful for cleaning up after other operations, e.g. allowing a node to be detached and any unused meshes, materials, or other resources to be removed automatically.
Example:
document.getRoot().listMaterials(); // → [Material, Material]
await document.transform(prune());
document.getRoot().listMaterials(); // → [Material]
No options are currently implemented for this function.
Quantizes vertex attributes with KHR_mesh_quantization, reducing the size and memory footprint
of the file.
Optimizes Mesh Primitives for locality of reference. Choose whether the order should be optimal for transmission size (recommended for Web) or for GPU rendering performance. Requires a MeshoptEncoder instance from the Meshoptimizer library.
Example:
import { MeshoptEncoder } from 'meshoptimizer';
import { reorder } from '@gltf-transform/functions';
await MeshoptEncoder.ready;
await document.transform(
reorder({encoder: MeshoptEncoder})
);
Resample Animations, losslessly deduplicating keyframes to reduce file size. Duplicate keyframes are commonly present in animation 'baked' by the authoring software to apply IK constraints or other software-specific features. Based on THREE.KeyframeTrack.optimize().
Example: (0,0,0,0,1,1,1,0,0,0,0,0,0,0) --> (0,0,1,1,0,0)
Simplification algorithm, based on meshoptimizer, producing meshes with fewer triangles and vertices. Simplification is lossy, but the algorithm aims to preserve visual quality as much as possible for given parameters.
The algorithm aims to reach the target 'ratio', while minimizing error. If error exceeds the specified 'error' threshold, the algorithm will quit before reaching the target ratio. Examples:
Topology, particularly split vertices, will also limit the simplifier. For best results, apply a weld operation before simplification.
Example:
import { simplify, weld } from '@gltf-transform/functions';
import { MeshoptSimplifier } from 'meshoptimizer';
await document.transform(
weld({ tolerance: 0.0001 }),
simplify({ simplifier: MeshoptSimplifier, ratio: 0.75, error: 0.001 })
);
References:
Sorts skinning weights from high to low, for each vertex of the input Primitive or PrimitiveTarget, and normalizes the weights. Optionally, uses the given 'limit' to remove least-significant joint influences such that no vertex has more than 'limit' influences.
Most realtime engines support a limited number of joint influences per vertex, often 4 or 8. Sorting and removing the additional influences can reduce file size and improve compatibility.
Example:
import { sortPrimitiveWeights } from '@gltf-transform/functions';
const limit = 4;
for (const mesh of document.getRoot().listMeshes()) {
for (const prim of mesh.listPrimitives()) {
sortPrimitiveWeights(prim, limit);
}
}
Generates MikkTSpace vertex tangents for mesh primitives, which may fix rendering issues occuring with some baked normal maps. Requires access to the mikktspace WASM package, or equivalent.
Example:
import { generateTangents } from 'mikktspace';
import { tangents } from '@gltf-transform/functions';
await document.transform(
tangents({generateTangents})
);
Resize PNG or JPEG Textures, with Lanczos filtering. Implementation provided by ndarray-lanczos package.
Method:
Example:
import { fromTranslation } from 'gl-matrix/mat4';
import { transformMesh } from '@gltf-transform/functions';
// offset vertices, y += 10.
transformMesh(mesh, fromTranslation([], [0, 10, 0]));
Applies a transform matrix to a Primitive.
When calling transformPrimitive, any un-masked vertices are overwritten directly in the underlying vertex streams. If streams should be detached instead, see transformMesh.
Example:
import { fromTranslation } from 'gl-matrix/mat4';
import { transformPrimitive } from '@gltf-transform/functions';
// offset vertices, y += 10.
transformPrimitive(prim, fromTranslation([], [0, 10, 0]));
Removes partitions from the binary payload of a glTF file, so that the asset
contains at most one (1) .bin Buffer. This process reverses the
changes from a partition transform.
Example:
document.getRoot().listBuffers(); // → [Buffer, Buffer, ...]
await document.transform(unpartition());
document.getRoot().listBuffers(); // → [Buffer]
De-index Primitives, disconnecting any shared vertices. This operation will generally increase the number of vertices in a mesh, but may be helpful for some geometry operations or for creating hard edges.
No options are currently implemented for this function.
Converts images to WebP, using the TextureWebP extension.
Requires @squoosh/lib, and currently works only in Node.js
environments. Support for encoding in web browsers may be available pending
GoogleChromeLabs/squoosh#1084.
Example:
import { cpus } from 'os';
import * as squoosh from '@squoosh/lib';
import { webp } from '@gltf-transform/functions';
await document.transform(
webp({ squoosh, jobs: cpus().length })
);
Index Primitives and (optionally) merge similar vertices. When merged and indexed, data is shared more efficiently between vertices. File size can be reduced, and the GPU can sometimes use the vertex cache more efficiently.
When welding, the 'tolerance' threshold determines which vertices qualify for welding based on distance between the vertices as a fraction of the primitive's bounding box (AABB). For example, tolerance=0.01 welds vertices within +/-1% of the AABB's longest dimension. Other vertex attributes are also compared during welding, with attribute-specific thresholds. For --tolerance=0, geometry is indexed in place, without merging.
Example:
import { weld } from '@gltf-transform/functions';
await document.transform(
weld({ tolerance: 0.001 })
);
Index a Primitive and (optionally) weld similar vertices. When merged and indexed, data is shared more efficiently between vertices. File size can be reduced, and the GPU can sometimes use the vertex cache more efficiently.
When welding, the 'tolerance' threshold determines which vertices qualify for welding based on distance between the vertices as a fraction of the primitive's bounding box (AABB). For example, tolerance=0.01 welds vertices within +/-1% of the AABB's longest dimension. Other vertex attributes are also compared during welding, with attribute-specific thresholds. For --tolerance=0, geometry is indexed in place, without merging.
Example:
import { weldPrimitive } from '@gltf-transform/functions';
const mesh = document.getRoot().listMeshes()
.find((mesh) => mesh.getName() === 'Gizmo');
for (const prim of mesh.listPrimitives()) {
weldPrimitive(document, prim, {tolerance: 0.0001});
}
Made by Don McCurdy • TypeDoc documentation • Copyright 2021 under MIT license
Functions
Common glTF modifications, written using the core API.
Most of these functions are Transforms, applying a modification to the Document, used with Document.transform. This project includes many common transforms already, and others can be quickly implemented using the same APIs. Other functions, like bounds, provide non-mutating functionality on top of the existing glTF-Transform property types.
Installation
Install:
Import: