The
Tileset3D
class is being generalized to handle more use cases. Since this may require modifying some APIs, this class should be considered experiemental.
The Tileset3D
class can be instantiated with tileset data formatted according to the 3D Tiles Category, which is supported by the Tiles3DLoader.
References
Loading a tileset and instantiating a Tileset3D
instance.
import {load} from '@loaders.gl/core';
import {Tileset3D} from '@loaders.gl/tiles';
import {Tiles3DLoader} from '@loaders.gl/3d-tiles';
const tilesetUrl = 'https://assets.cesium.com/43978/tileset.json';
const tilesetJson = await load(tilesetUrl, Tiles3DLoader);
const tileset3d = new Tileset3D(tilesetJson, {
onTileLoad: tile => console.log(tile)
});
Loading a tileset and dynamically load/unload with viewport.
import {load} from '@loaders.gl/core';
import {Tileset3D} from '@loaders.gl/tiles';
import {I3SLoader} from '@loaders.gl/i3s';
import {WebMercatorViewport} from '@deck.gl/web-mercator';
const tileseturl =
'https://tiles.arcgis.com/tiles/z2tnIkrLQ2BRzr6P/arcgis/rest/services/SanFrancisco_Bldgs/SceneServer/layers/0';
const tilesetJson = await load(tilesetUrl, I3SLoader);
const tileset3d = new Tileset3D(tilesetJson, {
onTileLoad: tile => console.log(tile)
});
const viewport = new WebMercatorViewport({latitude, longitude, zoom});
tileset3d.update(viewport);
Since Tileset3D's update
is a synchronized call, which selects the tiles qualified for rendering based on current viewport and available tiles, user can trigger another update
when new tiles are loaded.
import {Tileset3D} from '@loaders.gl/tiles';
const viewport = new WebMercatorViewport({latitude, longitude, zoom});
const tileset3d = new Tileset3D(tilesetJson, {
onTileLoad: tile => tileset3d.update(viewport)
});
new Tileset3D(tilesetJson, {
onTileLoad: tile => console.log(tile)
});
Parameters:
json
: loaded tileset json object, should follow the format tiles formatoptions
:options.ellipsoid
=Ellipsoid.WGS84
(Ellipsoid
) - The ellipsoid determining the size and shape of the globe.options.throttleRequests
=true
(Boolean
) - Determines whether or not to throttle tile fetching requests.options.modelMatrix
=Matrix4.IDENTITY
(Matrix4
) - A 4x4 transformation matrix this transforms the entire tileset.options.maximumMemoryUsage
=512
] (Number
) - The maximum amount of memory in MB that can be used by the tileset.options.fetchOptions
- fetchOptions, i.e. headers, used to load tiles from tiling serverCallbacks:
onTileLoad
((tileHeader : Tile3DHeader) : void
) - callback when a tile node is fully loaded during the tileset traversal.onTileUnload
((tileHeader : Tile3DHeader) : void
) - callback when a tile node is unloaded during the tileset traversal.onTileError
((tileHeader : Tile3DHeader, message : String) : void
) - callback when a tile faile to load during the tileset traversal.The Tileset3D
allows callbacks (onTileLoad
, onTileUnload
) to be registered that notify the app when the set of tiles available for rendering has changed. This is important because tile loads complete asynchronously, after the tileset3D.update(...)
call has returned.
Cesium 3D tiles specific options:
options.maximumScreenSpaceError
=16
] (Number
) - The maximum screen space error used to drive level of detail refinement.boundingVolume
(BoundingVolume)The root tile's bounding volume, which is also the bouding volume of the entire tileset. Check Tile3DHeader#boundingVolume
cartesianCenter
(Number[3])Center of tileset in fixed frame coordinates.
cartographicCenter
(Number[3])Center of tileset in cartographic coordinates [long, lat, elevation]
ellipsoid
(Ellipsoid
)Gets an ellipsoid describing the shape of the globe.
modelMatrix
(Matrix4)A Matrix4 instance (4x4 transformation matrix) that transforms the entire tileset.
root
(Tile3DHeader)The root tile header.
tiles
(Tile3DHeader[])All the tiles that have been traversed.
stats
(Stats
)An instance of a probe.gl Stats
object that contains information on how many tiles have been loaded etc. Easy to display using a probe.gl StatsWidget
.
tileset
(Object)The original tileset data this object instanced from.
tilesLoaded
(Boolean)When true
, all tiles that meet the screen space error this frame are loaded. The tileset is completely loaded for this view.
gpuMemoryUsageInBytes
(Number)The total amount of GPU memory in bytes used by the tileset. This value is estimated from geometry, texture, and batch table textures of loaded tiles. For point clouds, this value also includes per-point metadata.
url
(String)The url to a tileset JSON file.
zoom
(Number[3])A web mercator zoom level that displays the entire tile set bounding volume
tilesLoaded
: booleanWhen true
, all tiles that meet the screen space error this frame are loaded. The tileset is
completely loaded for this view.
See Tileset3D#allTilesLoaded
Gets the tileset's asset object property, which contains metadata about the tileset.
See the asset schema reference in the 3D Tiles spec for the full set of properties.
Gets the tileset's properties dictionary object, which contains metadata about per-feature properties.
See the properties schema reference in the 3D Tiles spec for the full set of properties.
The maximum screen space error used to drive level of detail refinement. This value helps determine when a tile refines to its descendants, and therefore plays a major role in balancing performance with visual quality.
A tile's screen space error is roughly equivalent to the number of pixels wide that would be drawn if a sphere with a
radius equal to the tile's geometric error were rendered at the tile's position. If this value exceeds
maximumScreenSpaceError
the tile refines to its descendants.
Depending on the tileset, maximumScreenSpaceError
may need to be tweaked to achieve the right balance. Higher values provide better performance but lower visual quality. *
^default 16 *
^exception maximumScreenSpaceError
must be greater than or equal to zero.
The maximum amount of GPU memory (in MB) that may be used to cache tiles. This value is estimated from geometry, textures, and batch table textures of loaded tiles. For point clouds, this value also includes per-point metadata.
Tiles not in view are unloaded to enforce this.
If decreasing this value results in unloading tiles, the tiles are unloaded the next frame.
If tiles sized more than maximumMemoryUsage
are needed
to meet the desired screen space error, determined by Tileset3D.maximumScreenSpaceError
,
for the current view, then the memory usage of the tiles loaded will exceed
maximumMemoryUsage
. For example, if the maximum is 256 MB, but
300 MB of tiles are needed to meet the screen space error, then 300 MB of tiles may be loaded. When
these tiles go out of view, they will be unloaded.
^default 512 *
^exception maximumMemoryUsage
must be greater than or equal to zero.
^see Tileset3D#gpuMemoryUsageInBytes
The root tile header.
The tileset's bounding sphere.
var tileset = viewer.scene.primitives.add(
new Tileset3D({
url: 'http://localhost:8002/tilesets/Seattle/tileset.json'
})
);
tileset.readyPromise.then(function(tileset) {
// Set the camera to view the newly added tileset
viewer.camera.viewBoundingSphere(tileset.boundingSphere, new HeadingPitchRange(0, -0.5, 0));
});
A 4x4 transformation matrix that transforms the entire tileset.
The total amount of GPU memory in bytes used by the tileset. This value is estimated from geometry, texture, and batch table textures of loaded tiles. For point clouds, this value also includes per-point metadata.
An instance of a probe.gl Stats
object that contains information on how many tiles have been loaded etc. Easy to display using a probe.gl StatsWidget
.
Gets an ellipsoid describing the shape of the globe.
Returns the extras
property at the top-level of the tileset JSON, which contains application specific metadata.
Returns undefined
if extras
does not exist.
Exception The tileset is not loaded. Use Tileset3D.readyPromise or wait for Tileset3D.ready to be true.
See Extras in the 3D Tiles specification.}
Unloads all tiles that weren't selected the previous frame. This can be used to
explicitly manage the tile cache and reduce the total number of tiles loaded below
Tileset3D.maximumMemoryUsage
.
Tile unloads occur at the next frame to keep all the WebGL delete calls within the render loop.
Returns true if this object was destroyed; otherwise, false.
If this object was destroyed, it should not be used; calling any function other than
isDestroyed
will result in an exception.
^returns Boolean
: true
if this object was destroyed; otherwise, false
.
Destroys the WebGL resources held by this object. Destroying an object allows for deterministic release of WebGL resources, instead of relying on the garbage collector to destroy this object.
Once an object is destroyed, it should not be used; calling any function other than isDestroyed
will result in an exception. Therefore, assign the return value undefined
to the object as done in the example.
Wxception This object was destroyed, i.e., destroy() was called.
update
update(viewport: WebMercatorViewport) : Number
:
Parameters:
viewport
: a WebMercatorViewport
Execute traversal under current viewport and fetch tiles needed for current viewport and update selectedTiles
. Return frameNumber
of this update frame.