How the Floor-Hold System Works in God's Eye View: Aircraft Rendering Without Terrain Failures

The floor-hold system in God's Eye View prevents aircraft from sinking below rendered terrain by computing a coarse cached ellipsoidal height grid and clamping each contact's altitude to never fall below that floor plus a safety lift.

This floor-hold system is a critical reliability mechanism in the bilawalsidhu/gods-eye-view repository. When the terrain-height service returns 504 errors or times out, the system guarantees that every aircraft remains visually anchored to a sensible ground plane rather than disappearing into the geoid.

Core Architecture of the Floor-Hold System

The floor-hold system operates through a deterministic pipeline that transforms raw aircraft positions into render-safe coordinates. All core logic resides in src/data/groundFloor.js.

Coarse Grid Definition

The system builds upon a 3-decimal-degree cell (FLOOR_CELL_DEG = 0.001), approximately 111 meters per cell. This granularity balances cache efficiency with spatial precision.

Each cell maps to a cached ellipsoidal ground height via cachedRealEllipsoidalGround. The coarse grid avoids excessive memory consumption while ensuring every rendered position has a defined floor.

// From groundFloor.js — grid constant
export const FLOOR_CELL_DEG = 0.001;  // ~111m cells at equator

Altitude Clamping Functions

Two complementary clamping functions enforce the floor hold:

• floorAltitudeM(altM, groundM, liftM) — Returns max(altM, groundM + liftM), with default liftM = 1.5 meters. When ground is unknown, returns the original altitude unchanged.
• displayFloorHeightM(displayHeightM, floorM, liftM) — Applies floor constraints to dead-reckoned positions that drift from their original fix.

import { floorAltitudeM, displayFloorHeightM } from '../src/data/groundFloor.js';

// Aircraft reports no altitude (null from ADS-B)
const rawAltM = null;
const groundM = 153;  // Cached ellipsoidal height

// Clamp to floor + lift (154.5m)
const safeAltM = floorAltitudeM(rawAltM, groundM);  // → 154.5

// Drifting renderer position caught below floor
const driftedAltM = 150;
const correctedAltM = displayFloorHeightM(driftedAltM, groundM);  // → 154.5

Resilience Mechanisms

Neighbor Floor Fallback

When a cell's terrain height is unresolved (cold cache), neighborFloorM(cell) borrows the lowest floor among eight adjacent cells. This activates only after NEIGHBOR_FLOOR_MIN_SAMPLES = 2 neighbors resolve, preventing false floors from isolated high terrain.

This neighbor-fallback mechanism ensures continuity during rolling terrain-proxy outages without creating "floating" contacts.

import { neighborFloorM, coarseFloorCoord } from '../src/data/groundFloor.js';

const cell = coarseFloorCoord(30.1975, -97.6660);

// If cell itself is cold, check neighbors for lowest safe floor
const fallbackFloor = neighborFloorM(cell);  // → 152m or null

Sticky Cell Selection

Rapid cell-flipping causes jarring altitude jumps. stickyFloorCell(lat, lon, previousCell) maintains hysteresis through CELL_HYSTERESIS_DEG, keeping a contact on its current floor cell until it exits a tolerance band.

import { stickyFloorCell } from '../src/data/groundFloor.js';

let activeCell = null;

function renderFrame(lat, lon) {
  // Prevent rapid cell switching
  activeCell = stickyFloorCell(lat, lon, activeCell);
  // Proceed with floor lookup for activeCell...
}

Integration in the Flight Render Pipeline

The src/data/flights.js module orchestrates floor-hold application for every contact:

1. Query cachedGroundFloor for the contact's cell
2. Apply floorAltitudeM to the raw altitude
3. Apply displayFloorHeightM to the dead-reckoned display position
4. Convert to Cartesian coordinates for WebGL rendering

When cachedGroundFloor encounters a 504 from /api/terrain/heights, the cached floor values and neighbor fallbacks ensure uninterrupted rendering.

// Conceptual pipeline from flights.js
const floorM = await cachedGroundFloor(cell.lat, cell.lon);
const flooredAltM = floorAltitudeM(report.altitudeM, floorM);
const displayAltM = displayFloorHeightM(drPosition.altitudeM, floorM);

Verification via Outage Simulation

The scripts/qa-floor-hold.mjs test rigorously validates the floor-hold system:

• Forces every terrain request to return 504
• Pins camera over known runway coordinates
• Asserts that contacts never fall below rendered mesh or bare-earth DEM

Output logs (hold-*.json) confirm the hold passes every simulation tick, demonstrating production-grade reliability.

Key Implementation Files

File	Purpose
src/data/groundFloor.js	Core floor-hold logic: grid, clamps, neighbor fallback, hysteresis
src/data/flights.js	Render-loop integration applying floor constraints per contact
scripts/qa-floor-hold.mjs	End-to-end outage simulation and validation
src/data/terrainHeights.js	Cache and resolver for ellipsoidal ground heights
src/data/groundSnap.js	One-shot ground-height snap for modeled grounded aircraft

Summary

• The floor-hold system uses a 0.001° coarse grid (~111m cells) cached from ellipsoidal terrain heights
• floorAltitudeM and displayFloorHeightM enforce dual clamps on raw and drifted positions
• Neighbor borrowing with NEIGHBOR_FLOOR_MIN_SAMPLES = 2 provides robust fallback during cache misses
• Sticky cell selection via stickyFloorCell eliminates visual jitter from rapid grid transitions
• The qa-floor-hold.mjs test proves the system survives complete terrain-service outages

Frequently Asked Questions

What happens when the terrain-height service is completely unavailable?

The floor-hold system continues operating on cached floor values and neighbor fallbacks. The qa-floor-hold.mjs test explicitly simulates this scenario by forcing 504 responses and verifies that aircraft never sink below the rendered mesh.

How does sticky cell selection improve visual stability?

stickyFloorCell applies hysteresis through CELL_HYSTERESIS_DEG, preventing a contact from rapidly switching between adjacent floor cells as it crosses grid boundaries. This eliminates altitude flickering that would otherwise occur from discrete floor height differences between neighboring cells.

Why use the lowest neighbor floor in the fallback mechanism?

Borrowing the lowest floor among neighbors prevents artificial "floating" that would occur if a high outlier neighbor were selected. The neighborFloorM function requires at least two resolved neighbors (NEIGHBOR_FLOOR_MIN_SAMPLES = 2) before activating, ensuring statistical confidence in the borrowed value.

What is the default lift value and why does it matter?

The default liftM = 1.5 meters in floorAltitudeM provides a small safety margin above the ellipsoidal ground height. This accounts for landing gear offset, GPS vertical error, and ensures the rendered aircraft sits visibly on top of the terrain rather than clipping through it.

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