3DTilesRendererJS

3d-tiles-renderer-js

IN PROGRESS

In progress three.js implementation of the 3D Tiles format.

The renderer supports a limited subset of the spec for the moment. See Issue #15 for information on which features are not yet implemented.

See it in action here!

In Progress Features

• Performance
• Bug Triage
• Tileset / Browser validation

Use

Basic TilesRenderer

import { TilesRenderer } from '3d-tiles-renderer';

// ... initialize three scene ...

const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );
tilesRenderer.setCamera( camera );
tilesRenderer.setResolutionFromRenderer( camera, renderer );
scene.add( tilesRenderer.group );

renderLoop();

function renderLoop() {

	requestAnimationFrame( renderLoop );

	// The camera matrix is expected to be up to date
	// before calling tilesRenderer.update
	camera.updateMatrixWorld();
	tilesRenderer.update();
	renderer.render( camera, scene );

}

Custom Material

const tilesRenderer = new TilesRenderer( './path/to/tileset.json' );
tilesRenderer.setCamera( camera );
tilesRenderer.setResolutionFromRenderer( camera, renderer );
tilesRenderer.onLoadModel = function ( scene ) {

	scene.traverse( c => {

		if ( c.material ) {

			c.originalMaterial = material;
			c.material = new MeshBasicMaterial();

		}

	} );

}
scene.add( tilesRenderer.group );

API

TilesRenderer

extends TilesRendererBase, which can be used to implement a 3d tiles renderer in other engines

.errorTarget

errorTarget = 6 : Number

The target screenspace error in pixels to target when updating the geometry. Tiles will not render if they have below this level of screenspace error.

.errorThreshold

errorThreshold = Infinity : Number

Value used to compute the threshold errorTarget * errorThreshold above which tiles will not render. This is used to enable traversal to skip loading and rendering parent tiles far from the cameras current screenspace error requirement.

If errorThreshold is set to Infinity then all parent tiles will be loaded and rendered. If it's set to 0 then no parent tiles will render and only the tiles that are being rendered will be loaded.

.maxDepth

maxDepth = Infinity : Number

The max depth to which tiles will be loaded and rendered.

.loadSiblings

loadSiblings = true : Boolean

If true then all sibling tiles will be loaded, as well, to ensure coherence when moving the camera. If false then only currently viewed tiles will be loaded.

.lruCache

lruCache = new LRUCache() : LRUCache

NOTE: This cannot be set once update is called for the first time.

.downloadQueue

downloadQueue = new PriorityQueue : PriorityQueue

NOTE: This cannot be set once update is called for the first time.

.parseQueue

parseQueue = new PriorityQueue : PriorityQueue

NOTE: This cannot be modified once update is called for the first time.

.group

group : Group

The container group for the 3d tiles. Add this to the three.js scene in order to render it.

When raycasting a higher performance traversal approach is used if raycaster.firstHitOnly = true. If true then only the first hit of the terrain is reported in the tileset.

.constructor

constructor( url : String )

Takes the url of the tileset.json for the tileset to be rendered.

.update

update() : void

Updates the tiles to render and kicks off loads for the appropriate tiles in the 3d tile set.

Both group.matrixWorld and all cameras world matrices are expected to be to date before this is called.

.getBounds

getBounds( box : Box3 ) : boolean

Sets box to the root bounding box of the tileset in the group frame. Returns false if the tile root was not loaded.

.hasCamera

hasCamera( camera : Camera ) : boolean

Returns true if the camera has already been set on the renderer.

.setCamera

setCamera( camera : Camera ) : boolean

Adds the camera to the camera to be accounted for when traversing the tileset. Returns false if the camera is already being tracked. Returns true otherwise.

.deleteCamera

deleteCamera( camera : Camera ) : boolean

Removes the given camera from being accounted for when traversing the tileset. Returns false if the camera was not tracked.

.setResolution

setResolution( camera : Camera, resolution : Vector2 ) : boolean
setResolution( camera : Camera, x : number, y : number ) : boolean

Sets the resolution being rendered to for the given camera. Returns false if the camera is not being tracked.

.setResolutionFromRenderer

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

Sets the resolution being rendered to for the given camera via renderer which accounts for canvas size and current pixel ratio. Returns false if the camera is not being tracked.

.forEachLoadedModel

forEachLoadedModel( callback : ( scene : Object3D, tile : object ) => void ) : void

Fires the callback for every loaded scene in the hierarchy with the associatd tile as the second argument. This can be used to update the materials of all loaded meshes in the tile set.

.onLoadModel

onLoadModel = null : ( scene : Object3D, tile : objec ) => void

Callback that is called every time a model is loaded. This can be used in conjunction with .forEachLoadedModel to set the material of all load and still yet to load meshes in the tile set.

DebugTilesRenderer

extends TilesRenderer

Special variant of TilesRenderer that includes helpers for debugging and visualizing the various tiles in the tileset. Material overrides will not work as expected with this renderer.

.colorMode

colorMode = NONE : ColorMode

Which color mode to use when rendering the tileset. 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 maxDepth 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

.displayBoxBounds

displayBoxBounds = false : Boolean

Display wireframe bounding boxes from the tiles boundingVolume.box for every visible tile.

.displaySphereBounds

displaySphereBounds = false : Boolean

Display wireframe bounding boxes from the tiles boundingVolume.sphere (or derived from the bounding box) for every visible tile.

.maxDebugDepth

maxDebugDepth = - 1 : Number

TODO

.maxDebugError

maxDebugError = - 1 : Number

TODO

.maxDebugDistance

maxDebugDistance = - 1 : Number

TODO

PriorityQueue

Piority-sorted queue to prioritize file downloads and parsing.

.maxJobs

maxJobs = 6 : number

The maximum number of jobs to be processing at once.

.unloadPriorityCallback

unloadPriorityCallback = null : ( item ) => Number

Function to derive the unload priority of the given item. Higher priority values get unloaded first.

LRUCache

Utility class for the TilesRenderer to keep track of currently used items so rendered items will not be unloaded.

.maxSize

maxSize = 800 : number

The maximum cached size. If that current amount of cached items is equal to this value then no more items can be cached.

.minSize

minSize = 600 : number

The minimum cache size. Above this cached data will be unloaded if it's unused.

.unloadPercent

unloadPercent = 0.05 : number

The maximum percentage of minSize to unload during a given frame.

.priorityCallback

priorityCallback = null : ( item ) => Number

Function to derive the job priority of the given item. Higher priority values get processed first.

LICENSE

The software is available under the Apache V2.0 license.

Copyright © 2020 California Institute of Technology. ALL RIGHTS RESERVED. United States Government Sponsorship Acknowledged. This software may be subject to U.S. export control laws. By accepting this software, the user agrees to comply with all applicable U.S. export laws and regulations. User has the responsibility to obtain export licenses, or other export authority as may be required before exporting such information to foreign countries or providing access to foreign persons. Neither the name of Caltech nor its operating division, the Jet Propulsion Laboratory, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.