Class: Model

Methods

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

SuperMap3D supports glTF assets with the following extensions:

SUPERMAP3D_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 可选 The base path that paths in the glTF JSON are relative to. show Boolean true 可选 Determines if the model primitive will be shown. modelMatrix Matrix4 Matrix4.IDENTITY 可选 The 4x4 transformation matrix that transforms the model from model to world coordinates. scale Number 1.0 可选 A uniform scale applied to this model. minimumPixelSize Number 0.0 可选 The approximate minimum pixel size of the model regardless of zoom. maximumScale Number 可选 The maximum scale for the model. id Object 可选 A user-defined object to return when the model is picked with Scene#pick. allowPicking Boolean true 可选 When true, each glTF mesh and primitive is pickable with Scene#pick. incrementallyLoadTextures Boolean true 可选 Determine if textures may continue to stream in after the model is loaded. asynchronous Boolean true 可选 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 可选 Determines if the model's animations should hold a pose over frames where no keyframes are specified. shadows ShadowMode ShadowMode.ENABLED 可选 Determines whether the model casts or receives shadows from each light source. debugShowBoundingVolume Boolean false 可选 For debugging only. Draws the bounding sphere for each DrawCommand in the model. debugWireframe Boolean false 可选 For debugging only. Draws the model in wireframe. heightReference HeightReference 可选 Determines how the model is drawn relative to terrain. scene Scene 可选 Must be passed in for models that use the height reference property. distanceDisplayCondition DistanceDisplayCondition 可选 The condition specifying at what distance from the camera that this model will be displayed. color Color Color.WHITE 可选 A color that blends with the model's rendered color. colorBlendMode ColorBlendMode ColorBlendMode.HIGHLIGHT 可选 Defines how the color blends with the model. colorBlendAmount Number 0.5 可选 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 可选 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 可选 The size of the silhouette in pixels. clippingPlanes ClippingPlaneCollection 可选 The ClippingPlaneCollection used to selectively disable rendering the model. dequantizeInShader Boolean true 可选 Determines if a Draco encoded model is dequantized on the GPU. This decreases total memory usage for encoded models.

Returns:

Type	Description
Model	The newly created model.

Examples

// Example 1. Create a model from a glTF asset
var model = scene.primitives.add(SuperMap3D.Model.fromGltf({
  url : './duck/duck.gltf'
}));

// Example 2. Create model and provide all properties and events
var origin = SuperMap3D.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
var modelMatrix = SuperMap3D.Transforms.eastNorthUpToFixedFrame(origin);

var model = scene.primitives.add(SuperMap3D.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 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: Name Type Default Description url string | Resource The url to the .gltf or .glb file. basePath string | Resource '' 可选 The base path that paths in the glTF JSON are relative to. show boolean true 可选 Whether or not to render the model. modelMatrix Matrix4 Matrix4.IDENTITY 可选 The 4x4 transformation matrix that transforms the model from model to world coordinates. scale number 1.0 可选 A uniform scale applied to this model. minimumPixelSize number 0.0 可选 The approximate minimum pixel size of the model regardless of zoom. maximumScale number 可选 The maximum scale size of a model. An upper limit for minimumPixelSize. id object 可选 A user-defined object to return when the model is picked with Scene#pick. allowPicking boolean true 可选 When true, each primitive is pickable with Scene#pick. incrementallyLoadTextures boolean true 可选 Determine if textures may continue to stream in after the model is loaded. asynchronous boolean true 可选 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 可选 Determines if the model's animations should hold a pose over frames where no keyframes are specified. shadows ShadowMode ShadowMode.ENABLED 可选 Determines whether the model casts or receives shadows from light sources. releaseGltfJson boolean false 可选 When true, the glTF JSON is released once the glTF is loaded. This is is especially useful for cases like 3D Tiles, where each .gltf model is unique and caching the glTF JSON is not effective. debugShowBoundingVolume boolean false 可选 For debugging only. Draws the bounding sphere for each draw command in the model. enableDebugWireframe boolean false 可选 For debugging only. This must be set to true for debugWireframe to work in WebGL1. This cannot be set after the model has loaded. debugWireframe boolean false 可选 For debugging only. Draws the model in wireframe. Will only work for WebGL1 if enableDebugWireframe is set to true. cull boolean true 可选 Whether or not to cull the model using frustum/horizon culling. If the model is part of a 3D Tiles tileset, this property will always be false, since the 3D Tiles culling system is used. opaquePass boolean Pass.OPAQUE 可选 The pass to use in the DrawCommand for the opaque portions of the model. upAxis Axis Axis.Y 可选 The up-axis of the glTF model. forwardAxis Axis Axis.Z 可选 The forward-axis of the glTF model. customShader CustomShader 可选 A custom shader. This will add user-defined GLSL code to the vertex and fragment shaders. Using custom shaders with a Cesium3DTileStyle may lead to undefined behavior. content Cesium3DTileContent 可选 The tile content this model belongs to. This property will be undefined if model is not loaded as part of a tileset. heightReference HeightReference HeightReference.NONE 可选 Determines how the model is drawn relative to terrain. scene Scene 可选 Must be passed in for models that use the height reference property. distanceDisplayCondition DistanceDisplayCondition 可选 The condition specifying at what distance from the camera that this model will be displayed. color Color 可选 A color that blends with the model's rendered color. colorBlendMode ColorBlendMode ColorBlendMode.HIGHLIGHT 可选 Defines how the color blends with the model. colorBlendAmount number 0.5 可选 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 可选 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 可选 The size of the silhouette in pixels. enableShowOutline boolean true 可选 Whether to enable outlines for models using the CESIUM_primitive_outline extension. This can be set false to avoid post-processing geometry at load time. When false, the showOutlines and outlineColor options are ignored. showOutline boolean true 可选 Whether to display the outline for models using the CESIUM_primitive_outline extension. When true, outlines are displayed. When false, outlines are not displayed. outlineColor Color Color.BLACK 可选 The color to use when rendering outlines. clippingPlanes ClippingPlaneCollection 可选 The ClippingPlaneCollection used to selectively disable rendering the model. lightColor Cartesian3 可选 The light color when shading the model. When undefined the scene's light color is used instead. imageBasedLighting ImageBasedLighting 可选 The properties for managing image-based lighting on this model. backFaceCulling boolean true 可选 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 the model's color is translucent. credit Credit | string 可选 A credit for the data source, which is displayed on the canvas. showCreditsOnScreen boolean false 可选 Whether to display the credits of this model on screen. splitDirection SplitDirection SplitDirection.NONE 可选 The SplitDirection split to apply to this model. projectTo2D boolean false 可选 Whether to accurately project the model's positions in 2D. If this is true, the model will be projected accurately to 2D, but it will use more memory to do so. If this is false, the model will use less memory and will still render in 2D / CV mode, but its positions may be inaccurate. This disables minimumPixelSize and prevents future modification to the model matrix. This also cannot be set after the model has loaded. enablePick boolean false 可选 Whether to allow with CPU picking with pick when not using WebGL 2 or above. If using WebGL 2 or above, this option will be ignored. If using WebGL 1 and this is true, the pick operation will work correctly, but it will use more memory to do so. If running with WebGL 1 and this is false, the model will use less memory, but pick will always return undefined. This cannot be set after the model has loaded. featureIdLabel string | number "featureId_0" 可选 Label of the feature ID set to use for picking and styling. 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 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. instanceFeatureIdLabel string | number "instanceFeatureId_0" 可选 Label of the instance feature ID set used for picking and styling. 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. pointCloudShading object 可选 Options for constructing a PointCloudShading object to control point attenuation and lighting. classificationType ClassificationType 可选 Determines whether terrain, 3D Tiles or both will be classified by this model. This cannot be set after the model has loaded. gltfCallback Model.GltfCallback 可选 A function that is called with the loaded gltf object once loaded.

Throws:

• The model failed to load.

  Type

  RuntimeError

• Unsupported glTF version.

  Type

  RuntimeError

• Unsupported glTF Extension

  Type

  RuntimeError

Returns:

Type	Description
Promise.<Model>	A promise that resolves to the created model when it is ready to render.

Examples

// Load a model and add it to the scene
try {
 const model = await SuperMap3D.Model.fromGltfAsync({
   url: "./duck/duck.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 = SuperMap3D.Cartesian3.fromDegrees(
  -123.0744619,
  44.0503706,
  5000.0
);
const headingPositionRoll = new SuperMap3D.HeadingPitchRoll();
const fixedFrameTransform = SuperMap3D.Transforms.localFrameToFixedFrameGenerator(
  "north",
  "west"
);
try {
 const model = await SuperMap3D.Model.fromGltfAsync({
   url: "./duck/duck.glb",
   modelMatrix: SuperMap3D.Transforms.headingPitchRollToFixedFrame(
     position,
     headingPositionRoll,
     SuperMap3D.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 SuperMap3D.Model.fromGltfAsync({
   url: "./duck/duck.glb",
   gltfCallback: gltf => {
     animations = gltf.animations
   }
 });
 viewer.scene.primitives.add(model);
 model.readyEvent.addEventListener(() => {
   model.activeAnimations.add({
     index: animations.length - 1,
     loop: SuperMap3D.ModelAnimationLoop.REPEAT,
     multiplier: 0.5,
   });
 });
} catch (error) {
 console.log(`Failed to load model. ${error}`);
}

static silhouetteSupported(scene){Boolean}

Determines if silhouettes are supported.

Name	Type	Description
scene	Scene	The scene.

Returns:

Type	Description
Boolean	true if silhouettes are supported; otherwise, returns false

applyArticulations()

Applies any modified articulation stages to the matrix of each node that participates in any articulation. Note that this will overwrite any node transformations on participating nodes.

Throws:

The model is not loaded. Use Model.readyEvent or wait for Model.ready to be true.

Type

DeveloperError

destroy()

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.

See:

• Model#isDestroyed

Throws:

This object was destroyed, i.e., destroy() was called.

Type

DeveloperError

Example

model = model && model.destroy();

destroy()

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.

See:

• Model#isDestroyed

Throws:

This object was destroyed, i.e., destroy() was called.

Type

DeveloperError

Example

model = model && model.destroy();

getMaterial(name){ModelMaterial}

Returns the glTF material with the given name property.

Name	Type	Description
name	String	The glTF name of the material.

Throws:

The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.

Type

DeveloperError

Returns:

Type	Description
ModelMaterial	The material or undefined if no material with name exists.

getMesh(name){ModelMesh}

Returns the glTF mesh with the given name property.

Name	Type	Description
name	String	The glTF name of the mesh.

Throws:

The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.

Type

DeveloperError

Returns:

Type	Description
ModelMesh	The mesh or undefined if no mesh with name exists.

getNode(name){ModelNode}

Returns the node with the given 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.

Throws:

The model is not loaded. Use Model.readyEvent or wait for Model.ready to be true.

Type

DeveloperError

Returns:

Type	Description
ModelNode	The node, or undefined if no node with the name exists.

Example

// Apply non-uniform scale to node "Hand"
const node = model.getNode("Hand");
node.matrix = SuperMap3D.Matrix4.fromScale(new SuperMap3D.Cartesian3(5.0, 1.0, 1.0), node.matrix);

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.

Throws:

The model is not loaded. Use Model.readyPromise or wait for Model.ready to be true.

Type

DeveloperError

Returns:

Type	Description
ModelNode	The node or undefined if no node with name exists.

Example

// Apply non-uniform scale to node LOD3sp
var node = model.getNode('LOD3sp');
node.matrix = SuperMap3D.Matrix4.fromScale(new SuperMap3D.Cartesian3(5.0, 1.0, 1.0), node.matrix);

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.

See:

• Model#destroy

Returns:

Type	Description
boolean	true if this object was destroyed; otherwise, false.

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.

See:

• Model#destroy

Returns:

Type	Description
Boolean	true if this object was destroyed; otherwise, false.

makeStyleDirty()

Marks the model's Model#style as dirty, which forces all features to re-evaluate the style in the next frame the model is visible.

setArticulationStage(articulationStageKey, value)

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.

See:

• Model#applyArticulations

Throws:

The model is not loaded. Use Model.readyEvent or wait for Model.ready to be true.

Type

DeveloperError

Example

// Sets the value of the stage named "MoveX" belonging to the articulation named "SampleArticulation"
model.setArticulationStage("SampleArticulation MoveX", 50.0);

update()

Called when Viewer or Widget 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:

Failed to load external reference.

Type

RuntimeError

update()

Called when Viewer or Widget 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:

Failed to load external reference.

Type

RuntimeError

Type Definitions

GltfCallback(gltf)

Interface for the function that is called with the loaded gltf object once loaded.

Name	Type	Description
gltf	object	The gltf object