API.md

3d-tiles-renderer/three

Constants

ENU_FRAME

ENU_FRAME: number

Frame constant for the East-North-Up (ENU) coordinate frame, with X pointing east, Y pointing north, and Z pointing up (away from the ellipsoid surface).

CAMERA_FRAME

CAMERA_FRAME: number

Frame constant for a camera-convention frame relative to the ENU frame, oriented with "+Y" up and "-Z" forward (matching three.js camera conventions).

OBJECT_FRAME

OBJECT_FRAME: number

Frame constant for an object-convention frame relative to the ENU frame, oriented with "+Y" up and "+Z" forward (matching three.js object conventions).

B3DMLoader

extends B3DMLoaderBase

Loader for the legacy 3D Tiles Batched 3D Model (b3dm) format. Parses the b3dm container and returns a GLTF result with batchTable and featureTable attached to the resolved scene object.

.constructor

constructor( manager: LoadingManager )

.parse

parse(
	buffer: ArrayBuffer
): Promise<{scene: Group, scenes: Array, batchTable: BatchTable, featureTable: FeatureTable}>

Parses a b3dm buffer and resolves to a GLTF result object extended with legacy tile metadata. Both model and model.scene receive the extra fields.

CameraTransitionManager

extends EventDispatcher

Manages an animated transition between a perspective and an orthographic camera. During the transition a blended transitionCamera is used. Fires events for the transition lifecycle and the active camera change.

.animating

readonly animating: boolean

Whether a transition animation is currently in progress.

.alpha

readonly alpha: number

Transition progress from 0 (at perspective) to 1 (at orthographic).

.camera

readonly camera: Camera

The currently active camera. Returns perspectiveCamera, orthographicCamera, or the blended transitionCamera depending on the current transition state.

.mode

mode: string

The target camera mode. Set to 'perspective' or 'orthographic' to jump instantly without animation. Use toggle() to animate the transition.

.orthographicPositionalZoom

orthographicPositionalZoom: boolean

When true, the orthographic camera position is offset backwards along the view direction so it does not clip into terrain. Default is true.

.orthographicOffset

orthographicOffset: number

Distance the orthographic camera is pushed back when orthographicPositionalZoom is true. Default is 50.

.fixedPoint

fixedPoint: Vector3

World-space point that remains visually fixed during the transition.

.duration

duration: number

Duration of the animated transition in milliseconds. Default is 200.

.autoSync

autoSync: boolean

When true, cameras are synced automatically before each update call. Default is true.

.easeFunction

easeFunction: function

Easing function applied to the raw transition alpha. Receives and returns a value in [0, 1]. Default is the identity function.

.constructor

constructor( perspectiveCamera: PerspectiveCamera, orthographicCamera: OrthographicCamera )

.toggle

toggle(): void

Begins an animated transition to the opposite camera mode. Dispatches a 'toggle' event.

.update

update( deltaTime: number ): void

Advances the transition animation and updates the active camera. Must be called each frame.

.syncCameras

syncCameras(): void

Synchronises the non-active camera so that both cameras represent the same viewpoint. Called automatically by update when autoSync is true.

CMPTLoader

extends CMPTLoaderBase

Loader for the legacy 3D Tiles Composite (cmpt) format. Parses a cmpt container that bundles multiple b3dm, i3dm, and pnts tiles, returning a scene Group containing all sub-tile scenes.

.constructor

constructor( manager: LoadingManager )

.parse

parse( buffer: ArrayBuffer ): Promise<{scene: Group, tiles: Array}>

Parses a cmpt buffer and resolves to an object containing a Group with all sub-tile scenes added as children, and the individual sub-tile results.

Ellipsoid

Represents a triaxial ellipsoid defined by three semi-axis radii. Used to model planet-scale surfaces such as the Earth (see WGS84_ELLIPSOID). All geographic coordinates use latitude and longitude in radians.

.name

name: string

Optional name for this ellipsoid instance.

.radius

radius: Vector3

Semi-axis radii of the ellipsoid.

.constructor

constructor( x = 1: number, y = 1: number, z = 1: number )

.intersectRay

intersectRay( ray: Ray, target: Vector3 ): Vector3 | null

Returns the point where the given ray intersects the ellipsoid surface, or null if no intersection exists. Writes the result into target.

.getEastNorthUpFrame

getEastNorthUpFrame(
	lat: number,
	lon: number,
	height: number,
	target: Matrix4
): Matrix4

Returns a Matrix4 representing the East-North-Up (ENU) frame at the given geographic position: X points east, Y points north, Z points up. Writes the result into target.

.getOrientedEastNorthUpFrame

getOrientedEastNorthUpFrame(
	lat: number,
	lon: number,
	height: number,
	az: number,
	el: number,
	roll: number,
	target: Matrix4
): Matrix4

Returns a Matrix4 representing the ENU frame at the given position, rotated by the given azimuth, elevation, and roll. Equivalent to getObjectFrame with ENU_FRAME.

.getObjectFrame

getObjectFrame(
	lat: number,
	lon: number,
	height: number,
	az: number,
	el: number,
	roll: number,
	target: Matrix4,
	frame = OBJECT_FRAME: Frames
): Matrix4

Returns a Matrix4 representing a frame at the given geographic position, rotated by the given azimuth, elevation, and roll, and adjusted to match the three.js frame convention. OBJECT_FRAME orients with "+Y" up and "+Z" forward; CAMERA_FRAME orients with "+Y" up and "-Z" forward; ENU_FRAME returns the raw ENU-relative rotation.

.getCartographicFromObjectFrame

getCartographicFromObjectFrame(
	matrix: Matrix4,
	target: Object,
	frame = OBJECT_FRAME: Frames
): Object

Extracts geographic position and orientation (lat, lon, height, azimuth, elevation, roll) from the given object/camera frame matrix. The inverse of getObjectFrame. Writes the result into target and returns it.

.getEastNorthUpAxes

getEastNorthUpAxes(
	lat: number,
	lon: number,
	vecEast: Vector3,
	vecNorth: Vector3,
	vecUp: Vector3,
	point: Vector3
): void

Fills in the east, north, and up unit vectors for the ENU frame at the given latitude and longitude. Optionally writes the surface position into point.

.getCartographicToPosition

getCartographicToPosition(
	lat: number,
	lon: number,
	height: number,
	target: Vector3
): Vector3

Converts geographic coordinates to a 3D Cartesian position on the ellipsoid surface (plus the given height offset). Writes the result into target and returns it.

.getPositionToCartographic

getPositionToCartographic( pos: Vector3, target: Object ): Object

Converts a 3D Cartesian position to geographic coordinates (lat, lon, height). Writes the result into target and returns it.

.getCartographicToNormal

getCartographicToNormal( lat: number, lon: number, target: Vector3 ): Vector3

Returns the surface normal of the ellipsoid at the given latitude and longitude. Writes the result into target and returns it.

.getPositionToNormal

getPositionToNormal( pos: Vector3, target: Vector3 ): Vector3

Returns the surface normal of the ellipsoid at the given 3D Cartesian position. Writes the result into target and returns it.

.getPositionToSurfacePoint

getPositionToSurfacePoint( pos: Vector3, target: Vector3 ): Vector3 | null

Projects the given 3D position onto the ellipsoid surface along the geodetic normal. Returns null if the position is at or near the center. Writes the result into target.

.calculateHorizonDistance

calculateHorizonDistance( latitude: number, elevation: number ): number

Returns the geometric distance to the horizon from the given latitude and elevation above the ellipsoid surface.

.calculateEffectiveRadius

calculateEffectiveRadius( latitude: number ): number

Returns the prime vertical radius of curvature (distance from the center of the ellipsoid to the surface along the normal) at the given latitude.

.getPositionElevation

getPositionElevation( pos: Vector3 ): number

Returns the height of the given 3D position above (or below) the ellipsoid surface.

.closestPointToRayEstimate

closestPointToRayEstimate( ray: Ray, target: Vector3 ): Vector3

Returns an estimate of the closest point on the ellipsoid surface to the given ray. Returns the exact surface intersection point if the ray intersects the ellipsoid.

.copy

copy( source: Ellipsoid ): this

Copies the radius from the given ellipsoid into this one.

.clone

clone(): Ellipsoid

Returns a new Ellipsoid with the same radius as this one.

EnvironmentControls

extends EventDispatcher

Camera controls for exploring a 3D environment. Supports drag-to-pan, scroll-to-zoom, right-click-to-rotate, and optional damping/inertia. Works with any Three.js scene.

.enabled

enabled: boolean

Whether the controls are active. When set to false, all input is ignored and inertia is cleared.

.cameraRadius

cameraRadius: number

Minimum camera distance above the surface in world units. Prevents clipping into terrain. Default is 5.

.rotationSpeed

rotationSpeed: number

Rotation sensitivity multiplier. Default is 1.

.minAltitude

minAltitude: number

Minimum camera angle above the horizon in radians. Default is 0.

.maxAltitude

maxAltitude: number

Maximum camera angle above the horizon in radians. Default is 0.45π.

.minDistance

minDistance: number

Minimum zoom distance in world units. Default is 10.

.maxDistance

maxDistance: number

Maximum zoom distance in world units. Default is Infinity.

.minZoom

minZoom: number

Minimum orthographic zoom level. Default is 0.

.maxZoom

maxZoom: number

Maximum orthographic zoom level. Default is Infinity.

.zoomSpeed

zoomSpeed: number

Zoom sensitivity multiplier. Default is 1.

.adjustHeight

adjustHeight: boolean

When true, the camera height is automatically adjusted to avoid clipping into the terrain. Default is true.

.enableDamping

enableDamping: boolean

When true, camera movements decelerate gradually after input ends. Default is false.

.dampingFactor

dampingFactor: number

Rate of inertia decay per frame when damping is enabled. Lower values produce longer coasting. Default is 0.15.

.fallbackPlane

fallbackPlane: Plane

Fallback plane used for drag/zoom when no scene geometry is hit. Default is the XZ plane (y=0).

.useFallbackPlane

useFallbackPlane: boolean

When true, the fallback plane is used when raycasting misses scene geometry. Default is true.

.constructor

constructor( scene = null: Object3D, camera = null: Camera, domElement = null: HTMLElement )

.setScene

setScene( scene: Object3D ): void

Sets the scene to raycast against for surface-based interaction.

.setCamera

setCamera( camera: Camera ): void

Sets the camera to control.

.attach

attach( domElement: HTMLElement ): void

Attaches the controls to a DOM element, registering all pointer and keyboard event listeners.

.detach

detach(): void

Detaches the controls from the DOM element, removing all event listeners.

.getUpDirection

getUpDirection( point: Vector3, target: Vector3 ): void

Returns the local up direction at a world-space point. Override to provide terrain-aware up vectors (e.g. ellipsoid normals). Default returns the controls' up vector.

.getCameraUpDirection

getCameraUpDirection( target: Vector3 ): void

Returns the local up direction at the camera's current position.

.getPivotPoint

getPivotPoint( target: Vector3 ): Vector3 | null

Returns the current drag or rotation pivot point in world space.

.resetState

resetState(): void

Clears the current interaction state, cancelling any active drag, rotate, or zoom.

.setState

setState( state: number, fireEvent = true: boolean ): void

Sets the current control state (e.g. NONE, DRAG, ROTATE, ZOOM).

.update

update( deltaTime: number ): void

Applies pending input and inertia to the camera. Must be called each frame.

.adjustCamera

adjustCamera( camera: Camera ): void

Adjusts the camera to satisfy altitude and distance constraints. Called automatically by update. Override in subclasses to add custom camera adjustment behaviour (e.g. near/far plane updates).

.dispose

dispose(): void

Disposes of event listeners and internal resources. Calls detach if currently attached.

GlobeControls

extends EnvironmentControls

Camera controls for navigating a globe-shaped tileset. Extends EnvironmentControls with ellipsoid-aware rotation, globe inertia, and automatic near/far plane adjustment.

.ellipsoidFrame

readonly ellipsoidFrame: Matrix4

The world matrix of ellipsoidGroup, representing the ellipsoid's coordinate frame.

.ellipsoidFrameInverse

readonly ellipsoidFrameInverse: Matrix4

The inverse of ellipsoidFrame.

.nearMargin

nearMargin: number

Fraction of the near plane distance added as a buffer. Default is 0.25.

.farMargin

farMargin: number

Fraction of the far plane distance added as a buffer. Default is 0.

.globeInertia

globeInertia: Quaternion

Accumulated globe rotation inertia quaternion. Applied each frame when globe inertia is active.

.globeInertiaFactor

globeInertiaFactor: number

Magnitude of the current globe rotation inertia. Decays to zero over time.

.ellipsoid

ellipsoid: Ellipsoid

The ellipsoid model used for surface interaction and up-direction calculation. Defaults to WGS84.

.ellipsoidGroup

ellipsoidGroup: Group

The Three.js group whose world matrix defines the ellipsoid's coordinate frame.

.constructor

constructor( scene = null: Object3D, camera = null: Camera, domElement = null: HTMLElement )

.setEllipsoid

setEllipsoid( ellipsoid: Ellipsoid, ellipsoidGroup: Group ): void

Sets the ellipsoid model and its scene group for globe-aware interaction.

.getVectorToCenter

getVectorToCenter( target: Vector3 ): Vector3

Returns the vector from the camera to the center of the ellipsoid in world space.

.getDistanceToCenter

getDistanceToCenter(): number

Returns the distance from the camera to the center of the ellipsoid.

I3DMLoader

extends I3DMLoaderBase

Loader for the legacy 3D Tiles Instanced 3D Model (i3dm) format. Parses the i3dm container and returns instanced meshes with batchTable and featureTable attached to the resolved scene object.

.constructor

constructor( manager: LoadingManager )

.parse

parse(
	buffer: ArrayBuffer
): Promise<{scene: Group, batchTable: BatchTable, featureTable: FeatureTable}>

Parses an i3dm buffer and resolves to a GLTF result object where the scene's meshes have been replaced with InstancedMesh objects (one per GLTF mesh), with metadata attached to both model and model.scene.

PNTSLoader

extends PNTSLoaderBase

Loader for the legacy 3D Tiles Point Cloud (pnts) format. Parses the pnts container and returns a three.js Points object with batchTable and featureTable attached to the resolved scene object.

.constructor

constructor( manager: LoadingManager )

.parse

parse(
	buffer: ArrayBuffer
): Promise<{scene: Points, batchTable: BatchTable, featureTable: FeatureTable}>

Parses a pnts buffer and resolves to a result object containing a constructed three.js Points scene with metadata attached.

TilesRenderer

extends TilesRendererBase

Three.js implementation of a 3D Tiles renderer. Extends TilesRendererBase with camera management, three.js scene integration, and GPU-accelerated tile loading. Add tiles.group to your scene and call tiles.update() each frame.

.autoDisableRendererCulling

autoDisableRendererCulling: boolean

If true, all tile meshes automatically have frustumCulled set to false since the tiles renderer performs its own frustum culling. If displayActiveTiles is true or multiple cameras are being used, consider setting this to false.

.group

group: Group

The container Group for the 3D tiles. Add this to the three.js scene. The group also exposes a matrixWorldInverse field for transforming objects into the local tileset frame.

.ellipsoid

ellipsoid: Ellipsoid

The ellipsoid definition used for the tileset. Defaults to WGS84 and may be overridden by the 3DTILES_ellipsoid extension. Specified in the local frame of TilesRenderer.group.

.cameras

cameras: Array<Camera>

Array of cameras registered with this renderer.

.manager

manager: LoadingManager

The LoadingManager used when loading tile geometry.

.getBoundingBox

getBoundingBox( target: Box3 ): boolean

Returns the axis-aligned bounding box of the root tile in the group's local space.

.getOrientedBoundingBox

getOrientedBoundingBox( targetBox: Box3, targetMatrix: Matrix4 ): boolean

Returns the oriented bounding box and transform of the root tile.

.getBoundingSphere

getBoundingSphere( target: Sphere ): boolean

Returns the bounding sphere of the root tile in the group's local space.

.forEachLoadedModel

forEachLoadedModel( callback: function ): void

Iterates over all currently loaded tile scenes.

.raycast

raycast( raycaster: Raycaster, intersects: Array ): void

Performs a raycast against all loaded tile scenes. Compatible with Three.js raycasting. Supports raycaster.firstHitOnly for early termination.

.hasCamera

hasCamera( camera: Camera ): boolean

Returns whether the given camera is registered with this renderer.

.setCamera

setCamera( camera: Camera ): boolean

Registers a camera with the renderer so it is used for tile selection and screen-space error calculation. Use setResolution or setResolutionFromRenderer to provide the camera's resolution.

.setResolution

setResolution( camera: Camera, xOrVec: number | Vector2, y: number ): boolean

Sets the render resolution for a registered camera, used for screen-space error calculation.

.setResolutionFromRenderer

setResolutionFromRenderer( camera: Camera, renderer: WebGLRenderer ): boolean

Sets the render resolution for a camera by reading the current size from a WebGLRenderer.

.deleteCamera

deleteCamera( camera: Camera ): boolean

Unregisters a camera from the renderer.

Frames

extends ENU_FRAME

Functions

decodeOctNormal

decodeOctNormal( x: number, y: number, target: Vector3 ): void

Decode an octahedron-encoded normal (as a pair of 8-bit unsigned numbers) into a Vector3.

Resources:

• https://stackoverflow.com/a/74745666/2704779
• https://knarkowicz.wordpress.com/2014/04/16/octahedron-normal-vector-encoding/