Class: Model

Model

new Model(optionsopt)

A 3D model based on glTF, the runtime asset format for WebGL, OpenGL ES, and OpenGL.

Cesium includes support for geometry and materials, glTF animations, and glTF skinning. In addition, individual glTF nodes are pickable with Scene#pick and animatable with Model#getNode. glTF cameras and lights are not currently supported.

An external glTF asset is created with Model.fromGltf. glTF JSON can also be created at runtime and passed to this constructor function. In either case, the Model#readyPromise is resolved when the model is ready to render, i.e., when the external binary, image, and shader files are downloaded and the WebGL resources are created.

For high-precision rendering, Cesium supports the CESIUM_RTC extension, which introduces the CESIUM_RTC_MODELVIEW parameter semantic that says the node is in WGS84 coordinates translated relative to a local origin.

Parameters:
Name Type Attributes Description
options Object <optional>
 Object with the following properties:
Properties
Name Type Attributes Default Description
gltf Object | ArrayBuffer | Uint8Array <optional>
 The object for the glTF JSON or an arraybuffer of Binary glTF defined by the KHR_binary_glTF extension.
basePath String <optional>
 '' The base path that paths in the glTF JSON are relative to.
show Boolean <optional>
 true Determines if the model primitive will be shown.
modelMatrix Matrix4 <optional>
 Matrix4.IDENTITY The 4x4 transformation matrix that transforms the model from model to world coordinates.
scale Number <optional>
 1.0 A uniform scale applied to this model.
minimumPixelSize Number <optional>
 0.0 The approximate minimum pixel size of the model regardless of zoom.
maximumScale Number <optional>
 The maximum scale size of a model. An upper limit for minimumPixelSize.
id Object <optional>
 A user-defined object to return when the model is picked with Scene#pick.
allowPicking Boolean <optional>
 true When true, each glTF mesh and primitive is pickable with Scene#pick.
incrementallyLoadTextures Boolean <optional>
 true Determine if textures may continue to stream in after the model is loaded.
asynchronous Boolean <optional>
 true Determines if model WebGL resource creation will be spread out over several frames or block until completion once all glTF files are loaded.
shadows ShadowMode <optional>
 ShadowMode.ENABLED Determines whether the model casts or receives shadows from each light source.
debugShowBoundingVolume Boolean <optional>
 false For debugging only. Draws the bounding sphere for each draw command in the model.
debugWireframe Boolean <optional>
 false For debugging only. Draws the model in wireframe.
heightReference HeightReference <optional>
 Determines how the model is drawn relative to terrain.
scene Scene <optional>
 Must be passed in for models that use the height reference property.
istanceDisplayCondition DistanceDisplayCondition <optional>
 The condition specifying at what distance from the camera that this model will be displayed.
Source:
See:
Throws:

Members

activeAnimations :ModelAnimationCollection

The currently playing glTF animations.
Type:
Source:

(readonly) allowPicking :Boolean

When true, each glTF mesh and primitive is pickable with Scene#pick. When false, GPU memory is saved.
Type:
  • Boolean
Default Value:
  • true
Source:

(readonly) asynchronous :Boolean

Determines if model WebGL resource creation will be spread out over several frames or block until completion once all glTF files are loaded.
Type:
  • Boolean
Default Value:
  • true
Source:

(readonly) basePath :String

The base path that paths in the glTF JSON are relative to. The base path is the same path as the path containing the .gltf file minus the .gltf file, when binary, image, and shader files are in the same directory as the .gltf. When this is '', the app's base path is used.
Type:
  • String
Default Value:
  • ''
Source:

(readonly) boundingSphere :BoundingSphere

The model's bounding sphere in its local coordinate system. This does not take into account glTF animations and skins nor does it take into account Model#minimumPixelSize.
Type:
Default Value:
  • undefined
Source:
Example
// Center in WGS84 coordinates
var center = Cesium.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new Cesium.Cartesian3());

debugShowBoundingVolume :Boolean

This property is for debugging only; it is not for production use nor is it optimized.

Draws the bounding sphere for each draw command in the model. A glTF primitive corresponds to one draw command. A glTF mesh has an array of primitives, often of length one.

Type:
  • Boolean
Default Value:
  • false
Source:

debugWireframe :Boolean

This property is for debugging only; it is not for production use nor is it optimized.

Draws the model in wireframe.

Type:
  • Boolean
Default Value:
  • false
Source:

distanceDisplayCondition :DistanceDisplayCondition

Gets or sets the condition specifying at what distance from the camera that this model will be displayed.
Type:
Default Value:
  • undefined
Source:

(readonly) gltf :Object

The object for the glTF JSON, including properties with default values omitted from the JSON provided to this model.
Type:
  • Object
Default Value:
  • undefined
Source:

id :Object

User-defined object returned when the model is picked.
Type:
  • Object
Default Value:
  • undefined
Source:
See:

(readonly) incrementallyLoadTextures :Boolean

Determine if textures may continue to stream in after the model is loaded.
Type:
  • Boolean
Default Value:
  • true
Source:

maximumScale :Number

The maximum scale size for a model. This can be used to give an upper limit to the Model#minimumPixelSize, ensuring that the model is never an unreasonable scale.
Type:
  • Number
Source:

minimumPixelSize :Number

The approximate minimum pixel size of the model regardless of zoom. This can be used to ensure that a model is visible even when the viewer zooms out. When 0.0, no minimum size is enforced.
Type:
  • Number
Default Value:
  • 0.0
Source:

modelMatrix :Matrix4

The 4x4 transformation matrix that transforms the model from model to world coordinates. When this is the identity matrix, the model is drawn in world coordinates, i.e., Earth's WGS84 coordinates. Local reference frames can be used by providing a different transformation matrix, like that returned by Transforms.eastNorthUpToFixedFrame.
Type:
Default Value:
Source:
Example
var origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
m.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);

(readonly) pendingTextureLoads :Number

Return the number of pending texture loads.
Type:
  • Number
Source:

(readonly) ready :Boolean

When true, this model is ready to render, i.e., the external binary, image, and shader files were downloaded and the WebGL resources were created. This is set to true right before Model#readyPromise is resolved.
Type:
  • Boolean
Default Value:
  • false
Source:

(readonly) readyPromise :Promise.<Model>

Gets the promise that will be resolved when this model is ready to render, i.e., when the external binary, image, and shader files were downloaded and the WebGL resources were created.

This promise is resolved at the end of the frame before the first frame the model is rendered in.

Type:
Source:
See:
Example
// Play all animations at half-speed when the model is ready to render
Cesium.when(model.readyPromise).then(function(model) {
  model.activeAnimations.addAll({
    speedup : 0.5
  });
}).otherwise(function(error){
  window.alert(error);
});

scale :Number

A uniform scale applied to this model before the Model#modelMatrix. Values greater than 1.0 increase the size of the model; values less than 1.0 decrease.
Type:
  • Number
Default Value:
  • 1.0
Source:

shadows :ShadowMode

Determines whether the model casts or receives shadows from each light source.
Type:
  • ShadowMode
Default Value:
  • ShadowMode.ENABLED
Source:

show :Boolean

Determines if the model primitive will be shown.
Type:
  • Boolean
Default Value:
  • true
Source:

Methods

(static) fromGltf(options) → {Model}

Creates a model from a glTF asset. When the model is ready to render, i.e., when the external binary, image, and shader files are downloaded and the WebGL resources are created, the Model#readyPromise is resolved.

The model can be a traditional glTF asset with a .gltf extension or a Binary glTF using the KHR_binary_glTF extension with a .glb extension.

For high-precision rendering, Cesium supports the CESIUM_RTC extension, which introduces the CESIUM_RTC_MODELVIEW parameter semantic that says the node is in WGS84 coordinates translated relative to a local origin.

Parameters:
Name Type Description
options Object Object with the following properties:
Properties
Name Type Attributes Default Description
url String The url to the .gltf file.
headers Object <optional>
 HTTP headers to send with the request.
show Boolean <optional>
 true Determines if the model primitive will be shown.
modelMatrix Matrix4 <optional>
 Matrix4.IDENTITY The 4x4 transformation matrix that transforms the model from model to world coordinates.
scale Number <optional>
 1.0 A uniform scale applied to this model.
minimumPixelSize Number <optional>
 0.0 The approximate minimum pixel size of the model regardless of zoom.
maximumScale Number <optional>
 The maximum scale for the model.
id Object <optional>
 A user-defined object to return when the model is picked with Scene#pick.
allowPicking Boolean <optional>
 true When true, each glTF mesh and primitive is pickable with Scene#pick.
incrementallyLoadTextures Boolean <optional>
 true Determine if textures may continue to stream in after the model is loaded.
asynchronous Boolean <optional>
 true Determines if model WebGL resource creation will be spread out over several frames or block until completion once all glTF files are loaded.
shadows ShadowMode <optional>
 ShadowMode.ENABLED Determines whether the model casts or receives shadows from each light source.
debugShowBoundingVolume Boolean <optional>
 false For debugging only. Draws the bounding sphere for each DrawCommand in the model.
debugWireframe Boolean <optional>
 false For debugging only. Draws the model in wireframe.
Source:
Throws:
Returns:
The newly created model.
Type
Model
Examples
// Example 1. Create a model from a glTF asset
var model = scene.primitives.add(Cesium.Model.fromGltf({
  url : './duck/duck.gltf'
}));
// Example 2. Create model and provide all properties and events
var origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
var modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);

var model = scene.primitives.add(Cesium.Model.fromGltf({
  url : './duck/duck.gltf',
  show : true,                     // default
  modelMatrix : modelMatrix,
  scale : 2.0,                     // double size
  minimumPixelSize : 128,          // never smaller than 128 pixels
  maximumScale: 20000,             // never larger than 20000 * model size (overrides minimumPixelSize)
  allowPicking : false,            // not pickable
  debugShowBoundingVolume : false, // default
  debugWireframe : false
}));

model.readyPromise.then(function(model) {
  // Play all animations when the model is ready to render
  model.activeAnimations.addAll();
});

destroy() → {undefined}

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 a DeveloperError exception. Therefore, assign the return value (undefined) to the object as done in the example.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
Type
undefined
Example
model = model && model.destroy();

getMaterial(name) → {ModelMaterial}

Returns the glTF material with the given name property.
Parameters:
Name Type Description
name String The glTF name of the material.
Source:
Throws:
The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.
Type
DeveloperError
Returns:
The material or undefined if no material with name exists.
Type
ModelMaterial

getMesh(name) → {ModelMesh}

Returns the glTF mesh with the given name property.
Parameters:
Name Type Description
name String The glTF name of the mesh.
Source:
Throws:
The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.
Type
DeveloperError
Returns:
The mesh or undefined if no mesh with name exists.
Type
ModelMesh

getNode(name) → {ModelNode}

Returns the glTF node with the given name property. This is used to modify a node's transform for animation outside of glTF animations.
Parameters:
Name Type Description
name String The glTF name of the node.
Source:
Throws:
The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.
Type
DeveloperError
Returns:
The node or undefined if no node with name exists.
Type
ModelNode
Example
// Apply non-uniform scale to node LOD3sp
var node = model.getNode('LOD3sp');
node.matrix = Cesium.Matrix4.fromScale(new Cesium.Cartesian3(5.0, 1.0, 1.0), node.matrix);

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 a DeveloperError exception.
Source:
See:
Returns:
true if this object was destroyed; otherwise, false.
Type
Boolean

update()

Called when Viewer or CesiumWidget render the scene to get the draw commands needed to render this primitive.

Do not call this function directly. This is documented just to list the exceptions that may be propagated when the scene is rendered:

Source:
Throws:
Failed to load external reference.
Type
RuntimeError