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.
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
object |
Object with the following properties:
|
Throws:
-
DeveloperError : options and options.canvas are required.
Example:
// Create scene without anisotropic texture filtering
const scene = new Cesium.Scene({
canvas : canvas,
contextOptions : {
allowTextureFilterAnisotropic : false
}
});See:
Members
backgroundColor : Color
The background color, which is only visible if there is no sky box, i.e.,
Scene#skyBox is undefined.
-
Default Value:
Color.BLACKSee:
readonly camera : Camera
Gets or sets the camera.
Whether or not the camera is underneath the globe.
-
Default Value:
false
Gets the canvas element to which this scene is bound.
Returns
true if the Scene#clampToHeight and Scene#clampToHeightMostDetailed functions are supported.
Determines whether or not to instantly complete the
scene transition animation on user input.
-
Default Value:
true
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.
const billboards = new Cesium.BillboardCollection();
scene.debugCommandFilter = function(command) {
return command.owner === billboards;
};
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
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
This property is for debugging only; it is not for production use.
Indicates which frustum will have depth information displayed.
-
Default Value:
1
This property is for debugging only; it is not for production use.
Displays frames per second and time between frames.
-
Default Value:
false
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
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
The drawingBufferHeight of the underlying GL context.
See:
The drawingBufferWidth of the underlying GL context.
See:
The eye separation distance in meters for use with cardboard or WebVR.
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
The focal length for use when with cardboard or WebVR.
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.
The value used for gamma correction. This is only used when rendering with high dynamic range.
-
Default Value:
2.2
Gets or sets the depth-test ellipsoid.
readonly groundPrimitives : PrimitiveCollection
Gets the collection of ground primitives.
Whether or not to use high dynamic range rendering.
-
Default Value:
false
Whether or not high dynamic range rendering is supported.
-
Default Value:
true
Gets the unique identifier for this scene.
readonly imageryLayers : ImageryLayerCollection
Gets the collection of image layers that will be rendered on the globe.
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
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
Returns
true if the Scene#invertClassification is supported.
readonly lastRenderTime : JulianDate
Gets the simulation time when the scene was last rendered. Returns undefined if the scene has not yet been
rendered.
The light source for shading. Defaults to a directional light from the Sun.
Whether or not to use a logarithmic depth buffer. Enabling this option will allow for less frustums in the multi-frustum,
increasing performance. This property relies on fragmentDepth being supported.
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
readonly mapMode2D : MapMode2D
Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
readonly mapProjection : MapProjection
Get the map projection to use in 2D and Columbus View modes.
-
Default Value:
new GeographicProjection()
The maximum aliased line width, in pixels, supported by this WebGL implementation. It will be at least one.
- glGet with
ALIASED_LINE_WIDTH_RANGE.
See:
The maximum length in pixels of one edge of a cube map, supported by this WebGL implementation. It will be at least 16.
- glGet with
GL_MAX_CUBE_MAP_TEXTURE_SIZE.
See:
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.0
See:
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
Gets or sets the current mode of the scene.
-
Default Value:
SceneMode.SCENE3D
The
Moon
-
Default Value:
undefined
morphComplete : Event
The event fired at the completion of a scene transition.
-
Default Value:
Event()
morphStart : Event
The event fired at the beginning of a scene transition.
-
Default Value:
Event()
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
The sample rate of multisample antialiasing (values greater than 1 enable MSAA).
-
Default Value:
1
Returns
true if the Scene's context supports MSAA.
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
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.
Returns
true if the Scene#pickPosition function is supported.
See:
When
true, enables picking translucent geometry using the depth buffer. Note that Scene#useDepthPicking must also be true for enabling this to work.
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) {
const pickedFeature = viewer.scene.pick(movement.position);
if (!Cesium.defined(pickedFeature)) {
// nothing picked
return;
}
const worldPosition = viewer.scene.pickPosition(movement.position);
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);postProcessStages : PostProcessStageCollection
Post processing effects applied to the final render.
readonly postRender : Event
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:
readonly postUpdate : Event
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.
readonly preRender : Event
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:
readonly preUpdate : Event
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:
readonly primitives : PrimitiveCollection
Gets the collection of primitives.
readonly renderError : Event
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.
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:
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
Gets whether or not the scene is optimized for 3D only viewing.
readonly screenSpaceCameraController : ScreenSpaceCameraController
Gets the controller for camera input handling.
shadowMap : ShadowMap
The shadow map for the scene's light source. When enabled, models, primitives, and the globe may cast and receive shadows.
skyAtmosphere : SkyAtmosphere
The sky atmosphere drawn around the globe.
-
Default Value:
undefined
skyBox : SkyBox
The
SkyBox used to draw the stars.
-
Default Value:
undefined
See:
The url to the KTX2 file containing the specular environment map and convoluted mipmaps for image-based lighting of PBR models.
Returns
true if specular environment maps are supported.
sphericalHarmonicCoefficients : Array.<Cartesian3>
The spherical harmonic coefficients for image-based lighting of PBR models.
Gets or sets the position of the splitter within the viewport. Valid values are between 0.0 and 1.0.
The
Sun.
-
Default Value:
undefined
Uses a bloom filter on the sun when enabled.
-
Default Value:
true
terrainProvider : TerrainProvider
The terrain provider providing surface geometry for the globe.
readonly terrainProviderChanged : Event
Gets an event that's raised when the terrain provider is changed
When
true, enables picking using the depth buffer.
-
Default Value:
true
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
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.
const scene = widget.scene;
const ellipsoid = scene.globe.ellipsoid;
const position = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
const 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
Clamps the given cartesian position to the scene geometry along the geodetic surface normal. Returns the
clamped position or
undefined if there was no scene geometry to clamp to. May be used to clamp
objects to the globe, 3D Tiles, or primitives in the scene.
This function only clamps to globe tiles and 3D Tiles that are rendered in the current view. Clamps to all other primitives regardless of their visibility.
| Name | Type | Default | Description |
|---|---|---|---|
cartesian |
Cartesian3 | The cartesian position. | |
objectsToExclude |
Array.<Object> | optional A list of primitives, entities, or 3D Tiles features to not clamp to. | |
width |
number |
0.1
|
optional Width of the intersection volume in meters. |
result |
Cartesian3 | optional An optional object to return the clamped position. |
Returns:
The modified result parameter or a new Cartesian3 instance if one was not provided. This may be
undefined if there was no scene geometry to clamp to.
Throws:
-
DeveloperError : clampToHeight is only supported in 3D mode.
-
DeveloperError : clampToHeight requires depth texture support. Check clampToHeightSupported.
Example:
// Clamp an entity to the underlying scene geometry
const position = entity.position.getValue(Cesium.JulianDate.now());
entity.position = viewer.scene.clampToHeight(position);See:
clampToHeightMostDetailed(cartesians, objectsToExclude, width) → Promise.<Array.<Cartesian3>>
Initiates an asynchronous
Scene#clampToHeight query for an array of Cartesian3 positions
using the maximum level of detail for 3D Tilesets in the scene. Returns a promise that is resolved when
the query completes. Each position is modified in place. If a position cannot be clamped because no geometry
can be sampled at that location, or another error occurs, the element in the array is set to undefined.
| Name | Type | Default | Description |
|---|---|---|---|
cartesians |
Array.<Cartesian3> | The cartesian positions to update with clamped positions. | |
objectsToExclude |
Array.<Object> | optional A list of primitives, entities, or 3D Tiles features to not clamp to. | |
width |
number |
0.1
|
optional Width of the intersection volume in meters. |
Returns:
A promise that resolves to the provided list of positions when the query has completed.
Throws:
-
DeveloperError : clampToHeightMostDetailed is only supported in 3D mode.
-
DeveloperError : clampToHeightMostDetailed requires depth texture support. Check clampToHeightSupported.
Example:
const cartesians = [
entities[0].position.getValue(Cesium.JulianDate.now()),
entities[1].position.getValue(Cesium.JulianDate.now())
];
const promise = viewer.scene.clampToHeightMostDetailed(cartesians);
promise.then(function(updatedCartesians) {
entities[0].position = updatedCartesians[0];
entities[1].position = updatedCartesians[1];
}See:
Instantly completes an active transition.
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
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:
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 and may be used to further identify the picked object. The primitives in
the list are ordered by their visual order in the scene (front to back).
| Name | Type | Default | Description |
|---|---|---|---|
windowPosition |
Cartesian2 | Window coordinates to perform picking on. | |
limit |
number | optional If supplied, stop drilling after collecting this many picks. | |
width |
number |
3
|
optional Width of the pick rectangle. |
height |
number |
3
|
optional Height of the pick rectangle. |
Returns:
Array of objects, each containing 1 picked primitives.
Throws:
-
DeveloperError : windowPosition is undefined.
Example:
const pickedObjects = scene.drillPick(new Cesium.Cartesian2(100.0, 200.0));See:
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.
Returns true if this object was destroyed; otherwise, false.
If this object was destroyed, it should not be used; calling any function other than
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:
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. |
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. |
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. |
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 and may be used to further identify the picked object.
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.
Example:
// On mouse over, color the feature yellow.
handler.setInputAction(function(movement) {
const feature = scene.pick(movement.endPosition);
if (feature instanceof Cesium.Cesium3DTileFeature) {
feature.color = Cesium.Color.YELLOW;
}
}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);pickPosition(windowPosition, result) → Cartesian3
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.
Update and render the scene. It is usually not necessary to call this function
directly because
CesiumWidget will do it automatically.
| Name | Type | Description |
|---|---|---|
time |
JulianDate | optional The simulation time at which to render. |
Requests a new rendered frame when
Scene#requestRenderMode is set to true.
The render rate will not exceed the CesiumWidget#targetFrameRate.
Returns the height of scene geometry at the given cartographic position or
undefined if there was no
scene geometry to sample height from. The height of the input position is ignored. May be used to clamp objects to
the globe, 3D Tiles, or primitives in the scene.
This function only samples height from globe tiles and 3D Tiles that are rendered in the current view. Samples height from all other primitives regardless of their visibility.
| Name | Type | Default | Description |
|---|---|---|---|
position |
Cartographic | The cartographic position to sample height from. | |
objectsToExclude |
Array.<Object> | optional A list of primitives, entities, or 3D Tiles features to not sample height from. | |
width |
number |
0.1
|
optional Width of the intersection volume in meters. |
Returns:
The height. This may be
undefined if there was no scene geometry to sample height from.
Throws:
-
DeveloperError : sampleHeight is only supported in 3D mode.
-
DeveloperError : sampleHeight requires depth texture support. Check sampleHeightSupported.
Example:
const position = new Cesium.Cartographic(-1.31968, 0.698874);
const height = viewer.scene.sampleHeight(position);
console.log(height);See:
sampleHeightMostDetailed(positions, objectsToExclude, width) → Promise.<Array.<Cartographic>>
Initiates an asynchronous
Scene#sampleHeight query for an array of Cartographic positions
using the maximum level of detail for 3D Tilesets in the scene. The height of the input positions is ignored.
Returns a promise that is resolved when the query completes. Each point height is modified in place.
If a height cannot be determined because no geometry can be sampled at that location, or another error occurs,
the height is set to undefined.
| Name | Type | Default | Description |
|---|---|---|---|
positions |
Array.<Cartographic> | The cartographic positions to update with sampled heights. | |
objectsToExclude |
Array.<Object> | optional A list of primitives, entities, or 3D Tiles features to not sample height from. | |
width |
number |
0.1
|
optional Width of the intersection volume in meters. |
Returns:
A promise that resolves to the provided list of positions when the query has completed.
Throws:
-
DeveloperError : sampleHeightMostDetailed is only supported in 3D mode.
-
DeveloperError : sampleHeightMostDetailed requires depth texture support. Check sampleHeightSupported.
Example:
const positions = [
new Cesium.Cartographic(-1.31968, 0.69887),
new Cesium.Cartographic(-1.10489, 0.83923)
];
const 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:
setTerrain(terrain) → Terrain
Update the terrain providing surface geometry for the globe.
| Name | Type | Description |
|---|---|---|
terrain |
Terrain | The terrain provider async helper |
Returns:
terrain The terrain provider async helper
Examples:
// Use Cesium World Terrain
scene.setTerrain(Cesium.Terrain.fromWorldTerrain());// Use a custom terrain provider
const terrain = new Cesium.Terrain(Cesium.CesiumTerrainProvider.fromUrl("https://myTestTerrain.com"));
scene.setTerrain(terrain);
terrain.errorEvent.addEventListener(error => {
alert(`Encountered an error while creating terrain! ${error}`);
});