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

> Learn how the floor-hold system in God's Eye View aircraft rendering prevents terrain failures. Discover its ellipsoidal height grid and safety lift clamping for stable flight simulation.

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

---

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

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

```javascript
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.

```javascript
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.

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

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/groundFloor.js) | Core floor-hold logic: grid, clamps, neighbor fallback, hysteresis |
| [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/terrainHeights.js) | Cache and resolver for ellipsoidal ground heights |
| [`src/data/groundSnap.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.