Model

new Cesium.Model ( options )

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

Cesium 包括对几何和材质、glTF 动画和 glTF 蒙皮的支持。此外,单个 glTF 节点可以通过 Scene#pick 并通过 Model#getNode 动画化。目前不支持 glTF 相机和灯光。

使用 Model.fromGltf 创建外部 Model.fromGltf 资产。 glTF JSON 也可以在运行时创建并传递给这个构造函数。在任何一种情况下, Model#readyPromise 都会在模型准备好渲染时解析,即下载外部二进制文件、图像和着色器文件并创建 WebGL 资源时。

Cesium 支持具有以下扩展的 glTF 资产:

注意:对于使用 KHR_texture_basisu 扩展的压缩纹理模型,我们建议在两个维度上使用 2 个纹理的幂,以获得最大的兼容性。这是因为一些采样器需要 2 个纹理的幂( 在 WebGL 中使用纹理 ),而 KHR_texture_basisu 需要 4 个维度的倍数( KHR_texture_basisu 附加要求 )。

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

Name Type Description
options Object 具有以下属性的 可选 对象:
姓名 类型 默认 描述
gltf 对象 | 数组缓冲区 | Uint8Array 可选 glTF JSON 对象,或二进制 glTF 缓冲区。
basePath 资源 | 细绳 '' 可选 glTF JSON 中的路径相对于的基本路径。
show 布尔值 true 可选 确定是否显示模型原语。
modelMatrix 矩阵4 Matrix4.IDENTITY 可选 将模型从模型转换为世界坐标的 4x4 转换矩阵。
scale 数字 1.0 可选 应用于此模型的统一比例。
minimumPixelSize 数字 0.0 可选 无论缩放如何,模型的近似最小像素大小。
maximumScale 数字 可选 模型的最大比例大小。 minimumPixelSize 的上限。
id 目的 可选 使用 Scene#pick 拾取模型时要返回的用户定义对象。
allowPicking 布尔值 true 可选 true 时,每个 glTF 网格和图元都可以使用 Scene#pick 进行拾取。
incrementallyLoadTextures 布尔值 true 可选 确定加载模型后纹理是否可以继续流入。
asynchronous 布尔值 true 可选 确定模型 WebGL 资源创建是否将分散到多个帧或阻塞,直到加载所有 glTF 文件后完成。
clampAnimations 布尔值 true 可选 确定模型的动画是否应在未指定关键帧的帧上保持姿势。
shadows 阴影模式 ShadowMode.ENABLED 可选 确定模型是投射还是接收来自光源的阴影。
debugShowBoundingVolume 布尔值 false 可选 仅用于调试。为模型中的每个绘制命令绘制边界球体。
debugWireframe 布尔值 false 可选 仅用于调试。在线框中绘制模型。
heightReference 高度参考 HeightReference.NONE 可选 确定模型相对于地形的绘制方式。
scene 场景 可选 对于使用高度参考属性的模型,必须传入。
distanceDisplayCondition 距离显示条件 可选 指定该模型将在距相机多远的距离处显示的条件。
color 颜色 Color.WHITE 可选 与模型渲染颜色混合的颜色。
colorBlendMode 颜色混合模式 ColorBlendMode.HIGHLIGHT 可选 定义颜色如何与模型混合。
colorBlendAmount 数字 0.5 可选 colorBlendMode MIX 时用于确定颜色强度的值。值 0.0 会导致模型的渲染颜色,而值 1.0 会导致纯色,介于两者之间的任何值都会导致两者混合。
silhouetteColor 颜色 Color.RED 可选 轮廓颜色。如果超过 256 个模型启用了轮廓,则重叠模型有很小的可能性会有轻微的伪影。
silhouetteSize 数字 0.0 可选 轮廓的大小(以像素为单位)。
clippingPlanes ClippingPlaneCollection 可选 ClippingPlaneCollection 用于选择性地禁用渲染模型。
dequantizeInShader 布尔值 true 可选 确定是否在 GPU 上对 Draco 编码模型进行去量化。这减少了编码模型的总内存使用量。在 CesiumJS 1.94 中已弃用,将在 CesiumJS 1.96 中删除。
lightColor 笛卡尔3 可选 为模型着色时的浅色。当 undefined 时,将使用场景的浅色。
imageBasedLighting 基于图像的照明 可选 用于管理此模型上基于图像的照明的属性。
credit 信用 | 细绳 可选 数据源的功劳,显示在画布上。
showCreditsOnScreen 布尔值 false 可选 是否在屏幕上显示该模型的学分。
backFaceCulling 布尔值 true 可选 是否剔除背面几何体。当为 true 时,背面剔除由材质的 doubleSided 属性决定;如果为 false,则禁用背面剔除。如果 Model#color 为半透明或 Model#silhouetteSize 大于 0.0,则不剔除背面。
showOutline 布尔值 true 可选 是否使用 CESIUM_primitive_outline 扩展显示模型的轮廓。为 true 时,将显示轮廓。如果为 false,则不显示轮廓。
splitDirection 拆分方向 SplitDirection.NONE 可选 要应用于此模型的 SplitDirection 拆分。
Demo:
See:

Members

当前播放的 glTF 动画。

readonly allowPicking : Boolean

当为 true 时,每个 glTF 网格和图元都可以使用 Scene#pick 进行拾取。当为 false 时,GPU 内存被保存。
Default Value: true

readonly asynchronous : Boolean

确定模型 WebGL 资源创建是否将分散到多个帧或阻塞,直到加载所有 glTF 文件后完成。
Default Value: true

backFaceCulling : Boolean

是否剔除背面几何体。当为 true 时,背面剔除由材质的 doubleSided 属性决定;如果为 false,则禁用背面剔除。如果 Model#color 为半透明或 Model#silhouetteSize 大于 0.0,则不剔除背面。
Default Value: true

readonly deprecated basePath : String

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

Deprecated: true

Default Value: ''
模型在其局部坐标系中的边界球。这不考虑 glTF 动画和皮肤,也不考虑 Model#minimumPixelSize
Default Value: undefined
Example:
// Center in WGS84 coordinates
const center = Cesium.Matrix4.multiplyByPoint(model.modelMatrix, model.boundingSphere.center, new Cesium.Cartesian3());

clampAnimations : Boolean

确定模型的动画是否应在未指定关键帧的帧上保持姿势。
ClippingPlaneCollection 用于选择性地禁用渲染模型。
与模型的渲染颜色混合的颜色。
Default Value: Color.WHITE

colorBlendAmount : Number

colorBlendMode MIX 时用于确定颜色强度的值。值 0.0 会导致模型的渲染颜色,而值 1.0 会导致纯色,介于两者之间的任何值都会导致两者混合。
Default Value: 0.5
定义颜色如何与模型混合。
Default Value: ColorBlendMode.HIGHLIGHT
获取将为模型显示的信用

debugShowBoundingVolume : Boolean

该属性仅用于调试;它不是用于生产用途,也不是优化的。

为模型中的每个绘制命令绘制边界球体。一个 glTF 基元对应一个绘制命令。 glTF 网格有一组基元,通常长度为 1。

Default Value: false

debugWireframe : Boolean

该属性仅用于调试;它不是用于生产用途,也不是优化的。

在线框中绘制模型。

Default Value: false
获取或设置条件,指定该模型将在距相机多远的距离处显示。
Default Value: undefined

readonly deprecated gltf : Object

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

Deprecated: true

Default Value: undefined
返回模型的高度参考
Default Value: HeightReference.NONE
拾取模型时返回的用户定义对象。
Default Value: undefined
See:
用于管理此模型上基于图像的照明的属性。

readonly incrementallyLoadTextures : Boolean

确定加载模型后纹理是否可以继续流入。
Default Value: true
为模型着色时的浅色。当 undefined 时,将使用场景的浅色。

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

Default Value: undefined

maximumScale : Number

模型的最大比例大小。这可用于为 Model#minimumPixelSize 提供上限,确保模型永远不会是不合理的比例。

minimumPixelSize : Number

无论缩放如何,模型的近似最小像素大小。这可用于确保模型即使在查看器缩小时也是可见的。当 0.0 时,不强制执行最小大小。
Default Value: 0.0
将模型从模型转换为世界坐标的 4x4 转换矩阵。当这是单位矩阵时,模型是在世界坐标系中绘制的,即地球的WGS84 坐标系。可以通过提供不同的变换矩阵来使用本地参考帧,就像 Transforms.eastNorthUpToFixedFrame 返回的那样。
Default Value: Matrix4.IDENTITY
Example:
const origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
m.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);

readonly deprecated pendingTextureLoads : Number

返回未决纹理加载的数量。

Deprecated: true

readonly ready : Boolean

当为 true 时,此模型已准备好渲染,即下载了外部二进制文件、图像和着色器文件并创建了 WebGL 资源。这在 Model#readyPromise 解决之前设置为 true
Default Value: false

readonly readyPromise : Promise.< Model >

获取该模型准备好渲染时将被解析的承诺,即下载外部二进制文件、图像和着色器文件并创建 WebGL 资源时。

这个承诺在模型渲染的第一帧之前的帧结束时解决。

Example:
// Play all animations at half-speed when the model is ready to render
Promise.resolve(model.readyPromise).then(function(model) {
  model.activeAnimations.addAll({
    multiplier : 0.5
  });
}).catch(function(error){
  window.alert(error);
});
See:

scale : Number

Model#modelMatrix 之前应用于此模型的统一比例。大于 1.0 的值会增加模型的大小;小于 1.0 的值减少。
Default Value: 1.0
确定模型是投射还是接收来自光源的阴影。
Default Value: ShadowMode.ENABLED

show : Boolean

确定是否显示模型原语。
Default Value: true

showCreditsOnScreen : Boolean

获取或设置模型的学分是否显示在屏幕上

readonly showOutline : Boolean

是否使用 CESIUM_primitive_outline 扩展显示模型的轮廓。为 true 时,将显示轮廓。如果为 false,则不显示轮廓。
Default Value: true
剪影颜色。
Default Value: Color.RED

silhouetteSize : Number

轮廓的大小(以像素为单位)。
Default Value: 0.0
应用于此模型的 SplitDirection
Default Value: SplitDirection.NONE

Methods

static Cesium.Model.fromGltf (options) Model

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

该模型可以是具有 .gltf 扩展名的传统 glTF 资产或使用 .glb 扩展名的二进制 glTF。

Cesium 支持具有以下扩展的 glTF 资产:

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

Name Type Description
options Object 具有以下属性的对象:
姓名 类型 默认 描述
url 资源 | 细绳 .gltf 文件的 url。
basePath 资源 | 细绳 可选 glTF JSON 中的路径相对于的基本路径。
show 布尔值 true 可选 确定是否显示模型原语。
modelMatrix 矩阵4 Matrix4.IDENTITY 可选 将模型从模型转换为世界坐标的 4x4 转换矩阵。
scale 数字 1.0 可选 应用于此模型的统一比例。
minimumPixelSize 数字 0.0 可选 无论缩放如何,模型的近似最小像素大小。
maximumScale 数字 可选 模型的最大比例。
id 目的 可选 使用 Scene#pick 拾取模型时要返回的用户定义对象。
allowPicking 布尔值 true 可选 true 时,每个 glTF 网格和图元都可以使用 Scene#pick 进行拾取。
incrementallyLoadTextures 布尔值 true 可选 确定加载模型后纹理是否可以继续流入。
asynchronous 布尔值 true 可选 确定模型 WebGL 资源创建是否将分散到多个帧或阻塞,直到加载所有 glTF 文件后完成。
clampAnimations 布尔值 true 可选 确定模型的动画是否应在未指定关键帧的帧上保持姿势。
shadows 阴影模式 ShadowMode.ENABLED 可选 确定模型是投射还是接收来自光源的阴影。
debugShowBoundingVolume 布尔值 false 可选 仅用于调试。为模型中的每个绘制命令绘制边界球体。
debugWireframe 布尔值 false 可选 仅用于调试。在线框中绘制模型。
heightReference 高度参考 HeightReference.NONE 可选 确定模型相对于地形的绘制方式。
scene 场景 可选 对于使用高度参考属性的模型,必须传入。
distanceDisplayCondition 距离显示条件 可选 指定该模型将在距相机多远的距离处显示的条件。
color 颜色 Color.WHITE 可选 与模型渲染颜色混合的颜色。
colorBlendMode 颜色混合模式 ColorBlendMode.HIGHLIGHT 可选 定义颜色如何与模型混合。
colorBlendAmount 数字 0.5 可选 colorBlendMode MIX 时用于确定颜色强度的值。值 0.0 会导致模型的渲染颜色,而值 1.0 会导致纯色,介于两者之间的任何值都会导致两者混合。
silhouetteColor 颜色 Color.RED 可选 轮廓颜色。如果超过 256 个模型启用了轮廓,则重叠模型有很小的可能性会有轻微的伪影。
silhouetteSize 数字 0.0 可选 轮廓的大小(以像素为单位)。
clippingPlanes ClippingPlaneCollection 可选 ClippingPlaneCollection 用于选择性地禁用渲染模型。
dequantizeInShader 布尔值 true 可选 确定是否在 GPU 上对 Draco 编码模型进行去量化。这减少了编码模型的总内存使用量。在 CesiumJS 1.94 中已弃用,将在 CesiumJS 1.96 中删除。
lightColor 笛卡尔3 可选 为模型着色时的浅色。当 undefined 时,将使用场景的浅色。
imageBasedLighting 基于图像的照明 可选 用于管理此图块集的基于图像的照明的属性。
credit 信用 | 细绳 可选 模型的功劳,显示在画布上。
showCreditsOnScreen 布尔值 false 可选 是否在屏幕上显示该模型的学分。
backFaceCulling 布尔值 true 可选 是否剔除背面几何体。当为 true 时,背面剔除由材质的 doubleSided 属性决定;如果为 false,则禁用背面剔除。如果 Model#color 为半透明或 Model#silhouetteSize 大于 0.0,则不剔除背面。
showOutline 布尔值 true 可选 是否使用 CESIUM_primitive_outline 扩展显示模型的轮廓。为 true 时,将显示轮廓。如果为 false,则不显示轮廓。
Returns:
新创建的模型。
Examples:
// Example 1. Create a model from a glTF asset
const model = scene.primitives.add(Cesium.Model.fromGltf({
  url : './duck/duck.gltf'
}));
// Example 2. Create model and provide all properties and events
const origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
const modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);

const 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

确定是否支持剪影。
Name Type Description
scene Scene 现场。
Returns:
如果支持剪影,则为 true ;否则,返回 false

applyArticulations ()

将任何修改后的发音阶段应用于参与任何发音的每个节点的矩阵。请注意,这将覆盖参与节点上的任何 nodeTransformations。
Throws:
  • DeveloperError : 模型未加载。使用 Model.readyPromise 或等待 Model.ready 为真。
销毁此对象持有的 WebGL 资源。销毁一个对象允许确定性地释放 WebGL 资源,而不是依赖垃圾收集器来销毁这个对象。

一旦一个对象被销毁,它就不应该被使用;调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。因此,如示例中所做的那样,将返回值 ( undefined ) 分配给对象。
Throws:
Example:
model = model && model.destroy();
See:
返回具有给定 name 属性的 glTF 材质。
Name Type Description
name String 材质的 glTF 名称。
Returns:
如果不存在具有 name 的材料,则材料或 undefined
Throws:
  • DeveloperError : 模型未加载。使用 Model.readyPromise 或等待 Model.ready 为真。
返回具有给定 name 属性的 glTF 网格。
Name Type Description
name String 网格的 glTF 名称。
Returns:
如果不存在具有 name 的网格,则网格或 undefined
Throws:
  • DeveloperError : 模型未加载。使用 Model.readyPromise 或等待 Model.ready 为真。
返回具有给定 name 属性的 glTF 节点。这用于为 glTF 动画之外的动画修改节点的变换。
Name Type Description
name String 节点的 glTF 名称。
Returns:
如果不存在具有 name 的节点,则该节点或 undefined
Throws:
  • DeveloperError : 模型未加载。使用 Model.readyPromise 或等待 Model.ready 为真。
Example:
// Apply non-uniform scale to node LOD3sp
const node = model.getNode('LOD3sp');
node.matrix = Cesium.Matrix4.fromScale(new Cesium.Cartesian3(5.0, 1.0, 1.0), node.matrix);

isDestroyed () Boolean

如果此对象被销毁,则返回 true;否则为假。

如果这个对象被破坏了,它就不应该被使用;调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。
Returns:
如果此对象被销毁,则为 true ;否则, false
See:

setArticulationStage (articulationStageKey, value)

设置清晰度阶段的当前值。设置一个或多个阶段值后,调用 Model.applyArticulations() 以重新计算节点矩阵。
Name Type Description
articulationStageKey String 关节名称、空格和舞台名称。
value Number 关节的这个阶段的数值。
Throws:
  • DeveloperError : 模型未加载。使用 Model.readyPromise 或等待 Model.ready 为真。
See:
Viewer CesiumWidget 渲染场景以获取渲染此图元所需的绘制命令时调用。

不要直接调用这个函数。记录这只是为了列出渲染场景时可能传播的异常:

Throws: