🛰️ WORLDVIEW - UI - Geospatial Intelligence Dashboard

A modern, real-time geospatial intelligence platform built with Next.js and CesiumJS.
Monitor global activity through an interactive 3D interface with live data from multiple public sources.

🔗 Live Demo - worldviewos.shez.app

preview.mp4

YouTube link: https://youtu.be/q8ASmSO6uIc

📋 Overview

WorldView-UI transforms publicly available geospatial data into a cohesive, military-grade situational awareness dashboard. Built as a modern alternative to traditional command-and-control interfaces, it demonstrates what's possible when combining open data sources with contemporary web technologies.

The platform aggregates six distinct data layers into a single, interactive 3D globe with a dark tactical interface and real-time visual effects.

✨ Key Features

Layer	Data Source	Update Frequency	Description
✈️ Commercial Flights	FlightRadar24 + adsb.fi	5–20 seconds	~25,000+ global aircraft with altitude-based coloring and route visualization
🛰️ Satellites	CelesTrak TLE + SGP4	2 seconds (propagation)	Live orbital tracking with ground tracks, nadir lines, and future path prediction
🌋 Earthquakes	USGS GeoJSON	60 seconds	Recent seismic activity with magnitude-based scaling and pulsing markers
🚢 Maritime Traffic	AISStream.io	60 seconds (burst-cached)	Global vessel tracking with ship type classification and movement trails
🚗 Road Traffic	OpenStreetMap Overpass	On-demand	Dynamic road network visualization with animated particle flow
📹 Public CCTV	TfL, Austin, NSW Transport	5 minutes	Live camera feeds projected onto their exact geographic locations

🎯 Why WorldView-UI?

This project serves multiple purposes:

Educational resource – Demonstrates integration of diverse real-time data sources
Geospatial experimentation – Showcases CesiumJS capabilities with modern React patterns
Open data advocacy – Highlights the wealth of publicly available geospatial information
Tactical interface design – Explores effective visualization of complex data streams

Unlike traditional geospatial applications, WorldView-UI prioritizes:

Performance – Handles thousands of moving entities at 60fps
Visual clarity – Military-inspired design language reduces cognitive load
Extensibility – Modular architecture makes adding new data layers straightforward

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                    Browser (Next.js App)                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ • Client page (`app/page.tsx`) + dynamic Cesium load   │  │
│  │ • Earthquakes fetch directly from USGS                 │  │
│  │ • Other telemetry via `/api/*` routes                  │  │
│  └────────────────────────────────────────────────────────┘  │
└────────────────────────────┬─────────────────────────────────┘
                             │ fetch /api/*
                             ▼
┌──────────────────────────────────────────────────────────────┐
│              Next.js API Routes (serverless)                   │
│  • /api/flights        – FR24 + adsb.fi fallback             │
│  • /api/flights/live   – adsb.fi regional (4 s cache)        │
│  • /api/satellites     – TLE proxy (2 h cache)               │
│  • /api/ships          – AISStream.io burst (60 s cache)     │
│  • /api/traffic/roads  – Overpass + static fallback          │
│  • /api/cctv           – Camera feed aggregation (5 m cache) │
│  • /api/cctv/image     – CORS-bypassing image proxy          │
│  • /api/geolocation    – IP geolocation fallback             │
│  • /api/health         – Uptime/status probe                 │
└──────────────────────────────────────────────────────────────┘

🔄 Data Flow

Client-side hooks (useFlights, useShips, etc.) poll Next.js API routes; useEarthquakes fetches USGS directly
API routes act as proxies — they fetch from upstream providers, cache responses, and handle authentication
CesiumJS scene renders entities using imperative primitives for optimal performance
UI components display controls and real-time event feeds outside the 3D canvas
Entity tracking locks camera to selected objects with smooth following behaviour

🛠️ Technology Stack

Frontend

Framework: Next.js 16 (App Router) with React 19
3D Rendering: CesiumJS 1.138 via Resium React bindings
Styling: Tailwind CSS 4 with custom tactical theme
Language: TypeScript 5.7 (strict mode)
Build Tool: Built-in Next.js compiler (SWC)

Backend (API Routes)

Runtime: Node.js 20+ (serverless on Vercel)
Caching: In-memory with TTL (simplified for serverless)
External APIs: REST + WebSocket (AISStream burst pattern)

Key Libraries

satellite.js – SGP4 orbit propagation
ws – WebSocket client for AISStream
resium – React bindings for CesiumJS

🚀 Getting Started

Prerequisites

Node.js 20.x or later
npm 10.x or later
Git

Installation

# Clone the repository
git clone https://github.com/shez1461/worldview-ui.git
cd worldview-ui

# Install dependencies
npm install

# Copy environment variable template
cp .env.local.example .env.local

Environment Configuration

WorldView-UI requires several API keys to function fully. Edit .env.local after copying:

# Required for 3D terrain and imagery (falls back to OSM if missing)
NEXT_PUBLIC_GOOGLE_API_KEY=your_google_maps_api_key
NEXT_PUBLIC_CESIUM_ION_TOKEN=your_cesium_ion_token

# Optional manual override for UI version shown in StatusBar.
# If omitted, version is derived automatically from git tags at build time.
# NEXT_PUBLIC_APP_VERSION=0.7.0

# Server-side only (never exposed to client)
AISSTREAM_API_KEY=your_aisstream_api_key
OPENSKY_CLIENT_ID=your_opensky_client_id
OPENSKY_CLIENT_SECRET=your_opensky_client_secret
NSW_TRANSPORT_API_KEY=your_nsw_transport_key

Useful Scripts

npm run dev
npm run build
npm run start
npm run lint
npm run proxy
npm run copy-cesium-assets

Development Server

npm run dev

Visit http://localhost:3000 to see the application.

🔑 Obtaining API Keys

🗺️ Google Maps 3D Tiles

Visit Google Cloud Console
Create a project and enable the Map Tiles API
Generate an API key and restrict it to:
- HTTP referrers (your domains)
- Map Tiles API only
Add to NEXT_PUBLIC_GOOGLE_API_KEY

Free tier: $200/month credit (~25,000 tile loads)

🛰️ Cesium Ion (optional)

Register at Cesium Ion
Copy your default access token
Add to NEXT_PUBLIC_CESIUM_ION_TOKEN

🚢 AISStream.io (maritime data)

Sign up at AISStream.io
Generate an API key from your dashboard
Add to AISSTREAM_API_KEY

Free tier provides full global AIS stream

📹 Transport for NSW (Australian CCTV)

Register at Transport NSW Open Data
Create an application and subscribe to Traffic & Cameras
Add key to NSW_TRANSPORT_API_KEY

📁 Project Structure

worldview-ui/
├── app/                         # Next.js App Router
│   ├── page.tsx                 # Main dashboard (client component)
│   ├── layout.tsx               # Root layout with tactical theme
│   ├── globals.css              # Tailwind v4 + wv-* design tokens
│   └── api/                     # API routes (serverless functions)
│       ├── flights/             # Global flight data (FR24 / OpenSky)
│       ├── flights/live/        # Regional high-frequency (adsb.fi)
│       ├── satellites/          # TLE fetch + SGP4 propagation
│       ├── ships/               # AISStream.io burst cache
│       ├── traffic/roads/       # OpenStreetMap road network
│       ├── cctv/                # Camera feed aggregation
│       ├── cctv/image/          # CORS-bypassing image proxy
│       ├── geolocation/         # IP geolocation fallback
│       └── health/              # uptime/status probe
├── src/
│   ├── globe/                   # Cesium viewer components
│   │   ├── GlobeViewer.tsx      # <Viewer> root + ShaderManager
│   │   └── EntityClickHandler.tsx  # drillPick → entity classification
│   ├── layers/                  # Data layer renderers (inside <Viewer>)
│   │   ├── FlightLayer.tsx      # BillboardCollection + PolylineCollection
│   │   ├── SatelliteLayer.tsx   # React <Entity> per satellite
│   │   ├── EarthquakeLayer.tsx  # Declarative <Entity> + memo()
│   │   ├── ShipLayer.tsx        # BillboardCollection (AIS vessels)
│   │   ├── TrafficLayer.tsx     # PolylineCollection + PointPrimitiveCollection
│   │   └── CCTVLayer.tsx        # BillboardCollection (camera icons)
│   ├── hooks/                   # Data-fetching hooks
│   │   ├── useFlights.ts        # Global aircraft (20 s poll)
│   │   ├── useFlightsLive.ts    # Regional aircraft (5 s poll)
│   │   ├── useSatellites.ts     # TLE propagation via satellite.js
│   │   ├── useEarthquakes.ts    # USGS direct fetch (60 s poll)
│   │   ├── useShips.ts          # AIS vessels (30 s poll)
│   │   ├── useTraffic.ts        # Road network + animated vehicles
│   │   ├── useCameras.ts        # CCTV feeds (5 min poll)
│   │   ├── useGeolocation.ts    # Browser GPS → IP fallback
│   │   ├── useAudio.ts          # Tactical audio singleton
│   │   └── useIsMobile.ts       # matchMedia breakpoint (768 px)
│   ├── lib/
│   │   └── audio.ts             # Web Audio API singleton
│   ├── data/
│   │   └── airports.ts          # Airport coordinate database
│   ├── shaders/
│   │   └── postprocess.ts       # GLSL strings for CRT / NVG / FLIR
│   ├── types/
│   │   └── camera.ts            # CameraFeed, CameraApiResponse types
│   └── ui/                      # HUD overlay components
│       ├── OperationsPanel.tsx  # Layer toggles, shader picker
│       ├── IntelFeed.tsx        # Scrolling event log
│       ├── StatusBar.tsx        # UTC clock, camera position
│       ├── TrackedEntityPanel.tsx  # Entity details when tracking
│       ├── CCTVPanel.tsx        # Camera thumbnails
│       ├── SplashScreen.tsx     # Boot sequence + audio cues
│       ├── MobileModal.tsx      # Full-screen modal (mobile)
│       ├── AudioToggle.tsx      # Mute/unmute button
│       ├── Crosshair.tsx        # Centre reticle overlay
│       └── FilmGrain.tsx        # Canvas-based analogue noise
├── .env.local.example           # Environment variable template
├── next.config.ts               # Next.js configuration
├── postcss.config.mjs           # Tailwind v4 PostCSS plugin
└── tsconfig.json                # TypeScript configuration

🎮 Features in Detail

🎯 Entity Tracking

Click any object on the globe to lock the camera and follow its movement:

Entity	Camera Distance	View
Aircraft	50 km	Trailing, heading-aligned
Satellites	200 km	Orbital perspective
Ships	20 km	Low-angle tracking
Earthquakes	100 km	Overhead
CCTV cameras	2 km	Street-level

Press ESC to release tracking.

🔭 Visual Modes

Cycle through post-processing effects for different analytical perspectives:

Mode	Visual Effect	Best For
Standard	Clean, unprocessed view	General observation
CRT	Scanlines, chromatic aberration	Retro tactical aesthetic
Night Vision	Green phosphor, noise grain	Low-light scenarios
FLIR	Thermal palette, edge detection	Heat signature analysis

🌐 Map Layers

Google 3D Tiles – Photorealistic buildings and terrain (requires API key)
OpenStreetMap – Fallback 2D imagery (always available, no key needed)

📡 API Routes

Endpoint	Method	Cache	Description
`/api/flights`	GET	30 s	Global commercial aircraft
`/api/flights/live?lat&lon&dist`	GET	4 s	Regional high-frequency flights
`/api/satellites`	GET	2 h	TLE data for all tracked satellites
`/api/ships?moving=1`	GET	60 s	Maritime vessel positions
`/api/traffic/roads?south&west&north&east`	GET	24 h	Road network geometry
`/api/cctv?country`	GET	5 m	Camera feed locations
`/api/cctv/image?url`	GET	60 s	CORS-bypassing image proxy
`/api/geolocation`	GET	—	IP geolocation fallback
`/api/health`	GET	—	Server status and uptime

🚢 Deployment to Vercel

One-Click Deploy

Push your code to a GitHub repository
Visit Vercel — New Project
Import your worldview-ui repository
Configure environment variables (copy from .env.local)
Click Deploy

Custom Domain

After deployment:

Go to your project dashboard on Vercel
Navigate to Settings → Domains
Add worldviewos.shez.app and follow the DNS configuration instructions

Vercel will automatically provision SSL certificates.

Environment Variables on Vercel

NEXT_PUBLIC_* variables are embedded at build time
Server-side variables are available to API routes at runtime

🧪 Performance Optimisations

WorldView-UI handles thousands of moving entities through several techniques:

Rendering

Imperative Cesium primitives – BillboardCollection, PolylineCollection instead of React <Entity> components for large datasets
Viewport culling – Entities outside the camera view aren't rendered
Instance sharing – Similar entities share geometry

Data

Dead reckoning – Positions extrapolated between updates at 60 fps
Smart polling – Frequencies adjusted based on zoom level and entity type
Aggressive caching – API routes cache responses to reduce upstream calls

React

Client-driven UI shell – app/page.tsx is a client component; Cesium loads via dynamic import ({ ssr: false })
Memoisation – useMemo and useCallback prevent unnecessary re-renders
Dynamic imports – Cesium loads only when needed ({ ssr: false })

🤝 Contributing

Contributions are welcome! Areas where help is most valuable:

New data layers – Weather, wildfires, power grids, ADS-B military
Additional CCTV sources – More cities and better global coverage
Shader effects – New visual post-processing modes
Performance improvements – Optimise rendering algorithms
Documentation – Tutorials, API references, video walkthroughs

📜 Credits & Acknowledgements

Original Inspiration

This project builds upon concepts from kevtoe/worldview, adapted and extended for the Next.js ecosystem.

Data Providers

Flight tracking: FlightRadar24, adsb.fi, OpenSky Network
Satellite orbits: CelesTrak
Earthquakes: USGS
Maritime: AISStream.io
Road networks: OpenStreetMap contributors
CCTV feeds: Transport for London, City of Austin, Transport for NSW

Technologies

CesiumJS – 3D globe rendering
Resium – React bindings for Cesium
Next.js – React framework
Tailwind CSS – Styling
satellite.js – SGP4 orbit propagation

🔒 Security Notice

No API keys are included in this repository.

All credentials must be provided via environment variables. The repository includes .env.local.example as a template only.

Before committing, verify:

.env* files are listed in .gitignore
No hardcoded API keys exist in source files
Google API key is restricted by HTTP referrer
Budget alerts are set in Google Cloud Console

If you discover a security issue, please open a private vulnerability report via GitHub.

FilesExpand file tree

README.md

Latest commit

History