threebox

Creating many individual 3D layers in Mapbox is resource-intensive because each layer is rendered separately. To optimize performance, use the multiLayer parameter.

When multiLayer is enabled, Threebox creates an embedded internal layer that manages rendering with a single call to tb.update. This ensures the Mapbox render loop only calls the Three.js render once, significantly saving resources.

You can also manage visibility for these layers using tb.setLayoutZoomRange to hide/show layers based on the current zoom level.

Threebox objects are categorized into two types based on how they interact with the map and coordinates:

• Static objects: Used for background or geographical features that do not move or change once placed. They use complex internal geometry expressed primarily in lnglat coordinates.
• Dynamic objects: Objects that can move around the map, positioned by a single lnglat point. Their internal geometries are produced in local scene units (e.g., via external .obj files or convenience methods like tb.extrusion).

You can enable built-in interaction modes for 3D objects using specific methods on the Threebox instance. These allow users to select, drag, rotate, and view tooltips for objects.

Key interaction methods:

• enableSelectingObjects: Enables raycasting and selection. Objects can be selected and unselected.
• enableDraggingObjects: Enables dragging. Once an object is selected, use the [Shift] key for translation and [Ctrl] for altitude.
• enableRotatingObjects: Enables rotation on the vertical axis. Once an object is selected, use the [Alt] key.
• enableTooltips: Enables default labels/tooltips at the object's altitude.

To run the provided Threebox examples, you must create a config.js file in the same directory as the example HTML file. This file must contain your Mapbox GL JS access token following the format of the config_template.js provided in the repository.

Example structure for config.js:

window.mapgl = { access_token: 'YOUR_MAPBOX_ACCESS_TOKEN' };

Threebox provides built-in support for realistic lighting and atmospheric effects:

• Atmospheric Sky: Add a sky layer by passing sky: true in the configuration parameters.
• Real Sunlight: Enable sunlight that follows real-world positions using realSunlight.
• Shadows:
  • For 3D objects: Enable via the castShadow property.
  • For Mapbox fill-extrusions: Use tb.setBuildingShadows.
• Sunlight Management:
  • setSunlight: Set the map lights based on a specific time/date.
  • tb.getSunTimes: Retrieve sun times to automatically change styles (e.g., from sunset to sunrise).

To maintain performance when rendering many identical objects, use obj.duplicate().

Important Note: If your object contains sub-objects that are not part of the obj.children collection, those sub-objects must also be cloned manually to ensure they are properly duplicated.

By default, tb.loadObj handles duplication for you.

To enable interaction with Mapbox features (like fill-extrusion layers) rather than just Threebox Object3D entities, use:

• enableSelectingFeatures: Enables built-in raycasting and selection for Mapbox features.
• enableTooltips: Enables default labels on altitude for features (e.g., for fill-extrusions).

You can manage selection events for features using the Mapbox event handler: map.on('SelectedFeatureChange', ...).

To use Threebox, you must add a custom layer to your Mapbox GL map. The onAdd function initializes the Threebox instance, and the render function calls tb.update() to ensure the 3D scene renders correctly.

map.addLayer({
	id: 'custom_layer',
	type: 'custom',
	renderingMode: '3d',
	onAdd: function (map, gl) {

		window.tb = new Threebox(
			map,
			gl,
			{
				defaultLights: true,
				enableSelectingFeatures: true,
				enableSelectingObjects: true,
				enableDraggingObjects: true,
				enableRotatingObjects: true,
				enableTooltips: true
			}
		);

		// Load objects here...
	},
	render: function (gl, matrix) {
		tb.update();
	}
});