CesiumJS Fallback to Re:Earth Terrain When Photorealistic Tiles Fail: A Complete Guide

God's Eye View implements a multi-layered fallback system that automatically switches from Google Photorealistic 3D Tiles to Re:Earth's key-less quantized-mesh terrain when network failures occur, ensuring the CesiumJS globe never renders as a flat ellipsoid.

God's Eye View (GEV) is an open-source 3D globe visualization application built on CesiumJS that leverages Google's Photorealistic 3D Tiles for high-fidelity terrain rendering. When these premium tiles become unavailable due to network errors, invalid API keys, or service outages, the application seamlessly falls back to Re:Earth's free terrain provider, maintaining a functional earth surface rather than degrading to a smooth ellipsoid.

How the Fallback System Detects Photorealistic Tile Failures

The fallback mechanism activates within the setStack() method in src/mapStackController.js whenever the application attempts to initialize the photorealistic tileset. When setStack('photoreal') is invoked—typically during application startup—the controller attempts to create the Google tileset instance.

If tileset creation throws an exception or the tileset fails to load, the code enters a dedicated fallback branch at line 283:

// Simplified logic from mapStackController.js#L283-L299
if (!tileset) {
  // Fallback branch activated
  console.warn('[mapStackController] Photorealistic tiles unavailable, activating Re:Earth terrain');
  // Proceed to Re:Earth terrain initialization...
}

This detection occurs before any terrain provider is attached to the viewer, ensuring that failed tile requests never leave the globe without surface geometry.

Implementing the Re:Earth Terrain Provider Fallback

Once the failure is detected, the controller immediately pivots to the Re:Earth TerrainProvider, a quantized-mesh endpoint that requires no authentication tokens.

Configuration Constants

The Re:Earth endpoint is defined as a module-level constant at lines 45-48 in src/mapStackController.js:

// From mapStackController.js#L45-L48
const REEARTH_TERRAIN_URL = 'https://terrain.reearth.land/cesium-mesh/ellipsoid';

This URL provides global elevation data via Cesium's quantized-mesh format without requiring a Cesium Ion token, making it ideal for key-less fallback scenarios.

Provider Installation

Upon successful connection to the Re:Earth service, the controller installs the provider and updates the internal state tracking at lines 309-311:

// From mapStackController.js#L309-L311
this.viewer.terrainProvider = provider;
this._terrainMode = targetMode;  // Set to 'reearth'

The _terrainMode property records the active terrain state as reearth, allowing other application modules to query the current fallback status via getTerrainMode().

Graceful Degradation to Ellipsoid Terrain

If the Re:Earth endpoint is unreachable—due to complete network isolation or regional blocking—the system implements a final safety net at line 326. The controller falls back to Cesium's built-in EllipsoidTerrainProvider, which renders a smooth, mathematically perfect earth ellipsoid without elevation data:

// From mapStackController.js#L326
console.warn('[mapStackController] Re:Earth terrain unavailable, falling back to flat ellipsoid terrain:', error);

This ensures the application always presents a recognizable globe surface rather than a void or rendering error, though without topographic detail.

Server-Side Height Sampling and Caching

Beyond the visual terrain provider, GEV maintains a secondary fallback for point-height queries used to position entities like aircraft and vehicles. The application registers a server-side proxy in vite.config.js at lines 2174-2282 that handles requests to /api/terrain/heights.

When the client requests elevation data for specific coordinates, the proxy first attempts to fetch from the Re:Earth service. If that service is unresponsive, the proxy falls back to an EGM96-based geoid calculator that computes approximate heights using the Earth Gravitational Model 1996. This guarantees that entity placement remains grounded to a plausible surface even when all external terrain services fail.

Integration Flow and Startup Sequence

The complete fallback chain executes automatically during application initialization. In src/main.js at line 191, the startup sequence creates the Cesium viewer and immediately invokes the photorealistic stack:

// Example: Switching map stacks with automatic fallback
import { MapStackController } from './mapStackController.js';
import { Viewer } from 'cesium';

// 1. Create Cesium viewer (no native globe)
const viewer = new Viewer('cesiumContainer', {
  globe: false,  // Photorealistic tiles provide their own terrain
});

// 2. Initialize the controller
const mapStackController = new MapStackController(viewer, {});

// 3. Attempt photorealistic stack with automatic fallback
await mapStackController.setStack('photoreal');

// 4. Query current terrain mode
console.log('Active terrain mode:', mapStackController.getTerrainMode());
// => "reearth" (or "flat" if Re:Earth also failed)

If you need to bypass the photorealistic attempt entirely and force Re:Earth terrain, call setStack('reearth') directly:

// Force Re:Earth terrain bypassing photorealistic tiles
await controller.setStack('reearth');
console.assert(controller.getTerrainMode() === 'reearth');

Summary

• src/mapStackController.js contains the core fallback logic, detecting Google tile failures at lines 283-299 and activating the Re:Earth provider at lines 309-311.
• The Re:Earth terrain provider uses the key-less endpoint https://terrain.reearth.land/cesium-mesh/ellipsoid, defined at lines 45-48.
• If Re:Earth is unavailable, the system falls back to Cesium's EllipsoidTerrainProvider with a console warning at line 326.
• A server-side height proxy in vite.config.js (lines 2174-2282) caches elevation queries and provides EGM96 geoid calculations when external services fail.
• The _terrainMode property tracks the current state as reearth or flat, queryable via getTerrainMode().

Frequently Asked Questions

What triggers the CesiumJS fallback to Re:Earth terrain?

The fallback triggers when MapStackController.setStack('photoreal') fails to create or load the Google Photorealistic 3D Tileset, typically caused by network errors, invalid API keys, or Google service outages. The detection occurs at lines 283-299 in src/mapStackController.js where the code checks if (!tileset) before entering the fallback branch.

Does Re:Earth terrain require an API key or token?

No. The Re:Earth terrain provider at https://terrain.reearth.land/cesium-mesh/ellipsoid is completely key-less and requires no Cesium Ion token or authentication. This makes it ideal as a zero-configuration fallback when authenticated services like Google Photorealistic Tiles fail.

What happens if both Google Tiles and Re:Earth terrain fail?

If the Re:Earth endpoint is unreachable, God's Eye View falls back to Cesium's EllipsoidTerrainProvider—a built-in, offline-capable provider that renders a smooth mathematical ellipsoid without elevation data. This final fallback ensures the globe remains visible and interactive rather than displaying blank terrain or error states.

How does the height sampling proxy work for entity positioning?

The /api/terrain/heights proxy registered in vite.config.js (lines 2174-2282) caches elevation queries to the Re:Earth service. When the service is unavailable, the proxy computes heights using an EGM96 geoid model, ensuring that entities like aircraft and vehicles maintain plausible ground contact even when the visual terrain provider has degraded to the flat ellipsoid fallback.

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