How Ground Probing Works for Altitude Display in Cockpit Mode

Ground probing in the Gods Eye View cockpit samples cached terrain heights to determine if an aircraft is grounded, then the cockpitAltitudeDisplayFt utility returns 0 ft for grounded contacts or converts the true MSL altitude from meters to feet for airborne targets.

The cockpit mode in bilawalsidhu/gods-eye-view provides pilots with a heads-up display showing critical flight data, including the aircraft’s altitude in feet. This readout relies on a ground probing subsystem that compares the aircraft’s reported altitude against cached terrain heights to distinguish between grounded and airborne states.

The Ground Probing Architecture

The ground probing workflow consists of two distinct phases: terrain height sampling and on-ground determination. This architecture ensures accurate altitude displays even when network terrain data is temporarily unavailable.

Caching Terrain Heights with groundFloor

When the scene initializes, the application queries a terrain service via the groundFloor module to obtain ellipsoidal ground heights for the current latitude and longitude. These values are stored in cachedGroundFloor to eliminate redundant network requests during subsequent frames.

The terrain resolution logic resides in src/data/terrainHeights.js, while the caching mechanism is implemented in src/data/groundFloor.js. Together, these modules provide the warmGroundFloor and cachedGroundFloor utilities for fast ground-height lookups.

Determining On-Ground Status

The render-altitude routine in src/data/renderAltitude.js compares the flight-track altitude against the sampled ground elevation. If the aircraft’s altitude falls within a small tolerance of the ground height, the system sets the onGround flag to true; otherwise, it remains false.

Converting Altitude for Cockpit Display

Once the ground-probing step resolves the onGround flag, the cockpitAltitudeDisplayFt function in src/cockpitMath.js handles the final conversion. This utility enforces the business rule that grounded contacts always display 0 ft, regardless of their actual MSL altitude.

// src/cockpitMath.js
export function cockpitAltitudeDisplayFt(altitudeM, onGround) {
  // Grounded contacts are rendered as zero feet.
  if (onGround === true) return 0;
  // Otherwise convert metres → feet (1 m ≈ 3.28084 ft).
  return Number.isFinite(altitudeM) ? altitudeM * 3.28084 : null;
}

For airborne aircraft, the function converts meters to feet using the standard 3.28084 multiplier. If the altitude value is not finite, the function returns null to prevent invalid readouts.

Integrating Ground Probing into the UI

The UI layer in src/ui.js orchestrates the ground probing pipeline during each update cycle. It retrieves the latest altitude in meters and the onGround boolean from the render-altitude logic, then passes both values to the conversion helper.

// src/ui.js (excerpt)
const altitudeFt = cockpitAltitudeDisplayFt(info.altitudeM, info.onGround);

This pattern ensures the cockpit HUD reflects real-time ground contact status. When an aircraft is taxiing or parked, the display immediately snaps to 0 ft, while climbing aircraft show precise MSL-derived foot values.

Practical Implementation Example

The following example demonstrates the complete ground probing workflow for a single contact:

// Example: rendering an altitude readout for a contact
import { cockpitAltitudeDisplayFt } from './cockpitMath.js';

// Assume we have a contact with these properties:
const contact = {
  altitudeM: 1500,            // metres above sea level
  lat: 37.7749,
  lon: -122.4194,
  // The groundFloor module provides the cached ground height (in metres)
  groundM: cachedGroundFloor(contact.lat, contact.lon)   // e.g., 30 m
};

// Determine if the contact is considered "on the ground"
const onGround = Math.abs(contact.altitudeM - contact.groundM) < 100; // 100 m tolerance

// Convert to feet for cockpit display
const altitudeFt = cockpitAltitudeDisplayFt(contact.altitudeM, onGround);
console.log(`Cockpit altitude: ${altitudeFt} ft`); // → 0 ft if onGround, else ≈ 4921 ft

The 100-meter tolerance provides a buffer for surface elevation variations and GPS altitude discrepancies, ensuring the cockpit does not flicker between 0 ft and low-altitude values during takeoff or landing rolls.

Summary

• Ground probing relies on cached terrain heights from src/data/groundFloor.js to establish a baseline ground elevation for each aircraft position.
• The onGround flag is determined in src/data/renderAltitude.js by comparing reported altitude against the cached ground height.
• The cockpitAltitudeDisplayFt function in src/cockpitMath.js returns 0 ft for grounded aircraft and converts meters to feet for airborne targets.
• The UI layer in src/ui.js binds these values to the cockpit HUD, ensuring real-time altitude accuracy.
• Terrain data caching eliminates redundant network requests, allowing the ground probing system to function efficiently across frame updates.

Frequently Asked Questions

What happens to the altitude display when an aircraft is taxiing?

When an aircraft is taxiing, the ground probing system detects that the flight-track altitude is within the ground height tolerance threshold. The onGround flag is set to true, causing cockpitAltitudeDisplayFt to return 0 ft regardless of the actual MSL altitude reading.

How does Gods Eye View cache terrain height data?

The application caches terrain heights using the cachedGroundFloor utility in src/data/groundFloor.js. When the scene loads, src/data/terrainHeights.js queries the terrain service and stores the ellipsoidal ground heights, allowing subsequent frames to reuse the data without additional network requests.

Why does the cockpit display use feet instead of meters?

The cockpit interface follows aviation standards where altitude is universally reported in feet. The cockpitAltitudeDisplayFt function handles the conversion from meters (the internal coordinate system) to feet using the 3.28084 conversion factor, ensuring the display matches pilot expectations and air traffic control conventions.

Which file determines if an aircraft is considered "on the ground"?

The on-ground determination logic resides in src/data/renderAltitude.js. This module compares the aircraft's reported altitude against the cached ground elevation from groundFloor and sets the onGround boolean flag that drives the cockpit altitude display logic.

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