Skip to main content

​
Overview

The GLTF/GLB loader enables you to load 3D models in the GLTF (GL Transmission Format) or GLB (binary GLTF) format. This format supports animations, skeletal animations, and PBR (Physically Based Rendering) materials.

​
Usage

tb.loadObj({
  type: 'gltf', // or 'glb'
  obj: 'https://example.com/model.gltf',
  units: 'meters',
  scale: 1,
  rotation: { x: 90, y: 0, z: 0 },
  anchor: 'center'
}, function(model) {
  tb.add(model);
});

​
Parameters

​
type
string
required
Loader type. Use 'gltf' for GLTF files or 'glb' for binary GLB files.
​
obj
string
required
URL or path to the GLTF/GLB model file.
​
units
string
default:"scene"
Units for the model scale. Options:
  • 'scene' - Scene units (default)
  • 'meters' - Meters
​
scale
number | array
default:"1"
Scale factor for the model. Can be:
  • A single number: 1 (uniform scale)
  • An array: [x, y, z] for per-axis scaling
Example: scale: [2, 2, 2] or scale: 2
​
rotation
number | object | array
default:"0"
Rotation for the model in degrees. Can be:
  • A single number: 90 (rotation around Y axis)
  • An object: { x: 90, y: 0, z: 0 }
  • An array: [90, 0, 0] (X, Y, Z rotation)
​
anchor
string
default:"bottom-left"
Anchor point for the model positioning. Options:
  • 'center' - Center of the model
  • 'bottom-left' - Bottom-left corner
  • 'bottom-right' - Bottom-right corner
  • 'top-left' - Top-left corner
  • 'top-right' - Top-right corner
  • 'bottom-center' - Bottom center
  • 'top-center' - Top center
  • 'left' - Left center
  • 'right' - Right center
​
adjustment
object
Manual adjustment to override the automatic center calculation.Example: { x: 0, y: 0, z: 0 }
​
normalize
boolean
default:"false"
Normalize specular, metalness, and shininess properties for better rendering in Mapbox.GLTF/GLB models may have high specular values that require many lights. Setting this to true reduces metalness and glossiness by 90% and 75% respectively.
​
defaultAnimation
number
default:"0"
Index of the default animation to play from the model’s animation array.
​
raycasted
boolean
default:"true"
Whether the model should be included in raycasting for mouse interactions.
​
bbox
boolean
default:"true"
Whether to calculate and display a bounding box for the model.
​
tooltip
boolean
default:"true"
Whether to enable tooltips for the model.
​
clone
boolean
default:"true"
Whether to clone the model when adding multiple instances.
​
withCredentials
boolean
default:"false"
Whether to send cookies and authorization headers with cross-origin requests.

​
Callback

The callback function receives the loaded model object with the following properties: 
function(model) {
  // Model object with added methods
  model.setCoords([lng, lat]); // Position on map
  model.setRotation({ x: 0, y: 90, z: 0 }); // Rotate model
  model.setScale(2); // Scale model
  
  // Access animations
  console.log(model.animations); // Array of animations
  
  // Access the internal THREE.js model
  console.log(model.model); // THREE.Object3D
}

​
Model Structure

GLTF/GLB models are loaded with the following structure:
  • The scene property becomes the root object
  • animations array is preserved and accessible via model.animations
  • All child meshes and materials are included
  • Skeletal animations are supported
From /home/daytona/workspace/source/src/objects/loadObj.js:71-74: 
case "gltf":
case "glb":
case "dae":
  animations = obj.animations;
  obj = obj.scene;
  break;

​
Normalization

GLTF/GLB models often have high specular values that may appear too shiny in Mapbox. Use the normalize option to reduce these values: 
tb.loadObj({
  type: 'gltf',
  obj: 'model.gltf',
  normalize: true // Reduces metalness and specular
}, callback);
This reduces:
  • Metalness by 90% (multiply by 0.1)
  • Glossiness by 75% (multiply by 0.25)
  • Sets specular color to (12, 12, 12) for MeshStandardMaterial
  • Sets shininess to 0.1 for MeshPhongMaterial

​
Examples

​
Basic GLTF Model

tb.loadObj({
  type: 'gltf',
  obj: 'https://example.com/robot.gltf',
  scale: 5,
  rotation: { x: 0, y: 180, z: 0 },
  anchor: 'center'
}, function(model) {
  model.setCoords([-122.4194, 37.7749]);
  tb.add(model);
});

​
GLB with Animation

tb.loadObj({
  type: 'glb',
  obj: 'https://example.com/character.glb',
  scale: 2,
  defaultAnimation: 0,
  normalize: true
}, function(model) {
  model.setCoords([-122.4194, 37.7749]);
  tb.add(model);
  
  // Play animation
  model.playAnimation({ animation: 0, duration: 1000 });
});

​
Multiple Instances

tb.loadObj({
  type: 'gltf',
  obj: 'https://example.com/tree.gltf',
  scale: 3,
  clone: true
}, function(model) {
  // First instance
  model.setCoords([-122.4194, 37.7749]);
  tb.add(model);
  
  // Second instance (will be cloned)
  let model2 = model.duplicate();
  model2.setCoords([-122.4200, 37.7750]);
  tb.add(model2);
});

Build docs developers (and LLMs) love

Get started for freeTalk to us