Model.fromGltfAsync
. Do not call the constructor directly.
Cesium supports glTF assets with the following extensions:
- AGI_articulations
- CESIUM_primitive_outline
- CESIUM_RTC
- EXT_instance_features
- EXT_mesh_features
- EXT_mesh_gpu_instancing
- EXT_meshopt_compression
- EXT_structural_metadata
- EXT_texture_webp
- KHR_draco_mesh_compression
- KHR_techniques_webgl
- KHR_materials_common
- KHR_materials_pbrSpecularGlossiness
- KHR_materials_unlit
- KHR_mesh_quantization
- KHR_texture_basisu
- KHR_texture_transform
- WEB3D_quantized_attributes
- NGA_gpm_local (experimental)
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).
Demo:
See:
Members
readonly activeAnimations : ModelAnimationCollection
Model#color
is translucent or Model#silhouetteSize
is greater than 0.0.
-
Default Value:
true
readonly boundingSphere : BoundingSphere
Model#minimumPixelSize
.
-
Default Value:
true
readonly classificationType : ClassificationType
Additionally, there are a few requirements/limitations:
- The glTF cannot contain morph targets, skins, or animations.
- The glTF cannot contain the
EXT_mesh_gpu_instancing
extension. - Only meshes with TRIANGLES can be used to classify other assets.
- The meshes must be watertight.
- The POSITION attribute is required.
- If feature IDs and an index buffer are both present, all indices with the same feature id must occupy contiguous sections of the index buffer.
- If feature IDs are present without an index buffer, all positions with the same feature id must occupy contiguous sections of the position buffer.
The 3D Tiles or terrain receiving the classification must be opaque.
-
Default Value:
undefined
Experimental
This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
clippingPlanes : ClippingPlaneCollection
ClippingPlaneCollection
used to selectively disable rendering the model.
clippingPolygons : ClippingPolygonCollection
ClippingPolygonCollection
used to selectively disable rendering the model.
-
Default Value:
undefined
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
-
Default Value:
ColorBlendMode.HIGHLIGHT
readonly credit : Credit
customShader : CustomShader
Cesium3DTileStyle
may lead to undefined behavior.
Experimental
This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
Draws the bounding sphere for each draw command in the model.
-
Default Value:
false
Draws the model in wireframe.
-
Default Value:
false
distanceDisplayCondition : DistanceDisplayCondition
-
Default Value:
undefined
true
, the model is exaggerated along the ellipsoid normal when Scene.verticalExaggeration
is set to a value other than 1.0
.
-
Default Value:
true
Example:
// Exaggerate terrain by a factor of 2, but prevent model exaggeration
scene.verticalExaggeration = 2.0;
model.enableVerticalExaggeration = false;
readonly environmentMapManager : DynamicEnvironmentMapManager
Example:
// Change the ground color used for a model's environment map to a forest green
const environmentMapManager = model.environmentMapManager;
environmentMapManager.groundColor = Cesium.Color.fromCssColorString("#203b34");
readonly errorEvent : Event
ModelError
.
For EXT_mesh_features, this is the feature ID's label property, or "featureId_N" (where N is the index in the featureIds array) when not specified. EXT_feature_metadata did not have a label field, so such feature ID sets are always labeled "featureId_N" where N is the index in the list of all feature Ids, where feature ID attributes are listed before feature ID textures.
If featureIdLabel is set to an integer N, it is converted to the string "featureId_N" automatically. If both per-primitive and per-instance feature IDs are present, the instance feature IDs take priority.
Experimental
This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
heightReference : HeightReference
-
Default Value:
{HeightReference.NONE}
-
Default Value:
undefined
See:
imageBasedLighting : ImageBasedLighting
If instanceFeatureIdLabel is set to an integer N, it is converted to the string "instanceFeatureId_N" automatically. If both per-primitive and per-instance feature IDs are present, the instance feature IDs take priority.
Experimental
This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
lightColor : Cartesian3
undefined
the scene's light color is used instead.
Disabling additional light sources by setting
model.imageBasedLighting.imageBasedLightingFactor = new 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);
outlineColor : Color
-
Default Value:
Color.BLACK
pointCloudShading : PointCloudShading
Cesium3DTileset
.
true
, this model is ready to render, i.e., the external binary, image,
and shader files were downloaded and the WebGL resources were created.
-
Default Value:
false
readonly readyEvent : Event
Model
.
If Model.incrementallyLoadTextures
is true, this event will be raised before all textures are loaded and ready for rendering. Subscribe to Model.texturesReadyEvent
to be notified when the textures are ready.
Model#modelMatrix
.
Values greater than 1.0
increase the size of the model; values
less than 1.0
decrease.
-
Default Value:
1.0
-
Default Value:
ShadowMode.ENABLED
-
Default Value:
true
-
Default Value:
false
-
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
CustomShader
is also applied.
readonly texturesReadyEvent : Event
Model.incrementallyLoadTextures
is true, is raised when the model textures are loaded and ready for rendering, i.e. when the external resources
have been downloaded and the WebGL resources are created. Event listeners
are passed an instance of the Model
.
Methods
static Cesium.Model.fromGltfAsync(options) → Promise.<Model>
Asynchronously creates a model from a glTF asset. This function returns a promise that resolves 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 can be a traditional glTF asset with a .gltf extension or a Binary glTF using the .glb extension.
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
object |
Object with the following properties:
|
Returns:
Throws:
-
RuntimeError : The model failed to load.
-
RuntimeError : Unsupported glTF version.
-
RuntimeError : Unsupported glTF Extension
Examples:
// Load a model and add it to the scene
try {
const model = await Cesium.Model.fromGltfAsync({
url: "../../SampleData/models/CesiumMan/Cesium_Man.glb"
});
viewer.scene.primitives.add(model);
} catch (error) {
console.log(`Failed to load model. ${error}`);
}
// Position a model with modelMatrix and display it with a minimum size of 128 pixels
const position = Cesium.Cartesian3.fromDegrees(
-123.0744619,
44.0503706,
5000.0
);
const headingPositionRoll = new Cesium.HeadingPitchRoll();
const fixedFrameTransform = Cesium.Transforms.localFrameToFixedFrameGenerator(
"north",
"west"
);
try {
const model = await Cesium.Model.fromGltfAsync({
url: "../../SampleData/models/CesiumAir/Cesium_Air.glb",
modelMatrix: Cesium.Transforms.headingPitchRollToFixedFrame(
position,
headingPositionRoll,
Cesium.Ellipsoid.WGS84,
fixedFrameTransform
),
minimumPixelSize: 128,
});
viewer.scene.primitives.add(model);
} catch (error) {
console.log(`Failed to load model. ${error}`);
}
// Load a model and play the last animation at half speed
let animations;
try {
const model = await Cesium.Model.fromGltfAsync({
url: "../../SampleData/models/CesiumMan/Cesium_Man.glb",
gltfCallback: gltf => {
animations = gltf.animations
}
});
viewer.scene.primitives.add(model);
model.readyEvent.addEventListener(() => {
model.activeAnimations.add({
index: animations.length - 1,
loop: Cesium.ModelAnimationLoop.REPEAT,
multiplier: 0.5,
});
});
} catch (error) {
console.log(`Failed to load model. ${error}`);
}
Throws:
-
DeveloperError : The model is not loaded. Use Model.readyEvent 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:
Name | Type | Description |
---|---|---|
extensionName |
string | The name of the extension |
Returns:
Throws:
-
DeveloperError : The model is not loaded. Use Model.readyEvent or wait for Model.ready to be true.
Experimental
This feature is not final and is subject to change without Cesium's standard deprecation policy.
getNode(name) → ModelNode
name
in the glTF. This is used to
modify a node's transform for user-defined animation.
Name | Type | Description |
---|---|---|
name |
string | The name of the node in the glTF. |
Returns:
undefined
if no node with the name
exists.
Throws:
-
DeveloperError : The model is not loaded. Use Model.readyEvent or wait for Model.ready to be true.
Example:
// Apply non-uniform scale to node "Hand"
const node = model.getNode("Hand");
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:
Model#style
as dirty, which forces all features
to re-evaluate the style in the next frame the model is visible.
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.readyEvent or wait for Model.ready to be true.
Example:
// Sets the value of the stage named "MoveX" belonging to the articulation named "SampleArticulation"
model.setArticulationStage("SampleArticulation MoveX", 50.0);
See:
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.
Type Definitions
Name | Type | Description |
---|---|---|
gltf |
object | The gltf object |