Model - SuperMap3D Documentation

new SuperMap3D.Model(options)

基于 glTF 的 3D 模型，glTF 是 WebGL、OpenGL ES 和 OpenGL 的运行时资产格式。

SuperMap3D支持几何体和材质、glTF动画以及 glTF 皮肤。此外，单个glTF节点可使用Scene#pick 挑选，并可使用Model#getNode动画。

glTF JSON 也可以在运行时创建并传递给此构造函数。无论哪种情况，Model#readyPromise 都会在模型准备好渲染（即下载外部二进制文件、影像和着色器文件并创建 WebGL 资源）时解析。

为实现高精度渲染，SuperMap3D 支持 CESIUM_RTC 扩展，该扩展引入了 CESIUM_RTC_MODELVIEW 参数语义，表示节点以 WGS84 坐标相对于本地原点进行平移。

Name Type Description

options

Object

optional 具有以下属性的对象:

Name	Type	Default	Description
`gltf`	Object \| ArrayBuffer \| Uint8Array		optional glTF JSON 对象或由 KHR_binary_glTF 扩展定义的二进制 glTF arraybuffer。
`basePath`	String	`''`	optional glTF JSON 中路径相对的基本路径。
`show`	Boolean	`true`	optional 确定是否显示模型基元。
`modelMatrix`	Matrix4	`Matrix4.IDENTITY`	optional 将模型从模型坐标转换到地理坐标的 4x4 变换矩阵。
`scale`	Number	`1.0`	optional 该模型采用统一的比例尺。
`minimumPixelSize`	Number	`0.0`	optional 无论变焦与否，模型的近似最小像素尺寸。
`maximumScale`	Number		optional 模型的最大比例尺寸。最小像素尺寸的上限。
`id`	Object		optional 用户自定义对象，当使用 `Scene#pick` 选取模型时返回。
`allowPicking`	Boolean	`true`	optional 当为true时，每个glTF网格和基元都可以使用`Scene#pick`进行拾取。
`incrementallyLoadTextures`	Boolean	`true`	optional 确定纹理是否可以在模型加载后继续流进。
`asynchronous`	Boolean	`true`	optional 确定模型WebGL资源的创建是分散在多个帧中进行，还是在加载所有glTF文件后分块完成。
`shadows`	ShadowMode	`ShadowMode.ENABLED`	optional 确定模型是从每个光源投射阴影还是接收阴影。
`debugShowBoundingVolume`	Boolean	`false`	optional 仅用于调试。为模型中的每个绘制命令绘制包围球。
`debugWireframe`	Boolean	`false`	optional 仅用于调试。绘制线框模型。
`heightReference`	HeightReference		optional 确定模型相对于地形的绘制方式。
`scene`	Scene		optional 必须用于使用高度参考属性的模型。
`addBatchIdToGeneratedShaders`	Boolean	`false`	optional 确定使用 KHR_materials_common 扩展为材质生成的着色器是否应包含批次 ID 属性。适用于包含在 b3dm 瓦片中的模型。
`distanceDisplayCondition`	DistanceDisplayCondition		optional 指定在距离相机多远的位置显示此模型的条件。
`color`	Color	`Color.WHITE`	optional 与模型渲染颜色相融合的颜色。
`colorBlendMode`	ColorBlendMode	`ColorBlendMode.HIGHLIGHT`	optional 定义颜色与模型的融合方式。
`colorBlendAmount`	Number	`0.5`	optional 当 colorBlendMode（混合模式）为 MIX 时，用于确定颜色强度的值。值为 0.0 时，将显示模型的渲染颜色，而值为 1.0 时，将显示纯色，任何介于两者之间的值都将显示两者的混合色。
`silhouetteColor`	Color	`Color.RED`	optional 轮廓颜色。如果有超过 256 个模型启用了轮廓功能，重叠的模型就有可能出现细微的伪影。
`silhouetteSize`	Number	`0.0`	optional 轮廓的大小（以像素为单位）。
`cacheKey`	String		optional 模型的cacheKey。

Throws:

DeveloperError : bgltf 不是有效的二进制 glTF 文件。
DeveloperError : 仅支持 glTF 二进制 1 版本。

See:

Model.fromGltf

Members

activeAnimations : ModelAnimationCollection

当前播放的 glTF 动画。

readonlyallowPicking : Boolean

当为true时，每个 glTF 网格和基元都可使用 Scene#pick 挑选。为false时将保存 GPU 内存。

Default Value: true

readonlyasynchronous : Boolean

确定模型 WebGL 资源的创建是分散在多个帧中进行，还是在加载所有 glTF 文件后分块完成。

Default Value: true

readonlybasePath : String

glTF JSON 中路径相对于的基本路径。当二进制文件、影像文件和着色器文件与 .gltf 文件位于同一目录时，基本路径与包含 .gltf 文件的路径相同。如果为''，则使用应用程序的基本路径。

Default Value: ''

readonlyboundingSphere : BoundingSphere

模型在其本地坐标系中的包围球。这没有考虑到glTF动画和皮肤，也没有考虑到Model#minimumPixelSize。

Default Value: undefined

Example:

// Center in WGS84 coordinates
var center = SuperMap3D.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new SuperMap3D.Cartesian3());

color : Color

与模型渲染颜色相融合的颜色。

Default Value: Color.WHITE

colorBlendAmount : Number

当 colorBlendMode（混合模式）为 MIX 时，用于确定颜色强度的值。值为 0.0 时，将显示模型的渲染颜色，而值为 1.0 时，将显示纯色，任何介于两者之间的值都将显示两者的混合效果。

Default Value: 0.5

colorBlendMode : ColorBlendMode

定义颜色与模型的融合方式。

Default Value: ColorBlendMode.HIGHLIGHT

debugShowBoundingVolume : Boolean

该属性仅用于调试，不用于生产，也未优化。

为模型中的每个绘制命令绘制包围球。一个 glTF 基元对应一条绘制命令。一个 glTF 网格有一个基元数组，通常长度为1。

Default Value: false

debugWireframe : Boolean

此属性仅用于调试，它不是用于生产的，也没有经过优化。

Draws the model in wireframe.

Default Value: false

distanceDisplayCondition : DistanceDisplayCondition

获取或设置条件，指定在距离相机多远的位置显示此模型。

Default Value: undefined

readonlygltf : Object

glTF JSON的对象，包括从提供给该模型的JSON中省略的带有默认值的属性。

Default Value: undefined

id : Object

选取模型时返回的用户自定义对象。

Default Value: undefined

See:

Scene#pick

readonlyincrementallyLoadTextures : Boolean

确定纹理是否可以在模型加载后继续流进。

Default Value: true

maximumScale : Number

模型的最大比例尺寸。它可以用来给Model#minimumPixelSize 设定一个上限，确保模型的比例合理。

minimumPixelSize : Number

无论缩放与否，模型的近似最小像素尺寸。该值可用于确保即使在查看器缩放时也能看到模型。0.0 时，不执行最小尺寸。

Default Value: 0.0

modelMatrix : Matrix4

将模型从模型坐标转换到地理坐标的 4x4 变换矩阵。当变换矩阵为同一矩阵时，模型将以地理坐标绘制，即WGS84 坐标。本地参照系可以通过提供不同的变换矩阵来使用，如 Transforms.eastNorthUpToFixedFrame 返回的矩阵。

Default Value: Matrix4.IDENTITY

Example:

var origin = SuperMap3D.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
m.modelMatrix = SuperMap3D.Transforms.eastNorthUpToFixedFrame(origin);

readonlypendingTextureLoads : Number

返回待加载纹理的次数。

readonlyready : Boolean

为true时，此模型已准备好渲染，即外部二进制文件、影像和着色器文件已下载，WebGL 资源已创建。在 Model#readyPromise 解析之前，该参数将被设置为 true。

Default Value: false

readonlyreadyPromise : Promise.<Model>

获取当此模型准备好渲染时（即下载外部二进制文件、影像和着色器文件以及创建 WebGL 资源时）将解析的promise。

该promise会在渲染模型的第一帧之前的帧末解析。

Example:

// Play all animations at half-speed when the model is ready to render
SuperMap3D.when(model.readyPromise).then(function(model) {
  model.activeAnimations.addAll({
    speedup : 0.5
  });
}).otherwise(function(error){
  window.alert(error);
});

See:

Model#ready

scale : Number

在Model#modelMatrix 之前应用于此模型的统一缩放比例。大于 1.0 的值会增大模型的大小；小于 1.0 的值会减小模型的大小。

Default Value: 1.0

shadows : ShadowMode

确定模型是从每个光源投射阴影还是接收阴影。

Default Value: ShadowMode.ENABLED

show : Boolean

确定是否显示模型基元。

Default Value: true

silhouetteColor : Color

轮廓颜色。

Default Value: Color.RED

silhouetteSize : Number

轮廓的大小（像素）。

Default Value: 0.0

Methods

staticSuperMap3D.Model.fromGltf(options) → Model

根据 glTF 资产创建模型。当模型准备好渲染时，即下载外部二进制文件、影像和着色器文件并创建 WebGL 资源时，Model#readyPromise 将被解析。

模型可以是扩展名为 .gltf 的传统 glTF 资产，也可以是使用 KHR_binary_glTF 扩展名为 .glb 的二进制 glTF。

为实现高精度渲染，SuperMap3D 支持 CESIUM_RTC 扩展，该扩展引入了 CESIUM_RTC_MODELVIEW 参数语义，表示节点以 WGS84 坐标相对于本地原点进行平移。

Name Type Description

options

Object

具有以下属性的对象:

Name	Type	Default	Description
`url`	String		.gltf 文件的 URL。
`headers`	Object		optional 与请求一起发送的 HTTP 标头。
`basePath`	String		optional glTF JSON 中路径相对的基本路径。
`show`	Boolean	`true`	optional 确定是否显示模型基元。
`modelMatrix`	Matrix4	`Matrix4.IDENTITY`	optional 将模型从模型坐标转换到地理坐标的 4x4 变换矩阵。
`scale`	Number	`1.0`	optional 该模型采用统一的比例尺。
`minimumPixelSize`	Number	`0.0`	optional 无论变焦与否，模型的近似最小像素尺寸。
`maximumScale`	Number		optional 模型的最大比例尺。
`id`	Object		optional 用户自定义对象，当使用 `Scene#pick` 选取模型时返回。
`allowPicking`	Boolean	`true`	optional 当为true时，每个 glTF 网格和基元都可以使用 `Scene#pick` 进行拾取。
`incrementallyLoadTextures`	Boolean	`true`	optional 确定纹理是否可以在模型加载后继续流进。
`asynchronous`	Boolean	`true`	optional 确定模型 WebGL 资源的创建是分散在多个帧中进行，还是在加载所有 glTF 文件后分块完成。
`shadows`	ShadowMode	`ShadowMode.ENABLED`	optional 确定模型是从每个光源投射阴影还是接收阴影。
`debugShowBoundingVolume`	Boolean	`false`	optional 仅用于调试。为模型中的每个 `DrawCommand` 绘制包围球。
`debugWireframe`	Boolean	`false`	optional 仅用于调试。绘制线框模型。

Returns:

The newly created model.

Throws:

DeveloperError : bgltf 不是有效的二进制 glTF 文件。
DeveloperError : 仅支持 glTF 二进制 1 版本。

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

staticSuperMap3D.Model.silhouetteSupported(scene) → Boolean

确定是否支持轮廓。

Name	Type	Description
`scene`	Scene	场景。

Returns:

如果支持轮廓，则返回 true；否则，返回 false。

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

getMaterial(name) → ModelMaterial

返回带有给定名称属性的 glTF 材质。

Name	Type	Description
`name`	String	材质的glTF名称。

Returns:

如果没有同名材质，则未定义。

Throws:

DeveloperError : 模型未加载。请使用 Model.readyPromise 或等待 Model.ready 为true。

getMesh(name) → ModelMesh

返回带有给定名称属性的 glTF 网格。

Name	Type	Description
`name`	String	网格的glTF名称。

Returns:

如果没有同名的网格，则未定义。

Throws:

DeveloperError : 模型未加载。请使用 Model.readyPromise 或等待 Model.ready 为true。

getNode(name) → ModelNode

返回具有给定名称属性的 glTF 节点。此属性用于修改节点的变换，以便在 glTF 动画之外制作动画。

Name	Type	Description
`name`	String	节点的 glTF 名称。

Returns:

如果没有同名的节点，则未定义。

Throws:

DeveloperError : 模型未加载。请使用 Model.readyPromise 或等待 Model.ready 为true。

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.

Returns:

true if this object was destroyed; otherwise, false.

See:

Model#destroy

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:

RuntimeError : Failed to load external reference.