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:
- KHR_binary_glTF (glTF 1.0)
- KHR_materials_common (glTF 1.0)
- WEB3D_quantized_attributes (glTF 1.0)
- AGI_articulations
- KHR_blend (draft)
- KHR_draco_mesh_compression
- KHR_materials_pbrSpecularGlossiness
- KHR_materials_unlit
- KHR_techniques_webgl
- KHR_texture_transform
- KHR_texture_basisu
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:
|
Demo:
See:
Members
activeAnimations : ModelAnimationCollection
true
, each glTF mesh and primitive is pickable with Scene#pick
. When false
, GPU memory is saved.
-
Default Value:
true
-
Default Value:
true
Model#color
is
translucent or Model#silhouetteSize
is greater than 0.0.
-
Default Value:
true
''
,
the app's base path is used.
Deprecated: true
Default Value:''
readonly boundingSphere : BoundingSphere
Model#minimumPixelSize
.
-
Default Value:
undefined
Example:
// Center in WGS84 coordinates
const center = Cesium.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new Cesium.Cartesian3());
clippingPlanes : ClippingPlaneCollection
ClippingPlaneCollection
used to selectively disable rendering the model.
color : Color
-
Default Value:
Color.WHITE
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
-
Default Value:
ColorBlendMode.HIGHLIGHT
credit : Credit
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
Draws the model in wireframe.
-
Default Value:
false
distanceDisplayCondition : DistanceDisplayCondition
-
Default Value:
undefined
Deprecated: true
Default Value:undefined
heightReference : HeightReference
-
Default Value:
HeightReference.NONE
-
Default Value:
undefined
See:
imageBasedLighting : ImageBasedLighting
-
Default Value:
true
lightColor : Cartesian3
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
Model#minimumPixelSize
, ensuring that the model
is never an unreasonable scale.
0.0
, no minimum size is enforced.
-
Default Value:
0.0
modelMatrix : Matrix4
Transforms.eastNorthUpToFixedFrame
.
-
Default Value:
Matrix4.IDENTITY
Example:
const origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
m.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);
Deprecated: true
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>
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:
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
-
Default Value:
ShadowMode.ENABLED
-
Default Value:
true
-
Default Value:
true
silhouetteColor : Color
-
Default Value:
Color.RED
-
Default Value:
0.0
splitDirection : SplitDirection
SplitDirection
to apply to this model.
-
Default Value:
SplitDirection.NONE
Methods
static Cesium.Model.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 .glb extension.
Cesium supports glTF assets with the following extensions:
- KHR_binary_glTF (glTF 1.0)
- KHR_materials_common (glTF 1.0)
- WEB3D_quantized_attributes (glTF 1.0)
- AGI_articulations
- KHR_blend (draft)
- KHR_draco_mesh_compression
- KHR_materials_pbrSpecularGlossiness
- KHR_materials_unlit
- KHR_techniques_webgl
- KHR_texture_transform
- KHR_texture_basisu
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:
|
Returns:
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();
});
Name | Type | Description |
---|---|---|
scene |
Scene | The scene. |
Returns:
true
if silhouettes are supported; otherwise, returns false
Throws:
-
DeveloperError : The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.
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
name
property.
Name | Type | Description |
---|---|---|
name |
String | The glTF name of the material. |
Returns:
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
name
property.
Name | Type | Description |
---|---|---|
name |
String | The glTF name of the mesh. |
Returns:
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
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:
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);
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:
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.
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:
-
RuntimeError : Failed to load external reference.