Skip to main content

​
Overview

The COLLADA loader enables you to load 3D models in the DAE (Digital Asset Exchange) format. COLLADA is an open standard XML-based format that supports animations, skeletal rigging, physics, and complex scene hierarchies.

​
Usage

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

​
Parameters

​
type
string
required
Loader type. Must be 'dae' for COLLADA files.
​
obj
string
required
URL or path to the DAE 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)
Note: COLLADA models may use different coordinate systems (Z-up vs Y-up) depending on the exporting software.
​
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.
​
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

COLLADA 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, lights, cameras, and scene hierarchy are included
  • Materials and textures are loaded automatically
  • Skeletal animations and morph targets are supported
From /home/daytona/workspace/source/src/objects/loadObj.js:71-76: 
case "gltf":
case "glb":
case "dae":
  animations = obj.animations;
  obj = obj.scene;
  break;

​
Coordinate Systems

COLLADA supports different coordinate systems depending on the software used to create the model:
  • Y-up (Maya, Cinema 4D): rotation: { x: 0, y: 0, z: 0 }
  • Z-up (Blender, 3ds Max): rotation: { x: 90, y: 0, z: 0 }
Threebox uses a Y-up coordinate system aligned with Mapbox. Adjust rotation as needed: 
tb.loadObj({
  type: 'dae',
  obj: 'model.dae',
  rotation: { x: 90, y: 0, z: 0 } // Z-up to Y-up conversion
}, callback);

​
Embedded Assets

COLLADA files can embed textures and other assets directly in the XML or reference external files: 
<!-- External texture reference -->
<image id="texture1">
  <init_from>textures/diffuse.png</init_from>
</image>

<!-- Embedded base64 texture -->
<image id="texture2">
  <data>iVBORw0KGgoAAAANS...</data>
</image>
Both methods are supported. External references are resolved relative to the DAE file location.

​
Examples

​
Basic COLLADA Model

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

​
COLLADA with Animation

tb.loadObj({
  type: 'dae',
  obj: 'https://example.com/character.dae',
  scale: 2,
  rotation: { x: 90, y: 0, z: 0 },
  defaultAnimation: 0
}, function(model) {
  model.setCoords([-122.4194, 37.7749]);
  tb.add(model);
  
  // Play walk animation
  if (model.animations && model.animations.length > 0) {
    model.playAnimation({ 
      animation: 0, 
      duration: 3000,
      loop: true 
    });
  }
});

​
Multiple Animations

tb.loadObj({
  type: 'dae',
  obj: 'https://example.com/robot.dae',
  scale: 3,
  rotation: { x: 90, y: 0, z: 0 }
}, function(model) {
  model.setCoords([-122.4194, 37.7749]);
  tb.add(model);
  
  console.log('Available animations:', model.animations.length);
  
  // Play first animation (idle)
  model.playAnimation({ animation: 0, loop: true });
  
  // Switch to second animation (wave) after 3 seconds
  setTimeout(() => {
    model.playAnimation({ animation: 1, loop: true });
  }, 3000);
});

​
Scene with Lights and Cameras

tb.loadObj({
  type: 'dae',
  obj: 'https://example.com/scene.dae',
  scale: 1
}, function(model) {
  model.setCoords([-122.4194, 37.7749]);
  tb.add(model);
  
  // Access lights from the COLLADA scene
  model.model.traverse(function(child) {
    if (child.isLight) {
      console.log('Found light:', child.name, child.type);
      // Adjust light intensity for Mapbox
      child.intensity *= 0.5;
    }
  });
});

​
Normalization

COLLADA models may have high specular values. Use the normalize option: 
tb.loadObj({
  type: 'dae',
  obj: 'model.dae',
  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

​
Common Issues

​
Model Not Visible

If the model loads but isn’t visible:
  1. Check the scale - COLLADA files may use different unit systems
  2. Verify rotation - adjust for coordinate system differences
  3. Check the anchor point - try 'center' or 'bottom-center'
tb.loadObj({
  type: 'dae',
  obj: 'model.dae',
  scale: 0.01, // Try different scales
  rotation: { x: 90, y: 0, z: 0 },
  anchor: 'center'
}, callback);

​
Texture Not Loading

If textures are missing:
  1. Check browser console for loading errors
  2. Verify texture paths in the DAE file are correct
  3. Ensure CORS headers are set for external texture URLs
  4. Check that texture files exist at the referenced paths

​
Animation Issues

If animations don’t play:
  1. Check if animations exist: console.log(model.animations)
  2. Verify the animation index is valid
  3. Use model.idle() to initialize skeletal animations
function(model) {
  console.log('Animations:', model.animations);
  if (model.animations.length > 0) {
    model.idle(); // Initialize skeleton
    model.playAnimation({ animation: 0 });
  }
}

​
Performance Considerations

COLLADA files can be large and complex:
  • Use clone: true to efficiently create multiple instances
  • Enable normalize: true to reduce rendering overhead
  • Consider converting complex DAE files to GLB for better performance
  • Simplify mesh geometry and reduce polygon count if possible

Build docs developers (and LLMs) love

Get started for freeTalk to us