# Gods-Eye-View README File: Complete Guide to the Real-Time 3D Globe Simulator > Explore the Gods-Eye-View README for a complete guide to this real-time 3D spy-satellite simulator. Learn installation, data layers, voice commands, and API setup. - Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view) - Tags: getting-started - Published: 2026-08-30 --- **Yes, the gods-eye-view repository includes a comprehensive README.md file at the repository root that explains the spy-satellite simulator project, covering installation, live data layers, voice commands, and API configuration.** The gods-eye-view project by bilawalsidhu is a browser-based "spy-satellite" simulator that aggregates real-time public data streams onto a photorealistic 3D globe. This open-source application visualizes live aircraft transponders, ship AIS signals, satellite orbital elements, earthquakes, and public CCTV feeds through an interactive cockpit interface. The gods-eye-view README serves as the canonical entry point for developers and users, providing setup instructions, architectural context, and API integration details. ## Locating the Gods-Eye-View README Documentation The primary documentation for this project resides in [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md) at the repository root. This file contains the project overview, quick-start instructions, and detailed explanations of the voice-driven interface and data visualization capabilities. ### Key Sections in the README The gods-eye-view README is organized into several critical sections that cover both user and developer workflows: - **Quick Start**: Installation and local development server setup instructions - **What's on the Globe**: Catalog of available live data layers including flights, maritime traffic, and seismic activity - **Talk to It**: Voice command interface documentation and supported natural language queries - **API Keys**: Required credentials for Google Maps and OpenAI integration ## Installation and Setup Guide To run the gods-eye-view project locally, start by cloning the repository and configuring your environment variables. The README specifies that you must copy `.env.example` to `.env` and populate it with your `GOOGLE_MAPS_API_KEY` before launching the development server. ```bash # Clone and install dependencies cp .env.example .env # Add your GOOGLE_MAPS_API_KEY here npm install npm run dev -- --host localhost --port 4173 ``` After starting the server, navigate to `http://localhost:4173` to access the globe interface. ## Core Source Files and Architecture According to the gods-eye-view source code, the application follows a modular architecture with clear separation between rendering, camera control, and data management. Understanding these key files is essential for extending the platform's capabilities. ### Entry Point and Bootstrap ([`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)) The [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) file serves as the application entry point, bootstrapping the Cesium.js globe instance, initializing UI panels, and wiring the data-layer manager. This module orchestrates the initial load sequence and establishes the connection between the visualization engine and incoming data streams. ### Camera Control System ([`src/camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/camera.js)) The [`src/camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/camera.js) module implements the central camera controller exposing methods like `flyTo()`, `setStyle()`, and `resetGlobe()`. These functions power both the user interface and voice-driven navigation, enabling cinematic transitions between geographic coordinates. ```javascript import { camera } from './src/camera.js'; // Navigate to Los Angeles International Airport camera.flyTo({ lat: 33.9425, lon: -118.4081, altitude: 3000 }); // Apply night-vision styling (0-6 range: CRT, NVG, FLIR, etc.) camera.setStyle(3); ``` ### Data Layer Management ([`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js)) Located in [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) (and aliased as `dataLayerManager`), this module manages enabling and disabling of live visualization layers. It tracks health status for each feed and handles API-key authentication propagation for external data sources. ```javascript import { dataLayerManager } from './src/mapStackController.js'; // Enable live flight tracking dataLayerManager.enableLayer('flights'); // Display public CCTV cameras in Austin dataLayerManager.enableLayer('cctv'); ``` ### Contact Selection and Cockpit View ([`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js)) The [`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) file implements the "focus" logic for selecting contacts, handling cockpit entry transitions, and routing camera hand-offs when tracking specific aircraft or vessels. ### Voice Interface ([`src/voiceAgent.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voiceAgent.js)) While indirectly referenced in the camera verb mappings, [`src/voiceAgent.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voiceAgent.js) handles OpenAI API integration for parsing spoken commands, translating natural language into camera movements and data queries. ## Working with Live Data and Voice Commands The gods-eye-view README documents how to interact with the system beyond manual controls. Users can enable specific data layers programmatically or through the UI, then analyze real-time feeds using cockpit-style instruments. ### Programmatic Layer Control Each data source connects through the layer management API, allowing developers to toggle visibility of specific intelligence feeds based on application state or user preferences. ### Voice-Driven Interaction The README includes instructions for voice-controlled usage, which requires an OpenAI API key configured in your environment. After clicking the "GEV MIC" button, users can issue commands like: > "Take me to LAX and select the nearest airborne aircraft." The [`voiceAgent.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/voiceAgent.js) module parses this input, triggers the camera controller's `flyTo` method, and activates the cockpit view for the selected contact. ## Additional Technical Documentation Beyond the README, the repository includes [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md), which provides an in-depth technical overview of the architecture, data pipelines, and layer lifecycles. This document complements the README by offering implementation details for contributors working on the Cesium.js visualization stack or live data aggregation systems. ## Summary - The gods-eye-view README ([`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md)) is located at the repository root and serves as the primary documentation entry point. - The file contains essential sections for Quick Start, live data layer catalogs, voice interaction guides, and API key requirements. - Key source files include [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) (bootstrap), [`src/camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/camera.js) (navigation), [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) (data layers), and [`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) (contact selection). - Installation requires Node.js, npm, and a Google Maps API key configured in `.env`. - Voice control functionality requires OpenAI API integration and exposes camera verbs for hands-free navigation. ## Frequently Asked Questions ### Where is the gods-eye-view README file located? The README file is located at the repository root as [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md). It contains the complete project documentation, installation instructions, and usage guides for the spy-satellite simulator, making it the definitive starting point for new users and contributors. ### What API keys are required to run the gods-eye-view project? According to the README, you need a **Google Maps API key** for the base map tiles and geocoding services. If you want to use voice commands, you also need an **OpenAI API key** for the natural language processing features in [`src/voiceAgent.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voiceAgent.js). Both credentials must be configured in your `.env` file before starting the development server. ### Can I add custom data layers to the gods-eye-view globe? Yes. The [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) file exposes the `dataLayerManager` API, which allows developers to programmatically enable and disable layers. You can extend this system to ingest custom feeds by following the layer lifecycle patterns documented in [`docs/CURRENT-STATE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/CURRENT-STATE.md). ### How does the voice control system work in gods-eye-view? The voice interface, implemented in [`src/voiceAgent.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voiceAgent.js), captures audio through the browser, sends it to OpenAI's API for transcription and intent recognition, then maps recognized commands to camera verbs defined in [`src/camera.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/camera.js). This allows hands-free navigation to specific coordinates or automatic selection of airborne and maritime contacts.