# God’s Eye View Map Stack Options: Google 3D, Bing Imagery, and OpenStreetMap

> Explore God's Eye View map stack options: Google 3D, Bing Aerial, Bing Labels, and OpenStreetMap. Discover token requirements and integration patterns for each.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: deep-dive
- Published: 2026-08-29

---

**God’s Eye View provides four distinct map stack options—Google 3D Photorealistic, Bing Aerial, Bing Labels, and OpenStreetMap—each with specific token requirements and integration patterns defined in the MapStackController.**

God’s Eye View is an open-source Cesium-based geospatial viewer that supports multiple base map providers through a configurable stack system. The application’s **map stack options** allow users to switch between high-fidelity 3D tiles and traditional raster imagery depending on their visualization needs and available API credentials.

## Available Map Stack Options in God’s Eye View

The `MapStackController` defined in [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) (lines 5‑34) enumerates four selectable providers. Each stack has unique requirements for API tokens and rendering capabilities.

### Google 3D Photorealistic (`photoreal`)

The **Google 3D** stack provides cinematic, photorealistic 3D tiles using Google’s Photorealistic 3D Tiles API. Unlike the Bing options, this stack does not require a Cesium Ion token; instead, it relies on a Google Maps API key to authenticate tile requests. When active, this stack hides Cesium’s native globe to present seamless high-resolution geometry.

### Bing Aerial (`bing-aerial`)

The **Bing Aerial** stack delivers classic satellite imagery through Cesium Ion. This option requires a valid Cesium Ion token and utilizes `Cesium.IonWorldImageryStyle.AERIAL` to fetch Bing’s aerial photography layers. According to the source code, the controller checks for token presence before marking this stack as available.

### Bing Labels (`bing-labels`)

Similar to Bing Aerial, the **Bing Labels** stack requires a Cesium Ion token but includes overlaid place-name labels and administrative boundaries using `Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS`. This variant combines satellite imagery with contextual geographic text for reference purposes.

### OpenStreetMap (`osm`)

The **OSM** stack provides a lightweight alternative using standard OpenStreetMap raster tiles served from `https://tile.openstreetmap.org/`. This option requires no authentication tokens, making it immediately available for users without Google or Ion credentials, though it offers lower visual fidelity than the 3D or aerial alternatives.

## How the MapStackController Manages Provider Switching

The core logic for handling these map stack options resides in [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js). The controller initializes with configuration objects containing optional `googleTileset` and `cesiumToken` parameters, then calculates availability based on these credentials.

When switching providers, the `setStack(stackId)` method asynchronously activates the selected imagery layer and manages terrain provider synchronization. The controller exposes `getActiveId()` to retrieve the current stack identifier and `getStacks()` to return the full configuration array with availability flags.

```javascript
// Programmatically switch to Bing Aerial (requires valid Cesium Ion token)
import { MapStackController } from './src/mapStackController.js';
import { Viewer } from 'cesium';

const viewer = new Viewer('cesiumContainer');

const controller = new MapStackController(viewer, {
  googleTileset: null,          // No Google 3D tileset
  cesiumToken: 'YOUR_ION_TOKEN' // Required for Bing stacks
});

await controller.setStack('bing-aerial');
console.log('Active map stack:', controller.getActiveId()); // "bing-aerial"

```

## Rendering Map Stack Selection in the UI

The repository includes a dedicated UI component in [`src/mapStackChips.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackChips.js) that renders interactive selection buttons for each available stack. This component consumes the controller’s state to display an "ION" badge for stacks requiring Cesium Ion tokens when credentials are missing.

The `renderMapStackChips` function accepts a DOM container, the stacks array from `controller.getStacks()`, and callback handlers for selection events. It automatically disables unavailable stacks and highlights the active selection using `controller.getActiveId()`.

```javascript
// Render selectable map stack chips
import { renderMapStackChips } from './src/mapStackChips.js';
import { MapStackController } from './src/mapStackController.js';

const container = document.getElementById('map-stack-chips');
const controller = new MapStackController(viewer, { /* config */ });

renderMapStackChips(container, controller.getStacks(), {
  activeId: controller.getActiveId(),
  onSelect: (stackId) => controller.setStack(stackId)
});

```

## Token Requirements and Availability Logic

God’s Eye View implements conditional availability for its map stack options based on authentication state. The controller performs runtime checks during initialization:

- **Google 3D**: Available only if a Google tileset is provided in the constructor options
- **Bing variants**: Available only if a valid `cesiumToken` is supplied
- **OpenStreetMap**: Always available regardless of authentication

This logic ensures the UI, managed by [`src/mapStackChips.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackChips.js) (lines 13‑19), only presents viable options to users. The [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) file instantiates the controller and sets the initial stack based on whether the Google 3D tileset loads successfully, defaulting to OSM or Bing only when necessary.

## Summary

- God’s Eye View offers four **map stack options**: Google 3D Photorealistic, Bing Aerial, Bing Labels, and OpenStreetMap.
- Configuration and switching logic lives in [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js), which manages terrain providers and availability states.
- Google 3D requires a Google Maps API key but no Cesium Ion token; Bing stacks require a valid Ion token; OSM requires no authentication.
- The `setStack()` method handles asynchronous provider switching, while `getActiveId()` tracks the current selection.
- UI representation is handled by [`src/mapStackChips.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackChips.js), which renders availability-aware selection controls.

## Frequently Asked Questions

### What map stack options are available in God’s Eye View?

God’s Eye View supports four base map providers: Google 3D Photorealistic tiles, Bing Aerial imagery, Bing Aerial with Labels, and standard OpenStreetMap raster tiles. These are defined in the `MAP_STACKS` array within [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) and can be toggled programmatically or through the provided UI components.

### Do I need a Cesium Ion token for all map stacks?

No. Only the **Bing Aerial** and **Bing Labels** stacks require a Cesium Ion token. The **Google 3D** stack requires a Google Maps API key instead, while the **OpenStreetMap** stack functions without any authentication tokens, pulling tiles directly from the public OSM tile server.

### How do I switch between map stacks programmatically?

Instantiate the `MapStackController` with your viewer and credentials, then call the asynchronous `setStack(stackId)` method with the desired identifier (`'photoreal'`, `'bing-aerial'`, `'bing-labels'`, or `'osm'`). Verify the activation using `controller.getActiveId()`, which returns the string identifier of the currently active stack.

### Why is the Google 3D option unavailable in my deployment?

The Google 3D stack requires a valid Google Photorealistic 3D Tiles tileset passed to the `MapStackController` constructor via the `googleTileset` option. If this parameter is null or the tileset fails to load, the controller marks the stack as unavailable and the UI component in [`src/mapStackChips.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackChips.js) will disable or hide the selection button.