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.
import { TilesRenderer, EnvironmentControls } from '3d-tiles-renderer/three';
// scene, camera and renderer are initialized here
const URL = 'https://raw.githubusercontent.com/NASA-AMMOS/3DTilesSampleData/master/msl-dingo-gap/0528_0260184_to_s64o256_colorize/0528_0260184_to_s64o256_colorize/0528_0260184_to_s64o256_colorize_tileset.json';
const tiles = new TilesRenderer( URL );
tiles.setCamera( camera );
tiles.group.rotation.x = Math.PI / 2;
scene.add( tiles.group );
camera.position.set( 20, 10, 20 );
camera.lookAt( 0, 0, 0 );
const controls = new EnvironmentControls( scene, camera, renderer.domElement );
controls.enableDamping = true;
renderer.setAnimationLoop( () => {
controls.update();
camera.updateMatrixWorld();
tiles.setResolutionFromRenderer( camera, renderer );
tiles.update();
renderer.render( scene, camera );
} );On this page
- Properties
- enabled
- cameraRadius
- rotationSpeed
- minAltitude
- maxAltitude
- minDistance
- maxDistance
- minZoom
- maxZoom
- zoomSpeed
- adjustHeight
- enableDamping
- dampingFactor
- enableDoubleTapZoom
- doubleTapZoomScale
- doubleTapZoomDuration
- fallbackPlane
- useFallbackPlane
- enableFlight
- flightSpeed
- flightSpeedMultiplier
- Methods
- constructor
- setScene
- setCamera
- attach
- detach
- getUpDirection
- getCameraUpDirection
- getPivotPoint
- resetState
- setState
- update
- adjustCamera
- dispose
Properties
enabled: boolean = true
Whether the controls are active. When set to false, all input is ignored and inertia is cleared.
cameraRadius: number = 5
Minimum camera distance above the surface in world units. Prevents clipping into terrain.
rotationSpeed: number = 1
Rotation sensitivity multiplier.
minAltitude: number = 0
Minimum camera angle above the horizon in radians.
maxAltitude: number = 0.45 * Math.PI
Maximum camera angle above the horizon in radians.
minDistance: number = 10
Minimum zoom distance in world units.
maxDistance: number = Infinity
Maximum zoom distance in world units.
minZoom: number = 0
Minimum orthographic zoom level.
maxZoom: number = Infinity
Maximum orthographic zoom level.
zoomSpeed: number = 1
Zoom sensitivity multiplier.
adjustHeight: boolean = true
When true, the camera height is automatically adjusted to avoid clipping into the terrain.
enableDamping: boolean = false
When true, camera movements decelerate gradually after input ends.
dampingFactor: number = 0.15
Rate of inertia decay per frame when damping is enabled. Lower values produce longer coasting.
enableDoubleTapZoom: boolean = true
When true, double clicking or double tapping a point animates a zoom toward it.
doubleTapZoomScale: number = 2
Factor to zoom in toward the clicked point on a double tap.
doubleTapZoomDuration: number = 0.5
Duration of the double tap zoom animation in seconds.
fallbackPlane: Plane = new Plane( UP, 0 )
Fallback plane used for drag/zoom when no scene geometry is hit.
useFallbackPlane: boolean = true
When true, the fallback plane is used when raycasting misses scene geometry.
enableFlight: boolean = false
When true, enables keyboard flight: W/A/S/D and arrow keys move forward/back/strafe, Q/E move
up/down, and Shift multiplies speed by flightSpeedMultiplier. Right-click or Shift+left-click
enters free-look mode, rotating the camera in place without requiring a surface hit. Only
supported for perspective cameras.
flightSpeed: number = 10
Base camera speed in world units per second during keyboard flight.
flightSpeedMultiplier: number = 4
Speed multiplier applied when the fast key is held during flight.
Methods
new EnvironmentControls(
// The scene to raycast against for surface interaction.
scene: Object3D = null,
// The camera to control.
camera: Camera = null,
// The DOM element to attach pointer events to.
domElement: HTMLElement = null
)setScene( scene: Object3D ): voidSets the scene to raycast against for surface-based interaction.
setCamera( camera: Camera ): voidSets the camera to control.
attach( domElement: HTMLElement ): voidAttaches the controls to a DOM element, registering all pointer and keyboard event listeners.
detach(): voidDetaches the controls from the DOM element, removing all event listeners.
getUpDirection(
// World-space point to query.
point: Vector3,
// Target vector to write the result into.
target: Vector3
): voidReturns 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(
// Target vector to write the result into.
target: Vector3
): voidReturns the local up direction at the camera's current position.
getPivotPoint(
// Target vector to write the result into.
target: Vector3
): Vector3 | nullReturns the current drag or rotation pivot point in world space.
resetState(): voidClears the current interaction state, cancelling any active drag, rotate, or zoom.
setState(
// One of the exported state constants. Defaults to current state.
state?: number,
// Whether to dispatch `'start'` and `'end'` events.
fireEvent: boolean = true
): voidSets the current control state (e.g. NONE, DRAG, ROTATE, ZOOM).
update(
// Time in seconds since the last frame. Defaults to the clock delta, capped at 64ms.
deltaTime?: number
): voidApplies pending input and inertia to the camera. Must be called each frame.
adjustCamera( camera: Camera ): voidAdjusts 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(): voidDisposes of event listeners and internal resources. Calls detach if currently attached.