Class: CesiumWidgetView

CesiumWidgetView()

An interactive 2D and/or 3D map/globe rendered using CesiumJS. This view comprises the globe without any of the UI elements like the scalebar, layer list, etc.

Screenshot

Constructor

new CesiumWidgetView()

Since:
  • 2.18.0
Source:
Fires:
  • MapInteraction#event:moved
  • MapInteraction#event:moveEnd
  • MapInteraction#event:moveStart

Extends

  • Backbone.View

Members

className :string

The HTML classes to use for this view's element. Note that the first child element added to this view by cesium will have the class "cesium-widget".
Type:
  • string
Source:

highlightBorderColor :Cesium.Color

The border color to use on vector features that a user clicks. See https://cesium.com/learn/cesiumjs/ref-doc/Color.html?classFilter=color
Type:
  • Cesium.Color
Source:

mapAssetRenderFunctions :Array.<object>

An array of objects the match a Map Asset's type property to the function in this view that adds and renders that asset on the map, given the Map Asset model. Each object in the array has two properties: 'types' and 'renderFunction'.
Type:
  • Array.<object>
Properties:
Name Type Description
types Array.<string> The list of types that can be added to the map given the renderFunction
renderFunction string The name of the function in the view that will add the asset to the map and render it, when passed the cesiumModel attribute from the MapAsset model
removeFunction string The name of the function in the view that will remove the asset from the map, when passed the cesiumModel attribute from the MapAsset model
Source:

model :Map

The model that this view uses
Type:
Source:

requestRender

Because the Cesium widget is configured to use explicit rendering (see https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/), we need to tell Cesium when to render a new frame if it's not one of the cases handle automatically. This function tells the Cesium scene to render, but is limited by the underscore.js debounce function to only happen a maximum of once every 50 ms (see https://underscorejs.org/#debounce).
Source:

template :Underscore.template

The primary HTML template for this view
Type:
  • Underscore.template
Source:

type :string

The type of View this is
Type:
  • string
Source:

Methods

add3DTileset(cesiumModel)

Renders a 3D tileset in the map.
Parameters:
Name Type Description
cesiumModel Cesium.Cesium3DTileset The Cesium 3D tileset model that contains the information about the 3D tiles to render in the map
Source:

addAsset(mapAsset)

Finds the function that is configured for the given asset model type in the CesiumWidgetView#mapAssetRenderFunctions array, then renders the asset in the map. If there is a problem rendering the asset (e.g. it is an unsupported type that is not configured in the mapAssetRenderFunctions), then sets the AssetModel's status to error.
Parameters:
Name Type Description
mapAsset MapAsset A MapAsset layer to render in the map, such as a Cesium3DTileset or a CesiumImagery model.
Source:

addImagery(cesiumModel)

Renders imagery in the Map.
Parameters:
Name Type Description
cesiumModel Cesium.ImageryLayer The Cesium imagery model to render
Source:

addLayers()

Add all of the model's layers to the map. This function is called during the render function.
Since:
  • 2.26.0
Source:

addVectorData(cesiumModel)

Renders vector data (excluding 3D tilesets) in the Map.
Parameters:
Name Type Description
cesiumModel Cesium.GeoJsonDataSource The Cesium data source model to render on the map
Source:

completeFlight(target, options)

This function is called by CesiumWidgetView#postRender; it should only be called once the target has been fully rendered in the scene. This function gets the bounding sphere, if required, and moves the scene to encompass the full extent of the target.
Parameters:
Name Type Description
target MapAsset | Cesium.BoundingSphere | Object | Feature | GeoPoint The target asset, bounding sphere, or location to change the camera focus to. If target is a MapAsset, then the bounding sphere from that asset will be used for the target destination. If target is an Object, it may contain any of the properties that are supported by the Cesium camera flyTo options, see https://cesium.com/learn/cesiumjs/ref-doc/Camera.html#flyTo. The object may also be a position with longitude, latitude, and height. If the target is a Feature, then it must be a Feature of a CesiumVectorData layer (currently Cesium3DTileFeatures are not supported). The target can otherwise be a Cesium BoundingSphere, see https://cesium.com/learn/cesiumjs/ref-doc/BoundingSphere.html
options object For targets that are a bounding sphere or asset, options to pass to Cesium Camera.flyToBoundingSphere(). See https://cesium.com/learn/cesiumjs/ref-doc/Camera.html#flyToBoundingSphere. For other targets, options will be merged with the target object and passed to Cesium Camera.flyTo(). See https://cesium.com/learn/cesiumjs/ref-doc/Camera.html#flyTo
Source:

coversGlobe(coords, latAllowance, lonAllowance) → {Boolean}

Check if a given bounding box covers the entire globe.
Parameters:
Name Type Description
coords Object An object with the north, south, east, and west coordinates of a bounding box
latAllowance Number The number of degrees latitude to allow as a buffer. If the north and south coords range from -90 to 90, minus this buffer * 2, then it is considered to cover the globe.
lonAllowance Number The number of degrees longitude to allow as a buffer.
Source:
Returns:
Returns true if the bounding box covers the entire globe, false otherwise.
Type
Boolean

findEdges() → {Array.<Cesium.Cartesian3>}

Find four points that exist on the globe that are closest to the top-center, bottom-center, right-middle, and left-middle points of the screen. Note that these are not necessarily the northern, southern, eastern, and western -most points, since the map may be oriented in any direction (e.g. facing the north pole).
Source:
Returns:
Returns an object with the top, bottom, left, and right points of the globe.
Type
Array.<Cesium.Cartesian3>

findMidpoint(p1, p2) → {Cesium.Cartesian3|null}

Given two Cartesian3 points, compute the midpoint.
Parameters:
Name Type Description
p1 Cesium.Cartesian3 The first point
p2 Cesium.Cartesian3 The second point
Source:
Returns:
The midpoint or null if p1 or p2 is not defined.
Type
Cesium.Cartesian3 | null

findPointOnGlobe(startCoordinates, endCoordinates) → {Cesium.Cartesian3|null}

Find a coordinate that exists on the surface of the globe between two Cartesian points. The points do not need to be withing the bounds of the globe/map (i.e. they can be points in the sky). Uses the Bresenham Algorithm to traverse pixels from the first coordinate to the second, until it finds a valid coordinate.
Parameters:
Name Type Description
startCoordinates Cesium.Cartesian2 The coordinates to start searching, in pixels
endCoordinates Cesium.Cartesian2 The coordinates to stop searching, in pixels
Source:
See:
Returns:
Returns the x, y, z coordinates of the first real point, or null if a valid point was not found.
Type
Cesium.Cartesian3 | null

flyHome(duration)

Navigate to the homePosition that's set on the Map.
Parameters:
Name Type Description
duration number The duration of the flight in seconds.
Source:

flyTo(target, options)

Move the camera position and zoom to the specified target entity or position on the map, using a nice animation. This function starts the flying/zooming action by setting a zoomTarget and zoomOptions on the view and requesting the scene to render. The actual zooming is done by CesiumWidgetView#completeFlight after the scene has finished rendering.
Parameters:
Name Type Description
target MapAsset | Cesium.BoundingSphere | Object | Feature The target asset, bounding sphere, or location to change the camera focus to. If target is a MapAsset, then the bounding sphere from that asset will be used for the target destination. If target is an Object, it may contain any of the properties that are supported by the Cesium camera flyTo options, see https://cesium.com/learn/cesiumjs/ref-doc/Camera.html#flyTo. If the target is a Feature, then it must be a Feature of a CesiumVectorData layer (currently Cesium3DTileFeatures are not supported). The target can otherwise be a Cesium BoundingSphere, see https://cesium.com/learn/cesiumjs/ref-doc/BoundingSphere.html
options object For targets that are a bounding sphere or asset, options to pass to Cesium Camera.flyToBoundingSphere(). See https://cesium.com/learn/cesiumjs/ref-doc/Camera.html#flyToBoundingSphere.
Source:

getCameraPosition() → {MapConfig#CameraPosition}

Get the current positioning of the camera in the view.
Source:
Returns:
Returns an object with the longitude, latitude, height, heading, pitch, and roll in the same format that the Map model uses for the homePosition (see Map#defaults)
Type
MapConfig#CameraPosition

getDegreesFromCartesian(cartesian)

Get longitude and latitude degrees from a cartesian point.
Parameters:
Name Type Description
cartesian Cesium.Cartesian3 The point to get degrees for
Source:
Returns:
Returns an object with the longitude and latitude in degrees, as well as the height in meters

getEntityById(id, collection) → {Cesium.Entity}

Search an entity collection for an entity with a given id.
Parameters:
Name Type Description
id string The id of the entity to find.
collection Cesium.EntityCollection The collection to search.
Since:
  • 2.27.0
Source:
Returns:
The entity with the given id, or null if no entity with that id exists in the collection.
Type
Cesium.Entity

getViewExtent() → {MapConfig#ViewExtent}

Get the north, south, east, and west-most lat/long that define a bounding box around the currently visible area of the map. Also gives the height/ altitude of the camera in meters.
Source:
Returns:
The current view extent.
Type
MapConfig#ViewExtent

initialize(optionsopt)

Executed when a new CesiumWidgetView is created
Parameters:
Name Type Attributes Description
options Object <optional>
 A literal object with options to pass to the view
Source:

pixelToMeters() → {number|boolean}

Finds the geodesic distance (in meters) between two points that are 1 pixel apart at the bottom, center of the Cesium canvas. Adapted from TerriaJS. See https://github.com/TerriaJS/terriajs/blob/main/lib/ReactViews/Map/Legend/DistanceLegend.jsx
Source:
Returns:
Returns the distance on the globe, in meters, that is equivalent to 1 pixel on the screen at the center bottom point of the current scene. Returns false if there was a problem getting the measurement.
Type
number | boolean

positionToFlightTarget(position, duration)

Navigate to the homePosition that's set on the Map.
Parameters:
Name Type Description
position Object The position to navigate to. Must have longitude, latitude, and may have a height (elevation) in meters, heading, pitch, and roll in degrees.
duration number The duration of the flight in seconds.
Source:

postRender()

Functions called after each time the scene renders. If a zoom target has been set by the CesiumWidgetView#flyTo function, then calls the functions that calculates the bounding sphere and zooms to it (which required to visual elements to be rendered first.)
Source:

remove3DTileset(cesiumModel)

Remove a 3D tileset from the map.
Parameters:
Name Type Description
cesiumModel Cesium.Cesium3DTileset The Cesium 3D tileset model to remove from the map
Since:
  • 2.27.0
Source:

removeAsset(mapAsset)

When an asset is removed from the map model, remove it from the map.
Parameters:
Name Type Description
mapAsset MapAsset The MapAsset model removed from the map
Since:
  • 2.27.0
Source:

removeCameraListeners()

Remove any previously set camera listeners.
Since:
  • 2.27.0
Source:

removeImagery(cesiumModel)

Remove imagery from the Map.
Parameters:
Name Type Description
cesiumModel Cesium.ImageryLayer The Cesium imagery model to remove from the map
Since:
  • 2.27.0
Source:

removeMouseListeners()

Remove any previously set mouse listeners.
Since:
  • 2.27.0
Source:

removeNavigationListeners()

Remove listeners for dynamic navigation.
Since:
  • 2.27.0
Source:

removeVectorData(cesiumModel)

Remove vector data (excluding 3D tilesets) from the Map.
Parameters:
Name Type Description
cesiumModel Cesium.GeoJsonDataSource The Cesium data source model to remove from the map
Since:
  • 2.27.0
Source:

render() → {CesiumWidgetView}

Renders this view
Source:
Returns:
Returns the rendered view element
Type
CesiumWidgetView

renderWidget() → {Cesium.CesiumWidget}

Create the Cesium Widget and save a reference to it to the view
Since:
  • 2.27.0
Source:
Returns:
The Cesium Widget
Type
Cesium.CesiumWidget

setAssetListeners()

Listen for changes to the assets and update the map accordingly.
Since:
  • 2.27.0
Source:

setCameraListeners()

Listen to cesium camera events, and translate them to events on the interactions model. Also update the scale (pixels:meters) and the view extent when the camera has moved.
Source:

setHoveredFeatures(position, delayopt)

Record the feature hovered over by the mouse based on position.
Parameters:
Name Type Attributes Default Description
position Object The position of the mouse on the map
delay number <optional>
 200 The minimum number of milliseconds that must pass between calls to this function.
Since:
  • 2.27.0
Source:

setInteractionListeners()

React when the user interacts with the map.
Since:
  • 2.27.0
Source:

setLighting()

Configure the lighting on the globe.
Source:

setMouseListeners()

Set up listeners for mouse events on the map. This includes listening for mouse clicks, mouse movement, and mouse hovering over features. These listeners simply update the interactions model with mouse events.
Since:
  • 2.27.0
Source:

setMousePosition(event)

When the mouse is moved over the map, update the interactions model with the current mouse position.
Parameters:
Name Type Description
event Object The event object from Cesium
Since:
  • 2.27.0
Source:

setNavigationListeners()

Set up listeners to allow for dynamic navigation. This includes zooming to the extent of a layer and zooming to the home position. Note that other views may trigger an event on the layer/asset model that indicates that the map should navigate to a given extent.
Since:
  • 2.27.0
Source:

setUpDataSourceDisplay() → {Cesium.DataSourceDisplay}

Create a DataSourceDisplay and DataSourceCollection for the Cesium widget. This is required to display vector data (e.g. GeoJSON) on the map.
Since:
  • 2.27.0
Source:
Returns:
The Cesium DataSourceDisplay
Type
Cesium.DataSourceDisplay

setUpSilhouettes()

Set up the Cesium scene and set listeners and behavior that enable users to click on vector features on the map to highlight them.
Since:
  • 2.27.0
Source:

showImageryGrid(coloropt, tilingSchemeopt)

Display a box around every rendered tile in the tiling scheme, and draw a label inside it indicating the X, Y, Level indices of the tile. This is mostly useful for debugging terrain and imagery rendering problems. This function should be called after the other imagery layers have been added to the map, e.g. at the end of the render function.
Parameters:
Name Type Attributes Default Description
color string <optional>
 '#ffffff' The color of the grid outline and labels. Must be a CSS color string, beginning with a #.
tilingScheme 'GeographicTilingScheme' | 'WebMercatorTilingScheme' <optional>
 'GeographicTilingScheme' The tiling scheme to use. Defaults to GeographicTilingScheme.
Source:

showSelectedFeatures()

Highlight the features that are currently selected in the interactions model.
Since:
  • 2.27.0
Source:

sortImagery()

Arranges the imagery that is rendered the Map according to the order that the imagery is arranged in the layers collection.
Since:
  • 2.21.0
Source:

updateAllDataSources() → {boolean}

Run the update method and all visualizers for each data source.
Since:
  • 2.27.0
Source:
Returns:
Returns true if all data sources are ready to be displayed.
Type
boolean

updateCursor(hoveredFeatures)

Change the cursor to a pointer when the mouse is hovering over a feature.
Parameters:
Name Type Description
hoveredFeatures Object | null The feature that the mouse is hovering over or null if the mouse is not hovering over a feature.
Source:

updateScale()

Update the map model's currentScale attribute, which is used for the scale bar. Finds the distance between two pixels at the *bottom center* of the screen.
Source:

updateSearchParams()

Update the search parameters related to the current map position and heading.
Since:
  • 2.30.0
Source:

updateTerrain(cesiumModel)

Renders peaks and valleys in the 3D version of the map, given a terrain model. If a terrain model has already been set on the map, this will replace it.
Parameters:
Name Type Description
cesiumModel Cesium.TerrainProvider a Cesium Terrain Provider model to use for the map
Source:

updateViewExtent()

Update the 'currentViewExtent' attribute in the Map model with the bounding box of the currently visible area of the map.
Source: