Add Leaflet velocity wave visualizer: FastAPI+Gradio app, NOAA WW3 puller, endpoints, Dockerfile, requirements

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+# System deps for cfgrib/eccodes
+RUN apt-get update && \
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+      libeccodes0 libeccodes-data libeccodes-dev \
+      libopenjp2-7 libnetcdf19 ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+ENV PIP_NO_CACHE_DIR=1 \
+    PYTHONUNBUFFERED=1 \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860
+
+WORKDIR /app
+COPY requirements.txt ./
+RUN pip install -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+

app.py

@@ -0,0 +1,236 @@
+import os
+import json
+from datetime import datetime
+from functools import lru_cache
+from typing import Dict, Any, List
+
+import numpy as np
+from fastapi import FastAPI, Query
+from fastapi.responses import JSONResponse, HTMLResponse
+import gradio as gr
+
+# Local import: vendored from working project
+from backend.grib_wave_puller import GRIBWavePuller
+
+
+app = FastAPI(title="Wave Visualizer API")
+
+
+def _compute_uv_from_wave(height: np.ndarray, direction_deg: np.ndarray, scale: float = 0.1):
+    """Compute U/V components from wave height and meteorological 'from' direction.
+
+    - height: significant wave height array (m)
+    - direction_deg: wave direction (deg, meteorological, coming from)
+    - scale: visualization scaling factor
+    """
+    dir_rad = np.deg2rad(direction_deg)
+    mag = np.clip(height, 0, np.nanmax(height)) * scale
+    # Eastward (u) and northward (v) components; negative on v because 'from'
+    u = mag * np.sin(dir_rad)
+    v = -mag * np.cos(dir_rad)
+    return u, v
+
+
+def _build_velocity_grib_json(lats: np.ndarray, lons: np.ndarray, u: np.ndarray, v: np.ndarray, ref_time: str) -> List[Dict[str, Any]]:
+    """Build leaflet-velocity compatible JSON (Wind/Earth GRIB-like format).
+
+    Data must be provided on a regular lat-lon grid. Arrays are 2D with shape (ny, nx)
+    where ny=len(lats), nx=len(lons). Latitude should be provided in descending order
+    (north to south) to match common GRIB conventions; reorder if needed.
+    """
+    # Ensure 1D coordinate arrays
+    lats_1d = lats if lats.ndim == 1 else lats[:, 0]
+    lons_1d = lons if lons.ndim == 1 else lons[0, :]
+
+    ny = int(len(lats_1d))
+    nx = int(len(lons_1d))
+
+    # If latitude increases northward, reverse to north->south
+    if ny > 1 and lats_1d[0] < lats_1d[-1]:
+        lats_1d = lats_1d[::-1]
+        u = np.flipud(u)
+        v = np.flipud(v)
+
+    la1 = float(lats_1d[0])
+    la2 = float(lats_1d[-1])
+    lo1 = float(lons_1d[0])
+    lo2 = float(lons_1d[-1])
+
+    # Grid spacing (approx)
+    dy = float(abs(lats_1d[1] - lats_1d[0])) if ny > 1 else 0
+    dx = float(abs(lons_1d[1] - lons_1d[0])) if nx > 1 else 0
+
+    # Flatten row-major (lat-major first, then lon) matching header
+    u_data = np.asarray(u, dtype=float).flatten().tolist()
+    v_data = np.asarray(v, dtype=float).flatten().tolist()
+
+    header_common = {
+        "lo1": lo1,
+        "la1": la1,
+        "lo2": lo2,
+        "la2": la2,
+        "nx": nx,
+        "ny": ny,
+        "dx": dx,
+        "dy": dy,
+        "refTime": ref_time,
+    }
+
+    u_record = {
+        "header": {
+            **header_common,
+            "parameterCategory": 2,
+            "parameterNumber": 2,  # U component
+            "parameterUnit": "m/s",
+        },
+        "data": u_data,
+    }
+
+    v_record = {
+        "header": {
+            **header_common,
+            "parameterCategory": 2,
+            "parameterNumber": 3,  # V component
+            "parameterUnit": "m/s",
+        },
+        "data": v_data,
+    }
+
+    return [u_record, v_record]
+
+
+@lru_cache(maxsize=16)
+def get_puller() -> GRIBWavePuller:
+    return GRIBWavePuller()
+
+
+@app.get("/data/points")
+def data_points(hour: int = Query(0, ge=0, le=240)):
+    puller = get_puller()
+    data = puller.fetch_global_wave_data(hour)
+    if not data:
+        return JSONResponse(status_code=503, content={"error": "No data available"})
+    return JSONResponse(content=data)
+
+
+@app.get("/data/velocity")
+def data_velocity(hour: int = Query(0, ge=0, le=240), scale: float = Query(0.1)):
+    puller = get_puller()
+    result = puller.fetch_global_wave_data(hour)
+    if not result:
+        return JSONResponse(status_code=503, content={"error": "No data available"})
+
+    # If we have a downsampled UV grid, return leaflet-velocity JSON
+    grid_uv = result.get("grid_uv")
+    if grid_uv:
+        lats = np.array(grid_uv['lats'])
+        lons = np.array(grid_uv['lons'])
+        u = np.array(grid_uv['u'])
+        v = np.array(grid_uv['v'])
+        payload = _build_velocity_grib_json(lats, lons, u, v, ref_time=result.get("timestamp", datetime.utcnow().isoformat()))
+        return JSONResponse(content=payload)
+
+    # Fallback to points if no grid is present
+    sample_points = result.get("sample_points", [])
+    return JSONResponse(content={"type": "points", "refTime": result.get("timestamp"), "points": sample_points})
+
+
+def leaflet_html() -> str:
+    return f"""
+<!doctype html>
+<html>
+  <head>
+    <meta charset=\"utf-8\" />
+    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />
+    <link rel=\"stylesheet\" href=\"https://unpkg.com/leaflet@1.9.4/dist/leaflet.css\" />
+    <style>
+      html, body, #map {{ height: 100%; margin: 0; }}
+      .leaflet-control-container .leaflet-top.leaflet-left {{ z-index: 1000; }}
+      .control {{ position:absolute; top:10px; left:10px; background:#fff; padding:8px; border-radius:4px; box-shadow:0 1px 3px rgba(0,0,0,0.3); }}
+    </style>
+  </head>
+  <body>
+    <div id=\"map\"></div>
+    <div class=\"control\">
+      <label>Forecast hour: <input type=\"number\" id=\"hour\" min=\"0\" max=\"240\" step=\"6\" value=\"0\" /></label>
+      <button id=\"load\">Load Waves</button>
+    </div>
+    <script src=\"https://unpkg.com/leaflet@1.9.4/dist/leaflet.js\"></script>
+    <script src=\"https://unpkg.com/leaflet-velocity/dist/leaflet-velocity.min.js\"></script>
+    <script>
+      const map = L.map('map').setView([20, 0], 2);
+      L.tileLayer('https://{{s}}.tile.openstreetmap.org/{{z}}/{{x}}/{{y}}.png', {{
+        maxZoom: 6,
+        attribution: '&copy; OpenStreetMap contributors'
+      }}).addTo(map);
+
+      let velocityLayer = null;
+      let pointLayer = null;
+
+      async function load(hour) {{
+        if (velocityLayer) {{ map.removeLayer(velocityLayer); velocityLayer = null; }}
+        if (pointLayer) {{ map.removeLayer(pointLayer); pointLayer = null; }}
+
+        const res = await fetch(`/data/velocity?hour=${{hour}}`);
+        if (!res.ok) {{ alert('Failed to fetch data'); return; }}
+        const payload = await res.json();
+
+        if (payload.type === 'points') {{
+          // Fallback: draw particle-like markers with direction
+          const features = payload.points.map(p => {{
+            const dir = p.wave_direction ?? 0;
+            const len = (p.wave_height ?? 0.5) * 50000; // scale for arrow length
+            const rad = dir * Math.PI/180.0;
+            const dx = Math.sin(rad) * len;
+            const dy = -Math.cos(rad) * len;
+            return L.polyline([[p.lat, p.lon], [p.lat + dy/1e6, p.lon + dx/1e6]], {{ color: '#0aa', weight: 1, opacity: 0.8 }});
+          });
+          pointLayer = L.layerGroup(features).addTo(map);
+        }} else {{
+          try {{
+            // Expected: array of two GRIB-like records (u and v)
+            velocityLayer = L.velocityLayer({{
+              displayValues: true,
+              displayOptions: {{ velocityType: 'Wave', position: 'bottomleft', emptyString: 'No wave data' }},
+              data: payload,
+              maxVelocity: 5,
+              velocityScale: 0.02,
+              particleAge: 60,
+              particleMultiplier: 0.01
+            }});
+            velocityLayer.addTo(map);
+          }} catch (e) {{
+            console.warn('Velocity layer failed, falling back to points:', e);
+            const res2 = await fetch(`/data/points?hour=${{hour}}`);
+            const payload2 = await res2.json();
+            const features = payload2.points.map(p => {{
+              const dir = p.wave_direction ?? 0;
+              const len = (p.wave_height ?? 0.5) * 50000;
+              const rad = dir * Math.PI/180.0;
+              const dx = Math.sin(rad) * len;
+              const dy = -Math.cos(rad) * len;
+              return L.polyline([[p.lat, p.lon], [p.lat + dy/1e6, p.lon + dx/1e6]], {{ color: '#0aa', weight: 1, opacity: 0.8 }});
+            }});
+            pointLayer = L.layerGroup(features).addTo(map);
+          }}
+        }}
+      }}
+
+      document.getElementById('load').onclick = () => {{
+        const h = parseInt(document.getElementById('hour').value || '0', 10);
+        load(h);
+      }};
+    </script>
+  </body>
+  </html>
+    """
+
+
+with gr.Blocks(title="Wave Visualizer") as demo:
+    gr.HTML(leaflet_html())
+
+
+# Mount Gradio UI on root path
+from gradio.routes import mount_gradio_app
+
+app = mount_gradio_app(app, demo, path="/")

backend/__init__.py

@@ -0,0 +1,2 @@
+"""Backend package for wave visualizer."""
+

backend/grib_wave_puller.py

@@ -0,0 +1,270 @@
+"""
+Vendored GRIBWavePuller from NWPS_SWAN project (trimmed only for runtime import here).
+If Arctic-specific helpers are missing, the puller will log and continue with fallbacks.
+"""
+
+import os
+import sys
+import tempfile
+import logging
+import subprocess
+from datetime import datetime, timedelta
+import numpy as np
+import xarray as xr
+from ecmwf.opendata import Client
+import requests
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Optional Arctic handler
+try:
+    from arctic_grib_handler import ArcticGRIBHandler  # type: ignore
+    ARCTIC_HANDLER_AVAILABLE = True
+    logger.info("✅ Arctic GRIB Handler loaded (Docker production version)")
+except Exception as e:
+    logger.warning(f"Arctic GRIB handler not available: {e}")
+    ARCTIC_HANDLER_AVAILABLE = False
+
+
+class GRIBWavePuller:
+    def __init__(self):
+        self.client = Client("ecmwf")
+        self.output_dir = os.getenv('OUTPUT_DIR', '/tmp/wave_data')
+        os.makedirs(self.output_dir, exist_ok=True)
+        self._setup_eccodes_environment()
+
+    def _setup_eccodes_environment(self):
+        try:
+            os.environ['ECCODES_GRIB_STRICT_PARSING'] = '0'
+            os.environ['ECCODES_GRIB_IGNORE_GRID_DEFINITION'] = '1'
+        except Exception:
+            pass
+
+    def fetch_ecmwf_wave_grib(self, forecast_time=0):
+        try:
+            temp_file = tempfile.NamedTemporaryFile(delete=False, suffix='.grib2')
+            try:
+                self.client.retrieve(
+                    type="fc",
+                    param=["swh"],
+                    time=0,
+                    step=forecast_time,
+                    target=temp_file.name,
+                )
+                return temp_file.name
+            except Exception:
+                if os.path.exists(temp_file.name):
+                    os.unlink(temp_file.name)
+                return None
+        except Exception:
+            return None
+
+    def fetch_noaa_wave_grib(self, forecast_hour=0):
+        """Fetch NOAA WW3 files (regional + global attempt). Returns list of (path, region, run, fh)."""
+        try:
+            base_url = "https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod"
+            now = datetime.utcnow()
+            dates_to_try = [
+                now.strftime("%Y%m%d"),
+                (now - timedelta(days=1)).strftime("%Y%m%d"),
+                (now - timedelta(days=2)).strftime("%Y%m%d"),
+            ]
+            if now.hour >= 18:
+                preferred_runs = ["18", "12", "06", "00"]
+            elif now.hour >= 12:
+                preferred_runs = ["12", "06", "00", "18"]
+            elif now.hour >= 6:
+                preferred_runs = ["06", "00", "18", "12"]
+            else:
+                preferred_runs = ["00", "18", "12", "06"]
+
+            for date_str in dates_to_try:
+                for hour in preferred_runs:
+                    successful = []
+                    regional_files = [
+                        (f"gfswave.t{hour}z.atlocn.0p16.f{forecast_hour:03d}.grib2", "Atlantic"),
+                        (f"gfswave.t{hour}z.epacif.0p16.f{forecast_hour:03d}.grib2", "East_Pacific"),
+                        (f"gfswave.t{hour}z.arctic.9km.f{forecast_hour:03d}.grib2", "Arctic"),
+                        (f"gfswave.t{hour}z.global.0p16.f{forecast_hour:03d}.grib2", "Global"),
+                    ]
+                    for filename, region_name in regional_files:
+                        url = f"{base_url}/gfs.{date_str}/{hour}/wave/gridded/{filename}"
+                        try:
+                            tf = tempfile.NamedTemporaryFile(delete=False, suffix='.grib2')
+                            r = requests.get(url, timeout=300)
+                            if r.status_code == 200:
+                                tf.write(r.content)
+                                tf.close()
+                                successful.append((tf.name, region_name, hour, forecast_hour))
+                            else:
+                                tf.close(); os.unlink(tf.name)
+                        except Exception:
+                            try:
+                                tf.close(); os.unlink(tf.name)
+                            except Exception:
+                                pass
+                            continue
+                    if successful:
+                        return successful
+            return None
+        except Exception:
+            return None
+
+    def process_grib_file(self, grib_file_path, region_name=None):
+        try:
+            ds = xr.open_dataset(grib_file_path, engine='cfgrib', decode_timedelta=True)
+        except Exception:
+            return None, None
+
+        # Identify variables
+        vars_map = {name: ds[name] for name in ds.variables}
+        wave_var = None
+        for cand in ['swh', 'HTSGW', 'htsgw']:
+            if cand in vars_map:
+                wave_var = cand; break
+        if wave_var is None:
+            # fallback heuristic
+            for n in vars_map:
+                if 'wave' in n.lower() and 'height' in n.lower():
+                    wave_var = n; break
+        if wave_var is None:
+            ds.close()
+            return None, None
+
+        wave_heights = vars_map[wave_var].values
+
+        wave_dir = None
+        for cand in ['dirpw', 'DIRPW', 'dp', 'wvdir', 'WVDIR', 'dir']:
+            if cand in vars_map:
+                wave_dir = vars_map[cand].values; break
+
+        wave_per = None
+        for cand in ['perpw', 'PERPW', 'tp', 'wvper', 'WVPER', 'per']:
+            if cand in vars_map:
+                wave_per = vars_map[cand].values; break
+
+        lats = ds.latitude.values if 'latitude' in ds else ds.lat.values
+        lons = ds.longitude.values if 'longitude' in ds else ds.lon.values
+
+        # Sample points (downsample for visualization)
+        lon_grid, lat_grid = np.meshgrid(lons, lats)
+        flat_lats = lat_grid.flatten()
+        flat_lons = lon_grid.flatten()
+        flat_waves = wave_heights.flatten()
+        mask = ~np.isnan(flat_waves)
+        if wave_dir is not None:
+            mask &= ~np.isnan(wave_dir.flatten())
+        idx = np.random.choice(np.where(mask)[0], size=min(1000, mask.sum()), replace=False) if mask.any() else np.array([])
+
+        points = []
+        for i in idx:
+            point = {
+                'lat': float(flat_lats[i]),
+                'lon': float(flat_lons[i]),
+                'wave_height': float(flat_waves[i]),
+            }
+            if wave_dir is not None:
+                d = float(wave_dir.flatten()[i])
+                point['wave_direction'] = d
+                mag = point['wave_height'] * 0.1
+                rad = np.deg2rad(d)
+                point['u_component'] = float(mag * np.sin(rad))
+                point['v_component'] = float(-mag * np.cos(rad))
+            if wave_per is not None:
+                point['wave_period'] = float(wave_per.flatten()[i])
+            points.append(point)
+
+        data = {
+            'timestamp': datetime.utcnow().isoformat(),
+            'data_source': 'NOAA_GRIB' if 'gfswave' in os.path.basename(grib_file_path) else 'GRIB',
+            'parameters_found': {
+                'wave_height': wave_var,
+                'wave_direction': 'present' if wave_dir is not None else None,
+                'wave_period': 'present' if wave_per is not None else None,
+                'has_velocity_components': wave_dir is not None,
+            },
+            'grid_info': {
+                'lat_min': float(np.nanmin(lats)),
+                'lat_max': float(np.nanmax(lats)),
+                'lon_min': float(np.nanmin(lons)),
+                'lon_max': float(np.nanmax(lons)),
+                'grid_shape': list(wave_heights.shape),
+            },
+            'sample_points': points,
+        }
+        # Optional: include a downsampled U/V grid for velocity layers
+        try:
+            if wave_dir is not None:
+                # Compute U/V on the native grid
+                # Determine reasonable downsample strides to keep <= ~360x180
+                ny, nx = wave_heights.shape
+                sy = max(1, ny // 180)
+                sx = max(1, nx // 360)
+                lats_ds = lats[::sy]
+                lons_ds = lons[::sx]
+                # Align 2D arrays for downsample
+                wh_ds = wave_heights[::sy, ::sx]
+                wd_ds = wave_dir[::sy, ::sx]
+                # Compute U/V (scale ~0.1 for visualization)
+                dir_rad = np.deg2rad(wd_ds)
+                mag = np.clip(wh_ds, 0, np.nanmax(wh_ds)) * 0.1
+                u_ds = mag * np.sin(dir_rad)
+                v_ds = -mag * np.cos(dir_rad)
+                data['grid_uv'] = {
+                    'lats': lats_ds.tolist() if hasattr(lats_ds, 'tolist') else list(map(float, lats_ds)),
+                    'lons': lons_ds.tolist() if hasattr(lons_ds, 'tolist') else list(map(float, lons_ds)),
+                    'u': u_ds.tolist(),
+                    'v': v_ds.tolist(),
+                }
+        except Exception:
+            # If any step fails, just skip embedding grid_uv
+            pass
+        ds.close()
+        return data, grib_file_path
+
+    def process_multiple_regional_files(self, regional_files):
+        combined = []
+        for path, region_name, *_ in regional_files:
+            try:
+                res, _ = self.process_grib_file(path, region_name=region_name)
+                if res and 'sample_points' in res:
+                    combined.extend(res['sample_points'])
+            finally:
+                try:
+                    if os.path.exists(path):
+                        os.unlink(path)
+                except Exception:
+                    pass
+        if not combined:
+            return None
+        return {
+            'timestamp': datetime.utcnow().isoformat(),
+            'data_source': 'NOAA_MULTI_REGIONAL_GRIB',
+            'parameters_found': {'has_velocity_components': True},
+            'grid_info': {},
+            'sample_points': combined,
+        }
+
+    def fetch_global_wave_data(self, forecast_hour=0):
+        result = self.fetch_noaa_wave_grib(forecast_hour)
+        if isinstance(result, list) and result:
+            if any(region == 'Global' for _, region, *_ in result):
+                # Prefer the global grid if present
+                global_entry = next((t for t in result if t[1] == 'Global'), None)
+                if global_entry:
+                    data, _ = self.process_grib_file(global_entry[0], region_name='Global')
+                    return data
+            # Otherwise combine sample points from regions
+            return self.process_multiple_regional_files(result)
+
+        # Fallback ECMWF (may not include waves)
+        grib_file = self.fetch_ecmwf_wave_grib(forecast_hour)
+        if grib_file:
+            data, _ = self.process_grib_file(grib_file)
+            try:
+                os.unlink(grib_file)
+            except Exception:
+                pass
+            return data
+        return None

requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.111.0
+gradio==4.44.0
+uvicorn[standard]==0.30.6
+numpy==1.26.4
+xarray==2024.2.0
+cfgrib==0.9.14.1
+eccodes==1.6.1
+requests==2.32.3
+ecmwf-opendata==0.3.3