Appearance
3D Globe
The Atlas globe is the primary OSINT surface — a single Cesium 3D world that overlays vessels (AIS), aircraft (ADS-B), news, and event pins, all driven by live data from the Atlas backend. Implemented in frontend/src/components/OsintGlobe.jsx.
Layers
The globe ships with four layers, each independently toggleable from the right sidebar:
- AIS (vessels) — live and recent vessel positions sourced from MarineTraffic via backend/routes/vessels.py. Vessel pins show name, MMSI, speed, and heading.
- ADS-B (aircraft) — live aircraft positions from OpenSky via backend/routes/aircraft.py. Aircraft pins show callsign, altitude, and ground speed.
- News pins — geolocated breaking news pinned by latitude/longitude (see backend/routes/news.py).
- Capitals & events — country capitals and timeline events pulled from backend/routes/events.py.
Sub-bar controls
The header sub-bar (see subbar.* keys in frontend/src/i18n/en.json) drives layer-specific filters in real time:
| Control | Layer | What it filters |
|---|---|---|
| All aircraft / saved | ADS-B | All live tracks vs. only your saved subset |
| All vessels / saved | AIS | All live tracks vs. only your saved subset |
| Callsign | ADS-B | Substring match on callsign |
| Name / MMSI | AIS | Substring match on vessel name or MMSI |
| Min/max altitude (m) | ADS-B | Altitude band |
| Min/max speed (kts) | AIS, ADS-B | Speed band |
Filter state is local to the session — saved subsets persist server-side via your account.
Live tracking
Click any pin to focus the camera and pin the detail card to the right rail. The card shows identification, live telemetry, route history (where available), last update timestamp, and a Generate intel action that hands the focused entity off to AI chat for plain-language analysis. Status badges (live, delayed, unconfirmed) reflect data freshness from the upstream provider.
Required env
The globe needs Cesium Ion tokens on both the backend and the frontend (the latter is bundled into the client at build time and is therefore public — never use a backend-only token here):
CESIUM_ION_TOKEN(backend, server-side rendering of tile URLs)VITE_CESIUM_ION_TOKEN(frontend, public Cesium Ion access)
See Quick Start for the full env list and Data delays & limits for AIS/ADS-B coverage gaps.
Tips
- The globe and the Watchlist are not directly linked — saving a vessel/aircraft from the globe creates an OSINT subset, not a market watchlist entry.
- Use Timeline & events to scrub historical positions; the globe alone is live-only.
- For large pin counts, the renderer clusters automatically — zoom in to disambiguate.
- Pin colors encode status freshness, not vessel type — green is fresh telemetry, amber is stale, gray is silent.
- Click-and-drag pans; right-click-and-drag tilts; scroll zooms. Use the
Homekey to reset the camera to a neutral world view.
Performance
The globe is the most GPU-intensive surface in Atlas. Expect:
- Smooth (60 FPS) on a discrete GPU rendering up to ~5,000 simultaneous pins after clustering.
- Workable (~30 FPS) on integrated graphics with the same load.
- Choppy when both AIS and ADS-B layers are zoomed out globally with no clustering — the renderer falls back to point-rendering instead of billboard sprites.
If you hit the choppy regime, drop one layer or zoom in. The performance budget is per-frame, not global, so a regional view of 2,000 pins is much faster than a global view of 200.
Common pitfalls
| Symptom | Likely cause | Fix |
|---|---|---|
| Globe blank, console "Cesium token invalid" | VITE_CESIUM_ION_TOKEN missing from build | Set the env, rebuild, redeploy |
| Globe loads but no pins | Provider key missing or layer toggle off | API keys; press v/a |
| Pins flicker on every refresh | Aggressive cache disabled in DevTools | Close DevTools or disable "Disable cache while DevTools open" |
| Camera won't move | Stuck in "follow target" mode after a click | Press Esc or click an empty area |
| Globe is rotated upside-down | Cesium camera-state corruption (rare) | Home key to reset, or hard-reload |
Anatomy of a detail card
When a pin is focused, the right rail shows:
┌───────────────────────────────┐
│ ⛴ MS WATCHFUL │ ← Identification
│ MMSI 123456789, FLAG NL │
├───────────────────────────────┤
│ ▸ Live telemetry │ ← Live position
│ Lat 51.94, Lon 4.13 │
│ Speed 12.3 kts, Heading 271° │
│ Last update 02:14 UTC ▮ live │
├───────────────────────────────┤
│ ▸ Route │ ← Recent track (if available)
│ ▸ AI summary [Generate intel] │ ← One-click AI chat handoff
│ ▸ Actions │
│ ☆ Save to subset │
│ 🔔 Alert on event │
│ 🔗 Share permalink │
└───────────────────────────────┘detail.* keys in frontend/src/i18n/en.json name each section.