# How Ground Probing Works for Altitude Display in Cockpit Mode

> Discover how ground probing works in cockpit mode to accurately display aircraft altitude. Learn how terrain heights determine grounded or airborne status for precise readings.

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

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/terrainHeights.js), while the caching mechanism is implemented in [`src/data/groundFloor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.

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

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

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/groundFloor.js) to establish a baseline ground elevation for each aircraft position.
- The `onGround` flag is determined in [`src/data/renderAltitude.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/renderAltitude.js) by comparing reported altitude against the cached ground height.
- The `cockpitAltitudeDisplayFt` function in [`src/cockpitMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitMath.js) returns 0 ft for grounded aircraft and converts meters to feet for airborne targets.
- The UI layer in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/groundFloor.js). When the scene loads, [`src/data/terrainHeights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.