How God’s Eye View Manages Entity Heights Using Terrain Sampling

God’s Eye View determines entity heights by combining an ellipsoidal ground lookup pipeline for DEM data with a rendered-mesh sampling pipeline for photorealistic 3-D tiles, caching results to ensure real-time performance.

The open-source tactical visualization platform God’s Eye View (bilawalsidhu/gods-eye-view) places vessels, aircraft, and track contacts at accurate world-space altitudes using a dual-tier terrain sampling system. This architecture separates ellipsoidal height resolution from photorealistic mesh sampling, ensuring entities appear correctly positioned whether flying over low-resolution terrain or detailed urban 3-D tiles.

The Dual-Pipeline Architecture

According to the source code, height resolution follows two independent pipelines that operate in parallel. The first provides a reliable baseline using digital elevation model (DEM) data, while the second upgrades accuracy when high-resolution photorealistic tiles are active.

Ellipsoidal Ground Lookup Pipeline

Located in src/data/terrainHeights.js, this pipeline queries the Re:Earth /api/terrain/heights proxy to obtain ellipsoidal heights. The implementation follows a strict caching and batching strategy:

• Coordinate quantization: Input coordinates are rounded to 5 decimal places (approximately 1-meter precision) to generate deterministic cache keys.
• In-memory caching: A JavaScript Map named cache stores objects with {ellipsoid, source} for each quantized key.
• Chunked network requests: Uncached keys are sent in sequential chunks of ≤ 64 points (CHUNK_SIZE) to prevent HTTP 431 header-size errors.
• Geoid fallback: If any chunk request fails, the entire chunk falls back to mathematical geoid calculation using geoidHeight (from src/data/geoid.js) plus optional orthometric offsets. These values are cached with source: 'geoid-fallback' and a short GEOID_FALLBACK_COOLDOWN_MS.

The function resolveEllipsoidalGround() returns an array of objects containing {ellipsoid: number | null, source: 'reearth' | 'geoid-fallback' | 'unresolved'}.

Rendered-Mesh Floor Sampling Pipeline

When the photorealistic "google-3d" regime is active and the camera is below 25 km, src/data/meshFloorSampler.js samples the actual rendered Cesium 3-D Tiles mesh:

• Budget-capped sampling: The sampler runs once per layer poll (not per entity) with a strict limit of MAX_SAMPLES_PER_CALL = 40 samples per invocation.
• Distance culling: Cells farther than MAX_SAMPLE_DIST_KM (15 km) from the viewer sub-point are ignored to avoid hitting unloaded tiles.
• One-shot latching: For each contact or waypoint, the coarse cell (coarseFloorCoord) is derived and cached in cachedMeshFloor. Once sampled, the height is latched permanently for that cell session.
• GPU height sampling: Validated cells invoke scene.sampleHeight with a scratch Cartographic to obtain the precise rendered mesh elevation.

Resolving Final Entity Altitudes

When positioning an entity, the system queries both pipelines in sequence:

1. Baseline resolution: Call resolveEllipsoidalGround() from src/data/terrainHeights.js to obtain the ellipsoidal ground height. Use cachedRealEllipsoidalGround() to filter out geoid-fallback values for physics-critical calculations.
2. Mesh upgrade: If meshFloorPreferred() returns true (photoreal active), check cachedGroundFloor() (re-exported from the mesh-floor module). If a rendered mesh height exists for the coarse cell, it overrides the DEM value.
3. Offset application: Add entity-specific vertical offsets (e.g., aircraft altitude AMSL, vessel draft depth) to the resolved ground height to obtain final world-space coordinates.

Key Implementation Files and Code Patterns

The following patterns demonstrate how to interact with the terrain sampling APIs:

Batch-Resolving Ground Heights

Use resolveEllipsoidalGround to fetch elevations for new tracks or vessel paths:

import { resolveEllipsoidalGround } from '@/data/terrainHeights.js';

async function getGroundHeights(points) {
  // points = [{lat, lon, sourceOrthometricM?}, …]
  const results = await resolveEllipsoidalGround(points);
  // results[i] => {ellipsoid, source}
  return results;
}

Sampling the Photoreal Mesh

Call sampleMeshFloorCells during layer polls to latch mesh heights:

import { sampleMeshFloorCells } from '@/data/meshFloorSampler.js';
import { viewer } from '@/app/viewer.js';

function pollMeshFloors(scene, contacts) {
  const points = contacts.map(c => ({lat: c.lat, lon: c.lon}));
  const viewerPos = viewer.camera.positionCartographic;
  sampleMeshFloorCells(scene, points, {
    viewerLat: viewerPos.latitude,
    viewerLon: viewerPos.longitude,
    excludeObjects: [],               // avoid self‑intersection
  });
}

Retrieving Final Entity Altitude

Combine both pipelines to determine placement height:

import { cachedGroundFloor } from '@/data/meshFloorSampler.js';
import { cachedRealEllipsoidalGround } from '@/data/terrainHeights.js';

function getEntityAltitude(lat, lon, entityOffsetM = 0) {
  // Prefer mesh floor if it exists, otherwise use real ellipsoidal ground.
  const meshHeight = cachedGroundFloor(lat, lon);
  const ground = meshHeight != null ? meshHeight
                                    : cachedRealEllipsoidalGround(lat, lon);
  return (ground ?? 0) + entityOffsetM;
}

Summary

• Dual-pipeline design: God’s Eye View separates DEM-based ellipsoidal lookup (src/data/terrainHeights.js) from photoreal mesh sampling (src/data/meshFloorSampler.js).
• Network resilience: The ellipsoidal pipeline batches requests in chunks of 64 and falls back to geoid math when the proxy is unavailable.
• Performance optimization: Deterministic coordinate rounding, in-memory Map caching, and one-shot mesh cell latching prevent redundant calculations and GPU queries.
• Accuracy layering: Entity heights default to reliable DEM data but upgrade to rendered mesh elevations when high-resolution 3-D tiles are visible and loaded.

Frequently Asked Questions

How does God’s Eye View handle terrain sampling when the network is offline?

When the Re:Earth /api/terrain/heights proxy is unreachable, the system automatically falls back to client-side geoid calculations using the geoidHeight function from src/data/geoid.js. Failed request chunks are cached with source: 'geoid-fallback' and a cooldown timer to prevent repeated network attempts while ensuring entities still receive mathematically derived elevation data.

What is the difference between cachedGroundFloor and cachedRealEllipsoidalGround?

cachedGroundFloor (from src/data/meshFloorSampler.js) returns the rendered mesh height from photorealistic 3-D tiles if available, falling back to null otherwise. cachedRealEllipsoidalGround (from src/data/terrainHeights.js) returns only confirmed DEM heights from the Re:Earth proxy, filtering out geoid-fallback values to provide physics-critical code with the most accurate ground truth available.

Why does the mesh sampler ignore cells farther than 15 km from the camera?

The MAX_SAMPLE_DIST_KM constant (15 km) prevents the sampler from requesting heights for tiles that Cesium has not yet loaded into memory. Sampling unloaded tiles would return null or default values, causing entities to flicker or sink. This distance culling ensures that only fully resolved, high-resolution geometry contributes to entity height calculations.

How are coordinate precision and caching optimized for performance?

Coordinates are quantized to 5 decimal places (roughly 1-meter resolution) before creating cache keys, ensuring that slightly jittered GPS positions map to the same terrain sample. The system uses chunked requests (max 64 points) to balance network efficiency against header size limits, and mesh sampling is capped at 40 samples per poll to maintain frame rate stability.

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