Traduction en cours
Cette page est automatiquement reflétée depuis l'original en anglais jusqu'à ce qu'une traduction française arrive. Le contenu est en anglais — la navigation et l'interface sont déjà traduites.
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 AISstream.io via backend/routes/vessels.py. AIS ingest is off by default and must be enabled. 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.
Map controls (bottom-left pill bar)
A single horizontal pill bar at the bottom-left of the globe:
| Pill | What it does |
|---|---|
| Map | Flat raster basemap |
| Satellite | High-resolution satellite imagery |
| 3D | Tilt + Cesium World Terrain + OSM Buildings (Pro feature) |
| ⌃ Layers | Opens the layer popover — aircraft / vessel / news / capital |
- 3D is enabled only in Satellite mode, and gated behind the
globe_premiumsubscription feature. Free accounts see a gold lock icon and a click redirects to/pricing. - Layers popover toggles each data layer independently. Off-state dims the colour swatch and hides pins.
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.
Live data reaches the browser via periodic REST polling (roughly every 30 seconds); there is no client-side WebSocket stream. Pins refresh on each poll rather than tick-by-tick.
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)OPENSKY_USERNAME/OPENSKY_PASSWORD(optional, raises ADS-B rate limit)AIRCRAFT_FIXTURE_FALLBACK— defaults toTrue, so when the aircraft table is empty the API serves 6 unlabeled demo planes (callsignsATLS101–ATLS606). Set it tofalsein production so live deployments never ship fixtures.
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.