Super El Niño — 3D Globe Visualization
An interactive 3D WebGL climatological simulation visualizing the El Niño–Southern Oscillation (ENSO) cycle and Super El Niño extremes. Built with Angular 21, Three.js, and modern SCSS design tokens.
🔗 Explore Live Demo: https://kmd-labs.github.io/el-nino/
🌍 Key Features
-
Interactive 3D WebGL Globe:
- Real-time procedural Sea Surface Temperature (SST) data texture (720×360 grid, 259,200 points) dynamically computed using scientific basis functions and color LUTs.
- Natural Earth continent vector overlays (
world-atlas GeoJSON) with offline local asset fallback.
- Precise delineation of the official Niño 3.4 monitoring box (170°W–120°W, 5°S–5°N).
- Atmospheric rim glow shader with additive blending and starfield point cloud.
- Smooth OrbitControls with momentum damping and toggleable auto-rotation.
-
Walker Circulation & Thermocline (merged view):
- Dual-cell tropospheric stream particle simulation with altitude-dependent thermodynamic coloring (warm rising air vs. cool subsiding air).
- Procedural convective storm cloud puffs clustered around the shifting Pacific warm pool.
- Dynamic rainfall streaks beneath the convective center.
- Real-time equatorial ocean depth profile (0–300 m) from Indonesia (120°E) to South America (80°W), with the 20 °C isotherm / thermocline tilt coupled to trade-wind strength.
-
Live data & splash experience:
- Initial splash loader waits for the SST timeline, Open-Meteo snapshot and land topology, then starts the cycle.
- Daily GitHub Action extends the NOAA OISST backfill and refreshes air temperature, wind and waves.
- Dock shows the selected date's Niño 3.4 sea-surface temperature plus live tropical air temperature and wind speed.
-
Historical Impacts Database:
- 23 global pin locations with 30+ peer-documented climate events across South America, North America, Africa, Asia, and Oceania.
- Interactive 3D billboard sprites with screen-space occlusion and raycast picking.
- Detailed modal cards highlighting human and economic tolls (GDP loss, casualties, agricultural failure) with links to international institutions (UN OCHA, World Bank, CDC, FAO, NOAA).
-
Simulation & Time Controls:
- One-click presets: La Niña (-1.6), Neutral (0.0), El Niño (+1.2), and Super El Niño (+2.6).
- Continuous ENSO strength slider (-2.00 to +3.00).
- 4-year idealized ENSO cycle simulation with animated monthly progression.
🏗️ Architecture & Component Design
The codebase follows modern Angular standalone component architecture with reactive state management powered by Angular Signals:
src/
├── _variables.scss # Reusable SCSS design system tokens (colors, radii, mixins, glass panels)
├── styles.scss # Global resets and typography
├── index.html # HTML entry point configured for GitHub Pages
├── main.ts # Application bootstrap
├── app/
│ ├── app.component.ts|html|scss# Root application shell
│ ├── core/
│ │ ├── constants/
│ │ │ └── enso-data.ts # Scientific data constants, color LUTs, and historical event records
│ │ ├── models/
│ │ │ └── enso.model.ts # TypeScript interfaces and domain types
│ │ └── services/
│ │ ├── enso-math.service.ts # Pure math model (climatology, anomalies, thermocline, 3D math)
│ │ └── enso-state.service.ts# Centralized reactive state using Angular Signals
│ └── components/
│ ├── globe/ # Three.js 3D viewport, particles, labels, and raycasting
│ ├── header/ # Brand logotype, language selector and view switcher
│ ├── map-dock/ # Floating glassmorphic control dock, date pill and legends
│ ├── walker-view/ # Walker circulation + thermocline cross-section
│ ├── splash/ # Host timing for the shared design-system loader
│ ├── impact-modal/ # Event detail dialog with external research links
│ └── glossary/ # Searchable glossary popup
└── assets/
└── data/
├── land-50m.json # Bundled Natural Earth land topology
├── timeline-meta.json # Weekly keyframes, live Open-Meteo snapshot
└── timeline-sst.bin.gz # Packed 0.5° weekly SST frames
🎨 Design System & SCSS Tokens
All UI styling is strictly tokenized in src/_variables.scss:
- Maps:
$colors, $breakpoints, $transitions, $radii, $font-weights, $font-sizes.
- Accessor Functions:
color($key), radius($key), font-size($key), font-weight($key), transition($key).
- Mixins:
@mixin glass-panel($heavy): Glassmorphic panel styling with backdrop-filter: blur(...) and glowing border highlights.@mixin respond-to($breakpoint): Mobile-first responsive layout breakpoints.@mixin custom-scrollbar: Sleek, unobtrusive dark-theme scrollbars.
🔬 Scientific Foundations
-
Sea Surface Temperature (SST) Climatology:
$$T_{\text{clim}}(\lambda, \phi) = -1.8 + 30.5 \cos^{2.2}(\phi) + \sum_{k} A_k \exp\left(-\frac{\Delta\lambda_k^2}{w_k^2}\right) \exp\left(-\frac{\phi^2}{\sigma_k^2}\right)$$
Models the Pacific warm pool, equatorial cold tongue, Humboldt Current, and global oceanic features.
-
ENSO Anomaly Formulation:
$$A(\lambda, \phi, s) = \begin{cases} s \cdot \text{basis}_P + \max(0, s - 1.4) \cdot \text{basis}_C & \text{if } s \ge 0 \ -s \cdot \text{basis}_N & \text{if } s < 0 \end{cases}$$
Incorporates the non-linear coastal Peruvian warming characteristic of historic Super El Niño events (1982–83, 1997–98, 2015–16).
-
Thermocline Profile:
Calculates the 20 °C isotherm depth across $120^\circ\text{E} \to 80^\circ\text{W}$ coupled to trade wind strength variations:
$$z(\lambda, s) = -1.75 + 0.85 \cdot \text{trade}(s) \cdot u(\lambda)$$
💻 Local Development
Prerequisites
- Node.js version 20+ (Node 22 LTS recommended)
- npm 10+
Setup & Run
# Clone the repository
git clone https://github.com/kmd-labs/el-nino.git
cd el-nino
# Install dependencies
npm install
# Start local development server (runs on http://localhost:4200/)
npm start
# Production build
npm run build
# Production build with GitHub Pages base-href
npm run build:gh-pages
🚀 Continuous Deployment (GitHub Actions)
Deployments to GitHub Pages are automated via .github/workflows/deploy.yml:
- Trigger: Pushes to
main, scheduled every 3 hours, repository dispatch or manual workflow_dispatch.
- Build Stage: Runs on
ubuntu-latest, refreshes the live Open-Meteo snapshot and NOAA OISST frames, compiles the application with npm run build:gh-pages (--base-href /el-nino/), and uploads static assets via actions/upload-pages-artifact@v3.
- Deploy Stage: Publishes to GitHub Pages with
actions/deploy-pages@v4.
- Clean Workspace: The build directory (
dist/) is gitignored, and build artifacts reside strictly in ephemeral runner environments.
.github/workflows/update-weather.yml runs daily at 05:17 UTC. It extends the weekly NOAA OISST backfill, refreshes the Open-Meteo air-temperature/wind/wave snapshot in src/assets/data/, commits the updated data to main, and dispatches the Pages deployment. The NOAA NetCDF downloads are cached between runs.
