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

The HUD in Gods Eye View is implemented via the IntelHUD class in 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 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 " or "SECTOR " through the helper module 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 or keyboard handlers.

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

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