Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Search & research

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-imagery

About 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:

ScaleHeight (m)Example
Street / block500–2,000Downtown intersection
City5,000–25,000Washington DC, Paris
Metro area50,000–200,000Greater London
Region / state300,000–1,500,000Florida, Japan
Continent3,000,000–8,000,000Europe, 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.

PropertyDefaultNotes
alpha1.00 = transparent, 1 = opaque
brightness1.0< 1 darker, > 1 brighter
contrast1.0< 1 lower, > 1 higher
hue0.0Shift in radians
saturation1.0< 1 desaturated, > 1 oversaturated
gamma1.0Gamma correction
showtrueVisibility toggle
splitDirectionSplitDirection.NONELEFT, RIGHT, or NONE
nightAlpha / dayAlpha1.0Requires 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 ↗