/cesiumjs-imagery

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.144 -- 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, OpenStreetMapImageryProvider, UrlTemplateImageryProvider, Math as CesiumMath } from "cesium";

// Clean viewer -- disable widgets that distract from imagery
const viewer = new Viewer("cesiumContainer", {
  baseLayer: new ImageryLayer(new OpenStreetMapImageryProvider({
    url: "https://tile.openstreetmap.org/",
    maximumLevel: 18,
  })),
  baseLayerPicker: false,
  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,
  },
});

// Public URL-backed overlay
const nightLayer = new ImageryLayer(new UrlTemplateImageryProvider({
  url: "https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/VIIRS_CityLights_2012/default/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpeg",
  maximumLevel: 8,
  credit: "NASA GIBS",
}));
nightLayer.alpha = 0.5;
nightLayer.brightness = 2.0;
viewer.imageryLayers.add(nightLayer);

Use `IonImageryProvider` and `ImageryLayer.fromWorldImagery` only when the runtime has the required Cesium ion entitlement. For public/no-token examples, prefer OpenStreetMap, ArcGIS, NASA GIBS, WMS, WMTS, or URL-template providers.

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)`.

Default to top-down framing when a scenario names a specific country, city, or region. It keeps the named feature centered without perspective skew. Oblique high-altitude views can easily show a neighboring landmass because the target falls outside the view frustum.

Framing Reference for Named Places

Frame named places by their actual longitude and latitude, not a nearby guess. Use `camera.setView` with `Cartesian3.fromDegrees(lon, lat, height)` and a top-down pitch unless the prompt explicitly asks for an oblique view.

| Place | lon, lat | Suggested height | |---|---|---:| | London | -0.12, 51.50 | 60,000 | | Paris | 2.35, 48.86 | 30,000 | | New York City | -74.00, 40.71 | 60,000 | | New York-Boston corridor | -72.5, 41.5 | 800,000 | | Washington DC, National Mall | -77.03, 38.89 | 25,000 | | Florida peninsula | -81.5, 28.0 | 1,500,000 | | Grand Canyon | -112.5, 36.3 | 200,000 | | Hawaiian Islands | -157.0, 20.5 | 1,800,000 | | Iceland | -19.0, 64.9 | 1,200,000 | | Italy peninsula | 12.5, 42.0 | 2,500,000 | | Southern Europe split view | 13.0, 42.0 | 4,500,000 | | Greenland | -42.0, 72.0 | 5,000,000 | | Japan, Honshu | 138.0, 36.5 | 2,500,000 |

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, RIG