# Model

#### new Cesium.Model(options)
Scene/Model.js 242

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:

- 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:

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.
`imageBasedLightingFactor` | Cartesian2 | `Cartesian2(1.0, 1.0)` | optional Scales diffuse and specular image-based lighting from the earth, sky, atmosphere and star skybox.
`lightColor` | Cartesian3 |  | optional The light color when shading the model. When `undefined` the scene's light color is used instead.
`luminanceAtZenith` | Number | `0.2` | optional The sun's luminance at the zenith in kilo candela per meter squared to use for this model's procedural environment map.
`sphericalHarmonicCoefficients` | Array.<Cartesian3> |  | optional The third order spherical harmonic coefficients used for the diffuse color of image-based lighting.
`specularEnvironmentMaps` | String |  | optional A URL to a KTX2 file that contains a cube map of the specular lighting and the convoluted specular mipmaps.
`credit` | Credit | String |  | optional A credit for the data source, which is displayed on the canvas.
`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.
`gltfParsedCallback` | function |  | optional gltf解析完成回调，提供修改gltf对象能力,目前用于给材质添加法向贴图
`fillClip` | Boolean | `false` | optional 是否需要填充M3D数据剖面，在model构造函数中给的原因是，要想支持剖面选取高亮必须统计primitive的oid列表,为了节省内存,原始数据在加载完成后就会释放，后续没有时机统计oid列表
`hasSectionGeometry` | Boolean | `false` | optional 是否会存在剖面几何，如果后续会addSectionGeometry方法给m3d图层设置剖切面设置为true
`textureCoordScale` | Cartesian2 |  | optional 模型纹理拉伸比例，默认不发生变化

##### Demo:

- Cesium Sandcastle Models Demo

##### See:

- Model.fromGltf

### Members

#### activeAnimations : ModelAnimationCollection
Scene/Model.js 438

The currently playing glTF animations.

#### readonly allowPicking : Boolean
Scene/Model.js 911

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 895

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 514

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 basePath : String
Scene/Model.js 785

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: `''`

#### readonly boundingSphere : BoundingSphere
Scene/Model.js 808

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
    var center = Cesium.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new Cesium.Cartesian3());

#### clampAnimations : Boolean
Scene/Model.js 445

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

#### clippingPlanes : ClippingPlaneCollection
Scene/Model.js 1117

The `ClippingPlaneCollection` used to selectively disable rendering the model.

#### color : Color
Scene/Model.js 468

A color that blends with the model's rendered color.

Default Value: `Color.WHITE`

#### colorBlendAmount : Number
Scene/Model.js 489

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 478

Defines how the color blends with the model.

Default Value: `ColorBlendMode.HIGHLIGHT`

#### credit : Credit
Scene/Model.js 1280

Gets the credit that will be displayed for the model

#### debugShowBoundingVolume : Boolean
Scene/Model.js 539

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 552

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 972

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

Default Value: `undefined`

#### readonly 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.

Default Value: `undefined`

#### heightReference : HeightReference
Scene/Model.js 410

Returns the height reference of the model

Default Value: `HeightReference.NONE`

#### id : Object
Scene/Model.js 400

User-defined object returned when the model is picked.

Default Value: `undefined`

##### See:

- Scene#pick

#### imageBasedLightingFactor : Cartesian2
Scene/Model.js 1148

Cesium adds lighting from the earth, sky, atmosphere, and star skybox. This cartesian is used to scale the final diffuse and specular lighting contribution from those sources to the final color. A value of 0.0 will disable those light sources.

Default Value: `Cartesian2(1.0, 1.0)`

#### readonly incrementallyLoadTextures : Boolean
Scene/Model.js 930

Determine if textures may continue to stream in after the model is loaded.

Default Value: `true`

#### lightColor : Cartesian3
Scene/Model.js 1184

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.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`

#### luminanceAtZenith : Number
Scene/Model.js 1208

The sun's luminance at the zenith in kilo candela per meter squared to use for this model's procedural environment map. This is used when `Model#specularEnvironmentMaps` and `Model#sphericalHarmonicCoefficients` are not defined.

Default Value: `0.2`

##### Demo:

- Sandcastle Image Based Lighting Demo

#### maximumScale : Number
Scene/Model.js 388

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 378

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 353

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);

#### readonly pendingTextureLoads : Number
Scene/Model.js 944

Return the number of pending texture loads.

#### readonly ready : Boolean
Scene/Model.js 849

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 878

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({
        multiplier : 0.5
      });
    }).otherwise(function(error){
      window.alert(error);
    });

##### See:

- Model#ready

#### scale : Number
Scene/Model.js 366

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 458

Determines whether the model casts or receives shadows from light sources.

Default Value: `ShadowMode.ENABLED`

#### show : Boolean
Scene/Model.js 316

Determines if the model primitive will be shown.

Default Value: `true`

#### readonly showOutline : Boolean
Scene/Model.js 526

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 325

The silhouette color.

Default Value: `Color.RED`

#### silhouetteSize : Number
Scene/Model.js 337

The size of the silhouette in pixels.

Default Value: `0.0`

#### specularEnvironmentMaps : String
Scene/Model.js 1266

A URL to a KTX2 file that contains a cube map of the specular lighting and the convoluted specular mipmaps.

##### Demo:

- Sandcastle Image Based Lighting Demo

##### See:

- Model#sphericalHarmonicCoefficients

#### sphericalHarmonicCoefficients : Array.<Cartesian3>
Scene/Model.js 1240

The third order spherical harmonic coefficients used for the diffuse color of image-based lighting. When `undefined`, a diffuse irradiance computed from the atmosphere color is used.

There are nine `Cartesian3` coefficients. The order of the coefficients is: L00, L1-1, L10, L11, L2-2, L2-1, L20, L21, L22

These values can be obtained by preprocessing the environment map using the `cmgen` tool of Google's Filament project. This will also generate a KTX file that can be supplied to `Model#specularEnvironmentMaps`.

##### Demo:

- Sandcastle Image Based Lighting Demo

##### See:

- An Efficient Representation for Irradiance Environment Maps

### Methods

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

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:

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.
`credit` | Credit | String |  | optional A credit for the model, which is displayed on the canvas.
`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
    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();
    });

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

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 1710

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 5565

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:

- Model#isDestroyed

#### getMaterial(name) → ModelMaterial
Scene/Model.js 1589

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 1577

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 1563

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
    var 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 5545

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:

- Model#destroy

#### setArticulationStage(articulationStageKey, value)
Scene/Model.js 1604

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:

- Model#applyArticulations

#### update()
Scene/Model.js 4911

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:

- RuntimeError : Failed to load external reference.