Project: E.Y.E. — Geospatial Intelligence Interface

OVERVIEW

Project

E.Y.E.

Version

1.0.0

Globe Engine

CesiumJS 1.122

Backend

Express 5 / Node.js

Frontend Build

Vite 5 + vite-plugin-cesium

Orbital Math

satellite.js 5.0 (SGP4)

Test Framework

Vitest 2 + happy-dom

Module System

ESM throughout

E.Y.E. pulls live data from multiple public APIs and WebSocket streams, proxies them through a lightweight Express backend with in-memory caching, then renders everything as billboard collections and entities on a CesiumJS 3D globe.

The HUD overlay is pure DOM — positioned above the Cesium canvas via z-index — and reacts to camera movement, entity hover, layer toggles, shader changes, and backend health warnings wired in main.js.

SCREENSHOTS

CCTVGrid view of live proxy-routed traffic cameras.

CCTVFull view of active camera feed marker.

EARTHQUAKE LAYERPulsing real-time global earthquake events from USGS.

AIS SHIPSLive tracking of marine vessels via AISStream.

SATELLITE LAYEROrbit paths generated via CelesTrak TLE data.

AIRCRAFT LAYERGlobal air traffic with interpolated dead-reckoning.

DATA LAYERS

Each layer is an ES module class in layers/ with enable() / disable() lifecycle methods. All toggled via the HUD side panel.

Aircraft

Live global ADS-B from adsb.lol. Progressive rendering via BillboardCollection. Dead-reckoning interpolates positions each frame. Refreshes every 10 s.

Source: api.adsb.lol/v2 · Refresh: 10 s · layers/aircraft.js

Satellites

TLE catalog from CelesTrak. SGP4 propagation via satellite.js, updated every 3 frames. Progressive loading and click-to-path visualization.

Source: celestrak.org · Cache: 2 hr · layers/satellites.js

CCTV

Traffic cameras from TfL, Austin, NSW, and Seattle. Renders markers with initial scale-up animations. Hover previews stream proxied JPEGs.

Sources: TfL · Austin · NSW · Seattle · Cache: 5 min · layers/cctv.js

Earthquakes

USGS all-day GeoJSON. Pulsing crosshair billboards sized by magnitude with progressive animation. Refreshes every 60 s.

Source: earthquake.usgs.gov · Refresh: 60 s · layers/earthquakes.js

Ships

Persistent AISStream feed with viewport-based pruning and LOD clustering for high-altitude viewing. Supports important-ship metadata overrides.

Source: stream.aisstream.io · Feed: persistent WS · layers/ships.js

HUD

Pure DOM overlay above the Cesium canvas. Includes tactical entity tracking, Reset Camera controls, layer state toggles, and shader post-processing.

File: hud/hud.js · CSS: hud/hud.css

POST-PROCESS SHADERS

CesiumJS PostProcessStage GLSL fragments in shaders/, managed by postprocessor.js. One stage active at a time; Normal removes the active stage.

NORMAL

No post-processing. Raw Cesium output.

NIGHTVISION

Green phosphor palette, boosted contrast, procedural noise grain.

FLIR

Luminance → false-color thermal (blue cold / green / red hot).

CRT

Horizontal scanlines, bloom-like glow, and subtle display curvature.

PostProcessor API

// postprocessor.js
import PostProcessor from './postprocessor.js';
const pp = new PostProcessor(viewer);
pp.setMode('CRT');       // activate shader
pp.setMode('Normal');    // remove active stage
pp.getActiveMode();    // → 'Normal' | 'NightVision' | 'FLIR' | 'CRT'

BACKEND API

Express on port 3001. Vite proxies /api/* to it. All routes use node-cache to throttle upstream calls.

Method	Endpoint	Description	Cache	Upstream
GET	/api/aircraft	All aircraft globally filtered for lat/lon.	15 s	api.adsb.lol
GET	/api/ships	Current in-memory ship state from a persistent AISStream websocket, merged with static identity messages.	Live state	stream.aisstream.io
GET	/api/cctv	Merged cameras. Accepts `?country` & `?source`.	5 min	TfL/Austin/NSW/Seattle
GET	/api/cctv/image	CORS proxy for camera JPEGs. `?url=`	60 s	Camera image hosts
GET	/api/satellites	TLE 3-line catalog. `?group=active` default, with JSON fallback if the primary upstream fails.	2 hr	CelesTrak / tle.ivanstanojevic.me
GET	/api/proxy	Generic CORS proxy. `?url=` — 5 s timeout.	—	Arbitrary

Camera Schema

// GET /api/cctv
{ id: "tfl-00001.03777", name: "Trafalgar Square",
  source: "tfl", country: "GB", region: "London",
  latitude: 51.5080, longitude: -0.1281,
  imageUrl: "https://...", available: true }

Ship Schema

// GET /api/ships
{ mmsi: "227000000", name: "FRENCH WARSHIP",
  lat: 47.393, lon: -2.686, sog: 7.8, cog: 66.1,
  heading: 65, status: 0, shipType: 35 }

ARCHITECTURE

adsb.lol API──→Express /api/aircraft──→AircraftLayer──→BillboardCollection

AISStream WS──→Persistent Ship State──→Express /api/ships──→ShipLayer──→BillboardCollection

CelesTrak TLE──→Express /api/satellites──→SatelliteLayer + SGP4──→BillboardCollection

TfL/Austin/NSW/SEA──→Express /api/cctv──→CCTVLayer──→Marker Entities

USGS GeoJSON──→Direct (browser)──→EarthquakeLayer──→BillboardCollection

CesiumJS Viewer──→PostProcessor──→GLSL PostProcessStage

All Layers──→wireApplication()──→HUD DOM Events

BillboardCollection vs Entity API: Aircraft, ships, satellites, and earthquakes use raw BillboardCollection for GPU-batched rendering. CCTV uses Cesium entities for point + label markers and attaches preview metadata for hover interaction.

Dead Reckoning: Aircraft and ships interpolate position each frame using last-known heading × speed × elapsed time, keeping motion smooth despite infrequent API calls.

AIS stream model: The backend maintains one long-lived AIS websocket, merges multiple position/static message types into an in-memory registry, and serves the current ship state to the frontend on demand.

ROADMAP

Planned phases cover expanded data sources, offline capability, collaborative overlays, and a full mobile HUD. Each phase is tracked as a visual node graph.

VIEW ROADMAP

PROJECT: E.Y.E. INTEL