feat: add openEO client with NDVI and true-color graph builders

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

app/openeo_client.py

@@ -0,0 +1,138 @@
+"""openEO connection management and processing graph builders.
+
+All heavy raster processing happens server-side on CDSE. This module
+defines the processing graphs and handles authentication. The returned
+datacubes are downloaded as GeoTIFFs by indicator code.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import openeo
+
+from app.config import OPENEO_BACKEND, OPENEO_CLIENT_ID, OPENEO_CLIENT_SECRET
+
+logger = logging.getLogger(__name__)
+
+_connection: openeo.Connection | None = None
+
+
+def get_connection() -> openeo.Connection:
+    """Get or create an authenticated openEO connection to CDSE.
+
+    The connection is cached for reuse across indicator calls within a job.
+    """
+    global _connection
+    if _connection is not None:
+        return _connection
+
+    logger.info("Connecting to openEO backend: %s", OPENEO_BACKEND)
+    conn = openeo.connect(OPENEO_BACKEND)
+
+    if OPENEO_CLIENT_ID and OPENEO_CLIENT_SECRET:
+        conn.authenticate_oidc(
+            client_id=OPENEO_CLIENT_ID,
+            client_secret=OPENEO_CLIENT_SECRET,
+        )
+    else:
+        conn.authenticate_oidc()
+
+    _connection = conn
+    return conn
+
+
+def _reset_connection() -> None:
+    """Reset the cached connection (for testing)."""
+    global _connection
+    _connection = None
+
+
+def _bbox_dict(bbox: list[float]) -> dict[str, float]:
+    """Convert [min_lon, min_lat, max_lon, max_lat] to openEO spatial_extent."""
+    return {
+        "west": bbox[0],
+        "south": bbox[1],
+        "east": bbox[2],
+        "north": bbox[3],
+    }
+
+
+def build_ndvi_graph(
+    *,
+    conn: openeo.Connection,
+    bbox: dict[str, float],
+    temporal_extent: list[str],
+    resolution_m: int = 100,
+) -> openeo.DataCube:
+    """Build an openEO process graph for monthly median NDVI composites.
+
+    Loads Sentinel-2 L2A, masks clouds using the SCL band, computes
+    NDVI = (B08 - B04) / (B08 + B04), and aggregates to monthly medians.
+
+    Returns an openEO DataCube (not yet executed).
+    """
+    cube = conn.load_collection(
+        collection_id="SENTINEL2_L2A",
+        spatial_extent=bbox,
+        temporal_extent=temporal_extent,
+        bands=["B04", "B08", "SCL"],
+    )
+
+    # Cloud mask: keep only vegetation, bare soil, water (SCL classes 4,5,6)
+    scl = cube.band("SCL")
+    cloud_mask = (scl == 4) | (scl == 5) | (scl == 6)
+    cube = cube.mask(~cloud_mask)
+
+    # NDVI
+    b08 = cube.band("B08")
+    b04 = cube.band("B04")
+    ndvi = (b08 - b04) / (b08 + b04)
+
+    # Monthly median composite
+    monthly = ndvi.aggregate_temporal_period("month", reducer="median")
+
+    # Resample to target resolution
+    if resolution_m > 10:
+        monthly = monthly.resample_spatial(resolution=resolution_m / 111320)
+
+    return monthly
+
+
+def build_true_color_graph(
+    *,
+    conn: openeo.Connection,
+    bbox: dict[str, float],
+    temporal_extent: list[str],
+    resolution_m: int = 100,
+) -> openeo.DataCube:
+    """Build an openEO process graph for a true-color Sentinel-2 composite.
+
+    Loads B04 (Red), B03 (Green), B02 (Blue), masks clouds,
+    and creates a median composite over the temporal extent.
+
+    Returns an openEO DataCube (not yet executed).
+    """
+    cube = conn.load_collection(
+        collection_id="SENTINEL2_L2A",
+        spatial_extent=bbox,
+        temporal_extent=temporal_extent,
+        bands=["B02", "B03", "B04", "SCL"],
+    )
+
+    # Cloud mask
+    scl = cube.band("SCL")
+    cloud_mask = (scl == 4) | (scl == 5) | (scl == 6)
+    cube = cube.mask(~cloud_mask)
+
+    # Drop SCL, keep RGB
+    rgb = cube.filter_bands(["B02", "B03", "B04"])
+
+    # Temporal median composite
+    composite = rgb.reduce_dimension(dimension="t", reducer="median")
+
+    # Resample
+    if resolution_m > 10:
+        composite = composite.resample_spatial(resolution=resolution_m / 111320)
+
+    return composite

tests/test_openeo_client.py

@@ -0,0 +1,80 @@
+"""Tests for app.openeo_client — openEO connection and graph builders."""
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+import pytest
+
+
+def test_get_connection_creates_authenticated_connection():
+    """get_connection() connects to CDSE and authenticates."""
+    mock_conn = MagicMock()
+    with patch("openeo.connect", return_value=mock_conn) as mock_connect:
+        from app.openeo_client import get_connection, _reset_connection
+        _reset_connection()
+        conn = get_connection()
+
+        mock_connect.assert_called_once_with("openeo.dataspace.copernicus.eu")
+        mock_conn.authenticate_oidc.assert_called_once()
+        assert conn is mock_conn
+        _reset_connection()
+
+
+def test_get_connection_reuses_cached():
+    """Subsequent calls return the same connection object."""
+    mock_conn = MagicMock()
+    with patch("openeo.connect", return_value=mock_conn):
+        from app.openeo_client import get_connection, _reset_connection
+        _reset_connection()
+        conn1 = get_connection()
+        conn2 = get_connection()
+        assert conn1 is conn2
+        _reset_connection()
+
+
+def test_build_ndvi_graph():
+    """build_ndvi_graph() loads Sentinel-2 with correct bands."""
+    mock_conn = MagicMock()
+    mock_cube = MagicMock()
+    mock_conn.load_collection.return_value = mock_cube
+
+    from app.openeo_client import build_ndvi_graph
+
+    bbox = {"west": 32.45, "south": 15.65, "east": 32.65, "north": 15.8}
+    result = build_ndvi_graph(
+        conn=mock_conn,
+        bbox=bbox,
+        temporal_extent=["2025-03-01", "2026-03-01"],
+        resolution_m=100,
+    )
+
+    mock_conn.load_collection.assert_called_once()
+    call_kwargs = mock_conn.load_collection.call_args
+    assert call_kwargs[1]["collection_id"] == "SENTINEL2_L2A"
+    assert call_kwargs[1]["spatial_extent"] == bbox
+    assert "B04" in call_kwargs[1]["bands"]
+    assert "B08" in call_kwargs[1]["bands"]
+    assert "SCL" in call_kwargs[1]["bands"]
+
+
+def test_build_true_color_graph():
+    """build_true_color_graph() loads RGB bands."""
+    mock_conn = MagicMock()
+    mock_cube = MagicMock()
+    mock_conn.load_collection.return_value = mock_cube
+
+    from app.openeo_client import build_true_color_graph
+
+    bbox = {"west": 32.45, "south": 15.65, "east": 32.65, "north": 15.8}
+    result = build_true_color_graph(
+        conn=mock_conn,
+        bbox=bbox,
+        temporal_extent=["2025-03-01", "2026-03-01"],
+        resolution_m=100,
+    )
+
+    mock_conn.load_collection.assert_called_once()
+    call_kwargs = mock_conn.load_collection.call_args
+    bands = call_kwargs[1]["bands"]
+    assert "B04" in bands
+    assert "B03" in bands
+    assert "B02" in bands