Cesium API - Model 中文文档

new Cesium.Model(options)

基于glTF的3D模型，此格式被WebGL、OpenGL ES和OpenGL所使用。

Cesium包括对几何体、材质、glTF动画和glTF蒙皮的支持。此外，可以使用 Scene#pick 拾取单个glTF节点，使用Model#getNode创建动画。目前不支持glTF相机和灯光。

用Model.fromGltf创建外部的glTF。glTF JSON也可以在运行时创建并传递给这个构造函数。不论发生何种情况，Model#readyPromise在模型准备渲染时被解析，即，当下载外部二进制文件、图像和着色器文件并创建WebGL资源时。

Cesium 支持下列扩展的glTF：

对于高精度渲染，Cesium支持CESIUM_RTC 扩展, 它引入了CESIUM_RTC_MODELVIEW参数语义，该语义表示节点在相对于本地原点的WGS84坐标中被转换。

Name Type Description

options

Object

optional 具有下列属性的对象：

Name	Type	Default	Description
`gltf`	Object \| ArrayBuffer \| Uint8Array		optional glTF JSON对象，或二进制glTF缓冲区。
`basePath`	Resource \| 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文件之前被阻塞。
`clampAnimations`	Boolean	`true`	optional 确定模型的动画是否应该在没有指定关键帧的帧上保持一个姿态。
`shadows`	ShadowMode	`ShadowMode.ENABLED`	optional 确定模型是否从每个光源投射或接收阴影。
`debugShowBoundingVolume`	Boolean	`false`	optional 仅用于调试。是否为模型中的每个绘制命令绘制包围球。
`debugWireframe`	Boolean	`false`	optional 仅用于调试，是否绘制模型线框。
`heightReference`	HeightReference	`HeightReference.NONE`	optional 确定如何相对于地形绘制模型。
`scene`	Scene		optional 如果heightReference不为NONE，必须传递此属性。
`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 轮廓的颜色。
`silhouetteSize`	Number	`0.0`	optional 轮廓的大小（以像素为单位）。
`clippingPlanes`	ClippingPlaneCollection		optional `ClippingPlaneCollection`用于有选择地禁用模型的渲染。
`dequantizeInShader`	Boolean	`true`	optional 确定Draco编码的模型是否在GPU上去量化（dequantized）。这减少了编码模型的总内存使用量。
`imageBasedLightingFactor`	Cartesian2	`Cartesian2(1.0, 1.0)`	optional 从地球，天空，大气和星空盒的漫反射和镜面反射的高光图像为基础的光照。
`lightColor`	Cartesian3		optional 用于遮罩模型的阳光的颜色和强度。
`luminanceAtZenith`	Number	`0.2`	optional 太阳在天顶的亮度单位为千坎德拉每平方米，用于该模型的程序环境地图。
`sphericalHarmonicCoefficients`	Array.<Cartesian3>		optional 三阶球谐函数系数用于基于图像的光照漫反射颜色。
`specularEnvironmentMaps`	String		optional 一个指向KTX文件的URL，该文件包含镜面反射光照和复杂的镜面反射贴图的立方体映射。
`credit`	Credit \| String		optional 显示在画布上的数据源的版权。

演示Demo：

Cesium Sandcastle Models Demo

参考：

Model.fromGltf

成员变量

activeAnimations : ModelAnimationCollection

Scene/Model.js 403

当前正在播放的glTF动画。

readonlyallowPicking : Boolean

Scene/Model.js 805

当为true时，可以使用Scene#pick拾取模型。当false时，GPU内存被节约。

Default Value: true

readonlyasynchronous : Boolean

Scene/Model.js 788

确定模型WebGL资源的创建是否会分散在几个帧中，或者在加载完所有glTF文件之前被阻塞。

Default Value: true

readonlybasePath : String

Scene/Model.js 682

glTF JSON中路径的基本路径是相对的。当二进制文件、图像和着色器文件位于与.gltf相同的目录中时，基本路径与包含.gltf文件减去.gltf文件的路径相同。当这是''时，使用应用程序的基本路径。

Default Value: ''

readonlyboundingSphere : BoundingSphere

Scene/Model.js 704

模型在其局部坐标系中的包围球。这并没有考虑到glTF动画和蒙皮，也没有考虑到Model#minimumPixelSize。使用Model.readyPromise或等待Model.ready变为true。

Default Value: undefined

示例：

// 在WGS84坐标系中的中心点
var center = Cesium.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new Cesium.Cartesian3());

clampAnimations : Boolean

Scene/Model.js 410

确定模型的动画是否应该在没有指定关键帧的帧上保持一个姿态。

clippingPlanes : ClippingPlaneCollection

Scene/Model.js 996

ClippingPlaneCollection用于有选择地禁用模型的渲染。

color : Color

Scene/Model.js 433

与模型混合的颜色。

Default Value: Color.WHITE

colorBlendAmount : Number

Scene/Model.js 453

当colorBlendMode是MIX时，用来确定颜色强度的值。 0.0的值表示模型的渲染颜色，1.0的值表示纯色，介于两者之间的值表示两者的混合。

Default Value: 0.5

colorBlendMode : ColorBlendMode

Scene/Model.js 443

定义颜色与模型的混合模式。

Default Value: ColorBlendMode.HIGHLIGHT

credit : Credit

Scene/Model.js 1154

获取将为模型显示的版权。

debugShowBoundingVolume : Boolean

Scene/Model.js 476

此属性仅用于调试；它既不用于生产，也不是最优的。

为模型中的每个绘制命令绘制包围球。

Default Value: false

debugWireframe : Boolean

Scene/Model.js 489

此属性仅用于调试；它既不用于生产，也不是最优的。

用线框模式绘制模型。

Default Value: false

distanceDisplayCondition : DistanceDisplayCondition

Scene/Model.js 863

设置或获取模型到相机的显示距离。

Default Value: undefined

readonlygltf : Object

Scene/Model.js 622

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

Default Value: undefined

heightReference : HeightReference

Scene/Model.js 375

返回模型的高度参考。（紧贴地形，相对于地形的高度等）

Default Value: HeightReference.NONE

id : Object

Scene/Model.js 365

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

Default Value: undefined

参考：

Scene#pick

imageBasedLightingFactor : Cartesian2

Scene/Model.js 1027

Cesium增加了来自地球、天空、大气和星空盒的光线。这个笛卡儿是用来衡量最终漫反射和镜面反射光照的贡献，从这些源到最终的颜色。0.0的值将禁用这些光源。

Default Value: Cartesian2(1.0,1.0)

readonlyincrementallyLoadTextures : Boolean

Scene/Model.js 821

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

Default Value: true

lightColor : Cartesian3

Scene/Model.js 1060

用于遮挡模型的阳光的颜色和强度。

例如，通过设置 model.imageBasedLightingFactor = new Cesium.Cartesian2(0.0，0.0)来禁用其他光源，模型要暗得多。在这里，增加光源的强度会使模型更亮。

Default Value: undefined

luminanceAtZenith : Number

Scene/Model.js 1084

太阳在天顶的亮度单位为千坎德拉每平方米，用于该模型的程序环境地图。当Model#specularEnvironmentMaps和Model#sphericalHarmonicCoefficients未定义时使用。

Default Value: 0.2

演示Demo：

Sandcastle Image Based Lighting Demo

maximumScale : Number

Scene/Model.js 353

这可以用来给Model#minimumPixelSize一个上限，确保模型永远不会是一个不合理的比例。

minimumPixelSize : Number

Scene/Model.js 345

不考虑缩放的模型的近似最小像素大小。这可以用来确保即使在查看器缩小时模型也是可见的。当0.0时，不强制执行最小大小。

Default Value: 0.0

modelMatrix : Matrix4

Scene/Model.js 322

将模型转换为世界坐标的4x4变换矩阵。当这是单位矩阵时，模型在世界坐标中绘制，即地球的WGS84坐标。本地参考系可以通过提供一个不同的转换矩阵来使用，比如Transforms.eastNorthUpToFixedFrame返回的转换矩阵。

Default Value: Matrix4.IDENTITY

示例：

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

readonlypendingTextureLoads : Number

Scene/Model.js 835

返回待处理纹理加载的数量。

readonlyready : Boolean

Scene/Model.js 744

当true时，该模型准备渲染，即下载了外部二进制文件、图像和着色器文件，并创建了WebGL资源。这个设置为true，就在Model#readyPromise解析之前。

Default Value: false

readonlyreadyPromise : Promise.<Model>

Scene/Model.js 772

获取将在此模型准备渲染时解析的Promise，即，当下载外部二进制文件、图像和着色器文件并创建WebGL资源时。

这个promise在模型的第一帧被渲染之前的帧结束时被解析。

示例：

// 当模型准备渲染时，以半速播放所有动画
Cesium.when(model.readyPromise).then(function(model) {
  model.activeAnimations.addAll({
    multiplier : 0.5
  });
}).otherwise(function(error){
  window.alert(error);
});

参考：

Model#ready

scale : Number

Scene/Model.js 334

在Model#modelMatrix之前应用于此模型的均匀缩放。大于1.0模型变大；小于1.0模型减少。

Default Value: 1.0

shadows : ShadowMode

Scene/Model.js 423

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

Default Value: ShadowMode.ENABLED

show : Boolean

Scene/Model.js 286

模型是否显示。

Default Value: true

silhouetteColor : Color

Scene/Model.js 295

轮廓的颜色。

Default Value: Color.RED

silhouetteSize : Number

Scene/Model.js 307

轮廓的大小（以像素为单位）。

Default Value: 0.0

specularEnvironmentMaps : String

Scene/Model.js 1140

一个指向KTX文件的URL，该文件包含镜面反射光照和复杂的镜面反射贴图的立方体映射。

演示Demo：

Sandcastle Image Based Lighting Demo

参考：

Model#sphericalHarmonicCoefficients

sphericalHarmonicCoefficients : Array.<Cartesian3>

Scene/Model.js 1114

三阶球谐函数系数用于基于图像的光照漫反射颜色。当undefined时，使用大气颜色计算漫反射辐照度。

有9个Cartesian3系数。系数的顺序是：L₀₀，L_1-1，L₁₀，L₁₁，L_2-2，L_2-1，L₂₀，L₂₁，L₂₂。

这些值可以通过使用Google's Filament project的cmgen工具对环境图进行预处理得到。这还将生成一个KTX文件，该文件可以提供给Model#specularEnvironmentMaps。

演示Demo：

Sandcastle Image Based Lighting Demo

参考：

An Efficient Representation for Irradiance Environment Maps

内置方法

staticCesium.Model.fromGltf(options) → Model

Scene/Model.js 1290

基于glTF的3D模型。当模型准备好渲染时，即，当下载外部二进制文件、图像和着色器文件并创建WebGL资源时，将解析Model#readyPromise。

该模型可以是扩展名为.gltf的传统glTF文件，也可以是扩展名为.glb的二进制glTF。

Cesium支持具有以下扩展名的glTF：

对于高精度的渲染，Cesium支持CESIUM_RTC扩展，它引入了CESIUM_RTC_MODELVIEW参数语义，表示节点在相对于本地原点的WGS84坐标中被转换。

Name Type Description

options

Object

optional 具有下列属性的对象：

Name	Type	Default	Description
`gltf`	Object \| ArrayBuffer \| Uint8Array		optional glTF JSON对象，或二进制glTF缓冲区。
`basePath`	Resource \| 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文件之前被阻塞。
`clampAnimations`	Boolean	`true`	optional 确定模型的动画是否应该在没有指定关键帧的帧上保持一个姿态。
`shadows`	ShadowMode	`ShadowMode.ENABLED`	optional 确定模型是否从每个光源投射或接收阴影。
`debugShowBoundingVolume`	Boolean	`false`	optional 仅用于调试。是否为模型中的每个绘制命令绘制包围球。
`debugWireframe`	Boolean	`false`	optional 仅用于调试，是否绘制模型线框。
`heightReference`	HeightReference	`HeightReference.NONE`	optional 确定如何相对于地形绘制模型。
`scene`	Scene		optional 如果heightReference不为NONE，必须传递此属性。
`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 轮廓的颜色。
`silhouetteSize`	Number	`0.0`	optional 轮廓的大小（以像素为单位）。
`clippingPlanes`	ClippingPlaneCollection		optional `ClippingPlaneCollection`用于有选择地禁用模型的渲染。
`dequantizeInShader`	Boolean	`true`	optional 确定Draco编码的模型是否在GPU上去量化（dequantized）。这减少了编码模型的总内存使用量。
`imageBasedLightingFactor`	Cartesian2	`Cartesian2(1.0, 1.0)`	optional 从地球，天空，大气和星空盒的漫反射和镜面反射的高光图像为基础的光照。
`lightColor`	Cartesian3		optional 用于遮罩模型的阳光的颜色和强度。
`luminanceAtZenith`	Number	`0.2`	optional 太阳在天顶的亮度单位为千坎德拉每平方米，用于该模型的程序环境地图。
`sphericalHarmonicCoefficients`	Array.<Cartesian3>		optional 三阶球谐函数系数用于基于图像的光照漫反射颜色。
`specularEnvironmentMaps`	String		optional 一个指向KTX文件的URL，该文件包含镜面反射光照和复杂的镜面反射贴图的立方体映射。
`credit`	Credit \| String		optional 显示在画布上的数据源的版权。

返回值：

新创建的模型。

示例：

// 例1：从glTF文件创建一个模型
var model = scene.primitives.add(Cesium.Model.fromGltf({
  url : './duck/duck.gltf'
}));

// 例2：创建模型并提供所有属性和事件
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,                     // 默认的
  modelMatrix : modelMatrix,
  scale : 2.0,                     // 双倍大小
  minimumPixelSize : 128,          // 从不小于128像素
  maximumScale: 20000,             // 不大于20000*模型尺寸 （重写minimumPixelSize）
  allowPicking : false,            // 不能拾取
  debugShowBoundingVolume : false, // 默认的
  debugWireframe : false
}));
model.readyPromise.then(function(model) {
  // 当模型准备渲染时播放所有动画
  model.activeAnimations.addAll();
});

staticCesium.Model.silhouetteSupported(scene) → Boolean

Scene/Model.js 1180

确定轮廓是否被支持。

Name	Type	Description
`scene`	Scene	场景（Scene对象）

返回值：

如果支持轮廓，返回true

applyArticulations()

Scene/Model.js 1547

将任何修改过的关节阶段应用于参与任何关节的每个节点的矩阵。注意，这将覆盖参与节点上的任何nodeTransformations。

异常情况：

DeveloperError : 模型没有加载。使用Model.readyPromise或等待Model.ready变为true。

destroy()

Scene/Model.js 4988

销毁此对象持有的WebGL资源。

一旦对象被销毁，它将不能在使用; 调用除isDestroyed之外的任何函数都会导致DeveloperError异常。因此，将返回值(undefined)赋给对象，如示例所示。

异常情况：

DeveloperError : 对象已经被销毁。

示例：

model = model && model.destroy();

参考：

Model#isDestroyed

getMaterial(name) → ModelMaterial

Scene/Model.js 1430

返回具有给定name属性的glTF材质。

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

返回值：

返回的模型材质。

异常情况：

DeveloperError : 模型没有成功加载。

getMesh(name) → ModelMesh

Scene/Model.js 1418

使用给定的name属性返回glTF网格。

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

返回值：

返回的网格。

异常情况：

DeveloperError : 模型没有成功加载。

getNode(name) → ModelNode

Scene/Model.js 1404

返回具有给定的name属性的glTF节点。这用于在glTF动画之外修改节点的动画转换。

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

返回值：

返回的模型节点。

异常情况：

DeveloperError : 模型没有成功加载。

示例：

//对名字为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 4971

如果该对象没被销毁，返回false。

如果该对象已经被销毁，使用isDestroyed 会触发 DeveloperError 异常。

返回值：

false

参考：