# How to Switch Between Different Basemaps in CesiumJS: The Complete Developer's Guide

> Learn how to switch basemaps in CesiumJS with the switchBasemap method. This guide shows developers how to easily swap imagery providers and load 3D tilesets in your application.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Switching basemaps in God's Eye View involves calling the `switchBasemap()` method with a stack identifier like `'osm'` or `'bing-aerial'`, which delegates to [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) to swap Cesium imagery providers or load 3D tilesets.**

The `bilawalsidhu/gods-eye-view` repository abstracts every basemap as a *map-stack*, providing a unified API to switch between OpenStreetMap, Bing Imagery, Esri satellites, and Google Photorealistic 3D tiles. Understanding how to switch between different basemaps in CesiumJS requires examining the controller logic that manages layer removal, provider instantiation, and scene updates.

## Understanding the Map Stack Architecture

God's Eye View treats basemaps as configurable stacks rather than static layers. This architecture separates the UI intent from the low-level Cesium imagery provider management.

### What is a Map Stack?

A map stack is a registered identifier (e.g., `osm`, `bing-aerial`, `esri-imagery`, `photoreal`) mapped to a specific Cesium imagery configuration. The [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) file documents these mappings in its basemap switching configuration around line 5266, defining how human-readable names translate to internal stack IDs.

### Supported Basemap Providers

The controller supports four distinct provider types:

- **OSM** – `UrlTemplateImageryProvider` pointing to OpenStreetMap tile servers
- **Bing** – `BingMapsImageryProvider` supporting both `AERIAL` and `AERIAL_WITH_LABELS` styles
- **Esri** – `IonResource.fromAssetId(3845)` for keyless Esri World Imagery
- **Photoreal** – `Cesium3DTileset` via Google's Photorealistic 3D Tiles API

## The Core Switching Mechanism

The actual layer manipulation occurs in [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js), which maintains a dictionary of stack identifiers to Cesium imagery providers.

### The mapStackController.js Implementation

When `set_map_stack` is invoked, the controller executes a three-step process:

1. **Removes** existing imagery layers from `viewer.scene.imageryLayers`
2. **Instantiates** the appropriate provider for the requested stack ID
3. **Adds** the new layer to the viewer and updates internal state

This logic handles both standard imagery providers and 3D tilesets, ensuring the scene graph remains consistent during transitions.

### Provider Creation Logic

Each stack ID triggers specific instantiation logic:

- **Bing aerial**: `new Cesium.BingMapsImageryProvider({url: 'https://dev.virtualearth.net', mapStyle: Cesium.BingMapsStyle.AERIAL})`
- **Bing labels**: Same provider with `AERIAL_WITH_LABELS` map style
- **Esri**: `Cesium.IonResource.fromAssetId(3845)` for satellite imagery
- **Photoreal**: Delegates to `loadPhotorealisticTileset` in [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js)

## How to Switch Basemaps Programmatically

The public API exposed in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) at line 7944 provides the `switchBasemap(stackId)` method. This function returns a boolean indicating success and handles the delegation to the controller.

```javascript
// Import from the UI module
import { switchBasemap } from './ui.js';

// Switch to OpenStreetMap road map
switchBasemap('osm');

// Switch to Bing aerial imagery
switchBasemap('bing-aerial');

// Switch to Esri satellite imagery
switchBasemap('esri-imagery');

// Switch to Google Photorealistic 3D tiles (requires API key)
switchBasemap('photoreal');

```

The `switchBasemap` function abstracts the complexity of provider management, making it safe to call from UI components or external scripts without direct Cesium API knowledge.

## Voice Action and UI Integration

The application supports voice-activated basemap switching through the action pipeline defined in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) (lines 869-873).

### gevActions.js Voice Pipeline

When the system receives a `set_map_stack` command, it parses the requested stack ID and forwards it to the UI layer:

```javascript
// In src/voice/gevActions.js – handling the “set_map_stack” command
if (name === 'set_map_stack') {
  const stackId = args[0];               // e.g. "osm"
  await ui.switchBasemap(stackId);       // delegates to UI controller
  return {action: 'set_map_stack', requested: stackId, success: true};
}

```

This pattern allows voice commands like "switch to satellite view" to trigger the same code path as button clicks.

### UI.js Public API

The UI layer at line 7944 serves as the abstraction boundary between user interactions and the map controller. According to the God's Eye View source code, this method validates the stack ID before forwarding to [`mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/mapStackController.js), preventing invalid provider instantiation.

## Handling Google Photorealistic 3D Tiles

The `photoreal` stack represents a special case requiring the `loadPhotorealisticTileset` helper from [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js). Unlike imagery providers, this loads a `Cesium3DTileset` primitive.

```javascript
import { loadPhotorealisticTileset } from './mapStartup.js';

async function enableGoogle3D(viewer, {googleApiKey, cesiumToken}) {
  const {tileset, route, errors} = await loadPhotorealisticTileset(
    Cesium,
    {googleApiKey, cesiumToken}
  );
  
  if (tileset) {
    viewer.scene.primitives.add(tileset);
    console.log(`Loaded Google 3D tiles via ${route}`);
  } else {
    console.warn('Failed to load Google 3D tiles, falling back to OSM');
  }
}

```

The function configures `Cesium.GoogleMaps.defaultApiKey` before creating the tileset, ensuring proper authentication for the Photorealistic 3D Tiles API.

## Summary

- **Map stacks** abstract basemaps into identifiers like `osm`, `bing-aerial`, and `photoreal` within [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js)
- **Switching** occurs via `ui.switchBasemap(stackId)`, which removes current layers and instantiates new Cesium providers
- **Voice integration** routes `set_map_stack` actions through [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) lines 869-873
- **Photoreal mode** requires special handling via [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) to load 3D tilesets rather than imagery layers
- **Provider types** include `UrlTemplateImageryProvider`, `BingMapsImageryProvider`, and `IonResource` for Esri data

## Frequently Asked Questions

### What basemap options are available in God's Eye View?

The repository supports five distinct configurations: `osm` (OpenStreetMap), `bing-aerial` (satellite), `bing-labels` (satellite with roads), `esri-imagery` (Esri World Imagery via Cesium Ion), and `photoreal` (Google Photorealistic 3D Tiles). These are documented in the [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) basemap switching configuration.

### How do I add a custom basemap to the controller?

You must register a new stack ID in [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) by adding an entry to the provider dictionary that returns your custom `ImageryProvider` instance. The controller expects either a standard imagery provider or a 3D tileset primitive, which `switchBasemap` will handle appropriately when added to the viewer's scene.

### Why does switching to photoreal mode require a Google API key?

Google Photorealistic 3D Tiles use a separate authentication flow via `Cesium.GoogleMaps.defaultApiKey` rather than standard Cesium Ion tokens. The `loadPhotorealisticTileset` function in [`src/mapStartup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStartup.js) configures this key before attempting to create the `Cesium3DTileset`, as the underlying tile endpoint requires Google Cloud Platform authentication.

### Can I switch basemaps using voice commands?

Yes. The voice action pipeline in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) handles `set_map_stack` commands by extracting the target stack ID and calling `ui.switchBasemap()`. This returns a confirmation object containing the action name, requested ID, and success status, allowing the voice system to provide audible feedback when the basemap changes.