Viewer - Cesium Documentation

new Cesium.Viewer(container, options)

Viewer is the basic building block for building applications that combine all standard Cesium components into a single reusable package. The viewer component can usually be extended with mixins to add functional functions that are useful to various applications.

Name Type Description

container Element | String Specifies the Document Object Model (DOM) or ID that holds the HTML element of the viewer component.

options

Object

optional The object has the following properties:

Name	Type	Default	Description
`clock`	Clock	`new Clock()`	optional The clock used to control the current time.
`selectedImageryProviderViewModel`	ProviderViewModel		optional The view model of the current underlying image layer, if not provided, uses the first available base layer. This value is only valid when options.baseLayerPicker is set to true.
`imageryProviderViewModels`	Array.<ProviderViewModel>	`createDefaultImageryProviderViewModels()`	optional The ProviderViewModels array can be selected from BaseLayerPicker. This value is only valid when options.baseLayerPicker is set to true.
`selectedTerrainProviderViewModel`	ProviderViewModel		optional The view model of the current base terrain layer, if not provided, uses the first available base layer. This value is only valid when options.baseLayerPicker is set to true.
`terrainProviderViewModels`	Array.<ProviderViewModel>	`createDefaultTerrainProviderViewModels()`	optional The ProviderViewModels array can be selected from BaseLayerPicker. This value is only valid when options.baseLayerPicker is set to true.
`imageryProvider`	ImageryProvider	`new BingMapsImageryProvider()`	optional The image provider used. This value is only valid when options.baseLayerPicker is set to false.
`terrainProvider`	TerrainProvider	`new EllipsoidTerrainProvider()`	optional The terrain provider used.
`skyBox`	SkyBox		optional The skybox used to render stars, when undefined, uses the default star effect.
`skyAtmosphere`	SkyAtmosphere		optional The blue sky and glow effects around the edge of the earth are set to false to turn them off.
`useDefaultRenderLoop`	Boolean	`true`	optional Set to true if this widget can control the render loop, otherwise set to false.
`targetFrameRate`	Number		optional The target frame rate when using the default render loop.
`showRenderLoopErrors`	Boolean	`true`	optional If set to true, an HTML panel containing the error message is automatically displayed to the user when a rendering loop error occurs.
`automaticallyTrackDataSourceClocks`	Boolean	`true`	optional If set to true, the clock settings for the newly added data source are automatically tracked and updated if the data source's clock changes. To set the clock separately, set this to false.
`contextOptions`	Object		optional Context and WebGL create attributes that match the options passed to `Scene`.
`mapProjection`	MapProjection	`new GeographicProjection()`	optional Map projection used in 2D and Columbus view modes.
`globe`	Globe	`new Globe(mapProjection.ellipsoid)`	optional Earth in the scene, if this item is set to false, no sphere object will be added.
`orderIndependentTranslucency`	Boolean	`true`	optional If this is set to true and device support is used, semi-transparency independent of the order will be used.
`creditContainer`	Element \| String		optional Specify a DOM element or ID that contains `CreditDisplay` information. If not specified, the credit information will be added to the bottom of the component.
`dataSources`	DataSourceCollection	`new DataSourceCollection()`	optional Specify a DOM element or ID that contains `CreditDisplay` information. If not specified, the credit information will be added to the bottom of the component.
`terrainExaggeration`	Number	`1.0`	optional A scalar used to exaggerate the terrain. Please note that setting terrain exaggeration does not modify any other data.
`shadows`	Boolean	`false`	optional Determine if the shadow is formed by the sun's projection.
`terrainShadows`	ShadowMode	`ShadowMode.RECEIVE_ONLY`	optional Determine if the terrain projects or accepts shadows from the sun.
`mapMode2D`	MapMode2D	`MapMode2D.INFINITE_SCROLL`	optional Make sure the 2D map is rotatable or can scroll infinitely in the horizontal direction.
`navigation`	Boolean	`false`	optional Whether to display the navigation compass control. To display, this item needs to be set to true when the viewer is initialized.

Throws:

DeveloperError : The "container" element with this ID does not exist in the document.
DeveloperError : when using the BaseLayerPicker component, options.imageryProvider is not available, please change to the specified options.selectedImageryProviderViewModel.
DeveloperError : when using the BaseLayerPicker component, options.terrainProvider is not available, please change to the specified options.selectedTerrainProviderViewModel.
DeveloperError : When using the BaseLayerPicker component, options.selectedImageryProviderViewModel is not available, please change to the specified options.imageryProvider.
DeveloperError : when using the BaseLayerPicker component, options.selectedTerrainProviderViewModel is not available, please change to the specified options.terrainProvider .

Example:

//Initialize the viewer component
var viewer = new Cesium.Viewer('cesiumContainer', {
    //Use STK World Terrain
    terrainProvider : new Cesium.CesiumTerrainProvider({
        url : 'https://assets.agi.com/stk-terrain/world'
    }),
    //Use OpenStreetMaps
    imageryProvider : Cesium.createOpenStreetMapImageryProvider({
        url : 'https://a.tile.openstreetmap.org/'
    }),
});

//Add basic drag and drop
viewer.extend(Cesium.viewerDragDropMixin);

//An error was encountered while processing the deleted file, and a pop-up warning was displayed.
viewer.dropError.addEventListener(function(dropHandler, name, error) {
    console.log(error);
    window.alert(error);
});

See:

Members

allowDataSourcesToSuspendAnimation : Boolean

Gets or sets whether the data source can temporarily pause the animation to avoid displaying incomplete images to the user. For example, if the background is processing an asynchronous function, the clock will not advance until the geometry is ready.

readonlyanimation : Animation

Get the Animation component.

readonlybaseLayerPicker : BaseLayerPicker

Get the base layer picker (BaseLayerPicker) object.

readonlybottomContainer : Element

Get the DOM element at the bottom of the window containing CreditDisplay and other potential information.

readonlycamera : Camera

Get the camera object.

readonlycanvas : Canvas

Get the canvas object.

readonlycesiumLogo : Element

Get the Cesium trademark element.

readonlycesiumWidget : CesiumWidget

Get the CesiumWidget object.

readonlyclock : Clock

Get the clock object.

readonlyclockViewModel : ClockViewModel

Get the clock view model.

readonlycontainer : Element

Get the parent container.

readonlydataSourceDisplay : DataSourceDisplay

Get the display for DataSource.

readonlydataSources : DataSourceCollection

Gets or sets the collection of DataSource instances of the data source to be visualized.

readonlyentities : EntityCollection

Get a collection of entities that are independent of a particular data source. This is a shortcut to access dataSourceDisplay.defaultDataSource.entities.

readonlyfullscreenButton : FullscreenButton

Get the full screen button (FullscreenButton) object.

readonlygeocoder : Geocoder

Get a geocoder object.

readonlyhomeButton : HomeButton

Get the Home button (HomeButton) object.

readonlyimageryLayers : ImageryLayerCollection

Get the collection of image layers that will be rendered on Earth.

readonlyinfoBox : InfoBox

Get the InfoBox object.

readonlynavigationHelpButton : NavigationHelpButton

Get the navigation help button (NavigationHelpButton) object.

readonlyprojectionPicker : ProjectionPicker

Get the projection picker.

resolutionScale : Number

Gets or sets the scaling factor of the rendering resolution. Values less than 1.0 can improve performance on less powerful devices; conversely, values greater than 1.0 will be rendered at higher resolutions and then scaled down to improve visual fidelity. For example, if the widget is 640x480, setting this property to 0.5 will cause the scene to be rendered at 320x240 resolution, and the scene will be scaled up. Setting it to 2.0 will cause the scene to be rendered at 1280x960 and the scene scaled down.

Default Value: 1.0

readonlyscene : Scene

Get the scene object.

readonlysceneModePicker : SceneModePicker

Get the scene mode picker (SceneModePicker) object.

readonlyscreenSpaceEventHandler : ScreenSpaceEventHandler

Get the screen space event handler.

selectedEntity : Entity

Gets or sets the object instance for which the selection indicator is displayed.

readonlyselectedEntityChanged : Event

Gets the event raised when the selected entity object changes.

readonlyselectionIndicator : SelectionIndicator

Get the SelectionIndicator object.

readonlyshadowMap : ShadowMap

Get a shadow map of the scene.

shadows : Boolean

Determine if the shadow is formed by the sun's projection.

targetFrameRate : Number

Gets or sets the target frame rate of the component when useDefaultRenderLoop is set to true. If this property is not defined, the frame rate is determined by the browser's requestAnimationFrame implementation; if this property is already defined, the value should be greater than 0, and Values larger than the underlying requestAnimationFrame will not work.

terrainProvider : TerrainProvider

A TerrainProvider object that provides surface geometry for the Earth.

terrainShadows : ShadowMode

Determine if the terrain projects or accepts shadows from the sun.

readonlytimeline : Timeline

Get the Timeline component.

trackedEntity : Entity

Gets or sets the entity instance currently being tracked by the camera.

readonlytrackedEntityChanged : Event

Gets the events raised when the tracking entity object changes.

useDefaultRenderLoop : Boolean

Gets or sets whether the widget can control the render loop.

When set to true, the component will use requestAnimationFrame to perform rendering and resizing parts, as well as driving the clock emulation; When set to false, you must manually call the render and resize methods as part of a custom loop render.

If an error occurs during rendering, Scene's renderError event will be fired and this property will be changed to false. This property must be changed back to true after the error occurs in order to continue rendering.

readonlyvrButton : VRButton

Get the VRButton object.

Methods

destroy()

Release the resources occupied by the object.

extend(mixin, options)

Use the provided mixin to extend the underlying viewer functionality. Mixin can add additional properties, functionality, or other behavior to the provided viewer instance.

Name	Type	Description
`mixin`	Viewer~ViewerMixin	Specifies the Viewer mixin object that will be added to the instance.
`options`	Object	optional Specifies the options object passed to the mixin function.

See:

viewerDragDropMixin

flyTo(target, options) → Promise.<Boolean>

The camera flies to the specified entity, entity set, or data source. If the data source is still loading, or if visualization is still in progress, this method waits for data to be ready before performing the flight.

The offset variable is represented by the "azimuth/pitch angle/range" in the local "east-north-up" reference frame (the center point is the center of the encircled ball). The angles of the azimuth and elevation angles are defined in the local "east-north-up" reference frame. Azimuth heading is the angular value that starts from the y-axis and increases toward the x-axis. The pitch angle pitch is the angle of rotation from the xy plane. The positive pitch angle is above the plane and the negative is below the plane. The distance range represents the distance from the center point. If range is 0, a range is calculated such that the entire bounding sphere is visible.

There must be a top-down view in 2D. The camera is located above the target. Range is the height above the target; headingy is determined by the offset. If the azimuth cannot be determined from the offset, heading is north.

Name Type Description

options

Object

optional The object has the following properties:

Name	Type	Default	Description
`duration`	Number	`3.0`	optional Flight duration (in seconds).
`maximumHeight`	Number		optional The maximum height in flight.
`offset`	HeadingPitchRange		optional In the local "east-north-up" reference frame centered on the target, the offset from the target.

Returns:

When the flight is successful, the promise is parsed as true; if the entity is not visualized in the scene or the flight is canceled, the promise is parsed to false.

forceResize()

Forced re-adjustment, so that the component reconsider the layout including component size, credit placement, and so on.

isDestroyed() → Boolean

Returns whether to release the resources occupied by the object.

Returns:

True means that the occupied resource has been released, otherwise it returns false.

render()

Render the scene. This function is called automatically unless useDefaultRenderLoop is set to false.

resize()

Resize the part to match the container. This function will be called automatically on demand unless useDefaultRenderLoop is set to false.

zoomTo(target, offset) → Promise.<Boolean>

Set up the camera asynchronously to view the specified entity, entity set, or data source. If the data source is still loading, or if visualization is still in progress, this method waits for the data to be ready before performing the scaling.

There must be a top-down view in 2D. The camera is located above the target. Range is the height above the target; heading has an offset determination, otherwise the azimuth cannot be determined from the offset, and heading is north.

Name	Type	Description
`target`	Entity \| Array.<Entity> \| EntityCollection \| DataSource \| ImageryLayer \| Promise.<(Entity\|Array.<Entity>\|EntityCollection\|DataSource\|ImageryLayer)>	Specifies the entity, entity set, data source, or image layer to view. You can also specify a promise to resolve one of the aforementioned types.
`offset`	HeadingPitchRange	optional Specifies the offset from the center of the local East-North-Up reference frame.

Returns:

When the scaling succeeds, the promise is parsed to true; if the entity is not visualized or zoomed out in the scene, the promise is resolved to false.

Type Definitions

ViewerMixin(viewer, options)

Add a function for a Viewer instance with additional functionality.

Name	Type	Description
`viewer`	Viewer	Viewer instance object.
`options`	Object	The options object passed to the mixin function.

See:

Viewer#extend