cesiumjs-imagery
CesiumJS imagery layers - ImageryProvider, ImageryLayer, ImageryLayerCollection, WMS, WMTS, Bing, OpenStreetMap, ArcGIS, Mapbox, tile discard policies. Use when adding or swapping base map layers, configuring imagery providers, layering multiple map sources, or creating split-screen imagery comparisons.
CesiumGS · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add CesiumGS/cesiumjs-skills --skill cesiumjs-imageryAbout this skill
name: cesiumjs-imagery description: "CesiumJS imagery layers - ImageryProvider, ImageryLayer, ImageryLayerCollection, WMS, WMTS, Bing, OpenStreetMap, ArcGIS, Mapbox, tile discard policies. Use when adding or swapping base map layers, configuring imagery providers, layering multiple map sources, or creating split-screen imagery comparisons."
CesiumJS Imagery Layers
CesiumJS v1.143 -- Imagery providers supply raster tile data rendered on the Globe or draped over a Cesium3DTileset. The three core abstractions are ImageryProvider (fetches tiles), ImageryLayer (display settings), and ImageryLayerCollection (ordered stack on the globe).
ImageryProvider (abstract -- fetches tile images)
-> ImageryLayer (wraps one provider; alpha, brightness, split, etc.)
-> ImageryLayerCollection (ordered stack; index 0 = base layer)
-> Globe / Cesium3DTileset
Layers render bottom-to-top. Index 0 is the base layer, stretched to fill the globe even if its rectangle does not cover the entire world.
Quick Start and ImageryLayer Factories
When creating a viewer for imagery work, disable unneeded widgets so the imagery
is the visual focus. Use camera.setView (not flyTo) when you need the camera
in position immediately — flyTo animates and may not finish before your code
continues.
import { Viewer, ImageryLayer, IonImageryProvider, IonWorldImageryStyle, Math as CesiumMath } from "cesium";
// Clean viewer -- disable widgets that distract from imagery
const viewer = new Viewer("cesiumContainer", {
animation: false,
timeline: false,
navigationHelpButton: false,
navigationInstructionsInitiallyVisible: false,
});
// Position camera immediately (no animation)
viewer.camera.setView({
destination: Cesium.Cartesian3.fromDegrees(-73.0, 41.0, 1500000),
orientation: {
heading: 0.0,
pitch: CesiumMath.toRadians(-90), // look straight down
roll: 0.0,
},
});
// Explicit base layer choice
const viewer2 = new Viewer("cesiumContainer", {
baseLayer: ImageryLayer.fromWorldImagery(),
});
// fromProviderAsync -- wraps any async provider; returns ImageryLayer immediately
const nightLayer = ImageryLayer.fromProviderAsync(
IonImageryProvider.fromAssetId(3812), // Earth at Night
);
nightLayer.alpha = 0.5;
nightLayer.brightness = 2.0;
viewer.imageryLayers.add(nightLayer);
// fromWorldImagery with style override
const roadLayer = ImageryLayer.fromWorldImagery({
style: IonWorldImageryStyle.ROAD,
});
viewer.imageryLayers.add(roadLayer);
Camera Height Reference for Imagery Scenes
Use camera.setView with these approximate heights:
| Scale | Height (m) | Example |
|---|---|---|
| Street / block | 500–2,000 | Downtown intersection |
| City | 5,000–25,000 | Washington DC, Paris |
| Metro area | 50,000–200,000 | Greater London |
| Region / state | 300,000–1,500,000 | Florida, Japan |
| Continent | 3,000,000–8,000,000 | Europe, North America |
For top-down (map-style) views set pitch: CesiumMath.toRadians(-90).
For oblique 3D views set pitch: CesiumMath.toRadians(-35) to CesiumMath.toRadians(-60).
ImageryLayerCollection API
Access via viewer.imageryLayers (same as viewer.scene.imageryLayers).
const layers = viewer.imageryLayers;
layers.add(myLayer); // add on top
layers.add(myLayer, 0); // add at index
layers.addImageryProvider(provider); // create layer + add
layers.raise(myLayer); // move up one
layers.lower(myLayer); // move down one
layers.raiseToTop(myLayer); // move to top
layers.lowerToBottom(myLayer); // move to bottom
layers.remove(myLayer); // remove and destroy
layers.remove(myLayer, false); // remove without destroying
layers.removeAll();
const count = layers.length;
const base = layers.get(0);
const idx = layers.indexOf(myLayer);
const has = layers.contains(myLayer);
Events: layerAdded(layer, index), layerRemoved(layer, index),
layerMoved(layer, newIndex, oldIndex), layerShownOrHidden(layer, index, show).
ImageryLayer Display Properties
Properties accept a number or a per-tile callback (frameState, layer, x, y, level) => value.
| Property | Default | Notes |
|---|---|---|
alpha | 1.0 | 0 = transparent, 1 = opaque |
brightness | 1.0 | < 1 darker, > 1 brighter |
contrast | 1.0 | < 1 lower, > 1 higher |
hue | 0.0 | Shift in radians |
saturation | 1.0 | < 1 desaturated, > 1 oversaturated |
gamma | 1.0 | Gamma correction |
show | true | Visibility toggle |
splitDirection | SplitDirection.NONE | LEFT, RIGHT, or NONE |
nightAlpha / dayAlpha | 1.0 | Requires Globe.enableLighting |
Additional options: rectangle, minimumTerrainLevel / maximumTerrainLevel,
cutoutRectangle, colorToAlpha / colorToAlphaThreshold,
minificationFilter / magnificationFilter (LINEAR default, or NEAREST).
// Adjust appearance at runtime
layer.alpha = 0.7;
layer.brightness = 1.3;
layer.contrast = 1.5;
layer.saturation = 0.5;
layer.gamma = 1.2;
Swapping the Base Layer
Remove the default base layer and replace it at index 0. The replacement becomes the new base layer, stretched to fill the globe.
import { ImageryLayer, OpenStreetMapImageryProvider } from "cesium";
// Remove default Bing aerial
viewer.imageryLayers.remove(viewer.imageryLayers.get(0));
// Add OSM as new base layer at index 0
const osmLayer = new ImageryLayer(
new OpenStreetMapImageryProvider({
url: "https://tile.openstreetmap.org/",
maximumLevel: 19,
credit: "OpenStreetMap contributors",
}),
);
viewer.imageryLayers.add(osmLayer, 0);
Imagery Providers
IonImageryProvider
// Always use fromAssetId (async factory); never call constructor directly
const layer = ImageryLayer.fromProviderAsync(
IonImageryProvider.fromAssetId(3812),
);
viewer.imageryLayers.add(layer);
OpenStreetMapImageryProvider
Extends UrlTemplateImageryProvider for Slippy
Read the complete source ↗