How to Contribute to the God’s Eye View Project: A Complete Developer Guide

You can contribute to the God’s Eye View project by cloning the repository, setting up the Node.js 24.14.0 environment, and submitting pull requests that follow the standardized layer interface for geospatial data visualization.

The God’s Eye View project is a vanilla-JavaScript web application that visualizes live public-source geospatial data on a 3-D globe using CesiumJS. According to the bilawalsidhu/gods-eye-view source code, the architecture is deliberately flat to help contributors quickly locate and modify specific components, from data layers to voice control interfaces.

Understanding the God’s Eye View Architecture

The codebase follows a modular, flat structure that separates concerns into distinct directories. Each data layer—such as flights, satellites, or CCTV feeds—exists as a self-contained module under src/data/.

Area	Responsibility	Primary Files
Bootstrap & globals	Initialize Cesium and register layers	src/main.js
UI façade	Panels, HUD, and control widgets	src/ui.js
Layer implementation	Individual data source modules	src/data/*.js (e.g., src/data/flights.js)
Voice tools	Server-side definitions and client actions	vite.config.js, src/voice/gevActions.js
Post-processing shaders	GLSL style presets (CRT, NVG, FLIR)	src/styles/*.js
Cockpit context	Camera interaction and HUD logic	src/cockpit*

All API keys remain server-side; the client only accesses public keys added via the POWER UP panel. This design ensures the codebase is safe to fork and run locally without hidden credentials.

Setting Up Your Development Environment

Getting started requires Node.js 24.14.0 (or Node 26.x as specified in package.json). The project uses Vite for build tooling and development.

1. Clone and install dependencies:

   git clone https://github.com/bilawalsidhu/gods-eye-view.git
   cd gods-eye-view
   nvm install 24.14.0
   nvm use 24.14.0
   npm install

2. Run the development server:

   npm run doctor        # Validates Node version and provider config
   
   ./scripts/dev-fresh.sh   # Optional: clears Vite cache
   
   npm run dev           # Starts the app on http://localhost:4173
   

   No API keys are required to start; the app automatically falls back to Esri World Imagery and OpenStreetMap.

3. Validate your changes:

   Before submitting a pull request, ensure all three checks pass:

   npm run build
   npm test
   npm run test:track   # Requires the dev server to be running
   

Contribution Paths for God’s Eye View

Adding or Improving Data Layers

To contribute a new geospatial layer, create a module in src/data/ that implements the standardized layer interface: init(), enable(), disable(), update(), and destroy(). Use src/data/flights.js as your template. The enable() method should handle data fetching, while disable() must clean up all Cesium primitives to prevent memory leaks.

Contributing CCTV Source Packs

Add new camera networks by creating JSON configuration files under config/ (e.g., cctv_sources.<city>.json). These files must include camera coordinates, attribution strings, and server-registered frame URLs. Reference the existing config/cctv_sources.shinjuku.json for the required schema.

Extending Voice Control Functionality

Voice commands are defined in vite.config.js under the GEV_REALTIME_TOOLS configuration object, with corresponding client-side handlers in src/voice/gevActions.js. When adding new voice tools, ensure you register the tool definition server-side and implement the action handler client-side to maintain the real-time command pipeline.

Creating Visual Styles

New visual post-processing effects require writing GLSL fragment shaders in src/styles/ and exposing them via the STYLES map in src/ui.js. Examine src/styles/retro.js to understand how to structure shader presets for effects like CRT scanlines or night-vision green tints.

Step-by-Step Guide to Adding a New Data Layer

Below is a minimal implementation for a custom layer called myLayer. This module fetches JSON data and renders point primitives on the Cesium globe:

// src/data/myLayer.js
import * as Cesium from 'cesium';
import { getCesiumScene } from '../cesiumHelpers.js';

let entityCollection = null;

export default {
  /** Called once at app start – set up any static resources. */
  init() {
    const scene = getCesiumScene();
    entityCollection = scene.primitives.add(new Cesium.PrimitiveCollection());
  },

  /** Enable the layer – start polling / subscribing. */
  async enable() {
    const data = await fetch('https://example.com/public-data.json').then(r => r.json());
    data.features.forEach(f => {
      const point = Cesium.Cartesian3.fromDegrees(f.geometry.coordinates[0], f.geometry.coordinates[1]);
      entityCollection.add(new Cesium.PointPrimitive({
        position: point,
        color: Cesium.Color.YELLOW,
        pixelSize: 6,
      }));
    });
  },

  /** Disable the layer – stop network activity & clean up. */
  disable() {
    if (entityCollection) {
      entityCollection.removeAll();
    }
  },

  /** Periodic update – called by the main loop (≈15 s). */
  async update() {
    // Re‑fetch and replace the primitives, or implement delta logic.
    this.disable();
    await this.enable();
  },

  /** Clean up when the app shuts down. */
  destroy() {
    this.disable();
    const scene = getCesiumScene();
    scene.primitives.remove(entityCollection);
    entityCollection = null;
  },

  /** Optional: expose stats for the UI. */
  getStats() {
    return { count: entityCollection?.length ?? 0 };
  },
};

To activate your layer, import it in src/ui.js and add it to the aggregateLayerLoading list near lines 59-75.

Submitting Your Contribution to God’s Eye View

Follow the standardized workflow to ensure your contribution to the gods-eye-view project is accepted:

1. Branch off main with a descriptive feature branch name.
2. Make incremental commits using 2-space indentation, single quotes, and semicolons.
3. Run the full test suite (npm test and npm run test:track) to maintain CI compliance.
4. Update documentation: Modify docs/CURRENT-STATE.md if you change runtime behavior, or update DATA_SOURCES.md when adding new data sources with proper license attribution.
5. Submit your PR for review by maintainers Bilawal Sidhu and Sameh Khamis.

All contributions are automatically licensed under the project’s MIT license as specified in the LICENSE file.

Summary

• God’s Eye View uses a flat architecture with self-contained data layers in src/data/*.js that implement init, enable, disable, update, and destroy methods.
• Development requires Node.js 24.14.0 and uses Vite; start with npm run doctor and npm run dev.
• Contributors can add CCTV sources via JSON configs, extend voice control through vite.config.js and src/voice/gevActions.js, or create GLSL shaders in src/styles/.
• Always run npm run build, npm test, and npm run test:track before submitting pull requests.
• Update docs/CURRENT-STATE.md or DATA_SOURCES.md when changing runtime behavior or adding data sources.

Frequently Asked Questions

Do I need API keys to contribute to God’s Eye View?

No. The application falls back to Esri World Imagery and OpenStreetMap when no API keys are present, allowing you to develop and test locally without credentials. Server-side secrets in vite.config.js proxy external API calls to keep keys out of the browser.

What is the standardized layer interface in God’s Eye View?

The layer interface requires five core methods: init() for setup, enable() to start data fetching, disable() to clean up resources, update() for periodic refreshes (called every ~15 seconds), and destroy() for final teardown. Optional methods like getStats() can expose metrics to the UI.

How do I add a new camera source to the CCTV layer?

Create a new JSON file in config/ following the cctv_sources.<city>.json naming convention. Include camera coordinates, attribution text, and the server-registered frame URL. See config/cctv_sources.shinjuku.json for the exact schema and field requirements.

Which file should I edit to change the visual appearance of the globe?

Visual styles are controlled in src/styles/*.js using GLSL fragment shaders. After creating your shader file, register it in the STYLES map within src/ui.js to make it selectable from the UI. Reference src/styles/retro.js for implementation details on post-processing effects like CRT or NVG modes.

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