forcingkit 0.8.0__tar.gz → 0.9.0__tar.gz

{forcingkit-0.8.0 → forcingkit-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forcingkit
-Version: 0.8.0
+Version: 0.9.0
 Summary: Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
 Project-URL: Documentation, https://forcingkit.docs.lhzn.io
 Project-URL: Issues, https://github.com/lhzn-io/forcingkit/issues
@@ -226,6 +226,7 @@ Requires-Dist: h5py>=3.16.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: jinja2>=3.0.0
 Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: pillow>=10.0
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pydap>=3.5.8
 Requires-Dist: pyproj>=3.7.2

{forcingkit-0.8.0 → forcingkit-0.9.0}/docs/source/conf.py

@@ -9,7 +9,7 @@ sys.path.insert(0, os.path.abspath("../../src"))
 project = "forcingkit"
 copyright = "2026, Long Horizon Observatory"
 author = "Daniel Fry"
-release = "0.8.0"
+release = "0.9.0"
 
 extensions = [
     "sphinx.ext.autodoc",

{forcingkit-0.8.0 → forcingkit-0.9.0}/docs/source/index.rst

@@ -166,5 +166,6 @@ PyPI as ``forcingkit``.
    :maxdepth: 1
    :caption: Reference
 
+   mesh_frames
    sources
    roadmap

forcingkit-0.9.0/docs/source/mesh_frames.rst

@@ -0,0 +1,89 @@
+Mesh frames: native-mesh image frames
+=====================================
+
+``forcingkit.mesh_frames`` reads model output on the model's own unstructured mesh (no
+regridding) and ``forcingkit.render`` draws it as a sequence of PNG frames: one flat colour per
+triangle, with an optional mesh-edge overlay. NECOFS FVCOM GOM7 surface currents are the first
+registered model.
+
+Data contract
+-------------
+
+``MeshFrames`` holds ``times`` (UTC), ``node_lon`` and ``node_lat``, ``tri`` (``n_tri`` x 3,
+zero-based node indices) and ``u``, ``v`` (``[t, n_tri]``, one value per element, NaN where an
+element has no value). Any triangle-mesh model fits it; an adapter is one function registered with
+``@register_adapter("name")`` that takes ``(bbox, times)`` and returns a ``MeshFrames``. The
+``forcingkit.mesh_frames`` module docstring shows the template.
+
+Projection
+----------
+
+Pixels are plain longitude/latitude, defined exactly by the caller's box ``(W, S, E, N)`` and image
+size ``(w, h)``: pixel column ``i`` spans longitudes ``W + [i, i+1) * (E - W) / w`` and row ``j``
+spans latitudes ``N - [j, j+1) * (N - S) / h``. A pixel takes the colour of the element containing
+its centre, so frames drawn with the same box and size line up pixel for pixel with any other
+renderer that uses the same convention. Outside the mesh (and wherever an element is NaN) is
+transparent, or the background colour when one is given.
+
+The mesh is rasterised once per (mesh, box, size) into an element-index image and the edges once
+into an overlay; both are cached, and each frame is a colour lookup per element and per pixel. On a
+synthetic mesh of 52 000 elements, 45 frames at 1600 x 900 render in about 0.6 s plus 0.5 s for the
+index image; writing the PNGs takes about 4.5 s.
+
+Colour
+------
+
+``color`` is any vectorised function from speed (m/s, shape ``(n,)``) to uint8 RGB or RGBA
+(``(n, 3)`` or ``(n, 4)``). Use a fixed scale so a colour means the same speed in every frame:
+
+- ``default_color``: viridis, linear over 0 to 1.5 m/s;
+- ``named_color(name, vmin, vmax, log=False, floor=None)``: a built-in ramp (``viridis``,
+  ``greys``) over a chosen range;
+- ``lut_color(rows, log=False, floor=None)``: a lookup table of ``(value, r, g, b[, a])`` rows.
+  Values below the first row, or below ``floor``, take the first colour; between rows each channel
+  is interpolated linearly in the value, or in log(value) when ``log`` is true; values above the
+  last row take the last colour; NaN is transparent. ``load_lut_csv(path)`` reads such a table
+  from a ``value,r,g,b[,a]`` CSV;
+- ``packaged_color("currents_lis")``: the surface-current table shipped with the package
+  (``forcingkit/ramps/currents_lis.csv``), 0.02 to 3.1 m/s on a log axis, pale blue through
+  yellow to dark green with CIELAB lightness falling monotonically. Its CSV header records the
+  knots and their source;
+- ``packaged_color("currents_lis_dark")``: its twin for a dark basemap, on the same speeds, from
+  midnight blue through steel blue to pale seafoam with lightness rising monotonically, so the
+  two swap by theme alone.
+
+Python
+------
+
+.. code-block:: python
+
+   from forcingkit.mesh_frames import mesh_frames
+   from forcingkit.render import lut_color, render_frames, write_frames
+
+   bbox = (-73.0, 40.95, -72.6, 41.15)  # central Long Island Sound
+   frames = mesh_frames("necofs", bbox, "2026-10-15T22:00Z", "2026-10-16T02:00Z", stride_h=1)
+   color = lut_color([(0.05, 230, 240, 250), (0.5, 120, 160, 200), (2.0, 20, 40, 90)], log=True)
+   images = render_frames(
+       frames, bbox, (1200, 800), color,
+       edges=((0, 0, 0, 40), 1), background=(242, 243, 240, 255),
+   )
+   write_frames(images, "frames/", times=frames.times)
+
+NECOFS hours are read from the SMAST daily history file that holds each one (falling back to the
+rolling forecast), so a window may cross several archive days.
+
+Command line
+------------
+
+.. code-block:: bash
+
+   uv run python -m forcingkit.render --model necofs \
+     --bbox -73.0 40.95 -72.6 41.15 \
+     --start 2026-10-15T22:00Z --end 2026-10-16T02:00Z --stride-h 1 \
+     --size 1200x800 --ramp viridis --vmax 1.5 \
+     --edges 0,0,0,40 --background 242,243,240 --out frames/
+
+``--ramp`` takes a built-in name, a packaged table (``currents_lis``, ``currents_lis_dark``) or a path to a
+``value,r,g,b[,a]`` CSV (with ``--log`` and ``--floor``). The output directory receives
+``frame_0000.png``, ``frame_0001.png``, ... and ``frames.json``, which lists the frame times, the box
+and the size.

{forcingkit-0.8.0 → forcingkit-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forcingkit"
-version = "0.8.0"
+version = "0.9.0"
 description = "Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -43,6 +43,7 @@ dependencies = [
     "dask[array]>=2026.3.0",
     "cftime>=1.6.5",
     "matplotlib>=3.10.9",
+    "pillow>=10.0",
 ]
 
 [tool.hatch.build.targets.wheel]

forcingkit-0.9.0/src/forcingkit/mesh_frames.py

@@ -0,0 +1,228 @@
+"""Model output on its native unstructured mesh, as a time series of per-element values.
+
+`MeshFrames` is the model-agnostic contract: node coordinates, triangle connectivity and, for each
+time, one value per triangle (element). `mesh_frames(model, bbox, start, end)` builds one from a
+registered model adapter. `forcingkit.render` turns it into image frames.
+
+Adding a model
+--------------
+An adapter is one function ``(bbox, times) -> MeshFrames`` registered under a name::
+
+    from forcingkit.mesh_frames import MeshFrames, register_adapter
+
+    @register_adapter("mymodel")
+    def _mymodel(bbox, times):
+        # bbox: (min_lon, min_lat, max_lon, max_lat); times: tz-aware UTC DatetimeIndex.
+        # Read every element that overlaps bbox (a margin beyond it is fine: the renderer
+        # clips) for the requested times; omit any time the source does not hold.
+        return MeshFrames(times=..., node_lon=..., node_lat=..., tri=..., u=..., v=...)
+
+The registry builds the requested time axis (``start`` to ``end`` inclusive, every ``stride_h``
+hours), so an adapter only reads and reshapes. Triangle meshes from FVCOM, ADCIRC or SCHISM fit
+directly: ``tri`` is the zero-based element-to-node table (FVCOM ``nv`` is one-based and
+transposed), and element values are the model's own (FVCOM u, v at centroids) or the mean of the
+three node values for node-centred models.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Callable, Sequence
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+BBox = Sequence[float]
+Adapter = Callable[[tuple[float, float, float, float], pd.DatetimeIndex], "MeshFrames"]
+
+_ADAPTERS: dict[str, Adapter] = {}
+
+
+def _to_utc(t) -> pd.Timestamp:
+    ts = pd.Timestamp(t)
+    return ts.tz_localize("UTC") if ts.tzinfo is None else ts.tz_convert("UTC")
+
+
+@dataclass
+class MeshFrames:
+    """Per-element values on a triangle mesh, one frame per time.
+
+    times: (t,) tz-aware UTC. Naive input is taken as UTC.
+    node_lon, node_lat: (n_node,) degrees.
+    tri: (n_tri, 3) zero-based node indices, one row per element.
+    u, v: (t, n_tri) eastward and northward value per element (m/s for currents). NaN marks an
+        element with no value at that time (dry, masked); it renders as outside the mesh.
+
+    Values are on elements only: one value per triangle, drawn with flat shading.
+    """
+
+    times: pd.DatetimeIndex
+    node_lon: np.ndarray
+    node_lat: np.ndarray
+    tri: np.ndarray
+    u: np.ndarray
+    v: np.ndarray
+    attrs: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        times = pd.DatetimeIndex(self.times)
+        self.times = (
+            times.tz_localize("UTC") if times.tz is None else times.tz_convert("UTC")
+        )
+        self.node_lon = np.asarray(self.node_lon, dtype=np.float64)
+        self.node_lat = np.asarray(self.node_lat, dtype=np.float64)
+        self.tri = np.asarray(self.tri, dtype=np.int64)
+        self.u = np.asarray(self.u, dtype=np.float32)
+        self.v = np.asarray(self.v, dtype=np.float32)
+        n_node = self.node_lon.shape[0]
+        if self.node_lat.shape != (n_node,) or self.node_lon.ndim != 1:
+            raise ValueError("node_lon and node_lat must be 1-D and the same length")
+        if self.tri.ndim != 2 or self.tri.shape[1] != 3:
+            raise ValueError(f"tri must be (n_tri, 3), got {self.tri.shape}")
+        if self.tri.size and (self.tri.min() < 0 or self.tri.max() >= n_node):
+            raise ValueError("tri holds node indices outside node_lon/node_lat")
+        shape = (len(self.times), self.tri.shape[0])
+        if self.u.shape != shape or self.v.shape != shape:
+            raise ValueError(
+                f"u and v must be (t, n_tri) = {shape}, got {self.u.shape} and {self.v.shape}"
+            )
+
+    def __len__(self) -> int:
+        return len(self.times)
+
+    def speed(self) -> np.ndarray:
+        """(t, n_tri) magnitude of (u, v)."""
+        return np.hypot(self.u, self.v)
+
+
+def register_adapter(name: str) -> Callable[[Adapter], Adapter]:
+    """Register `fn(bbox, times) -> MeshFrames` under `name` (see the module docstring)."""
+
+    def deco(fn: Adapter) -> Adapter:
+        _ADAPTERS[name.lower()] = fn
+        return fn
+
+    return deco
+
+
+def available_models() -> list[str]:
+    """Names accepted by `mesh_frames`."""
+    return sorted(_ADAPTERS)
+
+
+def frame_times(start, end, stride_h: int = 1) -> pd.DatetimeIndex:
+    """UTC times from `start` to `end` inclusive every `stride_h` hours, `start` floored to the hour."""
+    if stride_h < 1:
+        raise ValueError(f"stride_h must be a positive number of hours, got {stride_h}")
+    t0, t1 = _to_utc(start).floor("h"), _to_utc(end)
+    if t1 < t0:
+        raise ValueError(f"end {t1} precedes start {t0}")
+    return pd.date_range(t0, t1, freq=f"{int(stride_h)}h")
+
+
+def mesh_frames(model: str, bbox: BBox, start, end, stride_h: int = 1) -> MeshFrames:
+    """Values of `model` on its native mesh for the elements in `bbox` = (W, S, E, N), from `start`
+    to `end` inclusive every `stride_h` hours (UTC; naive times are taken as UTC).
+
+    Raises KeyError for an unregistered model. Times the source does not hold are left out of the
+    result and logged.
+    """
+    key = model.lower()
+    if key not in _ADAPTERS:
+        raise KeyError(
+            f"No mesh adapter for {model!r}; available: {available_models()}"
+        )
+    w, s, e, n = (float(x) for x in bbox)
+    if not (e > w and n > s):
+        raise ValueError(f"bbox must be (W, S, E, N) with E > W and N > S, got {bbox}")
+    times = frame_times(start, end, stride_h)
+    frames = _ADAPTERS[key]((w, s, e, n), times)
+    missing = times.difference(frames.times)
+    if len(missing):
+        logger.warning(
+            f"{model}: {len(missing)} of {len(times)} requested times unavailable"
+        )
+    return frames
+
+
+NECOFS_PAD_DEG = 0.05  # wider than the coarsest GOM7 elements near the coast
+
+
+@register_adapter("necofs")
+def _necofs_surface(
+    bbox: tuple[float, float, float, float], times: pd.DatetimeIndex
+) -> MeshFrames:
+    """NECOFS FVCOM GOM7 top-layer currents at element centroids.
+
+    Each hour is read from the SMAST daily history file that holds it (via `get_necofs_url`, which
+    falls back to the rolling forecast); consecutive hours served by the same file are read in one
+    request, and the results are concatenated with duplicate times dropped. `read_surface` keeps
+    elements whose centroids lie in its box, so the box is widened by NECOFS_PAD_DEG to cover the
+    requested one edge to edge.
+    """
+    from forcingkit.fetchers import necofs
+
+    w, s, e, n = bbox
+    p = NECOFS_PAD_DEG
+    read_box = [w - p, s - p, e + p, n + p]
+
+    naive = times.tz_convert("UTC").tz_localize(None)
+    url_by_day: dict[pd.Timestamp, str] = {}
+    groups: list[tuple[str, list[pd.Timestamp]]] = []
+    for t in naive:
+        day = necofs.necofs_archive_file_date(t)
+        if day not in url_by_day:
+            url_by_day[day] = necofs.get_necofs_url(day - pd.Timedelta(days=1))
+        url = url_by_day[day]
+        if groups and groups[-1][0] == url:
+            groups[-1][1].append(t)
+        else:
+            groups.append((url, [t]))
+
+    ref = None
+    got_t: list[pd.Timestamp] = []
+    got_u: list[np.ndarray] = []
+    got_v: list[np.ndarray] = []
+    seen: set[pd.Timestamp] = set()
+    for url, ts in groups:
+        hours = int((ts[-1] - ts[0]) / pd.Timedelta(hours=1)) + 1
+        try:
+            ds = necofs.read_surface(read_box, ts[0], hours, dap_url=url)
+        except RuntimeError as exc:
+            logger.warning(f"necofs: skipping {ts[0]} to {ts[-1]}: {exc}")
+            continue
+        if ref is None:
+            ref = ds
+        elif not np.array_equal(ds["element_id"].values, ref["element_id"].values):
+            raise RuntimeError(f"{url} subsets a different set of elements for {bbox}")
+        ds_times = pd.DatetimeIndex(ds["time"].values)
+        for t in ts:
+            i = ds_times.get_indexer([t])[0]
+            if i < 0 or t in seen:
+                continue
+            seen.add(t)
+            got_t.append(t)
+            got_u.append(ds["u"].values[i])
+            got_v.append(ds["v"].values[i])
+    if ref is None or not got_t:
+        raise RuntimeError(f"NECOFS holds none of {times[0]} to {times[-1]}")
+
+    order = np.argsort(np.asarray(got_t, dtype="datetime64[ns]"))
+    return MeshFrames(
+        times=pd.DatetimeIndex([got_t[i] for i in order]),
+        node_lon=ref["node_lon"].values,
+        node_lat=ref["node_lat"].values,
+        tri=ref["triangles"].values,
+        u=np.stack([got_u[i] for i in order]),
+        v=np.stack([got_v[i] for i in order]),
+        attrs={
+            "model": "necofs",
+            "source": "NECOFS FVCOM GOM7, UMass Dartmouth SMAST",
+            "variable": "surface current (top sigma layer)",
+            "units": "m s-1",
+            "bbox": list(bbox),
+        },
+    )

forcingkit-0.9.0/src/forcingkit/ramps/currents_lis.csv

@@ -0,0 +1,70 @@
+# Currents speed ramp: speed_m_s,r,g,b (sRGB). Interpolate in log(speed); speeds below the
+# first row take its colour (floor 0.02 m/s) and speeds above the last row (3.1 m/s) clamp to it.
+# Rows are sampled in CIELAB with lightness falling monotonically, linear in log(speed) between the
+# knots, from L* 93 (pale aqua) through L* 83 (aqua) and L* 50 (teal) to L* 25 (deep blue-green);
+# hue stays between 186 and 212 degrees, after cmocean "tempo" (Thyng et al. 2016): clear of chart
+# land buff and drying green, the violet wind ramp and the blue waves ramp.
+# Knots from 2026 NOAA CO-OPS current predictions (MAX_SLACK), Long Island Sound and Block Island
+# Sound: regional median daily maximum 0.494 m/s; ACT2611 Little Gull Island median daily maximum
+# 2.418 m/s, 95th percentile 2.964 m/s, annual maximum 3.097 m/s.
+speed_m_s,r,g,b
+0.0200,214,240,244
+0.0221,212,239,243
+0.0244,210,238,242
+0.0270,208,238,242
+0.0299,206,237,241
+0.0330,204,236,240
+0.0365,202,236,240
+0.0403,201,235,238
+0.0446,199,235,238
+0.0493,197,234,237
+0.0545,194,233,236
+0.0602,193,233,236
+0.0666,191,232,234
+0.0736,189,231,233
+0.0813,187,231,233
+0.0899,185,230,232
+0.0994,183,229,230
+0.1099,182,229,230
+0.1215,179,228,229
+0.1343,177,227,227
+0.1484,176,227,227
+0.1641,174,226,226
+0.1813,172,225,224
+0.2005,170,225,224
+0.2216,168,224,222
+0.2449,166,223,221
+0.2708,165,223,220
+0.2993,163,222,219
+0.3309,160,221,218
+0.3657,159,221,217
+0.4043,157,220,215
+0.4469,155,219,214
+0.4940,154,219,213
+0.5348,147,214,208
+0.5790,141,210,204
+0.6269,134,206,200
+0.6787,128,202,195
+0.7348,121,197,190
+0.7955,114,193,186
+0.8613,108,189,182
+0.9324,101,185,177
+1.0095,94,180,172
+1.0929,87,176,168
+1.1833,80,172,164
+1.2810,72,168,159
+1.3869,64,164,155
+1.5015,56,159,150
+1.6256,47,155,146
+1.7600,37,151,141
+1.9054,23,147,137
+2.0629,0,143,133
+2.2334,11,138,128
+2.4180,8,134,124
+2.5198,1,122,116
+2.6259,5,110,107
+2.7365,1,99,98
+2.8518,2,88,89
+2.9719,2,77,80
+3.0970,2,67,71
+3.1000,2,67,71

forcingkit-0.9.0/src/forcingkit/ramps/currents_lis_dark.csv

@@ -0,0 +1,69 @@
+# Currents speed ramp, dark-basemap twin: speed_m_s,r,g,b (sRGB). Interpolate in log(speed); speeds below the
+# first row take its colour (floor 0.02 m/s) and speeds above the last row (3.1 m/s) clamp to it.
+# Rows are sampled in CIELAB with lightness rising monotonically, linear in log(speed) between the knots,
+# from L* 20 (deep blue-teal) through L* 40 (dark teal) and L* 76 (seafoam) to L* 90 (pale seafoam), for a
+# dark basemap; hue 215 to 185 degrees, mirroring currents_lis.csv on the same speeds, so the two swap by theme.
+# Knots from 2026 NOAA CO-OPS current predictions (MAX_SLACK), Long Island Sound and Block Island
+# Sound: regional median daily maximum 0.494 m/s; ACT2611 Little Gull Island median daily maximum
+# 2.418 m/s, 95th percentile 2.964 m/s, annual maximum 3.097 m/s.
+speed_m_s,r,g,b
+0.0200,1,54,61
+0.0221,1,56,63
+0.0244,2,57,64
+0.0270,1,59,66
+0.0299,0,60,67
+0.0330,2,62,69
+0.0365,1,63,70
+0.0403,0,65,72
+0.0446,1,66,73
+0.0493,1,68,75
+0.0545,0,69,76
+0.0602,1,71,78
+0.0666,0,73,80
+0.0736,3,74,80
+0.0813,2,76,82
+0.0899,1,77,83
+0.0994,3,79,85
+0.1099,1,81,87
+0.1215,3,82,88
+0.1343,1,84,90
+0.1484,1,85,90
+0.1641,3,87,92
+0.1813,1,89,94
+0.2005,3,90,95
+0.2216,1,92,97
+0.2449,5,93,97
+0.2708,2,95,99
+0.2993,5,97,101
+0.3309,2,99,103
+0.3657,1,100,103
+0.4043,4,102,105
+0.4469,0,104,107
+0.4940,3,105,108
+0.5348,1,110,112
+0.5790,3,115,117
+0.6269,7,120,121
+0.6787,12,125,125
+0.7348,15,130,130
+0.7955,19,135,134
+0.8613,24,140,138
+0.9324,26,145,143
+1.0095,30,150,147
+1.0929,34,155,151
+1.1833,38,160,155
+1.2810,41,165,159
+1.3869,45,170,163
+1.5015,48,176,168
+1.6256,52,181,172
+1.7600,56,186,176
+1.9054,59,191,180
+2.0629,63,197,185
+2.2334,67,202,189
+2.4180,71,207,192
+2.5198,90,213,199
+2.6259,107,218,204
+2.7365,122,224,211
+2.8518,137,230,218
+2.9719,150,235,223
+3.0970,164,241,230
+3.1000,164,241,230