Object Creation

Methods for creating 3D objects, models, and geometric shapes

loadObj

Loads a 3D model from external files in different formats (OBJ/MTL, GLTF/GLB, FBX, DAE).

await tb.loadObj(options, callback)

Parameters

options · object · required

Configuration for the 3D model

type · string · required

Type of 3D model: "mtl", "gltf", "fbx", or "dae"

obj · string · required

URL path to the model file (.obj, .glb, .gltf, .fbx, .dae)

mtl · string

URL path to .mtl file (required for OBJ models)

bin · string

URL path to .bin file (for GLTF models)

units · string · default: "scene"

Units for interpreting vertices: "scene" or "meters". “meters” is recommended for precision

rotation · number | object · default: "0"

Rotation along the three axes. Can be a number or {x, y, z} object (e.g., {x: 90, y: 0, z: 0})

scale · number | object · default: "1"

Scale along the three axes. Can be a number or {x, y, z} object (e.g., {x: 1, y: 1, z: 3})

anchor · string · default: "bottom-left"

Position of the pivotal center: "top", "bottom", "left", "right", "center", "top-left", "top-right", "bottom-left", "bottom-right", or "auto"

adjustment · object · default: "{x: 0, y: 0, z: 0}"

Adjustment to correct center position in units per axis (e.g., {x: 0.5, y: 0.5, z: 0})

normalize · boolean · default: "true"

Normalize specular values from some 3D models

feature · GeoJSON.Feature

GeoJSON feature instance for storing relevant data

tooltip · boolean · default: "false"

Enable tooltip for this object

bbox · boolean · default: "false"

Enable bounding box for this object

raycasted · boolean · default: "true"

Whether the object should be included in raycasting

clone · boolean · default: "true"

Clone the object from cache. Set to false for unique instances when animations/textures don’t work well with cloning

defaultAnimation · number · default: "0"

Index of the default animation to play (ignored if the object has no animations)

callback · function · required

Function to run after the object loads. Receives the loaded object as first argument

Example

var options = {
  obj: '/3D/soldier/soldier.glb',
  type: 'gltf',
  scale: 20,
  units: 'meters',
  rotation: { x: 90, y: 0, z: 0 },
  adjustment: { x: 0, y: 0, z: 0 }
};

tb.loadObj(options, function (model) {
  soldier = model.setCoords(origin);
  tb.add(soldier);
});

---

sphere

Creates a sphere object.

tb.sphere(options)

Parameters

options · object · required

Configuration for the sphere. Accepts standard Object3D options plus geometry-specific parameters

Returns

sphere · Object3D

A sphere object that can be positioned and added to the scene

Example

let sphere = tb.sphere({
  radius: 10,
  units: 'meters',
  material: 'MeshStandardMaterial'
});
sphere.setCoords([lng, lat, altitude]);
tb.add(sphere);

---

line

Creates a line in full 3D space.

tb.line(options)

Parameters

options · object · required

Configuration for the line

geometry · array · required

Array of lnglat coordinates to draw the line

color · color · default: "black"

Color of the line. This color will render precisely as specified, regardless of scene lighting

width · number · default: "1"

Line width in display pixels (not meters or scene units)

opacity · number · default: "1"

Line opacity (0-1)

Returns

line · Object3D

A line object with the specified geometry and styling

Example

let line = tb.line({
  geometry: [
    [-122.48369693756104, 37.83381888486939],
    [-122.48348236083984, 37.83317489144141],
    [-122.48339653015138, 37.83270036637107]
  ],
  color: 'red',
  width: 3
});
tb.add(line);

---

tube

Creates a tube object.

tb.tube(options)

Parameters

options · object · required

Configuration for the tube. Accepts standard Object3D options plus tube-specific parameters

Returns

tube · Object3D

A tube object that can be positioned and added to the scene

Example

let tube = tb.tube({
  geometry: route,
  radius: 5,
  units: 'meters'
});
tb.add(tube);

---

extrusion

Creates an extruded shape.

tb.extrusion(options)

Parameters

options · object · required

Configuration for the extrusion

coordinates · array

Nested array following GeoJSON polygon format, or a THREE.Vector2 array

Returns

extrusion · Object3D

An extruded shape object

Example

let extrusion = tb.extrusion({
  coordinates: polygonCoordinates,
  height: 100,
  units: 'meters'
});
tb.add(extrusion);

---

label

Creates a CSS2D label.

tb.label(options)

Parameters

options · object · required

Configuration for the label

Returns

label · Object3D

A CSS2D label object

Example

let label = tb.label({
  text: 'My Location',
  cssClass: 'custom-label'
});
label.setCoords([lng, lat]);
tb.add(label);

---

tooltip

Creates a tooltip.

tb.tooltip(options)

Parameters

options · object · required

Configuration for the tooltip

text · string · required

Text content of the tooltip

mapboxStyle · boolean

Use Mapbox styling for the tooltip

feature · GeoJSON.Feature

Associated GeoJSON feature

Returns

tooltip · Object3D

A tooltip object

Example

let tooltip = tb.tooltip({
  text: 'Building Name',
  mapboxStyle: true
});
tooltip.setCoords([lng, lat]);
tb.add(tooltip);

---

Object3D

Wraps a Three.js object to make it compatible with Threebox positioning and methods.

tb.Object3D(options)

Parameters

options · object · required

Configuration for the Object3D wrapper

obj · THREE.Object3D · required

Three.js object to wrap

units · string · default: "scene"

Units for the object: "scene" or "meters"

anchor · string

Anchor position for the object

Returns

object · Object3D

A Threebox-compatible Object3D

Example

var geometry = new THREE.BoxGeometry(30, 60, 120);
let cube = new THREE.Mesh(geometry, new THREE.MeshPhongMaterial({ color: 0x660000 }));
cube = tb.Object3D({ obj: cube, units: 'meters' });
cube.setCoords([-3.460539968876, 40.4849214450]);
tb.add(cube);