Class: CesiumImagery

CesiumImagery()

A CesiumImagery Model contains the information required for Cesium to request and draw high-resolution image tiles using several standards (Cesium "imagery providers"), including Cesium Ion and Bing Maps. Imagery layers have brightness, contrast, gamma, hue, and saturation properties that can be dynamically changed.

Constructor

new CesiumImagery()

Since:
  • 2.18.0
Source:

Extends

Members

defaults :Object

Default attributes for CesiumImagery models
Type:
  • Object
Properties:
Name Type Description
type 'BingMapsImageryProvider' | 'IonImageryProvider' | 'TileMapServiceImageryProvider' | 'WebMapTileServiceImageryProvider' A string indicating a Cesium Imagery Provider type. See https://cesium.com/learn/cesiumjs-learn/cesiumjs-imagery/#more-imagery-providers
cesiumModel Cesium.ImageryLayer A model created and used by Cesium that organizes the data to display in the Cesium Widget. See https://cesium.com/learn/cesiumjs/ref-doc/ImageryLayer.html?classFilter=ImageryLayer and https://cesium.com/learn/cesiumjs/ref-doc/?classFilter=ImageryProvider
cesiumOptions CesiumImagery#cesiumOptions options that are passed to the function that creates the Cesium model. The properties of options are specific to each type of asset.
Overrides:
Source:

idAttribute :string

Use layerId as Backbone identity; id remains the DataONE package ID.
Type:
  • string
Since:
  • 2.41.0
Inherited From:
Source:

type :string

The name of this type of model
Type:
  • string
Overrides:
Source:

Methods

addCustomProperties(properties) → {object}

Given a set of properties from a Feature from this Map Asset model, add any custom properties to the properties object and return it.
Parameters:
Name Type Description
properties object A set of key-value pairs representing the existing properties of a feature from this asset.
Since:
  • 2.19.0
Inherited From:
Source:
Returns:
The properties object with any custom properties added.
Type
object

containsFeature(feature) → {boolean}

Given a feature object from a Feature model, checks if it is part of the selectedFeatures collection. See featureObject property from Feature#defaults. For vector and 3d tile models only.
Parameters:
Name Type Description
feature * An object that a Map widget uses to represent this feature in the map, e.g. a Cesium.Entity or a Cesium.Cesium3DTileFeature
Since:
  • 2.25.0
Inherited From:
Source:
Returns:
Returns true if the given feature is part of the selectedFeatures collection in this asset
Type
boolean

createCesiumModel(recreate)

Creates a Cesium ImageryLayer that contains information about how the imagery should render in Cesium. See https://cesium.com/learn/cesiumjs/ref-doc/ImageryLayer.html?classFilter=ImageryLay
Parameters:
Name Type Description
recreate Boolean Set recreate to true to force the function create the Cesium Model again. Otherwise, if a cesium model already exists, that is returned instead.
Source:

createCesiumModelWhenVisible()

Create the Cesium model for this asset, if it doesn't already exist and the asset is visible. If not visible, then wait until it becomes visible to create the model.
Since:
  • 2.36.0
Inherited From:
Source:

featureIsSelected(feature) → {boolean}

Given a feature object from a Feature model, checks if it is part of the selectedFeatures collection. See featureObject property from Feature#defaults. For vector and 3d tile models only.
Parameters:
Name Type Description
feature * An object that a Map widget uses to represent this feature in the map, e.g. a Cesium.Entity or a Cesium.Cesium3DTileFeature
Inherited From:
Source:
Returns:
Returns true if the given feature is part of the selectedFeatures collection in this asset
Type
boolean

featureIsVisible(properties) → {boolean}

This function checks whether a feature from the MapAsset is visible on the map based on the properties of the feature and the MapAsset's filter settings.
Parameters:
Name Type Description
properties object The properties of the feature to be filtered. (See the 'properties' attribute of Feature#defaults.)
Inherited From:
Source:
Returns:
Returns true if the feature passes all the filters, or if there are no filters set for this MapAsset. Returns false if the feature fails any of the filters.
Type
boolean

formatDateProperty(config, properties) → {string}

Given a definition for a new date property, and the properties that already exist on a specific feature, returns a new string with the formatted date.
Parameters:
Name Type Description
config MapConfig#CustomDateProperty An object that defines the new date property to create
properties object key-value pairs representing existing properties in a Feature
Since:
  • 2.19.0
Inherited From:
Source:
Returns:
The value for the new date property, formatted as defined by config, for the given feature
Type
string

formatStringProperty(config) → {string}

For a given set of Feature properties and a definition for a new sting property, returns the value of the custom property. Note that since only static strings are supported so far, this function essentially just returns the value of config.value. This function exists to allow support of dynamic strings in the future (e.g. combining strings from existing properties)
Parameters:
Name Type Description
config MapConfig#CustomStringProperty The object the defines the new custom property
Since:
  • 2.19.0
Inherited From:
Source:
Returns:
The new string for the given Feature property
Type
string

getBoundingSphere() → {Promise}

Gets a Cesium Bounding Sphere that can be used to navigate to view the full extent of the imagery. See https://cesium.com/learn/cesiumjs/ref-doc/BoundingSphere.html
Source:
Returns:
Returns a promise that resolves to a Cesium Bounding Sphere when ready
Type
Promise

getCesiumOptions() → {object}

Get the asset config's cesiumOptions, if it has any. This will return a copy of the cesiumOptions object, so that changes made to the returned object will not affect the original cesiumOptions object.
Since:
  • 2.26.0
Inherited From:
Source:
Returns:
A copy of the cesiumOptions object, or null if there are no cesiumOptions.
Type
object

getColor(properties) → {AssetColor#Color}

Given properties of a Feature model from this MapAsset, returns the color associated with that feature.
Parameters:
Name Type Description
properties object The properties of the feature to get the color for; An object containing key-value mapping of property names to properties. (See the 'properties' attribute of Feature#defaults.)
Inherited From:
Source:
Returns:
The color associated with the given set of properties.
Type
AssetColor#Color

getDataUriFromBitmap(bitmap) → {String}

Gets a data URI from a bitmap image.
Parameters:
Name Type Description
bitmap ImageBitmap The bitmap image to convert to a data URI
Source:
Returns:
Returns a string containing the requested data URI.
Type
String

getFeatureAttributes(feature) → {object}

Given a feature object from a Feature model, returns the attributes needed to create a Feature model. For vector and 3d tile models only.
Parameters:
Name Type Description
feature * An object that a Map widget uses to represent this feature in the map, e.g. a Cesium.Entity or a Cesium.Cesium3DTileFeature
Inherited From:
Source:
Returns:
An object with properties, mapAsset, featureID, featureObject, and label properties. Returns null if the feature is not the correct type for this asset model.
Type
object

getThumbnail()

Requests a tile from the imagery provider that is at the center of the layer's bounding box and at the minimum level. Once the image is fetched, sets its URL on the thumbnail property of this model. This function is first called when the layer initialized, but waits for the cesiumModel to be ready.
Source:

handleError()

When the asset can't be loaded, hide it from the map and show an error.
Since:
  • 2.27.0
Inherited From:
Source:

initUSGSImageryTopo(assetConfigopt)

Set default metadata for the USGS Imagery Topo asset.
Parameters:
Name Type Attributes Description
assetConfig MapConfig#MapAssetConfig <optional>
 The initial values of the attributes, which will be set on the model.
Source:

initialize(assetConfigopt)

Executed when a new CesiumImagery model is created.
Parameters:
Name Type Attributes Description
assetConfig MapConfig#MapAssetConfig <optional>
 The initial values of the attributes, which will be set on the model.
Overrides:
Source:

isDisplayReadyInScene(scene) → {boolean}

Returns true when this imagery layer has at least one drawable tile in cache and is currently shown in the scene.
Parameters:
Name Type Description
scene Cesium.Scene The scene where this imagery is rendered.
Since:
  • 2.41.0
Source:
Returns:
True when imagery should be considered display-ready.
Type
boolean

isVisible() → {boolean}

Checks that the visible attribute is set to true and that the opacity attribute is greater than zero. If both conditions are met, returns true.
Inherited From:
Source:
Returns:
Returns true if the MapAsset has opacity > 0 and is visible.
Type
boolean

listenToSelectedFeatures()

Update the appearance of features from this asset when they are selected or deselected in the map widget.
Since:
  • 2.27.0
Inherited From:
Source:

resetStatus()

Resets the Map Asset's status and statusDetails attributes to their default values.
Since:
  • 2.21.0
Inherited From:
Source:

setError(error)

Set an error status and message for this asset.
Parameters:
Name Type Description
error object | string An error object with a status code attribute or or string with details about the error.
Since:
  • 2.27.0
Inherited From:
Source:

setListeners()

Set listeners that update the cesium model when the backbone model is updated.
Overrides:
Source:

setReady()

Set a ready status for this asset.
Since:
  • 2.27.0
Inherited From:
Source:

show()

Make sure the layer is visible. Sets visibility to true if false, and sets opacity to 0.5 if it's less than 0.05.
Inherited From:
Source:

startLoadingStateTracking(context)

Start watching scene render events to mark this asset display-ready after its first drawable tile, and wrap the imagery provider to continuously track whether the layer currently has outstanding tile requests. Unlike displayReady (a one-time latch), tilesLoading is kept in sync for as long as the layer is in the scene, so the map loading indicator does not get stuck when no tiles are ever in view (or when Cesium abandons stale cache entries), and keeps working while panning brings new tiles into view after the first one loads.
Parameters:
Name Type Description
context object A context object with a Cesium scene.
Properties
Name Type Description
scene Cesium.Scene The scene where imagery is drawn.
Since:
  • 2.41.0
Overrides:
Source:

stopLoadingStateTracking()

Stop any pending display-ready/loading-state watcher for this imagery layer.
Since:
  • 2.41.0
Overrides:
Source:

toConfig() → {MapConfig#MapAssetConfig}

Save the current imagery source. Provider creation expands shortcuts and converts options on a copy, leaving these attributes as config.
Since:
  • 2.41.0
Overrides:
Source:
Returns:
A detached object of settings to save.
Type
MapConfig#MapAssetConfig

updateIcon(icon)

Sanitizes an SVG string and updates the model's 'icon' attribute the sanitized string. Also sets the 'iconStatus' attribute to 'success'.
Parameters:
Name Type Description
icon string An SVG string to use for the MapAsset icon
Inherited From:
Source:

usesFeatureType(feature) → {boolean}

Checks if a feature from the map (a Cesium object) is the type of feature that this map asset model contains. For example, if a Cesium3DTilesetFeature is passed to this function, this function will return true if it is a Cesium3DTileset model, and false if it is a CesiumVectorData model.
Parameters:
Name Type Description
feature Cesium.Cesium3DTilesetFeature | Cesium.Entity feature to be checked.
Since:
  • 2.25.0
Inherited From:
Source:
Returns:
true if the feature is an instance of the feature type set on the asset model, false otherwise.
Type
boolean

validate(attrs) → {object|undefined}

Validate candidate imagery source options without changing them.
Parameters:
Name Type Description
attrs object The candidate model attributes
Since:
  • 2.41.0
Source:
Returns:
Field messages, or no error when valid
Type
object | undefined

whenReady() → {Promise}

Checks if the asset information has been fetched and is ready to use.
Inherited From:
Source:
Returns:
Returns a promise that resolves to this model when ready.
Type
Promise

wrapRequestImageForPendingCount(provider, onPendingCountChange) → {function}

Wrap this layer's imagery provider so outstanding tile requests can be counted directly from the promises Cesium creates, instead of inferred from Cesium's internal tile cache. The cache can retain stale/orphaned entries in a transient state indefinitely - for example, an ancestor tile kept around for level-of-detail fallback that Cesium stops reprocessing once it's no longer needed for the current view - which would otherwise look like "still loading" even though there is no real network/processing activity. Counting requestImage calls avoids that: a call either returns undefined synchronously (Cesium declined to make a request - no work done) or a promise that settles when the real work finishes.
Parameters:
Name Type Description
provider Cesium.ImageryProvider The provider to wrap.
onPendingCountChange function Called with the current pending request count whenever it changes.
Since:
  • 2.41.0
Source:
Returns:
A function that restores the original requestImage function.
Type
function

zoomTo(target)

Indicate that the map widget should navigate to a given target from this MapAsset.
Parameters:
Name Type Description
target MapConfig#CameraPosition The target to navigate to.
Since:
  • 2.27.0
Inherited From:
Source:

Type Definitions

cesiumOptions

Options that are supported for creating imagery tiles. Any properties provided here are passed to the Cesium constructor function, so other properties that are documented in Cesium are also supported. See https://cesium.com/learn/cesiumjs/ref-doc/BingMapsImageryProvider.html#.ConstructorOptions and https://cesium.com/learn/cesiumjs/ref-doc/IonImageryProvider.html#.ConstructorOptions.
Type:
  • Object
Properties:
Name Type Description
ionAssetId string | number If this imagery is hosted by Cesium Ion, then Ion asset ID.
key string | number A key or token required to access the tiles. For example, if this is a BingMapsImageryProvider, then the Bing maps key. If one is required and not set, the model will look in the AppModel for a key, for example, AppModel#bingMapsKey
tilingScheme 'GeographicTilingScheme' | 'WebMercatorTilingScheme' The tiling scheme to use when constructing an imagery provider. If not set, Cesium uses WebMercatorTilingScheme by default.
rectangle Array.<Number> The rectangle covered by the layer. The list of west, south, east, north bounding degree coordinates, respectively. This will be passed to Cesium.Rectangle.fromDegrees to define the bounding box of the imagery layer. If left undefined, the layer will cover the entire globe.
Source: