Model - Cesium Documentation

# Model

#### new Model(options)

  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.

  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 The object for the glTF JSON or an arraybuffer of Binary glTF defined by the CESIUM_binary_glTF extension.
  `basePath` | 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.
  `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`.
  `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 draw command in the model.
  `debugWireframe` | Boolean | `false` | optional For debugging only. Draws the model in wireframe.

  ##### Throws:

  - DeveloperError : bgltf is not a valid Binary glTF file.
  - DeveloperError : Only glTF Binary version 1 is supported.

  ##### Demo:

  - Cesium Sandcastle Models Demo

  ##### See:

  - Model.fromGltf
  Source: Scene/Model.js, line 286

### 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 with `Scene#pick`. When `false`, 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:

  - Scene#pick
  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 to `true` right before `Model#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:

  - Model#ready
  Source: Scene/Model.js, line 658

#### scale :Number

  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`
  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 with `Scene#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 than `isDestroyed` will result in a `DeveloperError` 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:

  - Model#isDestroyed
  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 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.
  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 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.
  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 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);

  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 than `isDestroyed` will result in a `DeveloperError` exception.

  ##### Returns:

  `true` if this object was destroyed; otherwise, `false`.

  ##### See:

  - Model#destroy
  Source: Scene/Model.js, line 2929

#### update()

  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.
  Source: Scene/Model.js, line 2746