Chevron Down
Table of Contents
Chevron DownAPI Reference

Tileset3D

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 Tileset3DLoader.

References

Usage

Loading a tileset and instantiating a Tileset3D instance.

import {Tileset3DLoader, Tileset3D} from '@loaders.gl/3d-tiles';
import {parse} from '@loaders.gl/core';

const tilesetJSON = await parse(fetch(tileset));
const tileset = new Tileset3D(tilesetJson);

console.log(`Maximum building height: ${tileset.properties.height.maximum}`);
console.log(`Minimum building height: ${tileset.properties.height.minimum}`);

Common setting for the skipLevelOfDetail optimization

import {Tileset3D} from '@loaders.gl/3d-tiles';

const tileset = new Tileset3D(tilesetJson, {
  url: 'http://localhost:8002/tilesets/Seattle/tileset.json',
  baseScreenSpaceError: 1024,
  skipScreenSpaceErrorFactor: 16
});

Common settings for the dynamicScreenSpaceError optimization

import {Tileset3D} from '^loaders.gl/3d-tiles';
const tileset = new Tileset3D({
  url: 'http://localhost:8002/tilesets/Seattle/tileset.json',
  dynamicScreenSpaceError: true,
  dynamicScreenSpaceErrorDensity: 0.00278,
  dynamicScreenSpaceErrorFactor: 4.0
});

Properties

asset : Object (readonly)

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.

properties : Object (readonly)

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.

tilesLoaded : boolean (readonly)

When true, all tiles that meet the screen space error this frame are loaded. The tileset is completely loaded for this view.

See Tileset3D#allTilesLoaded

url : String (readonly)

The url to a tileset JSON file.

basePath : String (readonly) (deprecated)

The base path that non-absolute paths in tileset JSON file are relative to.

maximumScreenSpaceError : Number

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. *

maximumMemoryUsage : Number

^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#totalMemoryUsageInBytes

root : Tile3DHeader

The root tile header.

boundingSphere : BoundingSphere

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));
});

modelMatrix : Matrix4

A 4x4 transformation matrix that transforms the entire tileset.

// Adjust a tileset's height from the globe's surface.
var heightOffset = 20.0;
var boundingSphere = tileset.boundingSphere;
var cartographic = Cartographic.fromCartesian(boundingSphere.center);
var surface = Cartesian3.fromRadians(cartographic.longitude, cartographic.latitude, 0.0);
var offset = Cartesian3.fromRadians(cartographic.longitude, cartographic.latitude, heightOffset);
var translation = Cartesian3.subtract(offset, surface, new Cartesian3());
tileset.modelMatrix = Matrix4.fromTranslation(translation);

maximumMemoryUsage : Number

totalMemoryUsageInBytes : 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.

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.

ellipsoid : Ellipsoid

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.}

unloadTileset

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.

isDestroyed() : Boolean

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.

destroy()

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.

Methods

constructor(tileset : Object, url : String [, options : Object])

  • tileset: The loaded tileset (parsed JSON)
  • url: The url to a tileset JSON file.
  • options: Options object, see the options section below for available options.

Notes:

  • The version tileset must be 3D Tiles version 0.0 or 1.0.

hasExtension(extensionName : String) : Boolean

true if the tileset JSON file lists the extension in extensionsUsed; otherwise, false. ^param {String} extensionName The name of the extension to check. * ^returns {Boolean} true if the tileset JSON file lists the extension in extensionsUsed; otherwise, false.

Options

Tileset3D class is still being developed, not all options are guaranteed to be working.

The Tileset3D class supports a number of options

  • options.url (Resource|String|Promise.Resource|Promise.String) The url to a tileset JSON file.
  • options.show=true (Boolean) - Determines if the tileset will be shown.
  • options.modelMatrix=Matrix4.IDENTITY (Matrix4) - A 4x4 transformation matrix that transforms the tileset's root tile.
  • options.maximumScreenSpaceError=16] (Number) - The maximum screen space error used to drive level of detail refinement.
  • options.maximumMemoryUsage=512] (Number) - The maximum amount of memory in MB that can be used by the tileset.
  • options.dynamicScreenSpaceError=false] (Boolean) - Optimization option. Reduce the screen space error for tiles that are further away from the camera.
  • options.dynamicScreenSpaceErrorDensity=0.00278] (Number) - Density used to adjust the dynamic screen space error, similar to fog density.
  • options.dynamicScreenSpaceErrorFactor=4.0] (Number) - A factor used to increase the computed dynamic screen space error.
  • options.baseScreenSpaceError=1024 (Number) - When skipLevelOfDetail is true, the screen space error that must be reached before skipping levels of detail.
  • options.skipScreenSpaceErrorFactor=16 (Number) - When skipLevelOfDetail is true, a multiplier defining the minimum screen space error to skip. Used in conjunction with skipLevels to determine which tiles to load.
  • options.ellipsoid=Ellipsoid.WGS84 (Ellipsoid) - The ellipsoid determining the size and shape of the globe.

Callbacks

  • options.onTileLoad ((tileHeader : Tile3DHeader) : void) -
  • options.onTileUnload ((tileHeader : Tile3DHeader) :void) -
  • options.onTileLoadFailed (void(tileHeader : Tile3DHeader, message : String) : void) -

dynamicScreenSpaceError

=false

Optimization option. Whether the tileset should refine based on a dynamic screen space error. Tiles that are further away will be rendered with lower detail than closer tiles. This improves performance by rendering fewer tiles and making less requests, but may result in a slight drop in visual quality for tiles in the distance.

The algorithm is biased towards "street views" where the camera is close to the ground plane of the tileset and looking at the horizon. In addition results are more accurate for tightly fitting bounding volumes like box and region.

dynamicScreenSpaceErrorDensity

=0.00278

A scalar that determines the density used to adjust the dynamic screen space error (similar to "fog"). Increasing this value has the effect of increasing the maximum screen space error for all tiles, but in a non-linear fashion.

The error starts at 0.0 and increases exponentially until a midpoint is reached, and then approaches 1.0 asymptotically. This has the effect of keeping high detail in the closer tiles and lower detail in the further tiles, with all tiles beyond a certain distance all roughly having an error of 1.0.

The dynamic error is in the range [0.0, 1.0) and is multiplied by dynamicScreenSpaceErrorFactor to produce the final dynamic error. This dynamic error is then subtracted from the tile's actual screen space error.

Increasing dynamicScreenSpaceErrorDensity has the effect of moving the error midpoint closer to the camera. It is analogous to moving fog closer to the camera.

dynamicScreenSpaceErrorFactor

= 4.0;

A factor used to increase the screen space error of tiles for dynamic screen space error. As this value increases less tiles are requested for rendering and tiles in the distance will have lower detail. If set to zero, the feature will be disabled.

dynamicScreenSpaceErrorHeightFalloff

= 0.25;

A ratio of the tileset's height at which the density starts to falloff. If the camera is below this height the full computed density is applied, otherwise the density falls off. This has the effect of higher density at street level views.

Valid values are between 0.0 and 1.0.

onTileLoad(tileHeader : Tile3DHeader) : void

Indicate ssthat a tile's content was loaded.

The loaded Tile3DHeader is passed to the event listener.

This event is fired during the tileset traversal while the frame is being rendered so that updates to the tile take effect in the same frame. Do not create or modify entities or primitives during the event listener.

  new Tileset3D({
    onTileLoad(tileHeader => console.log('A tile was loaded.'));
  });

onTileUnload(tileHeader : Tile3DHeader) : void

Indicates that a tile's content was unloaded.

The unloaded Tile3DHeaders is passed to the event listener.

This event is fired immediately before the tile's content is unloaded while the frame is being rendered so that the event listener has access to the tile's content. Do not create or modify entities or primitives during the event listener.

  new Tileset3D({
    onTileUnload(tile =>  console.log('A tile was unloaded from the cache.'));
  });

See

  • Tileset3D#maximumMemoryUsage
  • Tileset3D#trimLoadedTiles

onTileLoadFail(tileHeader : Tile3DHeader) : void

Called to indicate that a tile's content failed to load. By default, error messages will be logged to the console.

The error object passed to the listener contains two properties:

  • url: the url of the failed tile.
  • message: the error message.
new Tileset3D({
  onTileFailed(tileHeader, url, message) {
    console.log('An error occurred loading tile: ', url);
    console.log('Error: ', message);
  }
});

skipLevelOfDetail : Boolean

Default: true

Optimization option. Determines if level of detail skipping should be applied during the traversal.

The common strategy for replacement-refinement traversal is to store all levels of the tree in memory and require all children to be loaded before the parent can refine. With this optimization levels of the tree can be skipped entirely and children can be rendered alongside their parents. The tileset requires significantly less memory when using this optimization.

baseScreenSpaceError : Number

Default: 1024

The screen space error that must be reached before skipping levels of detail.

Only used when skipLevelOfDetail is true.

skipScreenSpaceErrorFactor : Number

Default: 16

Multiplier defining the minimum screen space error to skip. For example, if a tile has screen space error of 100, no tiles will be loaded unless they are leaves or have a screen space error <= 100 / skipScreenSpaceErrorFactor.

Only used when Tileset3D.skipLevelOfDetail is true.

skipLevels

Default: 1

Constant defining the minimum number of levels to skip when loading tiles. When it is 0, no levels are skipped. For example, if a tile is level 1, no tiles will be loaded unless they are at level greater than 2.

Only used when Tileset3D.skipLevelOfDetail is true.

immediatelyLoadDesiredLevelOfDetail : false

When true, only tiles that meet the maximum screen space error will ever be downloaded. Skipping factors are ignored and just the desired tiles are loaded.

Only used when Tileset3D.skipLevelOfDetail is true.

loadSiblings: false

Determines whether siblings of visible tiles are always downloaded during traversal. This may be useful for ensuring that tiles are already available when the viewer turns left/right.

Only used when Tileset3D.skipLevelOfDetail is true.