# How the HUD is Implemented in Gods Eye View: The IntelHUD Architecture Explained

> Discover how the HUD is implemented in Gods Eye View using the IntelHUD architecture. Learn about its full-screen DOM overlay and real-time telemetry updates.

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

---

**The HUD in Gods Eye View is implemented via the `IntelHUD` class in [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js), which creates a full-screen DOM overlay that automatically appears for military shader styles and updates telemetry every 250ms using Cesium camera data and optional AI-generated summaries.**

Gods Eye View is a Cesium-based geospatial visualization platform that renders intelligence-style heads-up displays for surveillance and reconnaissance scenarios. The entire HUD system is encapsulated in the **`IntelHUD`** class, which binds to a `Cesium.Viewer` instance and manages real-time overlays of telemetry data, geospatial coordinates, and contextual summaries using CSS custom properties and timed extraction pipelines.

## Core Architecture of the IntelHUD Class

The `IntelHUD` class serves as the central controller for the HUD, handling DOM construction, style reactivity, and telemetry polling. It is defined in [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js) and initializes by attaching a full-screen overlay to the viewer's container.

### DOM Structure and Initialisation

When instantiated with a `Cesium.Viewer`, the constructor calls **`_buildDOM()`** (lines 44–67) to generate the static HTML structure. This creates a container with the ID `intel-hud` that includes banner elements, corner brackets, edge strips, and a bottom summary bar. The DOM is constructed once and attached to the viewer element, remaining hidden until activated by style changes.

### Style-Driven Visibility and Theming

The HUD does not display for all visualization modes. The **`onStyleChange()`** method (lines 28–34) monitors the active shader style and automatically calls `show()` or `hide()` based on membership in the `MILITARY_STYLES` set—specifically `surveillance`, `thermal`, and `retro` modes. When visible, the HUD applies colour themes by setting CSS custom properties including **`--hud-color`**, **`--hud-glow`**, and **`--hud-border`** from the `HUD_COLORS` mapping (lines 24–30).

## Telemetry and Data Pipeline

Once visible, the HUD begins extracting real-time data from the Cesium camera and geospatial context. This pipeline runs on independent timers to maintain consistent update frequencies without blocking the render loop.

### Camera Data Extraction and Geoid Correction

The **`_startTimers()`** method initiates periodic updates, with the primary telemetry timer calling **`_updateCameraData()`** every 250 milliseconds. This method extracts MGRS coordinates, latitude/longitude in DMS format, ground sample distance (GSD), NIIRS estimation, altitude, off-nadir angle (ONA), and Sun elevation. Altitude values undergo geoid correction using the EGM96 grid via **`_geoidUndulationM`**, which lazy-loads the geoid data on first use and caches results per 0.01° cell (lines 41–54).

### The Locality Tag System (hudLocality.js)

The HUD determines whether the view is "NEAR <POI>" or "SECTOR <lat lon>" through the helper module **[`src/hudLocality.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hudLocality.js)**. The **`composeLocalityTag()`** function calculates distances to curated points of interest, applying the **`NEAR_POI_MAX_KM = 150 km`** cutoff to decide between proximity-based or coordinate-based labeling (lines 24–53). This semantic tag feeds into the bottom summary line to provide immediate geographic context.

## Summary Generation Logic

The bottom bar displays either a deterministic telemetry summary or an AI-generated narrative describing the scene.

### Deterministic Summary Composition

The **`_composeSummary()`** method (lines 60–92) assembles a concise one-line description combining the mode, spectral band, locality tag, region label, altitude, view window dimensions, Sun elevation, ONA, and UTC offset. This provides a standardized intelligence briefing format derived entirely from live camera parameters and geoid-corrected elevations.

### AI-Powered Summary Integration

For enhanced contextual awareness, the HUD optionally queries the **`/api/openai/hud-summary`** endpoint. The **`_updateSummary()`** method (lines 22–33) POSTs the current context—including basemap labels and enabled layers—to this endpoint. Upon receipt, the AI-generated narrative replaces the deterministic summary line until the next telemetry update or scene change.

## Public API and Usage Examples

The `IntelHUD` class exposes a clean interface for external control, typically invoked from [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) or keyboard handlers.

```javascript
import { IntelHUD } from './src/hud.js';

// Initialize with a Cesium viewer
const viewer = new Cesium.Viewer('cesiumContainer');
const hud = new IntelHUD(viewer);

// React to shader style changes
function onStyleSelect(style) {
  hud.onStyleChange(style); // Auto-shows for military styles
}

// Manual toggle via keyboard
document.addEventListener('keydown', (e) => {
  if (e.key === 'h') hud.toggle();
});

// Switch layout variants: 'tactical', 'operator', or 'minimal'
hud.setVariant('operator');

// Cleanup on exit
window.addEventListener('unload', () => hud.destroy());

```

Key methods include **`show()`**, **`hide()`**, **`toggle()`**, **`setMode()`**, **`setVariant()`**, **`getVariant()`**, **`getMode()`**, and **`destroy()`** (lines 56–99).

## Summary

- The **`IntelHUD`** class in [`src/hud.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js) encapsulates all HUD functionality for Gods Eye View.
- The DOM overlay is built once via **`_buildDOM()`** and visibility is controlled by the **`onStyleChange()`** method, which filters for military shader styles.
- Telemetry updates run every 250ms via **`_updateCameraData()`**, incorporating EGM96 geoid correction for accurate altitude readings.
- Locality detection uses **[`src/hudLocality.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hudLocality.js)** with a 150km threshold to generate "NEAR" or "SECTOR" tags.
- The summary line is composed deterministically by **`_composeSummary()`** or optionally replaced by AI-generated text from the `/api/openai/hud-summary` endpoint.
- The public API provides methods for visibility control, layout variants, and proper cleanup through **`destroy()`**.

## Frequently Asked Questions

### What triggers the HUD to appear in Gods Eye View?

The HUD automatically appears when the active shader style is classified as military-grade. The **`onStyleChange()`** method checks if the style exists in the `MILITARY_STYLES` set (including `surveillance`, `thermal`, and `retro`), calling `show()` for matches and `hide()` for all other visualization modes.

### How accurate is the altitude measurement displayed in the HUD?

The altitude calculation is geoid-corrected using the EGM96 global model. The **`_geoidUndulationM`** method converts ellipsoidal heights to mean sea level (MSL) by lazy-loading the EGM96 grid and caching undulation values per 0.01° cell, ensuring sub-meter accuracy for most operational latitudes.

### Can the HUD summary text be customized without modifying the source code?

Yes. While the deterministic summary follows a fixed format generated by **`_composeSummary()`**, the system can display custom narratives by enabling the AI integration. When configured, **`_updateSummary()`** sends scene context to the `/api/openai/hud-summary` endpoint and displays the returned text, allowing dynamic summaries based on backend logic rather than frontend code changes.

### What is the performance impact of the telemetry updates?

The telemetry system uses a 250ms interval timer started by **`_startTimers()`**, which balances real-time responsiveness with render performance. Geoid calculations are cached after first lookup per cell, and DOM updates are scoped to specific text nodes, minimizing layout thrashing during camera movements.