Skip to main content

​
Overview

Threebox provides built-in methods to create simple 3D geometric primitives. These objects are lightweight alternatives to loading external models and are useful for markers, paths, and basic visualizations.

​
Sphere

Create spherical objects for markers, points of interest, or particles.

​
Basic Usage

const sphere = tb.sphere({
  radius: 50,
  sides: 20,
  units: 'meters',
  color: 'red',
  material: 'MeshStandardMaterial'
});

sphere.setCoords([-122.4194, 37.7749, 100]);
tb.add(sphere);

​
API Signature

tb.sphere(options)

​
Options

ParameterTypeDefaultDescription
radiusnumber1Sphere radius in specified units
sidesnumber20Number of segments (higher = smoother)
units'scene' | 'meters''scene'Coordinate system
materialstring | THREE.Material'MeshBasicMaterial'Material type
colorstring | number'black'Sphere color
opacitynumber1Opacity (0-1)
anchorstring'bottom-left'Anchor point
adjustment{x, y, z}{x:0, y:0, z:0}Center adjustment
bboxbooleantrueShow bounding box when selected
tooltipbooleantrueEnable tooltip
raycastedbooleantrueInclude in raycasting

​
Examples

// Create a red sphere marker
const marker = tb.sphere({
  radius: 30,
  color: 'red',
  units: 'meters'
});

marker.setCoords([-73.9857, 40.7484, 0]);
tb.add(marker);
Spheres use THREE.SphereBufferGeometry internally. Higher sides values create smoother spheres but impact performance.

​
Line

Create lines in full 3D space. Lines render with consistent color regardless of scene lighting.

​
Basic Usage

const line = tb.line({
  geometry: [
    [-122.4194, 37.7749, 0],
    [-122.4184, 37.7759, 50],
    [-122.4174, 37.7769, 100]
  ],
  color: 'red',
  width: 5
});

tb.add(line);

​
API Signature

tb.line(options)

​
Options

ParameterTypeDefaultDescription
geometryArray<[lng, lat, alt]>requiredArray of coordinates
colorstring | number'black'Line color (renders exactly as specified)
widthnumber1Line width in pixels
opacitynumber1Line opacity (0-1)

​
Examples

// Draw a path between two points
const path = tb.line({
  geometry: [
    [-73.9857, 40.7484, 0],
    [-73.9837, 40.7504, 0]
  ],
  color: 'blue',
  width: 3
});

tb.add(path);
Line width is measured in display pixels, not meters or scene units. Unlike other Threebox objects, line appearance is resolution-dependent.
Lines use a custom fat line shader and render with exact colors regardless of scene lighting. Perfect for route visualization and data overlays.

​
Tube

Create tubular/cylindrical shapes along a path using CatmullRom curves.

​
Basic Usage

const tube = tb.tube({
  geometry: [
    [0, 0, 0],
    [100, 100, 50],
    [200, 50, 100]
  ],
  radius: 10,
  sides: 8,
  material: 'MeshStandardMaterial',
  color: 'green'
});

tube.setCoords([-122.4194, 37.7749]);
tb.add(tube);

​
API Signature

tb.tube(options)

​
Options

ParameterTypeDefaultDescription
geometryArray<[x, y, z]>requiredArray of 3D points defining the curve
radiusnumber1Tube radius
sidesnumber6Number of radial segments
units'scene' | 'meters''scene'Coordinate system
materialstring | THREE.Material'MeshBasicMaterial'Material type
colorstring | number'black'Tube color
opacitynumber1Opacity (0-1)
anchorstring'center'Anchor point
adjustment{x, y, z}{x:0, y:0, z:0}Center adjustment
bboxbooleantrueShow bounding box when selected
tooltipbooleantrueEnable tooltip
raycastedbooleantrueInclude in raycasting

​
Examples

// Simple cylindrical pipe
const pipe = tb.tube({
  geometry: [
    [0, 0, 0],
    [0, 0, 100],
    [50, 0, 150],
    [100, 0, 150]
  ],
  radius: 5,
  sides: 12,
  color: 'silver',
  material: 'MeshPhongMaterial',
  units: 'scene'
});

pipe.setCoords([-122.4194, 37.7749]);
tb.add(pipe);
Tubes use THREE.TubeGeometry with THREE.CatmullRomCurve3 to create smooth curves through the provided points. The curve is non-closed by default.

​
Material Options

All primitives support Three.js material types:
  • MeshBasicMaterial - Unaffected by lights, flat color
  • MeshStandardMaterial - PBR material with realistic lighting (recommended)
  • MeshPhongMaterial - Shiny/glossy appearance
  • MeshLambertMaterial - Matte, diffuse appearance
  • Custom THREE.Material instance
// Using material string
const obj1 = tb.sphere({
  radius: 50,
  material: 'MeshStandardMaterial',
  color: 'red'
});

// Using custom material
const customMat = new THREE.MeshPhysicalMaterial({
  color: 0xff0000,
  metalness: 0.5,
  roughness: 0.1,
  clearcoat: 1.0
});

const obj2 = tb.sphere({
  radius: 50,
  material: customMat
});

​
Common Patterns

​
Animated Marker

const marker = tb.sphere({
  radius: 30,
  color: 'red',
  units: 'meters'
});

marker.setCoords([-122.4194, 37.7749, 0]);
tb.add(marker);

// Animate marker bouncing
marker.set({
  duration: 2000,
  coords: [-122.4194, 37.7749, 100]
});

​
Flight Path Visualization

// Create line showing flight path
const flightPath = tb.line({
  geometry: [
    [-118.2437, 34.0522, 0],      // LA
    [-112.0740, 33.4484, 8000],    // Phoenix (cruising)
    [-104.9903, 39.7392, 8000],    // Denver (cruising)
    [-87.6298, 41.8781, 0]         // Chicago
  ],
  color: 'cyan',
  width: 3
});

tb.add(flightPath);

// Add spheres at endpoints
['#ff0000', '#00ff00'].forEach((color, i) => {
  const sphere = tb.sphere({
    radius: 50,
    color: color,
    units: 'meters'
  });
  sphere.setCoords(flightPath.geometry[i * 3]);
  tb.add(sphere);
});

​
Pipe Network

function createPipe(points, color) {
  return tb.tube({
    geometry: points,
    radius: 3,
    sides: 8,
    color: color,
    material: 'MeshPhongMaterial'
  });
}

const mainPipe = createPipe([
  [0, 0, 0],
  [100, 0, 0],
  [100, 100, 0]
], 'blue');

const branchPipe = createPipe([
  [50, 0, 0],
  [50, -50, 0]
], 'red');

mainPipe.setCoords([-122.4194, 37.7749]);
branchPipe.setCoords([-122.4194, 37.7749]);

tb.add(mainPipe);
tb.add(branchPipe);

​
Performance Tips

  • Keep sides parameter reasonable (8-32 for most uses)
  • Use fewer points in line/tube geometry when possible
  • Consider LOD (Level of Detail) for distant objects
  • Use MeshBasicMaterial for non-lit objects (better performance)
  • Use MeshStandardMaterial when lighting is important
  • Avoid expensive materials like MeshPhysicalMaterial for many objects
  • Group objects with the same material
  • Consider InstancedMesh for many identical objects
  • Reuse geometries when possible

​
Next Steps

Loading Models

Load complex 3D models from external files

Extrusions

Create 3D shapes from GeoJSON polygons

Build docs developers (and LLMs) love

Get started for freeTalk to us