Getting Started with the Gods Eye View Project: A Complete Developer Setup Guide

To get started with the gods eye view project, clone the repository, configure environment variables for Google Maps and optional OpenAI access, and launch the Vite development server to run the browser-based spy-satellite simulator.

The gods eye view project is an open-source, browser-based spy-satellite simulator built with Vanilla JavaScript, CesiumJS, and Vite. This visualization platform renders photorealistic 3D globes and overlays real-time data feeds for flights, maritime traffic, and satellites. This guide covers the essential setup steps, core architecture, and key source files you need to customize the application.

Prerequisites and Environment Setup

Before running the simulator, you must obtain API keys for the mapping infrastructure and optional voice features. The application requires a Google Maps API Key to load photorealistic 3D tiles, while an OpenAI API Key enables the real-time voice command interface powered by 28 distinct tools.

Create a .env file in the project root:

VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key
VITE_OPENAI_API_KEY=your_openai_api_key

Install dependencies and start the development server:

npm install
npm run dev

Understanding the Core Architecture

The gods eye view project cleanly separates concerns into three distinct systems: the rendering engine, the data layer manager, and the UI/voice interaction layer. According to the source code, these components communicate via custom events and normalized interfaces.

The Rendering Engine in main.js

The entry point at src/main.js bootstraps the Cesium Viewer and configures the global rendering context. It initializes Google Photorealistic 3D Tiles via Cesium.createGooglePhotorealistic3DTileset and explicitly caps the render loop at 60 FPS to conserve battery on low-power devices (lines 69-135).

Initialize the viewer and load the Google 3D Tiles:

// src/main.js – inside async init()
const googleApiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
Cesium.GoogleMaps.defaultApiKey = googleApiKey;

const tileset = await Cesium.createGooglePhotorealistic3DTileset({
  onlyUsingWithGoogleGeocoder: true,
});
viewer.scene.primitives.add(tileset);

The viewer configuration runs with minimal UI chrome and a custom credit container. If Google Tiles are unavailable, the system automatically falls back to the standard Cesium globe (lines 158-173).

The Data Layer Manager

The DataLayerManager class in src/data/manager.js (lines 13-112) orchestrates all live data overlays including flights, ships, and satellites. It normalizes heterogeneous feed statistics into a unified state palette: nominal, loading, degraded, stale, fallback, or unavailable.

Register new data layers through the manager:

// src/data/manager.js – after creating DataLayerManager instance
const dataLayerManager = new DataLayerManager(viewer);
dataLayerManager.register(flightsLayer);   // src/data/flights.js
dataLayerManager.register(trafficLayer);   // src/data/traffic.js

The manager implements visibility intent logic (lines 84-96) that guarantees ordered enable/disable actions and aborts superseded requests to prevent race conditions when users rapidly toggle layers.

UI and Voice Integration

The interface layer spans src/ui.js, src/styleManager.js, and src/voice/gevRealtime.js. These modules manage HUD panels, visual presets, post-processing effects, and hands-free control. The voice integration connects to the OpenAI Realtime API, offering AI-driven HUD summaries and map control without keyboard input (referenced in src/main.js lines 21-22).

Configuring the Map Stack Controller

Base map switching is handled by src/mapStackController.js, which manages transitions between Google 3D Tiles, Bing Maps, and OpenStreetMap. When the map source changes, the controller dispatches a custom gev:map-stack-changed event (handled in src/main.js lines 77-89) so that data layers can adjust their rendering parameters or resolution settings.

Listen for stack changes to synchronize layer behavior:

// Listen for map-stack changes (e.g., to adjust CCTV resolution)
window.addEventListener('gev:map-stack-changed', (e) => {
  const { stack } = e.detail;
  // React to stack change, e.g., update layer parameters
});

Working with Data Layers

Each data module (e.g., src/data/flights.js, src/data/traffic.js) exposes a common interface implementing getStats(), refresh(), and setEnabled(). This standardization allows the DataLayerManager to poll, render, and display feed health uniformly using the FEED_STATE_LABELS palette (lines 13-20).

Toggle layers programmatically via the manager:

// UI button click handler (simplified)
function onToggleLayer(layerId, enable) {
  const entry = dataLayerManager.layers.get(layerId);
  entry.module.setEnabled(enable); // each layer implements setEnabled()
}

Enabling the First Run Experience

New users encounter a guided tutorial system via src/firstRunExperience.js, registered in src/main.js at line 34. This mission-card interface introduces the data layers, map controls, and voice commands automatically on first launch, storing completion status in local storage to prevent re-triggering.

Summary

• The gods eye view project requires Vanilla JavaScript, CesiumJS, and Vite, with API keys for Google Maps and optional OpenAI integration.
• src/main.js initializes the Cesium Viewer and Google 3D Tiles between lines 69-135, capping the frame rate at 60 FPS for power efficiency.
• src/data/manager.js provides the DataLayerManager class to register, normalize, and control live data feeds with strict visibility intent handling (lines 84-96).
• src/mapStackController.js manages base map switching and emits gev:map-stack-changed events for cross-component synchronization.
• Voice commands via src/voice/gevRealtime.js offer hands-free control through the OpenAI Realtime API and 28 specialized tools.

Frequently Asked Questions

What API keys are required to run the gods eye view project locally?

You must provide a Google Maps API Key to load the photorealistic 3D tiles. An OpenAI API Key is optional and only required if you want to use the real-time voice command features and AI-driven HUD summaries.

How do I add a custom data feed to the simulator?

Create a new layer module that exports getStats(), refresh(), and setEnabled() methods, then register it with dataLayerManager.register(yourLayer) in src/data/manager.js. The manager normalizes your feed state through the layerFeedState system and handles lifecycle events automatically.

Why is the application render loop capped at 60 FPS?

The render loop in src/main.js intentionally throttles to 60 FPS to reduce power consumption on laptops and mobile devices. This optimization is implemented within the Cesium viewer configuration between lines 92-135 to ensure low-power usage without sacrificing visual smoothness.

Can users switch base maps if Google 3D Tiles fail to load?

Yes. The src/mapStackController.js automatically falls back to standard Cesium globe rendering if Google Tiles are unavailable, and users can manually switch between Google 3D, Bing, and OSM base maps via the UI. The system notifies all layers of these changes through the gev:map-stack-changed event.

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