Imagery

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.

Quick start

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:

Copy to clipboard. Data copied clipboard.
Cesium.Ion.defaultAccessToken = 'your_access_token';
var viewer = new Cesium.Viewer('cesiumContainer', {
    imageryProvider : Cesium.createWorldImagery({
        style : Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS
    }),
    baseLayerPicker : false
});

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

Copy to clipboard. Data copied clipboard.
var layers = viewer.scene.imageryLayers;
var blackMarble = layers.addImageryProvider(new Cesium.IonImageryProvider({ assetId: 3812 }));

NASA Black Marble

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:

Copy to clipboard. Data copied clipboard.
blackMarble.alpha = 0.5; // 0.0 is transparent.  1.0 is opaque.

Next, increase the brightness of the lights:

Copy to clipboard. Data copied clipboard.
blackMarble.brightness = 2.0; // > 1.0 increases brightness.  < 1.0 decreases.

To finish, add a third layer that draws a single image over a particular extent.

Copy to clipboard. Data copied clipboard.
layers.addImageryProvider(new Cesium.SingleTileImageryProvider({
    url : '../images/Cesium_Logo_overlay.png',
    rectangle : Cesium.Rectangle.fromDegrees(-75.0, 28.0, -67.0, 29.75)
}));

This is the complete code:

Copy to clipboard. Data copied clipboard.
Cesium.Ion.defaultAccessToken = 'your_access_token';
var viewer = new Cesium.Viewer('cesiumContainer', {
    imageryProvider : Cesium.createWorldImagery({
        style : Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS
    }),
    baseLayerPicker : false
});

var layers = viewer.scene.imageryLayers;
var blackMarble = layers.addImageryProvider(new Cesium.IonImageryProvider({ assetId: 3812 }));

blackMarble.alpha = 0.5; // 0.0 is transparent.  1.0 is opaque.

blackMarble.brightness = 2.0; // > 1.0 increases brightness.  < 1.0 decreases.

layers.addImageryProvider(new Cesium.SingleTileImageryProvider({
    url : '../images/Cesium_Logo_overlay.png',
    rectangle : Cesium.Rectangle.fromDegrees(-75.0, 28.0, -67.0, 29.75)
}));

See the full example in Sandcastle.

Ready-to-stream imagery

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:

Cross-origin resource sharing

As a security measure, web browsers prevent Javascript code from reading an image that comes from a different site. In particular, WebGL applications like CesiumJS are forbidden from using images as textures if those images (imagery tiles in our case) come from a different host name or port and the server does not explicitly allow the images to be used in this way. The server indicates the images do not contain confidential information, and it is therefore safe for other sites to read their pixels, by including Cross-Origin Resource Sharing (CORS) headers in the HTTP response.

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.

Copy to clipboard. Data copied clipboard.
layers.addImageryProvider(new Cesium.WebMapServiceImageryProvider({
    url : new Cesium.Resource({
        url: '/path/to/imagery',
        proxy : new Cesium.DefaultProxy('/proxy/')
    })
}));

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,

Copy to clipboard. Data copied clipboard.
var layer = layers.addImageryProvider(imageryProvider);

is shorthand for

Copy to clipboard. Data copied clipboard.
var layer = new ImageryLayer(imageryProvider);
layers.add(layer);

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 asshow, alpha, brightness, and contrast. See 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 add, remove, and get. In addition, layers can be reordered using raise, raiseToTop, lower, and lowerToBottom. See ImageryLayerCollection.

Resources

Checkout the imagery layers examples in Sandcastle:

In addition, checkout the reference documentation: