CesiumJS supports drawing and layering high-resolution imagery (maps) from many services, including Cesium ion. Use Cesium ion to stream curated high resolution imagery or tile your own imagery layers from raster data to CesiumJS apps. Layers can be ordered and blended together. Each layer’s brightness, contrast, gamma, hue, and saturation can be dynamically changed. This tutorial introduces imagery layer concepts and the related CesiumJS APIs.
Open the Hello World example in Sandcastle. This example creates a
Viewer widget with a single layer rendering Bing Maps Aerial imagery streaming through Cesium ion. Specify a different base layer by providing an additional parameter to the
Viewer constructor. Let’s use Bing Maps labeled imagery:
After modifying the example, press F8 to run it.
As you zoom in and out, the layer streams in as needed.
Add another Cesium ion imagery layer: Earth at Night
Since it was added last and covers the full extent of the globe, the Black Marble layer covers up the Bing layer. We could move Black Marble to the bottom with
layers.lower(blackMarble);, but instead let’s blend it with the Bing layer so we have a better sense of how the two layers relate:
Next, increase the brightness of the lights:
To finish, add a third layer that draws a single image over a particular extent.
This is the complete code:
See the full example in Sandcastle.
The ion Assets tab in Sandcastle contains more imagery tilesets hosted by Cesium ion that can be added to CesiumJS apps with a couple of lines of code. Many of these tilesets are also available for on-premise use.
More imagery providers
High-resolution imagery like the first two layers used above is too large to fit into memory or often even a single disk, so imagery is divided into smaller images, called tiles, that can be streamed to a client as needed based on the view. Cesium supports several standards for requesting tiles using imagery providers. Most imagery providers use a REST interface over HTTP to request tiles. Imagery providers differ based on how requests are formatted and how tiles are organized. Cesium has the following imagery providers:
WebMapServiceImageryProvider: Web Map Service (WMS), an OGC standard for requesting map tiles for a geographic region from distributed geospatial databases.
createTileMapServiceImageryProvider: Tile Map Service (TMS), a REST interface for accessing map tiles. Tiles can be generated with MapTiler or GDAL2Tiles.
WebMapTileServiceImageryProvider: OpenGIS Web Map Tile Service (WMTS), an OGC standard for serving pre-rendered georeferenced map tiles over the Internet.
createOpenStreetMapImageryProvider: Access to OpenStreetMap tiles or any Slippy map tiles. There are several ways to host these tiles.
BingMapsImageryProvider: Uses Bing Maps REST Services to access tiles. A Bing Maps key can be created at https://www.bingmapsportal.com/.
ArcGisMapServerImageryProvider: Uses the Esri ArcGIS Server REST API to access tiles hosted by an ArcGIS MapServer.
GoogleEarthEnterpriseMapsProvider: Provides access to the imagery stored in your organization’s Google Earth Enterprise server.
MapboxImageryProvider: Uses the Mapbox API to access tiles. Create an account and supply your access token.
SingleTileImageryProvider: Create a tile from a single image.
UrlTemplateImageryProvider: Create custom tiling schemes. Connect to a wide array of imagery sources by using a URL template. For example, a URL template for TMS is
TileCoordiantesImageryProvider: Shows how the globe is divided into tiles in a particular tiling scheme by drawing a border around each tile and labeling it with its level, X, and Y coordinates.
Cross-origin resource sharing
Unfortunately, not all imagery services support CORS. For those that don’t, a proxy server at the same origin as the website hosting your app must be used. When using such a proxy, tiles appear to the web browser and the CesiumJS client as if they came from the same origin. To use a proxy with an imagery provider, use the
proxy property when constructing the imagery provider. Cesium includes a simple proxy written in Node.js for development purposes.
If you are hosting public imagery, we encourage enabling CORS as described here instead of using a proxy.
Imagery providers vs. layers
So far, we haven’t clearly differentiated between imagery providers and layers. An imagery provider makes requests for tiles using a particular service, while a layer represents displayed tiles from an imagery provider. For example,
is shorthand for
We usually construct an imagery provider just to create a layer, then we manipulate the layer to change its visual appearance using its properties such as
ImageryLayer. Decoupling imagery providers and layers makes it easier to write new imagery providers.
An imagery layer collection, like
layers in the above examples, determines the order in which layers are drawn. Layers are drawn bottom-to-top based on the order they are added. Imagery layer collections are manipulated like any other collection in Cesium using functions such as
get. In addition, layers can be reordered using
Checkout the imagery layers examples in Sandcastle:
- Imagery Layers - Code example from this tutorial.
- Imagery Layers Manipulation - Layer imagery from multiple sources, and adjust the alpha of each independently.
- Imagery Adjustment - Adjust brightness, contrast, gamma, hue, and saturation of an imagery layer.
In addition, checkout the reference documentation: