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

1. 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.

2. 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).

3. 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:

1. Trigger: Pushes to main, scheduled every 3 hours, repository dispatch or manual workflow_dispatch.
2. 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.
3. Deploy Stage: Publishes to GitHub Pages with actions/deploy-pages@v4.
4. 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.