Scene

new Cesium.Scene(options)
Scene/Scene.js 240

The container for all 3D graphical objects and state in a Cesium virtual scene. Generally, a scene is not created directly; instead, it is implicitly created by CesiumWidget.

contextOptions parameter details:

The default values are: { webgl : { alpha : false, depth : true, stencil : false, antialias : true, premultipliedAlpha : true, preserveDrawingBuffer : false, failIfMajorPerformanceCaveat : false }, allowTextureFilterAnisotropic : true }

The webgl property corresponds to the WebGLContextAttributes object used to create the WebGL context.

webgl.alpha defaults to false, which can improve performance compared to the standard WebGL default of true. If an application needs to composite Cesium above other HTML elements using alpha-blending, set webgl.alpha to true.

The other webgl properties match the WebGL defaults for WebGLContextAttributes.

allowTextureFilterAnisotropic defaults to true, which enables anisotropic texture filtering when the WebGL extension is supported. Setting this to false will improve performance, but hurt visual quality, especially for horizon views.

Name Type Description
options Object optional Object with the following properties:
Name Type Default Description
canvas Canvas The HTML canvas element to create the scene for.
contextOptions Object optional Context and WebGL creation properties. See details above.
creditContainer Element optional The HTML element in which the credits will be displayed.
creditViewport Element optional The HTML element in which to display the credit popup. If not specified, the viewport will be a added as a sibling of the canvas.
mapProjection MapProjection new GeographicProjection() optional The map projection to use in 2D and Columbus View modes.
orderIndependentTranslucency Boolean true optional If true and the configuration supports it, use order independent translucency.
scene3DOnly Boolean false optional If true, optimizes memory use and performance for 3D mode but disables the ability to use 2D or Columbus View.
terrainExaggeration Number 1.0 optional A scalar used to exaggerate the terrain. Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
shadows Boolean false optional Determines if shadows are cast by the sun.
mapMode2D MapMode2D MapMode2D.INFINITE_SCROLL optional Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
requestRenderMode Boolean false optional If true, rendering a frame will only occur when needed as determined by changes within the scene. Enabling improves performance of the application, but requires using Scene#requestRender to render a new frame explicitly in this mode. This will be necessary in many cases after making changes to the scene in other parts of the API. See Improving Performance with Explicit Rendering.
maximumRenderTimeChange Number 0.0 optional If requestRenderMode is true, this value defines the maximum change in simulation time allowed before a render is requested. See Improving Performance with Explicit Rendering.
Throws:
Example:
// Create scene without anisotropic texture filtering
var scene = new Cesium.Scene({
  canvas : canvas,
  contextOptions : {
    allowTextureFilterAnisotropic : false
  }
});
See:

Members

backgroundColor : Color
Scene/Scene.js 448

The background color, which is only visible if there is no sky box, i.e., Scene#skyBox is undefined.
Default Value: Color.BLACK
See:

readonlycamera : Camera
Scene/Scene.js 975

Gets the camera.

readonlycanvas : Canvas
Scene/Scene.js 844

Gets the canvas element to which this scene is bound.

completeMorphOnUserInput : Boolean
Scene/Scene.js 381

Determines whether or not to instantly complete the scene transition animation on user input.
Default Value: true

debugCommandFilter : function
Scene/Scene.js 526

This property is for debugging only; it is not for production use.

A function that determines what commands are executed. As shown in the examples below, the function receives the command's owner as an argument, and returns a boolean indicating if the command should be executed.

The default is undefined, indicating that all commands are executed.

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

readonlydebugFrustumStatistics : Object
Scene/Scene.js 1233

This property is for debugging only; it is not for production use.

When Scene.debugShowFrustums is true, this contains properties with statistics about the number of command execute per frustum. totalCommands is the total number of commands executed, ignoring overlap. commandsInFrustums is an array with the number of times commands are executed redundantly, e.g., how many commands overlap two or three frustums.

Default Value: undefined

debugShowCommands : Boolean
Scene/Scene.js 540

This property is for debugging only; it is not for production use.

When true, commands are randomly shaded. This is useful for performance analysis to see what parts of a scene or model are command-dense and could benefit from batching.

Default Value: false

debugShowDepthFrustum : Number
Scene/Scene.js 595

This property is for debugging only; it is not for production use.

Indicates which frustum will have depth information displayed.

Default Value: 1

debugShowFramesPerSecond : Boolean
Scene/Scene.js 571

This property is for debugging only; it is not for production use.

Displays frames per second and time between frames.

Default Value: false

debugShowFrustumPlanes : Boolean
Scene/Scene.js 607

This property is for debugging only; it is not for production use.

When true, draws outlines to show the boundaries of the camera frustums

Default Value: false

debugShowFrustums : Boolean
Scene/Scene.js 557

This property is for debugging only; it is not for production use.

When true, commands are shaded based on the frustums they overlap. Commands in the closest frustum are tinted red, commands in the next closest are green, and commands in the farthest frustum are blue. If a command overlaps more than one frustum, the color components are combined, e.g., a command overlapping the first two frustums is tinted yellow.

Default Value: false

debugShowGlobeDepth : Boolean
Scene/Scene.js 583

This property is for debugging only; it is not for production use.

Displays depth information for the indicated frustum.

Default Value: false

readonlydrawingBufferHeight : Number
Scene/Scene.js 859

The drawingBufferWidth of the underlying GL context.
See:

readonlydrawingBufferWidth : Number
Scene/Scene.js 874

The drawingBufferHeight of the underlying GL context.
See:

eyeSeparation : Number
Scene/Scene.js 720

The eye separation distance in meters for use with cardboard or WebVR.

farToNearRatio : Number
Scene/Scene.js 474

The far-to-near ratio of the multi-frustum when using a normal depth buffer.

This value is used to create the near and far values for each frustum of the multi-frustum. It is only used when Scene#logarithmicDepthBuffer is false. When logarithmicDepthBuffer is true, use Scene#logarithmicDepthFarToNearRatio.

Default Value: 1000.0

focalLength : Number
Scene/Scene.js 714

The focal length for use when with cardboard or WebVR.

fog : Fog
Scene/Scene.js 675

Blends the atmosphere to geometry far from the camera for horizon views. Allows for additional performance improvements by rendering less geometry and dispatching less terrain requests.

fxaa : Boolean
Scene/Scene.js 618

When true, enables Fast Approximate Anti-aliasing even when order independent translucency is unsupported.
Default Value: true

globe : Globe
Scene/Scene.js 929

Gets or sets the depth-test ellipsoid.

readonlygroundPrimitives : PrimitiveCollection
Scene/Scene.js 962

Gets the collection of ground primitives.

readonlyid : String
Scene/Scene.js 1271

Gets the unique identifier for this scene.

readonlyimageryLayers : ImageryLayerCollection
Scene/Scene.js 1048

Gets the collection of image layers that will be rendered on the globe.

imagerySplitPosition : Number
Scene/Scene.js 1386

Gets or sets the position of the Imagery splitter within the viewport. Valid values are between 0.0 and 1.0.

invertClassification : Boolean
Scene/Scene.js 696

When false, 3D Tiles will render normally. When true, classified 3D Tile geometry will render normally and unclassified 3D Tile geometry will render with the color multiplied by Scene#invertClassificationColor.
Default Value: false

invertClassificationColor : Color
Scene/Scene.js 705

The highlight color of unclassified 3D Tile geometry when Scene#invertClassification is true.

When the color's alpha is less than 1.0, the unclassified portions of the 3D Tiles will not blend correctly with the classified positions of the 3D Tiles.

Also, when the color's alpha is less than 1.0, the WEBGL_depth_texture and EXT_frag_depth WebGL extensions must be supported.

Default Value: Color.WHITE

readonlylastRenderTime : JulianDate
Scene/Scene.js 1198

Gets the simulation time when the scene was last rendered. Returns undefined if the scene has not yet been rendered.

logarithmicDepthFarToNearRatio : Number
Scene/Scene.js 487

The far-to-near ratio of the multi-frustum when using a logarithmic depth buffer.

This value is used to create the near and far values for each frustum of the multi-frustum. It is only used when Scene#logarithmicDepthBuffer is true. When logarithmicDepthBuffer is false, use Scene#farToNearRatio.

Default Value: 1e9

mapMode2D : Boolean
Scene/Scene.js 1374

Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.

readonlymapProjection : MapProjection
Scene/Scene.js 1004

Get the map projection to use in 2D and Columbus View modes.
Default Value: new GeographicProjection()

readonlymaximumAliasedLineWidth : Number
Scene/Scene.js 889

The maximum aliased line width, in pixels, supported by this WebGL implementation. It will be at least one.
See:
  • glGet with ALIASED_LINE_WIDTH_RANGE.

readonlymaximumCubeMapSize : Number
Scene/Scene.js 904

The maximum length in pixels of one edge of a cube map, supported by this WebGL implementation. It will be at least 16.
See:
  • glGet with GL_MAX_CUBE_MAP_TEXTURE_SIZE.

maximumRenderTimeChange : Number
Scene/Scene.js 802

If Scene#requestRenderMode is true, this value defines the maximum change in simulation time allowed before a render is requested. Lower values increase the number of frames rendered and higher values decrease the number of frames rendered. If undefined, changes to the simulation time will never request a render. This value impacts the rate of rendering for changes in the scene like lighting, entity property updates, and animations.
Default Value: 0.5
See:

minimumDisableDepthTestDistance : Number
Scene/Scene.js 1404

The distance from the camera at which to disable the depth test of billboards, labels and points to, for example, prevent clipping against terrain. When set to zero, the depth test should always be applied. When less than zero, the depth test should never be applied. Setting the disableDepthTestDistance property of a billboard, label or point will override this value.
Default Value: 0.0

mode : SceneMode
Scene/Scene.js 1283

Gets or sets the current mode of the scene.
Default Value: SceneMode.SCENE3D

moon : Moon
Scene/Scene.js 438

The Moon
Default Value: undefined

morphComplete : Event
Scene/Scene.js 395

The event fired at the completion of a scene transition.
Default Value: Event()

morphStart : Event
Scene/Scene.js 388

The event fired at the beginning of a scene transition.
Default Value: Event()

morphTime : Number
Scene/Scene.js 461

The current morph transition time between 2D/Columbus View and 3D, with 0.0 being 2D or Columbus View and 1.0 being 3D.
Default Value: 1.0

nearToFarDistance2D : Number
Scene/Scene.js 497

Determines the uniform depth size in meters of each frustum of the multifrustum in 2D. If a primitive or model close to the surface shows z-fighting, decreasing this will eliminate the artifact, but decrease performance. On the other hand, increasing this will increase performance but may cause z-fighting among primitives close to the surface.
Default Value: 1.75e6

readonlyorderIndependentTranslucency : Boolean
Scene/Scene.js 1259

Gets whether or not the scene has order independent translucency enabled. Note that this only reflects the original construction option, and there are other factors that could prevent OIT from functioning on a given system configuration.

readonlypickPositionSupported : Boolean
Scene/Scene.js 917

Returns true if the pickPosition function is supported.

pickTranslucentDepth : Boolean
Scene/Scene.js 652

When true, enables picking translucent geometry using the depth buffer. Note that Scene#useDepthPicking must also be true for this enabling to work.

Render must be called between picks.
There is a decrease in performance when enabled. There are extra draw calls to write depth for translucent geometry.

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

readonlypostRender : Event
Scene/Scene.js 1184

Gets the event that will be raised immediately after the scene is rendered. Subscribers to the event receive the Scene instance as the first parameter and the current time as the second parameter.
See:

readonlypostUpdate : Event
Scene/Scene.js 1129

Gets the event that will be raised immediately after the scene is updated and before the scene is rendered. Subscribers to the event receive the Scene instance as the first parameter and the current time as the second parameter.
See:

readonlypreRender : Event
Scene/Scene.js 1165

Gets the event that will be raised after the scene is updated and immediately before the scene is rendered. Subscribers to the event receive the Scene instance as the first parameter and the current time as the second parameter.
See:

readonlypreUpdate : Event
Scene/Scene.js 1109

Gets the event that will be raised before the scene is updated or rendered. Subscribers to the event receive the Scene instance as the first parameter and the current time as the second parameter.
See:

readonlyprimitives : PrimitiveCollection
Scene/Scene.js 949

Gets the collection of primitives.

readonlyrenderError : Event
Scene/Scene.js 1145

Gets the event that will be raised when an error is thrown inside the render function. The Scene instance and the thrown error are the only two parameters passed to the event handler. By default, errors are not rethrown after this event is raised, but that can be changed by setting the rethrowRenderErrors property.

requestRenderMode : Boolean
Scene/Scene.js 785

When true, rendering a frame will only occur when needed as determined by changes within the scene. Enabling improves performance of the application, but requires using Scene#requestRender to render a new frame explicitly in this mode. This will be necessary in many cases after making changes to the scene in other parts of the API.
Default Value: false
See:

rethrowRenderErrors : Boolean
Scene/Scene.js 372

Exceptions occurring in render are always caught in order to raise the renderError event. If this property is true, the error is rethrown after the event is raised. If this property is false, the render function returns normally after raising the event.
Default Value: false

readonlyscene3DOnly : Boolean
Scene/Scene.js 1245

Gets whether or not the scene is optimized for 3D only viewing.

readonlyscreenSpaceCameraController : ScreenSpaceCameraController
Scene/Scene.js 989

Gets the controller for camera input handling.

shadowMap : ShadowMap
Scene/Scene.js 684

The shadow map in the scene. When enabled, models, primitives, and the globe may cast and receive shadows. By default the light source of the shadow map is the sun.

skyAtmosphere : SkyAtmosphere
Scene/Scene.js 413

The sky atmosphere drawn around the globe.
Default Value: undefined

skyBox : SkyBox
Scene/Scene.js 405

The SkyBox used to draw the stars.
Default Value: undefined
See:

sun : Sun
Scene/Scene.js 421

The Sun.
Default Value: undefined

sunBloom : Boolean
Scene/Scene.js 429

Uses a bloom filter on the sun when enabled.
Default Value: true

terrainExaggeration : Number
Scene/Scene.js 1326

Gets the scalar used to exaggerate the terrain.

terrainProvider : TerrainProvider
Scene/Scene.js 1064

The terrain provider providing surface geometry for the globe.

readonlyterrainProviderChanged : Event
Scene/Scene.js 1086

Gets an event that's raised when the terrain provider is changed

useDepthPicking : Boolean
Scene/Scene.js 626

When true, enables picking using the depth buffer.
Default Value: true

useWebVR : Boolean
Scene/Scene.js 1339

When true, splits the scene into two viewports with steroscopic views for the left and right eyes. Used for cardboard and WebVR.
Default Value: false

Methods

cartesianToCanvasCoordinates(position, result) → Cartesian2
Scene/Scene.js 3688

Transforms a position in cartesian coordinates to canvas coordinates. This is commonly used to place an HTML element at the same screen position as an object in the scene.
Name Type Description
position Cartesian3 The position in cartesian coordinates.
result Cartesian2 optional An optional object to return the input position transformed to canvas coordinates.
Returns:
The modified result parameter or a new Cartesian2 instance if one was not provided. This may be undefined if the input position is near the center of the ellipsoid.
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);

completeMorph()
Scene/Scene.js 3695

Instantly completes an active transition.

destroy()
Scene/Scene.js 3777

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.
Throws:
  • DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
scene = scene && scene.destroy();
See:

drillPick(windowPosition, limit) → Array.<Object>
Scene/Scene.js 3606

Returns a list of objects, each containing a `primitive` property, for all primitives at a particular window coordinate position. Other properties may also be set depending on the type of primitive. The primitives in the list are ordered by their visual order in the scene (front to back).
Name Type Description
windowPosition Cartesian2 Window coordinates to perform picking on.
limit Number optional If supplied, stop drilling after collecting this many picks.
Returns:
Array of objects, each containing 1 picked primitives.
Throws:
Example:
var pickedObjects = scene.drillPick(new Cesium.Cartesian2(100.0, 200.0));

getCompressedTextureFormatSupported(format) → boolean
Scene/Scene.js 1451

Determines if a compressed texture format is supported.
Name Type Description
format String The texture format. May be the name of the format or the WebGL extension name, e.g. s3tc or WEBGL_compressed_texture_s3tc.
Returns:
Whether or not the format is supported.

isDestroyed() → Boolean
Scene/Scene.js 3757

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:

morphTo2D(duration)
Scene/Scene.js 3703

Asynchronously transitions the scene to 2D.
Name Type Default Description
duration Number 2.0 optional The amount of time, in seconds, for transition animations to complete.

morphTo3D(duration)
Scene/Scene.js 3735

Asynchronously transitions the scene to 3D.
Name Type Default Description
duration Number 2.0 optional The amount of time, in seconds, for transition animations to complete.

morphToColumbusView(duration)
Scene/Scene.js 3719

Asynchronously transitions the scene to Columbus View.
Name Type Default Description
duration Number 2.0 optional The amount of time, in seconds, for transition animations to complete.

pick(windowPosition, width, height) → Object
Scene/Scene.js 3339

Returns an object with a `primitive` property that contains the first (top) primitive in the scene at a particular window coordinate or undefined if nothing is at the location. Other properties may potentially be set depending on the type of primitive.

When a feature of a 3D Tiles tileset is picked, pick returns a Cesium3DTileFeature object.

Name Type Default Description
windowPosition Cartesian2 Window coordinates to perform picking on.
width Number 3 optional Width of the pick rectangle.
height Number 3 optional Height of the pick rectangle.
Returns:
Object containing the picked primitive.
Throws:
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
Scene/Scene.js 3576

Returns the cartesian position reconstructed from the depth buffer and window position.

The position reconstructed from the depth buffer in 2D may be slightly different from those reconstructed in 3D and Columbus view. This is caused by the difference in the distribution of depth values of perspective and orthographic projection.

Set Scene#pickTranslucentDepth to true to include the depth of translucent primitives; otherwise, this essentially picks through translucent primitives.

Name Type Description
windowPosition Cartesian2 Window coordinates to perform picking on.
result Cartesian3 optional The object on which to restore the result.
Returns:
The cartesian position.
Throws:
  • DeveloperError : Picking from the depth buffer is not supported. Check pickPositionSupported.

requestRender()
Scene/Scene.js 3209

Requests a new rendered frame when Scene#requestRenderMode is set to true. The render rate will not exceed the CesiumWidget#targetFrameRate.
See: