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

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

How to Switch Basemaps Programmatically

The public API exposed in 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.

// 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 (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:

// 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, preventing invalid provider instantiation.

Handling Google Photorealistic 3D Tiles

The photoreal stack represents a special case requiring the loadPhotorealisticTileset helper from src/mapStartup.js. Unlike imagery providers, this loads a Cesium3DTileset primitive.

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
• 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 lines 869-873
• Photoreal mode requires special handling via 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 basemap switching configuration.

How do I add a custom basemap to the controller?

You must register a new stack ID in 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}