Documentation for plugins and extensions provided by the project and in the examples folder.
Set of three.js GLTFLoader plugins to be registered via GLTFLoader.register. To use with the TilesRenderer:
const tiles = new TilesRenderer( url );
const loader = new GLTFLoader( tiles.manager );
loader.register( () => new GLTFMeshFeaturesExtension() );
loader.register( () => new GLTFStructuralMetadataExtension() );
loader.register( () => new GLTFCesiumRTCExtension() );
tiles.manager.addHandler( /(gltf|glb)$/g, loader );Plugin that adds support for the EXT_mesh_features extension.
Adds a Object3D.userData.meshFeatures to each object with the extension that provides the following API:
getTextures() : Array<Texture>Returns an indexed list of all textures used by features in the extension.
getFeatureInfo() : {
label: string | null,
propertyTable: string | null,
nullFeatureId: number | null,
texture?: {
texCoord: number,
channels: Array<number>,
}
}Returns the feature information information associated with all features on the object.
getFeatures( triangle : number, barycoord : Vector3 ) : Array<number>Takes the triangle index from something like a raycast hit as well as the calculated barycentric coordinate and returns the list of feature ids extracted from the object at the given point. Indexed in the same order as the list of feature info in the extension.
const barycoord = new Vector3();
const triangle = new Triangle();
const hit = raycaster.raycast( object );
if ( hit ) {
const { face, point, faceIndex } = hit;
triangle.setFromAttributeAndIndices( object.geometry.attributes.position, face.a, face.b, face.c );
triangle.a.applyMatrix4( object.matrixWorld );
triangle.b.applyMatrix4( object.matrixWorld );
triangle.c.applyMatrix4( object.matrixWorld );
triangle.getBarycoord( point, barycoord );
const features = meshFeatures.getFeatures( faceIndex, barycoord );
// ...
}getFeaturesAsync( triangle : number, barycoord : Vector3 ) : Promise<Array<number>>Performs the same function as getFeatures but with the texture asynchronous texture read operation.
Plugin that adds support for the EXT_structural_metadata extension. Adds a Object3D.userData.structuralMetadata to each object with the extension that provides the following API.
Note that 64 bit integer types are not fully supported.
textures: Array<Texture>Returns an indexed list of all textures used by metadata accessors in the extension.
schema: ObjectThe extension schema object.
getPropertyTableData(
tableIndices : Array<number>,
ids : Array<number>,
target = [] : Array,
) : targetReturns data stored in property tables. Takes a list of table ids and ids from those tables, and returns a list of objects adhering to the structure class referenced in the table schema.
getPropertyTableInfo( tableIndices = null : Array<number> ) : Array<{
name: string,
className: string,
}>Returns information about the tables.
getPropertyTextureData(
triangle : number,
barycoord : Vector3,
target = [] : Array,
) : targetReturns data stored in property textures. Takes a triangle index and barycentric coordinate, and returns a list of objects adhering to the structure class referenced in the table schema. See MeshFeatures.getFeatures for how to calculate the index and barycoord.
getPropertyTextureDataAsync(
triangle : number,
barycoord : Vector3,
target = [] : Array,
) : Promise<target>Returns the same data from getPropertyTextureData but performs texture read operations asynchronously.
getPropertyTextureInfo() : Array<{
name: string,
className: string,
properties: {
[name]: {
channels: Array<number>,
index: number | null,
texCoord: number | null,
},
},
}>Returns information about the property texture accessors from the extension.
getPropertyAttributeData( attributeIndex : number, target = [] : Array) : targetReturns data stored as property attributes. Takes the index of an index from length of the attributes, and returns a list of objects adhering to the structure class referenced in the table schema.
getPropertyAttributeInfo() : Array<{
name: string,
className: string,
}>Returns information about the attribute accessors from the extension.
Plugin that adds support for CESIUM_RTC extension.
Plugins to register to the TilesRenderer instance to modify behavior.
const tiles = new TilesRenderer( url );
tiles.registerPlugin( new TilesCompressionPlugin() );
tiles.registerPlugin( new TilesFadePlugin() );Plugin TilesRenderer that includes helpers for debugging and visualizing the various tiles in the tile set. Material overrides will not work as expected with this plugin. The plugin includes additional logic and initialization code which can cause performance loss so it's recommended to only use this when needed.
colorMode = NONE : ColorModeWhich color mode to use when rendering the tile set. The following exported enumerations can be used:
// No special color mode. Uses the default materials.
NONE
// Render the screenspace error from black to white with errorTarget
// being the maximum value.
SCREEN_ERROR
// Render the geometric error from black to white with maxDebugError
// being the maximum value.
GEOMETRIC_ERROR
// Render the distance from the camera to the tile as black to white
// with maxDebugDistance being the maximum value.
DISTANCE
// Render the depth of the tile relative to the root as black to white
// with maxDebugDepth being the maximum value.
DEPTH
// Render the depth of the tile relative to the nearest rendered parent
// as black to white with maxDebugDepth being the maximum value.
RELATIVE_DEPTH
// Render leaf nodes as white and parent nodes as black.
IS_LEAF
// Render the tiles with a random color to show tile edges clearly.
RANDOM_COLOR
// Render every individual mesh in the scene with a random color.
RANDOM_NODE_COLOR
// Sets a custom color using the customColorCallback call back.
CUSTOM_COLORcustomColorCallback: (tile: Tile, child: Object3D) => voidThe callback used if debugColor is set to CUSTOM_COLOR. Value defaults to null and must be set explicitly.
displayBoxBounds = false : BooleanDisplay wireframe bounding boxes from the tiles boundingVolume.box (or derived from the region bounds) for every visible tile.
displaySphereBounds = false : BooleanDisplay wireframe bounding boxes from the tiles boundingVolume.sphere (or derived from the bounding box / region bounds) for every visible tile.
displayRegionBounds = false : BooleanDisplay wireframe bounding rgions from the tiles boundingVolume.region for every visible tile if it exists.
maxDebugDepth = - 1 : NumberThe depth value that represents white when rendering with DEPTH or RELATIVE_DEPTH colorMode. If maxDebugDepth is -1 then the maximum depth of the tile set is used.
maxDebugError = - 1 : NumberThe error value that represents white when rendering with GEOMETRIC_ERROR colorMode. If maxDebugError is -1 then the maximum geometric error in the tile set is used.
maxDebugDistance = - 1 : NumberThe distance value that represents white when rendering with DISTANCE colorMode. If maxDebugDistance is -1 then the radius of the tile set is used.
constructor( options = {} )Takes a set of options to initialize to.
getDebugColor : ( val : Number, target : Color ) => voidThe function used to map a [0, 1] value to a color for debug visualizations. By default the color is mapped from black to white.
constructor( { accessToken : String, autoRefreshToken = false : Boolean, logoUrl = null : String | null } )Takes the Google Cloud access token. If autoRefreshToken is set to true then the plugin will automatically perform a new root tile request once the existing token has expired after four hours. The url in "logoUrl" will be used to create an image attribution required for use with Google Photorealistic Tiles.
constructor( { accessToken : String, assetId = null : String | null, autoRefreshToken = false : Boolean } )Takes the CesiumIon access token and optionally the asset id. If the asset id is not provided then the Cesium Ion URL is expected to have been passed into the TilesRenderer constructor. If autoRefreshToken is set to true then the plugin will automatically perform a new root tile request once the existing token has expired after an hour.
available in the examples directory
Plugin for loading alternate texture sets and assigning them to geometry in the tile set.
textureUpdateCallback : ( tile, model, plugin ) => void;
Callback fired when the textures for a specific tile has been loaded. This function is required.
waitForLoadCompletion : BooleanIf true then the update callback will only fire for tiles once all the associated textures have loaded.
constructor( options = {
textureUpdateCallback: null,
waitForLoadCompletion: true,
} );
getTexturesForTile( tile : Tile, target = {} : Object ) : targetregisterLayer( name : string, customTextureCallback : Function ) : voidunregisterLayer( name : string ) : voidhasLayer( name : string ) : booleanavailable in the examples directory
Plugin that processes geometry buffer attributes into smaller data types on load and disables texture mipmaps to save memory. The default compression is fairly aggressive and may cause artifacts. Can reduce geometry memory footprint by more than half and texture memory by around a third.
constructor( options : Object )Available options are as follows:
{
// Whether to generate normals if they don't already exist.
generateNormals: false,
// Whether to disable use of mipmaps on all textures since they are typically
// not necessary.
disableMipmaps: true,
// Whether to compress and quantize attributes.
compressIndex: true,
compressNormals: true,
compressUvs: true,
compressPosition: false,
// The TypedArray type to use when compressing attributes.
uvType: Int8Array,
normalType: Int8Array,
positionType: Int16Array,
}available in the examples directory
Plugin that overrides material shaders to fade tile geometry in and out as tile LODs change. Based on this Cesium article on the topic.
fadeDuration = 250 : numberAmount of time a tile takes to fade in and out.
maximumFadeOutTiles = 50 : numberMaximum number of tiles to be fading at once. If this quantity is exceeded the animation ends and tiles pop in.
fadeRootTiles = false : booleanWhether to fade the root tile objects in.
available in the examples directory
Plugin for automatically adding common extensions and loaders for 3d tiles to the GLTFLoader used for parsing tile geometry.
constructor( options : Object )Available options are as follows:
{
// If true then the StructuralMetadata and MeshFeatures extensions are included.
metadata: true,
// If true then the Cesium RTC Center extension is included.
rtc: true,
// A list of other extensions to include in the loader. All elements are passed to the "GLTFLoader.register" function.
plugins: [],
// DRACOLoader and KTX2Loader instances to add to the loader.
dracoLoader: null,
ktxLoader: null,
// Whether to automatically dispose of the DRACO and KTX Loaders when the plugin is disposed.
autoDispose: true,
}available in the examples directory
Plugin for automatically re-orienting and re-centering the tile set to make it visible near the origin and facing the right direction.
constructor( options : Object )Available options are as follows:
{
// The latitude, longitude, and height of the point on the surface to orient to. Lat and lon are in radians. If
// no coordinates are provided then the plugin tries to determine if the tile set is a tile set on the globe surface
// and estimates the coordinates.
lat: null,
lon: null,
height: 0,
// If a set of lat and lon coordinates cannot be determined then the tile set is simple oriented so the provided axes
// is oriented to three.js' +Y up direction. Valid values are positive or negative x, y, or z.
up: '+z',
// Whether or not to recenter the tile set.
recenter: true,
}transformLatLonHeightToOrigin( lat, lon, height = 0 ) : voidTransforms the centers the tile set such that the given coordinates and height are positioned at the origin with "X" facing west and "Z" facing north.
enabled = true : booleanWhether the controls are enabled and active.
enableDamping = false : booleanFlag indicating whether residual inertial animation is played after interaction finishes.
constructor(
scene = null : Scene,
camera = null : Camera,
domElement = null : DomElement,
)Takes the scene to raycast against for click events, the camera being animated, and the dom element to listen for clicks on.
attach( domElement : DomElement ) : voidThe dom element to attach to for events.
detach() : voidDetaches from the current dom element.
setCamera( camera : Camera ) : voidSets the camera the controls are using.
setScene( scene : Object3D ) : voidThe scene to raycast against for control interactions.
update( deltaTime = null ) : voidUpdates the controls. Takes a delta time value in seconds to normalize inertia and damping speeds. Defaults to the time between call to the function.
dispose() : voidDetaches all events and makes the controls unusable.
getPivotPoint( target : Vector3 ) : targetGets the last used interaction point.
extends EnvironmentControls
constructor(
scene = null : Scene,
camera = null : Camera,
domElement = null : DomElement,
tilesRenderer = null : GoogleTilesRenderer,
)Takes the same items as EnvironmentControls in addition to the Google globe tiles renderer.
updateCameraClipPlanes( camera : Camera ) : voidUpdates the clip planes (and position if orthographic) of the given camera so the globe is encapsulated correctly. Used when working with the transition manager to make sure both cameras being transitioned are positioned properly.
Helper class for performing a transition animation between a perspective and orthographic camera.
const transition = new CameraTransitionManager( perspCamera, orthoCamera );
toggleButton.addEventListener( 'click', () => transition.toggle() );
// ...
renderer.setAnimationLoop( () => {
// set transition.fixedPoint to point that should remain stable
transition.update();
renderer.render( transition.camera, scene );
} );fixedPoint = ( 0, 0, 0 ) : Vector3The point that will represents the plan that will remain fixed during the animation. This point should be in front of the cameras.
readonly animation : booleanA flag indicating whether the transition is currently animating or not.
readonly camera : CameraThe current camera to render with. Switches between the perspective camera, orthographic camera, and animated transition camera.
orthographicPositionalZoom = true : booleanWhether the orthographic camera position should be updated so be synchronized with the necessary perspective camera position so the orthographic near clip planes do not get into into unexpected configurations.
constructor( perspectiveCamera : PerspectiveCamera, orthographicCamera : OrthographicCamera )Constructor takes the two cameras to animate between.
update() : voidSynchronizes the two camera positions and performs the transition animation if active.
toggle() : voidStarts the transition animation.