new Model(options)
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.
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
optional
Object with the following properties:
|
Throws:
-
DeveloperError : bgltf is not a valid Binary glTF file.
-
DeveloperError : Only glTF Binary version 1 is supported.
Demo:
See:
Members
-
activeAnimations :ModelAnimationCollection
-
The currently playing glTF animations.Source: Scene/Model.js, line 418
-
readonlyallowPicking :Boolean
-
When
true
, each glTF mesh and primitive is pickable withScene#pick
. Whenfalse
, GPU memory is saved.-
Default Value:
true
Source: Scene/Model.js, line 691 -
readonlyasynchronous :Boolean
-
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
Source: Scene/Model.js, line 675 -
readonlybasePath :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.-
Default Value:
''
Source: Scene/Model.js, line 571 -
readonlyboundingSphere :BoundingSphere
-
The model's bounding sphere in its local coordinate system. This does not take into account glTF animations and skins.
-
Default Value:
undefined
Example:
// Center in WGS84 coordinates var center = Cesium.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new Cesium.Cartesian3());
Source: Scene/Model.js, line 594 -
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.
-
Default Value:
false
Source: Scene/Model.js, line 433 -
debugWireframe :Boolean
-
This property is for debugging only; it is not for production use nor is it optimized.
Draws the model in wireframe.
-
Default Value:
false
Source: Scene/Model.js, line 446 -
readonlygltf :Object
-
The object for the glTF JSON, including properties with default values omitted from the JSON provided to this model.
-
Default Value:
undefined
Source: Scene/Model.js, line 506 -
id :Object
-
User-defined object returned when the model is picked.
-
Default Value:
undefined
See:
Source: Scene/Model.js, line 398 -
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.-
Default Value:
0.0
Source: Scene/Model.js, line 386 -
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
.-
Default Value:
Matrix4.IDENTITY
Example:
var origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0); m.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);
Source: Scene/Model.js, line 362 -
readonlyready :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 totrue
right beforeModel#readyPromise
is resolved.-
Default Value:
false
Source: Scene/Model.js, line 629 -
readonlyreadyPromise :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.
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); });
See:
Source: Scene/Model.js, line 658 -
scale :Number
-
A uniform scale applied to this model before the
Model#modelMatrix
. Values greater than1.0
increase the size of the model; values less than1.0
decrease.-
Default Value:
1.0
Source: Scene/Model.js, line 374 -
show :Boolean
-
Determines if the model primitive will be shown.
-
Default Value:
true
Source: Scene/Model.js, line 346
Methods
-
staticModel.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 CESIUM_binary_glTF extension with a .bgltf 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.
Name Type Description options
Object Object with the following properties: Name Type Default Description url
String The url to the .gltf file. headers
Object optional HTTP headers to send with the request. 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. allowPicking
Boolean true
optional When true
, each glTF mesh and primitive is pickable withScene#pick
.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. debugShowBoundingVolume
Boolean false
optional For debugging only. Draws the bounding sphere for each DrawCommand
in the model.debugWireframe
Boolean false
optional For debugging only. Draws the model in wireframe. Returns:
The newly created model.Throws:
-
DeveloperError : bgltf is not a valid Binary glTF file.
-
DeveloperError : Only glTF Binary version 1 is supported.
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(Model.fromGltf({ url : './duck/duck.gltf', show : true, // default modelMatrix : modelMatrix, scale : 2.0, // double size minimumPixelSize : 128, // never smaller than 128 pixels 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(); });
Source: Scene/Model.js, line 819 -
-
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 thanisDestroyed
will result in aDeveloperError
exception. Therefore, assign the return value (undefined
) to the object as done in the example.Returns:
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
model = model && model.destroy();
See:
Source: Scene/Model.js, line 2950 -
-
getMaterial(name) → ModelMaterial
-
Returns the glTF material with the given
name
property.Name Type Description name
String The glTF name of the material. Returns:
The material orundefined
if no material withname
exists.Throws:
-
DeveloperError : The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.
Source: Scene/Model.js, line 934 -
-
getMesh(name) → ModelMesh
-
Returns the glTF mesh with the given
name
property.Name Type Description name
String The glTF name of the mesh. Returns:
The mesh orundefined
if no mesh withname
exists.Throws:
-
DeveloperError : The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.
Source: Scene/Model.js, line 922 -
-
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.Name Type Description name
String The glTF name of the node. Returns:
The node orundefined
if no node withname
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 var node = model.getNode('LOD3sp'); node.matrix =Cesium. Matrix4.fromScale(new Cesium.Cartesian3(5.0, 1.0, 1.0), node.matrix);
Source: Scene/Model.js, line 908 -
-
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 thanisDestroyed
will result in aDeveloperError
exception.Returns:
true
if this object was destroyed; otherwise,false
.See:
Source: Scene/Model.js, line 2929 -
update()
-
Called when
Viewer
orCesiumWidget
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:
-
RuntimeError : Failed to load external reference.
Source: Scene/Model.js, line 2746 -