Scene

new Cesium.Scene ( options )

Cesium虚拟场景中所有3D图形对象和状态的容器。通常,场景不是直接创建的;而是由 CesiumWidget 隐式创建的。

contextOptions 参数详细信息:

默认值为: { webgl:{ alpha:false, 深度:是的, 模具:错误, 抗锯齿:是的, powerPreference:'高性能', premultipliedAlpha:true, reserveDrawingBuffer:false, failIfMajorPerformanceCaveat:false }, allowTextureFilterAnisotropic:true}

webgl 属性对应于 WebGLContextAttributes 用于创建WebGL上下文的对象。

webgl.alpha 的默认值为false,与标准的WebGL默认值相比可以提高性能是真的。如果应用程序需要使用alpha混合在其他HTML元素上方合成Cesium,请设置 webgl.alpha 设为true。

其他 webgl 属性与 WebGLContextAttributes 的WebGL默认值匹配。

allowTextureFilterAnisotropic 的默认值为true,当启用支持WebGL扩展。将其设置为false会提高性能,但会损害视觉质量,尤其是对于地平线视图。

Name Type Description
options Object optional Object with the following properties:
Name Type Default Description
canvas HTMLCanvasElement 用于为其创建场景的HTML canvas元素。
contextOptions Object 可选 上下文和WebGL创建属性。请参阅上面的详细信息。
creditContainer Element 可选 将在其中显示积分的HTML元素。
creditViewport Element 可选 在其中显示功劳弹出窗口的HTML元素。如果未指定,则视口将被添加为画布的同级。
mapProjection MapProjection new GeographicProjection() 可选 在2D和Columbus View模式下使用的地图投影。
orderIndependentTranslucency Boolean true 可选 如果为true并且配置支持它,则使用顺序无关的半透明性。
scene3DOnly Boolean false 可选 如果为true,则可以优化3D模式的内存使用和性能,但会禁用使用2D或Columbus View的功能。
terrainExaggeration Number 1.0 可选 用于放大地形的标量。请注意,地形夸张不会修改其他相对于椭球的图元。
shadows Boolean false 可选 确定阴影是否由光源投射。
mapMode2D MapMode2D MapMode2D.INFINITE_SCROLL 可选 确定2D地图是可旋转的还是可以在水平方向无限滚动。
requestRenderMode Boolean false 可选 如果为true,则仅根据场景中的更改确定是否需要渲染帧。启用可以提高应用程序的性能,但需要使用 '> Scene#requestRender 在此模式下显式渲染新框架。在API的其他部分对场景进行更改后,在许多情况下这是必要的。请参见 通过显式渲染提高性能
maximumRenderTimeChange Number 0.0 可选 如果requestRenderMode为true,则此值定义在请求渲染之前允许的最大仿真时间更改。请参见 通过显式渲染提高性能
Throws:
Example:
// Create scene without anisotropic texture filtering
var scene = new Cesium.Scene({
  canvas : canvas,
  contextOptions : {
    allowTextureFilterAnisotropic : false
  }
});
See:

Members

未定义背景色(仅在没有天窗的情况下才可见),即 Scene#skyBox
Default Value: Color.BLACK
See:
获取或设置相机。

readonly cameraUnderground : Boolean

相机是否在地球下方。
Default Value: false

readonly canvas : HTMLCanvasElement

获取此场景绑定到的canvas元素。

readonly clampToHeightSupported : Boolean

See:

completeMorphOnUserInput : Boolean

确定是否立即完成用户输入时的场景过渡动画。
Default Value: true

debugCommandFilter : function

此属性仅用于调试。它不用于生产。

确定执行哪些命令的功能。如以下示例所示,该函数接收命令的 owner 作为参数,并返回一个布尔值,指示是否命令应该被执行。

默认值为 undefined ,表示所有命令均已执行。

Default Value: undefined
Example:
// Do not execute any commands.
scene.debugCommandFilter = function(command) {
    return false;
};

// Execute only the billboard's commands.  That is, only draw the billboard.
var billboards = new Cesium.BillboardCollection();
scene.debugCommandFilter = function(command) {
    return command.owner === billboards;
};

readonly debugFrustumStatistics : Object

此属性仅用于调试。它不用于生产。

Scene.debugShowFrustums true 时,其中包含具有有关每个视锥执行的命令数量的统计信息的属性。 totalCommands 是已执行的命令总数,忽略交叠。 commandsInFrustums 是一个具有次数的数组命令是多余执行的,例如,有多少命令重叠两个或三个平截头体。

Default Value: undefined

debugShowCommands : Boolean

此属性仅用于调试。它不用于生产。

true 时,命令会随机阴影。这很有用用于性能分析,以查看场景或模型的哪些部分命令密集,可以从批处理中受益。

Default Value: false

debugShowDepthFrustum : Number

此属性仅用于调试。它不用于生产。

指示将显示深度信息的视锥。

Default Value: 1

debugShowFramesPerSecond : Boolean

此属性仅用于调试。它不用于生产。

显示每秒的帧数和帧之间的时间。

Default Value: false

debugShowFrustumPlanes : Boolean

此属性仅用于调试。它不用于生产。

true 时,绘制轮廓以显示摄像机视锥的边界

Default Value: false

debugShowFrustums : Boolean

此属性仅用于调试。它不用于生产。

true 时,命令将根据其平截头锥体着色交叠。最接近的视锥中的命令以红色标记,命令中的命令下一个最接近的是绿色,最远的平截头体中的命令是蓝色。如果命令重叠多个截头锥体,则颜色分量合并,例如,将前两个视锥重叠的命令设置为有色黄色。

Default Value: false

debugShowGlobeDepth : Boolean

此属性仅用于调试。它不用于生产。

显示指示的视锥的深度信息。

Default Value: false

readonly drawingBufferHeight : Number

基础GL上下文的drawingBufferHeight。
See:

readonly drawingBufferWidth : Number

基础GL上下文的drawingBufferHeight。
See:

eyeSeparation : Number

与硬纸板或WebVR一起使用时,眼间距以米为单位。

farToNearRatio : Number

使用常规深度缓冲区时,多截头锥体的远近比率。

该值用于为多视锥的每个视锥创建近和远值。仅用于当 Scene#logarithmicDepthBuffer false 时。当 logarithmicDepthBuffer true ,请使用 Scene#logarithmicDepthFarToNearRatio

Default Value: 1000.0

focalLength : Number

与硬纸板或WebVR一起使用时的焦距。
将大气与远离摄像机的几何体融合在一起,以获取地平线视图。允许额外通过减少几何图形和分配较少的地形请求来提高性能。
用于伽玛校正的值。仅在具有高动态范围的渲染时使用。
Default Value: 2.2
获取或设置深度测试椭球。
获取地面图元的集合。

highDynamicRange : Boolean

是否使用高动态范围渲染。
Default Value: true

readonly highDynamicRangeSupported : Boolean

是否支持高动态范围渲染。
Default Value: true

readonly id : String

获取此场景的唯一标识符。
获取将在地球上渲染的图像图层的集合。

imagerySplitPosition : Number

获取或设置图像拆分器在视口中的位置。有效值在0.0到1.0之间。

invertClassification : Boolean

如果 false ,则3D Tiles将正常渲染。如果 true ,则分类的3D Tile几何形状将正常渲染,未分类的3D Tile几何图形将使用颜色乘以 Scene#invertClassificationColor 进行渲染。
Default Value: false

invertClassificationColor : Color

Scene#invertClassification true 时,未分类的3D Tile几何图形的突出显示颜色。

当颜色的Alpha值小于1.0时,3D Tiles的未分类部分将无法与3D Tiles的分类位置正确融合。

此外,当颜色的Alpha值小于1.0时,必须支持WEBGL_depth_texture和EXT_frag_depth WebGL扩展。

Default Value: Color.WHITE

readonly invertClassificationSupported : Boolean

如果支持 Scene#invertClassification ,则返回 true
See:

readonly lastRenderTime : JulianDate

获取场景最后渲染时的仿真时间。如果场景尚未返回,则返回undefined呈现。
用于遮光的光源。默认为来自太阳的定向光。

logarithmicDepthBuffer : Boolean

是否使用对数深度缓冲区。启用此选项将减少多视锥中的视锥,提高性能。此属性取决于是否支持fragmentDepth。

logarithmicDepthFarToNearRatio : Number

使用对数深度缓冲区时,多截头圆锥体的远近比率。

该值用于为多视锥的每个视锥创建近和远值。仅用于当 Scene#logarithmicDepthBuffer true 时。当 logarithmicDepthBuffer false ,请使用 Scene#farToNearRatio

Default Value: 1e9
确定2D地图是可旋转的还是可以在水平方向无限滚动。
获取要在2D和Columbus View模式下使用的地图投影。
Default Value: new GeographicProjection()

readonly maximumAliasedLineWidth : Number

此WebGL实现支持的最大别名行宽度(以像素为单位)。至少会是一个。
See:
  • glGet with ALIASED_LINE_WIDTH_RANGE .

readonly maximumCubeMapSize : Number

此WebGL实现支持的多维数据集映射的一个边缘的最大长度(以像素为单位)。至少为16。
See:
  • glGet with GL_MAX_CUBE_MAP_TEXTURE_SIZE .

maximumRenderTimeChange : Number

如果 Scene#requestRenderMode true ,则此值定义请求渲染之前允许的模拟时间。较低的值会增加渲染的帧数较高的值会减少渲染的帧数。如果 undefined ,则更改为模拟时间永远不会要求渲染。这个值会影响场景变化的渲染速率,例如照明,实体属性更新,和动画。
Default Value: 0.0
See:

minimumDisableDepthTestDistance : Number

距离摄像机禁用广告牌,标签和点的深度测试的距离例如,以防止剪切地形。设置为零时,深度测试应始终被应用。如果小于零,则永远不要应用深度测试。设置disableDepthTestDistance广告牌,标签或点的属性将覆盖此值。
Default Value: 0.0
获取或设置场景的当前模式。
Default Value: SceneMode.SCENE3D
Default Value: undefined
事件在场景转换完成时触发。
Default Value: Event()
事件在场景转换开始时触发。
Default Value: Event()

morphTime : Number

当前的2D/Columbus View和3D之间的变形过渡时间,其中0.0是2D或Columbus View,而1.0是3D。
Default Value: 1.0

nearToFarDistance2D : Number

确定二维中的多个视锥的每个视锥的统一深度大小(以米为单位)。如果原始或模型关闭到表面显示Z值战斗,减少此次数将消除伪影,但会降低性能。在另一方面,增加它会提高性能,但可能会导致靠近曲面的图元之间发生z格斗。
Default Value: 1.75e6

readonly orderIndependentTranslucency : Boolean

获取场景是否启用了顺序无关的半透明性。请注意,这仅反映原始构造选项,并且有其他可能阻止OIT在给定系统配置上运行的因素。

readonly pickPositionSupported : Boolean

如果支持 Scene#pickPosition 函数,则返回 true
See:

pickTranslucentDepth : Boolean

如果为 true ,则启用使用深度缓冲区拾取半透明几何体的功能。请注意, Scene#useDepthPicking 也必须为true才能使其正常工作。

必须在两次选择之间调用渲染。
启用后性能会下降。还有额外的绘制调用以写入深度半透明的几何体。

Default Value: false
Example:
// picking the position of a translucent primitive
viewer.screenSpaceEventHandler.setInputAction(function onLeftClick(movement) {
     var pickedFeature = viewer.scene.pick(movement.position);
     if (!Cesium.defined(pickedFeature)) {
         // nothing picked
         return;
     }
     viewer.scene.render();
     var worldPosition = viewer.scene.pickPosition(movement.position);
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
后处理效果应用于最终渲染。

readonly postRender : Event

获取将在渲染场景后立即引发的事件。活动订阅者将Scene实例作为第一个参数,将当前时间作为第二个参数。
See:

readonly postUpdate : Event

获取在场景更新之后和场景渲染之前立即引发的事件。事件的订阅者将Scene实例作为第一个参数,将当前时间作为第二个参数参数。
See:
获取在场景更新之后以及场景渲染之前立即引发的事件。事件的订阅者将Scene实例作为第一个参数,将当前时间作为第二个参数参数。
See:
获取在更新或渲染场景之前将引发的事件。活动订阅者将Scene实例作为第一个参数,将当前时间作为第二个参数。
See:
获取基元的集合。

readonly renderError : Event

获取在 render 函数内引发错误时将引发的事件。Scene实例和引发的错误是传递给事件处理程序的仅有两个参数。默认情况下,引发此事件后不会重新引发错误,但是可以通过设置 rethrowRenderErrors 属性。

requestRenderMode : Boolean

如果为 true ,则仅根据场景中的更改确定是否需要渲染帧。启用可以提高应用程序的性能,但需要使用 '> Scene#requestRender 在此模式下显式渲染新框架。进行更改后,在许多情况下这是必要的API的其他部分。
Default Value: false
See:

rethrowRenderErrors : Boolean

总是捕获 render 中发生的异常,以提高 renderError 事件。如果此属性为true,则会重新引发错误事件引发之后。如果此属性为false,则 render 函数引发事件后通常返回。
Default Value: false

readonly sampleHeightSupported : Boolean

See:

readonly scene3DOnly : Boolean

获取是否针对仅3D观看优化了场景。

readonly screenSpaceCameraController : ScreenSpaceCameraController

获取用于摄像机输入处理的控制器。
场景光源的阴影贴图。启用后,模型,图元和地球可能会投射并接收阴影。
遍布全球的天空气氛。
Default Value: undefined
SkyBox 用于绘制星星。
Default Value: undefined
See:

specularEnvironmentMaps : String

KTX文件的url,包含镜面反射环境贴图和卷积的mipmap,用于基于图像的PBR模型照明。

readonly specularEnvironmentMapsSupported : Boolean

如果支持镜面环境贴图,则返回 true
See:

sphericalHarmonicCoefficients : Array.< Cartesian3 >

PBR模型基于图像的照明的球谐系数。
Sun
Default Value: undefined

sunBloom : Boolean

启用时,在太阳上使用布隆过滤器。
Default Value: true

readonly terrainExaggeration : Number

获取用于放大地形的标量。
地形提供者为地球提供表面几何形状。

readonly terrainProviderChanged : Event

获取更改地形提供者时引发的事件

useDepthPicking : Boolean

true 时,启用使用深度缓冲区的拾取。
Default Value: true

useWebVR : Boolean

true 时,将场景分为两个视口,左右眼具有立体视图。用于硬纸板和WebVR。
Default Value: false

Methods

cartesianToCanvasCoordinates (position, result ) Cartesian2

将笛卡尔坐标中的位置转换为画布坐标。这通常用于放置与场景中的对象位于同一屏幕位置的HTML元素。
Name Type Description
position Cartesian3 笛卡尔坐标中的位置。
result Cartesian2 可选 一个可选对象,用于返回转换为画布坐标的输入位置。
Returns:
修改后的结果参数,或者未提供新的Cartesian2实例。这可能是 未定义 如果输入位置在椭球的中心附近。
Example:
// Output the canvas position of longitude/latitude (0, 0) every time the mouse moves.
var scene = widget.scene;
var ellipsoid = scene.globe.ellipsoid;
var position = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
var handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
handler.setInputAction(function(movement) {
    console.log(scene.cartesianToCanvasCoordinates(position));
}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);

clampToHeight (cartesian, objectsToExclude , width , result ) Cartesian3

沿大地表面法线将给定的笛卡尔位置固定到场景几何。返回夹紧位置或 undefined (如果没有场景几何要夹紧)。可用于夹紧场景中的地球物体,3D瓷砖或图元。

此功能仅钳制当前视图中渲染的Globe瓷砖和3D Tiles。夹到所有其他原语,无论其可见性如何。

Name Type Default Description
cartesian Cartesian3 笛卡尔位置。
objectsToExclude Array.<Object> 可选 不可钳制的图元,实体或3D Tiles功能列表。
width Number 0.1 可选 交叉口的宽度(以米为单位)。
result Cartesian3 可选 返回夹紧位置的可选对象。
Returns:
修改后的结果参数,或者未提供新的Cartesian3实例。这可能是 未定义 如果没有场景几何要固定。
Throws:
Example:
// Clamp an entity to the underlying scene geometry
var position = entity.position.getValue(Cesium.JulianDate.now());
entity.position = viewer.scene.clampToHeight(position);
See:

clampToHeightMostDetailed (cartesians, objectsToExclude , width ) Promise.<Array.< Cartesian3 >>

启动异步 Scene#clampToHeight 查询以查询 Cartesian3 职位在场景中使用3D Tileset的最大细节级别。返回在以下情况下解决的承诺查询完成。每个位置均已修改。如果由于没有几何形状而无法夹紧位置可以在该位置进行采样,或者发生另一个错误,数组中的元素设置为undefined。
Name Type Default Description
cartesians Array.< Cartesian3 > 笛卡尔位置更新为夹紧位置。
objectsToExclude Array.<Object> 可选 不可钳制的图元,实体或3D Tiles功能列表。
width Number 0.1 可选 交叉口的宽度(以米为单位)。
Returns:
查询完成后解析为提供的职位清单的承诺。
Throws:
  • DeveloperError :仅在3D模式下支持clipToHeightMostDetailed。
  • DeveloperError :clipToHeightMostDetailed需要深度纹理支持。检查clipToHeightSupported。
Example:
var cartesians = [
    entities[0].position.getValue(Cesium.JulianDate.now()),
    entities[1].position.getValue(Cesium.JulianDate.now())
];
var promise = viewer.scene.clampToHeightMostDetailed(cartesians);
promise.then(function(updatedCartesians) {
    entities[0].position = updatedCartesians[0];
    entities[1].position = updatedCartesians[1];
}
See:

completeMorph ()

立即完成活动过渡。
销毁此对象拥有的WebGL资源。销毁对象可以确定性释放WebGL资源,而不是依赖垃圾回收器破坏此对象。

一旦物体被破坏,就不应使用。调用除 isDestroyed 将导致 DeveloperError 异常。因此,如示例中所述,将返回值( undefined )分配给对象。
Throws:
Example:
scene = scene && scene.destroy();
See:

drillPick (windowPosition, limit , width , height ) Array.<*>

返回所有对象的对象列表,每个对象包含一个' primitive'属性。特定的窗口坐标位置。也可以设置其他属性,具体取决于类型的图元,并可用于进一步标识拾取的对象。在中的原始列表按其在场景中的视觉顺序(从前到后)排序。
Name Type Default Description
windowPosition Cartesian2 窗口坐标以执行拾取。
limit Number 可选 如果提供的话,请在收集到这么多的镐后停止钻孔。
width Number 3 可选 拾取矩形的宽度。
height Number 3 可选 拾取矩形的高度。
Returns:
对象数组,每个对象包含1个选取的基元。
Throws:
Example:
var pickedObjects = scene.drillPick(new Cesium.Cartesian2(100.0, 200.0));
See:

getCompressedTextureFormatSupported (format) boolean

确定是否支持压缩纹理格式。
Name Type Description
format String 纹理格式。可以是格式名称或WebGL扩展名称,例如s3tc或WEBGL_compressed_texture_s3tc。
Returns:
是否支持该格式。

isDestroyed () Boolean

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

如果该对象被破坏,则不应使用。调用除 isDestroyed 将导致 DeveloperError 异常。
Returns:
真正 该物体是否被破坏;除此以外,
See:

morphTo2D ( duration )

异步将场景转换为2D。
Name Type Default Description
duration Number 2.0 可选 完成过渡动画的时间(以秒为单位)。

morphTo3D ( duration )

异步将场景转换为3D。
Name Type Default Description
duration Number 2.0 可选 完成过渡动画的时间(以秒为单位)。

morphToColumbusView ( duration )

异步将场景切换到哥伦布视图。
Name Type Default Description
duration Number 2.0 可选 完成过渡动画的时间(以秒为单位)。

pick (windowPosition, width , height ) Object

返回具有' primitive'属性的对象,该对象包含场景中的第一个(顶部)基本体在特定的窗口坐标处;如果位置不存在,则为undefined。其他属性可能可能根据图元的类型进行设置,并可用于进一步标识拾取的对象。

拾取3D Tiles贴图集的特征后, pick 返回 Cesium3DTileFeature 对象。

Name Type Default Description
windowPosition Cartesian2 窗口坐标以执行拾取。
width Number 3 可选 拾取矩形的宽度。
height Number 3 可选 拾取矩形的高度。
Returns:
包含选取的图元的对象。
Example:
// On mouse over, color the feature yellow.
handler.setInputAction(function(movement) {
    var feature = scene.pick(movement.endPosition);
    if (feature instanceof Cesium.Cesium3DTileFeature) {
        feature.color = Cesium.Color.YELLOW;
    }
}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);

pickPosition (windowPosition, result ) Cartesian3

返回从深度缓冲区和窗口位置重构的笛卡尔位置。

从2D深度缓冲区中重建的位置可能与那些位置略有不同在3D和哥伦布视图中重建。这是由于分布差异造成的透视图和正投影的深度值。

Scene#pickTranslucentDepth 设置为 true ,以包括半透明图元;否则,这本质上会选择半透明的基元。

Name Type Description
windowPosition Cartesian2 窗口坐标以执行拾取。
result Cartesian3 可选 恢复结果的对象。
Returns:
笛卡尔位置。
Throws:
  • DeveloperError :不支持从深度缓冲区中拾取。检查pickPositionSupported。

render ( time )

更新并渲染场景。通常没有必要调用此函数直接是因为 CesiumWidget Viewer 是自动执行的。
Name Type Description
time JulianDate 可选 渲染的模拟时间。

requestRender ()

Scene#requestRenderMode 设置为 true 时,请求新的渲染帧。呈现速率将不会超过 CesiumWidget#targetFrameRate
See:

sampleHeight (position, objectsToExclude , width ) Number

返回给定制图位置处场景几何的高度;如果没有,则返回 undefined 场景几何要从其采样高度。输入位置的高度被忽略。可用于将物体夹在地球,3D瓷砖或场景中的图元。

此功能仅从当前视图中渲染的Globe瓷砖和3D Tile采样高度。样品高度不受可见性影响。

Name Type Default Description
position Cartographic 制图位置到样品高度的起点。
objectsToExclude Array.<Object> 可选 不能采样高度的基本体,实体或3D Tiles功能列表。
width Number 0.1 可选 交叉口的宽度(以米为单位)。
Returns:
高度。这可能是 未定义 如果没有场景几何要从其采样高度。
Throws:
Example:
var position = new Cesium.Cartographic(-1.31968, 0.698874);
var height = viewer.scene.sampleHeight(position);
console.log(height);
See:

sampleHeightMostDetailed (positions, objectsToExclude , width ) Promise.<Array.< Cartographic >>

启动异步 Scene#sampleHeight 查询以查询 Cartographic 职位在场景中使用3D Tileset的最大细节级别。输入位置的高度将被忽略。返回查询完成时解决的promise。每个点的高度都已修改。如果由于无法在该位置采样几何而无法确定高度,或者发生了另一个错误,高度设置为未定义。
Name Type Default Description
positions Array.< Cartographic > 制图位置将根据采样高度进行更新。
objectsToExclude Array.<Object> 可选 不能采样高度的基本体,实体或3D Tiles功能列表。
width Number 0.1 可选 交叉口的宽度(以米为单位)。
Returns:
查询完成后解析为提供的职位清单的承诺。
Throws:
  • DeveloperError :sampleHeightMostDetailed仅在3D模式下受支持。
  • DeveloperError :sampleHeightMostDetailed需要深度纹理支持。检查sampleHeightSupported。
Example:
var positions = [
    new Cesium.Cartographic(-1.31968, 0.69887),
    new Cesium.Cartographic(-1.10489, 0.83923)
];
var promise = viewer.scene.sampleHeightMostDetailed(positions);
promise.then(function(updatedPosition) {
    // positions[0].height and positions[1].height have been updated.
    // updatedPositions is just a reference to positions.
}
See: