3d-tiles-renderer
Version:
https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/master/specification
1,108 lines (661 loc) • 21.3 kB
Markdown
<!-- This file is generated automatically. Do not edit it directly. -->
# 3d-tiles-renderer/three
## Constants
### ENU_FRAME
```js
ENU_FRAME
```
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
```js
CAMERA_FRAME
```
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
```js
OBJECT_FRAME
```
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`](../../core/renderer/API.md#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
```js
constructor( manager: LoadingManager )
```
### .parse
```js
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
```js
readonly animating: boolean
```
Whether a transition animation is currently in progress.
### .alpha
```js
readonly alpha: number
```
Transition progress from 0 (at perspective) to 1 (at orthographic).
### .camera
```js
readonly camera: Camera
```
The currently active camera. Returns `perspectiveCamera`, `orthographicCamera`, or the
blended `transitionCamera` depending on the current transition state.
### .mode
```js
mode: string
```
The target camera mode. Set to `'perspective'` or `'orthographic'` to jump instantly without
animation. Use `toggle()` to animate the transition.
### .orthographicPositionalZoom
```js
orthographicPositionalZoom: boolean = true
```
When true, the orthographic camera position is offset backwards along the view direction so it does not clip into terrain.
### .orthographicOffset
```js
orthographicOffset: number = 50
```
Distance the orthographic camera is pushed back when `orthographicPositionalZoom` is true.
### .fixedPoint
```js
fixedPoint: Vector3 = new Vector3()
```
World-space point that remains visually fixed during the transition.
### .duration
```js
duration: number = 200
```
Duration of the animated transition in milliseconds.
### .autoSync
```js
autoSync: boolean = true
```
When true, cameras are synced automatically before each `update` call.
### .easeFunction
```js
easeFunction: function = x => x
```
Easing function applied to the raw transition alpha. Receives and returns a value in [0, 1].
### .constructor
```js
constructor( perspectiveCamera: PerspectiveCamera, orthographicCamera: OrthographicCamera )
```
### .toggle
```js
toggle(): void
```
Begins an animated transition to the opposite camera mode. Dispatches a `'toggle'` event.
### .update
```js
update( deltaTime: number ): void
```
Advances the transition animation and updates the active camera. Must be called each frame.
### .syncCameras
```js
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`](../../core/renderer/API.md#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
```js
constructor( manager: LoadingManager )
```
### .parse
```js
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](WGS84_ELLIPSOID)). All geographic coordinates use
latitude and longitude in radians.
### .name
```js
name: string
```
Optional name for this ellipsoid instance.
### .radius
```js
radius: Vector3
```
Semi-axis radii of the ellipsoid.
### .constructor
```js
constructor( x = 1: number, y = 1: number, z = 1: number )
```
### .intersectRay
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
calculateHorizonDistance( latitude: number, elevation: number ): number
```
Returns the geometric distance to the horizon from the given latitude and elevation above
the ellipsoid surface.
### .calculateEffectiveRadius
```js
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
```js
getPositionElevation( pos: Vector3 ): number
```
Returns the height of the given 3D position above (or below) the ellipsoid surface.
### .closestPointToRayEstimate
```js
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
```js
copy( source: Ellipsoid ): this
```
Copies the radius from the given ellipsoid into this one.
### .clone
```js
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
```js
enabled: boolean = true
```
Whether the controls are active. When set to false, all input is ignored
and inertia is cleared.
### .cameraRadius
```js
cameraRadius: number = 5
```
Minimum camera distance above the surface in world units. Prevents clipping into terrain.
### .rotationSpeed
```js
rotationSpeed: number = 1
```
Rotation sensitivity multiplier.
### .minAltitude
```js
minAltitude: number = 0
```
Minimum camera angle above the horizon in radians.
### .maxAltitude
```js
maxAltitude: number = 0.45 * Math.PI
```
Maximum camera angle above the horizon in radians.
### .minDistance
```js
minDistance: number = 10
```
Minimum zoom distance in world units.
### .maxDistance
```js
maxDistance: number = Infinity
```
Maximum zoom distance in world units.
### .minZoom
```js
minZoom: number = 0
```
Minimum orthographic zoom level.
### .maxZoom
```js
maxZoom: number = Infinity
```
Maximum orthographic zoom level.
### .zoomSpeed
```js
zoomSpeed: number = 1
```
Zoom sensitivity multiplier.
### .adjustHeight
```js
adjustHeight: boolean = true
```
When true, the camera height is automatically adjusted to avoid clipping into the terrain.
### .enableDamping
```js
enableDamping: boolean = false
```
When true, camera movements decelerate gradually after input ends.
### .dampingFactor
```js
dampingFactor: number = 0.15
```
Rate of inertia decay per frame when damping is enabled. Lower values produce longer coasting.
### .fallbackPlane
```js
fallbackPlane: Plane = new Plane( UP, 0 )
```
Fallback plane used for drag/zoom when no scene geometry is hit.
### .useFallbackPlane
```js
useFallbackPlane: boolean = true
```
When true, the fallback plane is used when raycasting misses scene geometry.
### .enableFlight
```js
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
```js
flightSpeed: number = 10
```
Base camera speed in world units per second during keyboard flight.
### .flightSpeedMultiplier
```js
flightSpeedMultiplier: number = 4
```
Speed multiplier applied when the fast key is held during flight.
### .constructor
```js
constructor( scene = null: Object3D, camera = null: Camera, domElement = null: HTMLElement )
```
### .setScene
```js
setScene( scene: Object3D ): void
```
Sets the scene to raycast against for surface-based interaction.
### .setCamera
```js
setCamera( camera: Camera ): void
```
Sets the camera to control.
### .attach
```js
attach( domElement: HTMLElement ): void
```
Attaches the controls to a DOM element, registering all pointer and keyboard event listeners.
### .detach
```js
detach(): void
```
Detaches the controls from the DOM element, removing all event listeners.
### .getUpDirection
```js
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
```js
getCameraUpDirection( target: Vector3 ): void
```
Returns the local up direction at the camera's current position.
### .getPivotPoint
```js
getPivotPoint( target: Vector3 ): Vector3 | null
```
Returns the current drag or rotation pivot point in world space.
### .resetState
```js
resetState(): void
```
Clears the current interaction state, cancelling any active drag, rotate, or zoom.
### .setState
```js
setState( state: number, fireEvent = true: boolean ): void
```
Sets the current control state (e.g. `NONE`, `DRAG`, `ROTATE`, `ZOOM`).
### .update
```js
update( deltaTime: number ): void
```
Applies pending input and inertia to the camera. Must be called each frame.
### .adjustCamera
```js
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
```js
dispose(): void
```
Disposes of event listeners and internal resources. Calls `detach` if currently attached.
## GlobeControls
_extends [`EnvironmentControls`](../../r3f/API.md#environmentcontrols)_
Camera controls for navigating a globe-shaped tileset. Extends EnvironmentControls with
ellipsoid-aware rotation, globe inertia, and automatic near/far plane adjustment.
### .ellipsoidFrame
```js
readonly ellipsoidFrame: Matrix4
```
The world matrix of `ellipsoidGroup`, representing the ellipsoid's coordinate frame.
### .ellipsoidFrameInverse
```js
readonly ellipsoidFrameInverse: Matrix4
```
The inverse of `ellipsoidFrame`.
### .nearMargin
```js
nearMargin: number = 0.25
```
Fraction of the near plane distance added as a buffer.
### .farMargin
```js
farMargin: number = 0
```
Fraction of the far plane distance added as a buffer.
### .globeInertia
```js
globeInertia: Quaternion = new Quaternion()
```
Accumulated globe rotation inertia quaternion. Applied each frame when globe inertia is active.
### .globeInertiaFactor
```js
globeInertiaFactor: number = 0
```
Magnitude of the current globe rotation inertia. Decays to zero over time.
### .ellipsoid
```js
ellipsoid: Ellipsoid = WGS84_ELLIPSOID
```
The ellipsoid model used for surface interaction and up-direction calculation.
### .ellipsoidGroup
```js
ellipsoidGroup: Group = new Group()
```
The Three.js group whose world matrix defines the ellipsoid's coordinate frame.
### .constructor
```js
constructor( scene = null: Object3D, camera = null: Camera, domElement = null: HTMLElement )
```
### .setEllipsoid
```js
setEllipsoid( ellipsoid: Ellipsoid, ellipsoidGroup: Group ): void
```
Sets the ellipsoid model and its scene group for globe-aware interaction.
### .getVectorToCenter
```js
getVectorToCenter( target: Vector3 ): Vector3
```
Returns the vector from the camera to the center of the ellipsoid in world space.
### .getDistanceToCenter
```js
getDistanceToCenter(): number
```
Returns the distance from the camera to the center of the ellipsoid.
## I3DMLoader
_extends [`I3DMLoaderBase`](../../core/renderer/API.md#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
```js
constructor( manager: LoadingManager )
```
### .parse
```js
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`](../../core/renderer/API.md#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
```js
constructor( manager: LoadingManager )
```
### .parse
```js
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`](../../core/renderer/API.md#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
```js
autoDisableRendererCulling: boolean = true
```
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`.
### .accelerateRaycast
```js
accelerateRaycast: boolean = true
```
Whether to use the bounding-volume hierarchy to accelerate raycasting. When disabled,
all active tile geometry is tested directly. Useful for tilesets with inaccurate
bounding volumes (e.g. Google Photorealistic Tiles) where traversal may miss
geometry between bounding volumes.
### .group
```js
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
```js
ellipsoid: Ellipsoid = WGS84_ELLIPSOID
```
The ellipsoid definition used for the tileset. May be overridden by the
`3DTILES_ellipsoid` extension. Specified in the local frame of `TilesRenderer.group`.
### .cameras
```js
cameras: Array<Camera>
```
Array of cameras registered with this renderer.
### .manager
```js
manager: LoadingManager = new LoadingManager()
```
The `LoadingManager` used when loading tile geometry.
### .getBoundingBox
```js
getBoundingBox( target: Box3 ): boolean
```
Returns the axis-aligned bounding box of the root tile in the group's local space.
### .getOrientedBoundingBox
```js
getOrientedBoundingBox( targetBox: Box3, targetMatrix: Matrix4 ): boolean
```
Returns the oriented bounding box and transform of the root tile.
### .getBoundingSphere
```js
getBoundingSphere( target: Sphere ): boolean
```
Returns the bounding sphere of the root tile in the group's local space.
### .forEachLoadedModel
```js
forEachLoadedModel( callback: function ): void
```
Iterates over all currently loaded tile scenes.
### .raycast
```js
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
```js
hasCamera( camera: Camera ): boolean
```
Returns whether the given camera is registered with this renderer.
### .setCamera
```js
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
```js
setResolution( camera: Camera, xOrVec: number | Vector2, y: number ): boolean
```
Sets the render resolution for a registered camera, used for screen-space error calculation.
### .getResolution
```js
getResolution( camera: Camera, target: Vector2 ): Vector2 | null
```
Returns the render resolution previously set for a registered camera.
### .setResolutionFromRenderer
```js
setResolutionFromRenderer( camera: Camera, renderer: WebGLRenderer ): boolean
```
Sets the render resolution for a camera by reading the current size from a WebGLRenderer.
### .deleteCamera
```js
deleteCamera( camera: Camera ): boolean
```
Unregisters a camera from the renderer.
## Frames
_extends `ENU_FRAME`_
## Functions
### decodeOctNormal
```js
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/