Documentation for plugins and extensions provided by the 3d-tiles-renderer/plugins export.
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 TileCompressionPlugin() );
tiles.registerPlugin( new TilesFadePlugin() );Plugin that adds support for 3d tiles implicit tiling feature.
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.
enabled = true : booleanIf true then the debug logic is enabled, which can affect performance. It's recommended to disable or remove the plugin when not in use.
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, useRecommendedSettings = true : Boolean } )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.
This plugin changes below values to be more efficient for the photorealistic tiles if useRecommendedSettings = true (default):
tiles.parseQueue.maxJobs = 10;
tiles.downloadQueue.maxJobs = 30;
tiles.errorTarget = 40;constructor( { apiToken : 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 ) : booleanPlugin that processes geometry buffer attributes into smaller data types on load and disables texture mipmaps to save memory. While geometry attribute compression is disabled by default, the default target attribute size when enabled 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: false,
compressUvs: false,
compressPosition: false,
// The TypedArray type to use when compressing attributes.
uvType: Int8Array,
normalType: Int8Array,
positionType: Int16Array,
}Plugin that overrides material shaders to fade tile geometry in and out as tile LODs change. Based on this Cesium article on the topic.
The plugin will dispatch fade-change, fade-start, and fade-end events per tile on the TilesRenderer when the animation updates. These events should be used in addition to any others required when performing on-demand rendering.
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.
Plugin for automatically adding common extensions and loaders for 3d tiles to the GLTFLoader used for parsing tile geometry. Additionally, a DRACOLoader is added, as well, to support loading compressed point cloud files.
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, KTX2Loader, and MeshoptDecoder instances to add to the loader.
dracoLoader: null,
ktxLoader: null,
meshoptDecoder: null,
// Whether to automatically dispose of the DRACO and KTX Loaders when the plugin is disposed.
autoDispose: true,
}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.
Plugin that unloads geometry, textures, and materials of any given tile when the visibility changes to non-visible to save GPU memory. The model still exists on the CPU until it is completely removed from the cache.
estimatedGPUBytes : numberThe number of bytes that are actually uploaded to the GPU for rendering compared to lruCache.cachedBytes which reports the amount of texture and geometry buffer bytes actually downloaded.
constructor( options : Object )Available options are as follows:
{
// The amount of time to wait in milliseconds before unloading tile content from the GPU. This option can be
// used to account for cases where the user is moving the camera and tiles are coming in and out of frame.
delay: 0,
// The amount of bytes to unload to.
bytesTarget: 0,
}available in the examples directory
Plugin that uses three.js' BatchedMesh to limit the number of draw calls required and improve performance. The BatchedMesh geometry and instance size are automatically resized and optimized as new geometry is added and removed. The max number of instances to generate is limited by the max size of a 3d texture.
Warning
All tile geometry rendered with BatchedMesh will use the same material and only a single material "map" is supported. Only tiles geometry containing a single mesh are supported. Not compatible with other plugins that modify mesh materials or rely on other bespoke mesh data (eg TilesFadePlugin, DebugTilesPlugin, GLTF Metadata extensions).
constructor( options : Object )Available options are as follows:
{
// WebGLRenderer used for generating a WebGLArrayRenderTarget
renderer,
// The initial number of instances to use for rendering
instanceCount: 500,
// The minimum amount of vertex and index space to save per tile geometry added. If adequate tile space is already allocated
// when a new tile geometry is added then it can prevent more expensive geometry resizing and optimization.
vertexCount: 1000,
indexCount: 1000,
// The amount to increase the geometry and instance allocation when the operations must occur
expandPercent: 0.25,
// The material to use for the BatchedMesh. The material of the first tile rendered with be used if not set.
material: null,
// If true then the original scene geometry is automatically discarded after adding the geometry to the batched mesh to save memory.
// This must be set to "false" if being used with plugins such as "UnloadTilesPlugin".
discardOriginalContent: true
}