Skip to main content

Lighting Methods

setSunlight

Updates the sun light position based on a given datetime and coordinates.
tb.setSunlight(newDate, coords)

Parameters

newDate
Date
default:"new Date()"
Date and time for calculating sun position
coords
object | array
Coordinates for sun calculation. Can be {lng, lat} object or [lng, lat] array. If omitted, uses map.getCenter()

Example

// Set sunlight for current time at map center
tb.setSunlight();

// Set sunlight for specific date and location
tb.setSunlight(new Date('2024-06-21 12:00:00'), [-122.4, 37.8]);

defaultLights

Creates the default illumination for the Threebox scene.
tb.defaultLights()
This method creates:
  • THREE.AmbientLight (assigned to tb.lights.ambientLight)
  • Two THREE.DirectionalLight instances (assigned to tb.lights.dirLight and tb.lights.dirLightBack)

Example

window.tb = new Threebox(map, gl);
tb.defaultLights();

realSunlight

Creates illumination that simulates real sun light.
tb.realSunlight(helper)

Parameters

helper
boolean
default:"false"
Whether to show a visual helper for the directional light
This method creates:
  • THREE.DirectionalLight with shadow mapping
  • THREE.HemisphereLight for ambient sky/ground lighting
  • Automatically positions light based on sun position using SunCalc

Example

window.tb = new Threebox(map, gl);
tb.realSunlight(true); // Show light helper

Sun Position Methods

getSunPosition

Gets the sun position (azimuth, altitude) for a given date and coordinates.
tb.getSunPosition(date, coords)

Parameters

date
Date
required
Date and time for sun position calculation
coords
array
required
Coordinates as [lng, lat]

Returns

position
object
Object with azimuth and altitude properties in radians

Example

let sunPos = tb.getSunPosition(new Date(), [-122.4, 37.8]);
console.log('Azimuth:', sunPos.azimuth, 'Altitude:', sunPos.altitude);

getSunSky

Gets the sun sky layer position for atmospheric rendering.
tb.getSunSky(date, sunPos)

Parameters

date
Date
Date for calculation. If omitted, uses new Date()
sunPos
object
Pre-calculated sun position. If omitted, calculates based on map.getCenter()

Returns

position
array
Array with [azimuth, altitude] in degrees

Example

let skyPos = tb.getSunSky();
tb.updateSunSky(skyPos);

getSunTimes

Gets sun times for different light phases (sunrise, sunset, etc.).
tb.getSunTimes(date, coords)

Parameters

date
Date
required
Date for sun times calculation
coords
array
required
Coordinates as [lng, lat, altitude] (altitude is optional)

Returns

times
object
Object with Date properties for:
  • sunrise - Sunrise (top edge of sun appears)
  • sunriseEnd - Sunrise ends (bottom edge touches horizon)
  • goldenHourEnd - Morning golden hour ends
  • solarNoon - Solar noon (sun at highest position)
  • goldenHour - Evening golden hour starts
  • sunsetStart - Sunset starts
  • sunset - Sunset (sun disappears)
  • dusk - Evening nautical twilight starts
  • nauticalDusk - Evening astronomical twilight starts
  • night - Night starts
  • nadir - Darkest moment
  • nightEnd - Night ends
  • nauticalDawn - Morning nautical twilight starts
  • dawn - Morning civil twilight starts

Example

let times = tb.getSunTimes(new Date(), [-122.4, 37.8]);
console.log('Sunrise:', times.sunrise);
console.log('Sunset:', times.sunset);

Coordinate Conversion

projectToWorld

Converts geographic coordinates to Three.js world coordinates.
tb.projectToWorld(coords)

Parameters

coords
array
required
Geographic coordinates as [lng, lat]

Returns

vector
THREE.Vector3
Three.js Vector3 in world space

Example

let worldPos = tb.projectToWorld([-122.4, 37.8]);

unprojectFromWorld

Converts Three.js world coordinates to geographic coordinates.
tb.unprojectFromWorld(v3)

Parameters

v3
THREE.Vector3
required
Three.js Vector3 in world space

Returns

coords
object
Geographic coordinates with lng and lat properties

Example

let lngLat = tb.unprojectFromWorld(new THREE.Vector3(100, 200, 0));
console.log(lngLat.lng, lngLat.lat);

projectedUnitsPerMeter

Gets the projected units per meter at a given latitude.
tb.projectedUnitsPerMeter(lat)

Parameters

lat
number
required
Latitude in degrees

Returns

units
number
Number of projected units per meter at the given latitude

Example

let scale = tb.projectedUnitsPerMeter(37.8);

Query Methods

queryRenderedFeatures

Finds objects intersecting a screen point using raycasting.
tb.queryRenderedFeatures(point)

Parameters

point
object
required
Screen coordinates as {x: number, y: number} (as returned by Mapbox mouse events as e.point)

Returns

intersects
array
Array of intersected objects ordered by distance (closest first)

Example

map.on('click', function(e) {
  let intersects = tb.queryRenderedFeatures(e.point);
  if (intersects.length > 0) {
    console.log('Clicked object:', intersects[0]);
  }
});

findParent3DObject

Finds the parent Object3D from a mesh.
tb.findParent3DObject(mesh)

Parameters

mesh
THREE.Mesh
required
Mesh object (typically from raycaster intersection)

Returns

object
Object3D
The parent Object3D in the Threebox scene

Example

let intersects = tb.queryRenderedFeatures(e.point);
if (intersects.length > 0) {
  let object = tb.findParent3DObject(intersects[0]);
}

Feature Utilities

getFeatureCenter

Calculates the center of a GeoJSON feature geometry.
tb.getFeatureCenter(feature, model, level)

Parameters

feature
GeoJSON.Feature
required
GeoJSON feature
model
Object3D
3D model (optional)
level
number
Level/floor number (optional)

Returns

coords
array
Center coordinates as [lng, lat, altitude]

getObjectHeightOnFloor

Calculates the altitude for a GeoJSON feature at a given level.
tb.getObjectHeightOnFloor(feature, obj, level)

Parameters

feature
GeoJSON.Feature
required
GeoJSON feature
obj
Object3D
3D object (optional)
level
number
required
Level/floor number

Returns

altitude
number
Altitude in meters

Info Methods

memory

Returns memory information from the WebGL renderer.
tb.memory()

Returns

memory
object
Memory info from THREE.WebGLRenderer.info.memory

programs

Returns the number of WebGL programs.
tb.programs()

Returns

count
number
Number of active WebGL programs

findParent3DObject

Finds the parent Object3D from a raycast intersection mesh.
tb.findParent3DObject(mesh)

Parameters

mesh
object
required
Raycast intersection result containing an object property

Returns

object
Object3D
The parent Object3D, or undefined if not found

Layer Management

setLayerZoomRange

Sets the zoom range for a layer and enables zoom-based visibility toggling.
tb.setLayerZoomRange(layerId, minZoom, maxZoom)

Parameters

layerId
string
required
Layer ID
minZoom
number
required
Minimum zoom level
maxZoom
number
required
Maximum zoom level

setLayoutProperty

Sets a layout property on a Mapbox layer.
tb.setLayoutProperty(layerId, property, value)

Parameters

layerId
string
required
Layer ID
property
string
required
Property name (e.g., ‘visibility’)
value
any
required
Property value

toggleLayer

Toggles layer visibility based on zoom range.
tb.toggleLayer(layerId, visible)

Parameters

layerId
string
required
Layer ID
visible
boolean
Force visibility state (default: true)

toggle

Sets layer and label visibility.
tb.toggle(layerId, visible)

Parameters

layerId
string
required
Layer ID
visible
boolean
required
Visibility state

Sky and Terrain Updates

updateSunGround

Updates terrain layer opacity based on sun position (for day/night effect).
tb.updateSunGround(sunPos)

Parameters

sunPos
object
required
Sun position object with altitude property from getSunPosition()

Example

const sunPos = tb.getSunPosition(new Date(), [lng, lat]);
tb.updateSunGround(sunPos);

updateSunSky

Updates the sky layer with new sun position parameters.
tb.updateSunSky(sunSky)

Parameters

sunSky
object
required
Sky parameters object from getSunSky()

Example

const sunSky = tb.getSunSky(new Date(), [lng, lat]);
tb.updateSunSky(sunSky);

Build docs developers (and LLMs) love