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

> Ensure your CesiumJS app never shows a flat globe. Learn how God's Eye View seamlessly falls back to Re:Earth terrain when photorealistic tiles fail due to network issues.

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

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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**:

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js):

```javascript
// 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**:

```javascript
// 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:

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) at **line 191**, the startup sequence creates the Cesium viewer and immediately invokes the photorealistic stack:

```javascript
// 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:

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

```

## Summary

- **[`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.