Model

new Cesium.Model(options)
Scene/Model.js 238

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.

Cesium supports glTF assets with the following extensions:

Note: for models with compressed textures using the KHR_texture_basisu extension, we recommend power of 2 textures in both dimensions for maximum compatibility. This is because some samplers require power of 2 textures (Using textures in WebGL) and KHR_texture_basisu requires multiple of 4 dimensions (KHR_texture_basisu additional requirements).

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.

Name Type Description
options Object optional Object with the following properties:
Name Type Default Description
gltf Object | ArrayBuffer | Uint8Array optional A glTF JSON object, or a binary glTF buffer.
basePath Resource | String '' optional The base path that paths in the glTF JSON are relative to.
show Boolean true optional Determines if the model primitive will be shown.
modelMatrix Matrix4 Matrix4.IDENTITY optional The 4x4 transformation matrix that transforms the model from model to world coordinates.
scale Number 1.0 optional A uniform scale applied to this model.
minimumPixelSize Number 0.0 optional 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 true optional When true, each glTF mesh and primitive is pickable with Scene#pick.
incrementallyLoadTextures Boolean true optional Determine if textures may continue to stream in after the model is loaded.
asynchronous Boolean true optional Determines if model WebGL resource creation will be spread out over several frames or block until completion once all glTF files are loaded.
clampAnimations Boolean true optional Determines if the model's animations should hold a pose over frames where no keyframes are specified.
shadows ShadowMode ShadowMode.ENABLED optional Determines whether the model casts or receives shadows from light sources.
debugShowBoundingVolume Boolean false optional For debugging only. Draws the bounding sphere for each draw command in the model.
debugWireframe Boolean false optional For debugging only. Draws the model in wireframe.
heightReference HeightReference HeightReference.NONE 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.
distanceDisplayCondition DistanceDisplayCondition optional The condition specifying at what distance from the camera that this model will be displayed.
color Color Color.WHITE optional A color that blends with the model's rendered color.
colorBlendMode ColorBlendMode ColorBlendMode.HIGHLIGHT optional Defines how the color blends with the model.
colorBlendAmount Number 0.5 optional Value used to determine the color strength when the colorBlendMode is MIX. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
silhouetteColor Color Color.RED optional The silhouette color. If more than 256 models have silhouettes enabled, there is a small chance that overlapping models will have minor artifacts.
silhouetteSize Number 0.0 optional The size of the silhouette in pixels.
clippingPlanes ClippingPlaneCollection optional The ClippingPlaneCollection used to selectively disable rendering the model.
dequantizeInShader Boolean true optional Determines if a Draco encoded model is dequantized on the GPU. This decreases total memory usage for encoded models. Deprecated in CesiumJS 1.94, will be removed in CesiumJS 1.95.
lightColor Cartesian3 optional The light color when shading the model. When undefined the scene's light color is used instead.
imageBasedLighting ImageBasedLighting optional The properties for managing image-based lighting on this model.
credit Credit | String optional A credit for the data source, which is displayed on the canvas.
showCreditsOnScreen Boolean false optional Whether to display the credits of this model on screen.
backFaceCulling Boolean true optional Whether to cull back-facing geometry. When true, back face culling is determined by the material's doubleSided property; when false, back face culling is disabled. Back faces are not culled if Model#color is translucent or Model#silhouetteSize is greater than 0.0.
showOutline Boolean true optional Whether to display the outline for models using the CESIUM_primitive_outline extension. When true, outlines are displayed. When false, outlines are not displayed.
splitDirection SplitDirection SplitDirection.NONE optional The SplitDirection split to apply to this model.
Demo:
See:

Members

activeAnimations : ModelAnimationCollection
Scene/Model.js 445

The currently playing glTF animations.

readonly allowPicking : Boolean
Scene/Model.js 975

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

readonly asynchronous : Boolean
Scene/Model.js 959

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

backFaceCulling : Boolean
Scene/Model.js 527

Whether to cull back-facing geometry. When true, back face culling is determined by the material's doubleSided property; when false, back face culling is disabled. Back faces are not culled if Model#color is translucent or Model#silhouetteSize is greater than 0.0.
Default Value: true

readonly deprecated basePath : String
Scene/Model.js 802

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.

Deprecated: true

Default Value: ''

readonly boundingSphere : BoundingSphere
Scene/Model.js 839

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.
Default Value: undefined
Example:
// Center in WGS84 coordinates
const center = Cesium.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new Cesium.Cartesian3());

clampAnimations : Boolean
Scene/Model.js 452

Determines if the model's animations should hold a pose over frames where no keyframes are specified.

clippingPlanes : ClippingPlaneCollection
Scene/Model.js 1204

The ClippingPlaneCollection used to selectively disable rendering the model.

color : Color
Scene/Model.js 478

A color that blends with the model's rendered color.
Default Value: Color.WHITE

colorBlendAmount : Number
Scene/Model.js 502

Value used to determine the color strength when the colorBlendMode is MIX. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
Default Value: 0.5

colorBlendMode : ColorBlendMode
Scene/Model.js 488

Defines how the color blends with the model.
Default Value: ColorBlendMode.HIGHLIGHT

credit : Credit
Scene/Model.js 1291

Gets the credit that will be displayed for the model

debugShowBoundingVolume : Boolean
Scene/Model.js 564

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.

Default Value: false

debugWireframe : Boolean
Scene/Model.js 580

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

Draws the model in wireframe.

Default Value: false

distanceDisplayCondition : DistanceDisplayCondition
Scene/Model.js 1052

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

readonly deprecated gltf : Object
Scene/Model.js 721

The object for the glTF JSON, including properties with default values omitted from the JSON provided to this model.

Deprecated: true

Default Value: undefined

heightReference : HeightReference
Scene/Model.js 411

Returns the height reference of the model
Default Value: HeightReference.NONE

id : Object
Scene/Model.js 401

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

imageBasedLighting : ImageBasedLighting
Scene/Model.js 1263

The properties for managing image-based lighting on this model.

readonly incrementallyLoadTextures : Boolean
Scene/Model.js 991

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

lightColor : Cartesian3
Scene/Model.js 1239

The light color when shading the model. When undefined the scene's light color is used instead.

For example, disabling additional light sources by setting model.imageBasedLighting.imageBasedLightingFactor = new Cesium.Cartesian2(0.0, 0.0) will make the model much darker. Here, increasing the intensity of the light source will make the model brighter.

Default Value: undefined

maximumScale : Number
Scene/Model.js 389

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.

minimumPixelSize : Number
Scene/Model.js 379

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.
Default Value: 0.0

modelMatrix : Matrix4
Scene/Model.js 352

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.
Default Value: Matrix4.IDENTITY
Example:
const origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
m.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);

readonly deprecated pendingTextureLoads : Number
Scene/Model.js 1007

Return the number of pending texture loads.

Deprecated: true

readonly ready : Boolean
Scene/Model.js 913

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.
Default Value: false

readonly readyPromise : Promise.<Model>
Scene/Model.js 942

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.

Example:
// Play all animations at half-speed when the model is ready to render
Promise.resolve(model.readyPromise).then(function(model) {
  model.activeAnimations.addAll({
    multiplier : 0.5
  });
}).catch(function(error){
  window.alert(error);
});
See:

scale : Number
Scene/Model.js 367

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.
Default Value: 1.0

shadows : ShadowMode
Scene/Model.js 468

Determines whether the model casts or receives shadows from light sources.
Default Value: ShadowMode.ENABLED

show : Boolean
Scene/Model.js 315

Determines if the model primitive will be shown.
Default Value: true

showCreditsOnScreen : Boolean
Scene/Model.js 1302

Gets or sets whether the credits of the model will be displayed on the screen

readonly showOutline : Boolean
Scene/Model.js 539

Whether to display the outline for models using the CESIUM_primitive_outline extension. When true, outlines are displayed. When false, outlines are not displayed.
Default Value: true

silhouetteColor : Color
Scene/Model.js 324

The silhouette color.
Default Value: Color.RED

silhouetteSize : Number
Scene/Model.js 336

The size of the silhouette in pixels.
Default Value: 0.0

splitDirection : SplitDirection
Scene/Model.js 547

The SplitDirection to apply to this model.
Default Value: SplitDirection.NONE

Methods

static Cesium.Model.fromGltf(options) → Model
Scene/Model.js 1467

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 .glb extension.

Cesium supports glTF assets with the following extensions:

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.

Name Type Description
options Object Object with the following properties:
Name Type Default Description
url Resource | String The url to the .gltf file.
basePath Resource | String optional The base path that paths in the glTF JSON are relative to.
show Boolean true optional Determines if the model primitive will be shown.
modelMatrix Matrix4 Matrix4.IDENTITY optional The 4x4 transformation matrix that transforms the model from model to world coordinates.
scale Number 1.0 optional A uniform scale applied to this model.
minimumPixelSize Number 0.0 optional 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 true optional When true, each glTF mesh and primitive is pickable with Scene#pick.
incrementallyLoadTextures Boolean true optional Determine if textures may continue to stream in after the model is loaded.
asynchronous Boolean true optional Determines if model WebGL resource creation will be spread out over several frames or block until completion once all glTF files are loaded.
clampAnimations Boolean true optional Determines if the model's animations should hold a pose over frames where no keyframes are specified.
shadows ShadowMode ShadowMode.ENABLED optional Determines whether the model casts or receives shadows from light sources.
debugShowBoundingVolume Boolean false optional For debugging only. Draws the bounding sphere for each draw command in the model.
debugWireframe Boolean false optional For debugging only. Draws the model in wireframe.
heightReference HeightReference HeightReference.NONE 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.
distanceDisplayCondition DistanceDisplayCondition optional The condition specifying at what distance from the camera that this model will be displayed.
color Color Color.WHITE optional A color that blends with the model's rendered color.
colorBlendMode ColorBlendMode ColorBlendMode.HIGHLIGHT optional Defines how the color blends with the model.
colorBlendAmount Number 0.5 optional Value used to determine the color strength when the colorBlendMode is MIX. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
silhouetteColor Color Color.RED optional The silhouette color. If more than 256 models have silhouettes enabled, there is a small chance that overlapping models will have minor artifacts.
silhouetteSize Number 0.0 optional The size of the silhouette in pixels.
clippingPlanes ClippingPlaneCollection optional The ClippingPlaneCollection used to selectively disable rendering the model.
dequantizeInShader Boolean true optional Determines if a Draco encoded model is dequantized on the GPU. This decreases total memory usage for encoded models. Deprecated in CesiumJS 1.94, will be removed in CesiumJS 1.95.
lightColor Cartesian3 optional The light color when shading the model. When undefined the scene's light color is used instead.
imageBasedLighting ImageBasedLighting optional The properties for managing image-based lighting for this tileset.
credit Credit | String optional A credit for the model, which is displayed on the canvas.
showCreditsOnScreen Boolean false optional Whether to display the credits of this model on screen.
backFaceCulling Boolean true optional Whether to cull back-facing geometry. When true, back face culling is determined by the material's doubleSided property; when false, back face culling is disabled. Back faces are not culled if Model#color is translucent or Model#silhouetteSize is greater than 0.0.
showOutline Boolean true optional Whether to display the outline for models using the CESIUM_primitive_outline extension. When true, outlines are displayed. When false, outlines are not displayed.
Returns:
The newly created model.
Examples:
// Example 1. Create a model from a glTF asset
const model = scene.primitives.add(Cesium.Model.fromGltf({
  url : './duck/duck.gltf'
}));
// Example 2. Create model and provide all properties and events
const origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
const modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);

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

static Cesium.Model.silhouetteSupported(scene) → Boolean
Scene/Model.js 1354

Determines if silhouettes are supported.
Name Type Description
scene Scene The scene.
Returns:
true if silhouettes are supported; otherwise, returns false

applyArticulations()
Scene/Model.js 1754

Applies any modified articulation stages to the matrix of each node that participates in any articulation. Note that this will overwrite any nodeTransformations on participating nodes.
Throws:
  • DeveloperError : The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.

destroy()
Scene/Model.js 5869

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.
Throws:
  • DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
model = model && model.destroy();
See:

getMaterial(name) → ModelMaterial
Scene/Model.js 1618

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

getMesh(name) → ModelMesh
Scene/Model.js 1606

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

getNode(name) → ModelNode
Scene/Model.js 1592

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

isDestroyed() → Boolean
Scene/Model.js 5849

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.
Returns:
true if this object was destroyed; otherwise, false.
See:

setArticulationStage(articulationStageKey, value)
Scene/Model.js 1633

Sets the current value of an articulation stage. After setting one or multiple stage values, call Model.applyArticulations() to cause the node matrices to be recalculated.
Name Type Description
articulationStageKey String The name of the articulation, a space, and the name of the stage.
value Number The numeric value of this stage of the articulation.
Throws:
  • DeveloperError : The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.
See:

update()
Scene/Model.js 5203

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:

Throws:
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.