7da9eeaeb0
Applied 4 confirmed findings from the multi-agent review (5th was a documented deliberate deviation): - aircraft: self-healing visibilitychange listener — the live feed no longer stalls permanently after tab hide->show while the clock is paused (MAJOR) - SPEC §9: nginx proxy_pass with $is_args$args needs a resolver or prod 502s while nginx -t still passes — documented + hardened the deploy step (MAJOR) - ships: live-AIS map now evicts true least-recently-updated (move-to-end), not oldest-inserted - ships: corrected inverted Hormuz lane direction labels (tracks with decreasing longitude sail west/inbound, not east) - README: full data-source + attribution table, real-vs-DEMO breakdown, architecture, roadmap Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
101 lines
6.6 KiB
Markdown
101 lines
6.6 KiB
Markdown
# GODSIGH ▸ World View
|
||
|
||
A browser-based **3D/4D OSINT world view** — a CesiumJS digital-twin globe that fuses independent, public sensor feeds onto one scrubbable timeline. Satellite orbits, live aircraft, ship traffic, and energy infrastructure, all synced to a single space-time slider. Inspired by Bilawal Sidhu's *God's Eye View*.
|
||
|
||
Everything runs client-side from free, public, **unclassified** data. No API keys are required. No Cesium ion token. No build step.
|
||
|
||
---
|
||
|
||
## Quickstart
|
||
|
||
```sh
|
||
python3 serve.py 8137
|
||
# open http://127.0.0.1:8137
|
||
```
|
||
|
||
`serve.py` is a zero-dependency (stdlib-only) static server that also proxies the two feeds a browser can't call directly. Open the page and the globe boots over the Persian Gulf; give the satellites a few seconds to propagate.
|
||
|
||
## What you're looking at
|
||
|
||
A dark digital-twin globe with the built-in Cesium **timeline + animation widget** along the bottom acting as the space-time slider — scrub it and every time-aware layer moves with the clock (now ±6 hours). Two rendering skins, toggled top-left:
|
||
|
||
- **Data Mode** — a flat, high-contrast dark basemap for asset tracking (the default).
|
||
- **Photo Mode** — Sentinel-2 satellite imagery with a live day/night terminator.
|
||
|
||
The HUD lists every layer with a live status line and an on/off toggle, plus a `LIVE / SCRUBBED` chip that shows when you've scrubbed off wall-clock-now (at which point the live-only layers pause to save quota).
|
||
|
||
## Layers & data sources
|
||
|
||
| Layer | Source | Live? | Notes |
|
||
|---|---|---|---|
|
||
| **Satellites** (~97) | [Celestrak](https://celestrak.org) GP/TLE | ✅ deterministic | SGP4-propagated orbits with glowing paths; EO/recon birds incl. WorldView, Pléiades, Capella, SkySat, plus Chinese **Gaofen** and Russian **Cosmos** (Persona) military satellites. Click one for orbital elements. |
|
||
| **Aircraft** | [OpenSky Network](https://opensky-network.org) ADS-B | ✅ live | Thousands of live flights, colored by altitude band; click one for callsign/country/altitude/speed/heading. |
|
||
| **Ships** `[DEMO]` | synthetic | — | Illustrative tanker traffic through the Strait of Hormuz, incl. a "toll-route" carrier, a **dark-vessel AIS gap**, and the Fujairah idle anchorage. Optional live AIS — see below. |
|
||
| **Infrastructure** | static vectors | — | Choke points (Hormuz, Bab el-Mandeb, Suez, Malacca), the East–West Petroline & Habshan–Fujairah pipelines, and key oil/desal/base facilities. Coordinates approximate. |
|
||
| **Events** `[DEMO]` | synthetic | — | Time-anchored markers that appear as the slider crosses their moment — illustrative placeholders for a future real event feed. |
|
||
|
||
### Basemaps
|
||
- **Data Mode:** © OpenStreetMap contributors © CARTO (dark_all raster tiles).
|
||
- **Photo Mode:** Sentinel-2 cloudless by [EOX](https://s2maps.eu) — modified Copernicus Sentinel data 2023.
|
||
|
||
## What is real vs. DEMO
|
||
|
||
**Real, live, public data:** satellites (Celestrak TLEs) and aircraft (OpenSky ADS-B). Satellite positions are computed live via SGP4; aircraft are polled from OpenSky.
|
||
|
||
**Synthetic `[DEMO]` data:** ships and events. These are hand-authored to illustrate the *kind* of analysis the platform is built for (dark-vessel detection, choke-point pressure, strike/pass correlation) without claiming to depict a real event. Every demo entity is labeled `[DEMO]` in its name, the HUD, and its info panel.
|
||
|
||
> OpenSky's anonymous API has a small daily quota (~400 credits; a global snapshot costs 4). The aircraft layer polls every 90 s only while the tab is focused and the clock is live, and shows the remaining quota in its status line. If you hit the limit it backs off and says so.
|
||
|
||
## Optional: live AIS ship tracking
|
||
|
||
The demo fleet is the default. To show **real** ship traffic, get a free key from [aisstream.io](https://aisstream.io) and set it in [`js/config.js`](js/config.js):
|
||
|
||
```js
|
||
AISSTREAM_API_KEY: 'your-key-here',
|
||
```
|
||
|
||
On the first live position report the demo fleet hides and real vessels stream in over a WebSocket (no proxy needed).
|
||
|
||
## Architecture
|
||
|
||
No framework, no bundler — vanilla ES modules plus two CDN globals (CesiumJS, satellite.js).
|
||
|
||
```
|
||
index.html CDN script tags, HUD shell, #cesiumContainer
|
||
css/style.css dark HUD styling
|
||
js/config.js all URLs, intervals, camera, colors, keys — one file
|
||
js/lib.js shared helpers (glyphs, bearing, color bands)
|
||
js/ui.js HUD: layer rows, status lines, LIVE/SCRUBBED chip
|
||
js/main.js viewer bootstrap, basemaps, clock, gating, picking, loader
|
||
js/layers/*.js one module per layer (satellites, aircraft, ships, infra, events)
|
||
serve.py dev server + same-origin proxy (proxy/opensky, proxy/celestrak)
|
||
```
|
||
|
||
**Why the proxy?** OpenSky pins its CORS header to its own domain, so a browser can't fetch it cross-origin. `serve.py` (dev) and nginx (prod) forward `proxy/opensky` and `proxy/celestrak` from the same origin. Every URL in the app is **relative**, so it works unchanged at `/` and at `/godsigh/`.
|
||
|
||
**Entities vs. primitives:** satellites, ships, infrastructure, and events are Cesium entities (time dynamics + click InfoBox for free). Aircraft are a `BillboardCollection` primitive — thousands of them, rebuilt each poll — with a custom click overlay.
|
||
|
||
## Roadmap
|
||
|
||
- **Live AIS** by default (aisstream.io key) — implemented, opt-in today.
|
||
- **GPS-jamming heatmap** from [gpsjam.org](https://gpsjam.org) daily H3 tiles.
|
||
- **Historical recording** — a cron job appending OpenSky/AIS snapshots to JSONL for true time-travel beyond the live ±6h window.
|
||
- **Classified-sat amateur TLEs** (community "classfd" catalogs) for birds Celestrak omits.
|
||
- **Economic side panel** — Brent / WTI oil futures synced to the timeline.
|
||
- **Cesium ion terrain & photorealistic 3D tiles** (needs a token).
|
||
- **Agentic event ingestion** — LLM/agent pipelines that task, scrape, and structure OSINT into the event feed.
|
||
|
||
## Deployment
|
||
|
||
Target: `https://partly.party/godsigh/` (games VPS, behind the `forum-nginx` container and Cloudflare). Only `index.html`, `css/`, and `js/` ship; `serve.py` is replaced by nginx `location` blocks that proxy OpenSky/Celestrak. See [SPEC.md](SPEC.md) §9 for the exact deploy steps.
|
||
|
||
## Attribution & terms
|
||
|
||
- **OpenSky Network** — data under their terms; non-commercial use. https://opensky-network.org
|
||
- **Celestrak** — GP/TLE orbital data. https://celestrak.org
|
||
- **CARTO / OpenStreetMap** — basemap tiles. © OpenStreetMap contributors © CARTO.
|
||
- **EOX** — Sentinel-2 cloudless; modified Copernicus Sentinel data 2023. https://s2maps.eu
|
||
- **CesiumJS**, **satellite.js** — Apache-2.0 / MIT.
|
||
|
||
The Cesium credit display is kept visible in-app as a condition of these licenses.
|