ARGANS Waterlines from Sentinel-2 algorithm

algorithm_catalog/argans/record.json

@@ -0,0 +1,68 @@
+{
+  "id": "argans",
+  "type": "Feature",
+  "conformsTo": [
+    "https://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core"
+  ],
+  "properties": {
+    "created": "2026-04-01T00:00:00Z",
+    "updated": "2026-04-01T00:00:00Z",
+    "type": "algorithm_provider",
+    "title": "Argans Ltd",
+    "description": "Argans specializes in satellite-based Earth observation, remote sensing, and GIS for monitoring marine, atmospheric, and land environments.",
+    "keywords": [],
+    "language": {
+      "code": "en-US",
+      "name": "English (United States)"
+    },
+    "languages": [
+      {
+        "code": "en-US",
+        "name": "English (United States)"
+      }
+    ],
+    "contacts": [
+      {
+        "name": "Argans Ltd",
+        "emails": [
+          {
+            "value": "enquiries@argans.co.uk"
+          }
+        ],
+        "links": [
+          {
+            "href": "https://argans.co.uk",
+            "type": "text/html",
+            "title": "Argans Ltd",
+            "rel": "website"
+          }
+        ]
+      }
+    ],
+    "themes": [],
+    "acl": {
+      "admin": ["@argans.co.uk"]
+    }
+  },
+  "linkTemplates": [],
+  "links": [
+    {
+      "rel": "website",
+      "type": "text/html",
+      "title": "Argans Ltd",
+      "href": "https://argans.co.uk"
+    },
+    {
+      "rel": "logo-light",
+      "type": "image/png",
+      "title": "Logo",
+      "href": "https://argans.co.uk/img/logo.png"
+    },
+    {
+      "rel": "logo-dark",
+      "type": "image/png",
+      "title": "Logo",
+      "href": "https://argans.co.uk/img/logos/argans_white_new.png"
+    }
+  ]
+}

algorithm_catalog/argans/waterlines/benchmark_scenarios/waterlines.json

@@ -0,0 +1,30 @@
+[
+  {
+    "id": "waterlines",
+    "type": "openeo",
+    "backend": "openeofed.dataspace.copernicus.eu",
+    "process_graph": {
+      "waterlines1": {
+        "process_id": "waterlines_v1",
+        "namespace": "https://raw.githubusercontent.com/ESA-APEx/apex_algorithms/43d0b17c4ae5bed9db5f9cc5df38efcdcdfb7ecf/algorithm_catalog/argans/waterlines/openeo_udp/waterlines.json",
+        "arguments": {
+          "temporal_extent": ["2024-06-01", "2024-06-30"],
+          "spatial_extent": {
+            "west": -95.13,
+            "south": 29.078,
+            "east": -95.12,
+            "north": 29.082,
+            "crs": "EPSG:4326"
+          },
+          "iterations": 2,
+          "max_cloud_coverage": 5,
+          "ndwi_threshold": 0.01,
+          "simplify_tolerance": 10
+        },
+        "result": true
+      }
+    },
+    "reference_data": {
+    }
+  }
+]

algorithm_catalog/argans/waterlines/openeo_udp/README.md

@@ -0,0 +1,48 @@
+# Waterlines openEO UDP
+## Purpose
+Extract coastline waterlines from Sentinel-2 imagery using NDWI-based water detection, morphological refinement, and UDF-based conversion from water polygons to coast waterlines.
+
+## Methodology
+### Water/Land Classification
+Water masks are generated using the **Normalized Difference Water Index (NDWI)**, where pixels are classified as water when **NDWI > threshold**. The default threshold is **0.01**, but it can be adjusted using the `ndwi_threshold` parameter.
+
+NDWI is computed as the normalized difference between the Sentinel-2 **Green** band (B03) and **Near-Infrared** band (B08), defined as the difference between these bands divided by their sum.
+
+*This MVP supports only one method (**S2_NDWI**). Originally, multiple methods were selectable via a parameter, but this required openEO `if_()` logic, which converts the result into a `ProcessBuilder` instead of a `DataCube`.
+This breaks the `raster_to_vector()` step needed for waterline extraction.*
+
+### Morphological Processing
+For each timestamp, the water/land mask is refined using morphological operations to remove small isolated objects, fill small holes, smooth boundaries and reduce artifacts such as narrow bridges and estuaries. This improves the quality and stability of the resulting waterlines.
+
+### Waterline Extraction
+The cleaned masks are vectorized using the built-in openEO function `raster_to_vector()`. The resulting water polygons are then transformed into waterlines via a UDF, producing time-resolved geometries for each timestep.
+
+The output is a vector cube of coastline waterlines with the following properties:
+- **time**: Acquisition timestamp (Sentinel-2 datetime)  
+- **type**: Feature type (`waterline_segment`)  
+- **sea_direction_8**: Sea direction (N, NE, E, SE, S, SW, W, NW)  
+- **sea_azimuth_deg**: Sea direction in degrees (azimuth, clockwise from north)  
+- **geometry**: Waterline geometry (LineString or MultiLineString) in EPSG:3857  
+
+The **sea_azimuth_deg** property is particularly useful for downstream processing, as it can be used to shift the waterline and derive a shoreline (*a waterline normalized for beach slope and tidal conditions*).
+
+## Authors / Contact
+- **Milena Napiorkowska** (openEO UDP) Argans Ltd  
+  mnapiorkowska@argans.co.uk  
+
+- **Martin Jones** (Project Manager) Argans Ltd  
+  mjones@argans.co.uk  
+
+- **Holly Baxter** (Methodology) Argans Ltd  
+  hbaxtar@argans.co.uk  
+
+- **Cameron Mackenzie** (Methodology, openEO UDP) Argans Ltd
+  cmackenzie@argans.co.uk  
+
+## Acknowledgments
+This work was developed as part of an ESA-funded **Fast Track** project.
+
+## Known Limitations
+- Results are most reliable for scenes with low cloud coverage  
+- NoData areas may introduce artifacts, particularly along boundaries between valid and invalid pixels  
+- NDWI might be less reliable in turbid waters

algorithm_catalog/argans/waterlines/openeo_udp/generate.py

@@ -0,0 +1,179 @@
+import json
+from pathlib import Path
+
+import openeo
+from openeo import UDF
+from openeo.api.process import Parameter
+from openeo.rest.connection import Connection
+from openeo.rest.datacube import DataCube
+from openeo.rest.udp import build_process_dict
+
+from s2_index import (
+    s2_index_mask,
+    DEFAULT_S2_COLLECTION,
+    DEFAULT_MAX_CLOUD_COVER,
+    WATERLAND_THRESHOLDS,
+)
+
+
+def apply_morphology(cube: DataCube, iterations: int) -> DataCube:
+    udf = UDF.from_file(
+        Path(__file__).parent / "udf_morph_operations.py",
+        context={"from_parameter": "context"},
+    )
+    return cube.apply_dimension(
+        process=udf,
+        dimension="t",
+        context={"iterations": iterations},
+    )
+
+
+def create_waterlines(cube: DataCube, simplify_tolerance: float = 10) -> DataCube:
+    """
+    Extract waterlines from a water/land mask using a UDF.
+
+    The input must remain a DataCube because the workflow relies on
+    `raster_to_vector()` before applying the vector-based waterline UDF.
+    """
+    cube = cube.raster_to_vector()
+
+    udf = UDF.from_file(
+        Path(__file__).parent / "udf_waterlines_from_water_land_mask.py",
+        context={"from_parameter": "context"},
+    )
+    return cube.apply_dimension(
+        process=udf,
+        dimension="geometry",
+        context={"simplify_tolerance": simplify_tolerance},
+    )
+
+
+def build_water_land_mask_cube(
+    con: Connection,
+    bbox,
+    time_range,
+    max_cloud_coverage,
+    iterations,
+    ndwi_threshold,
+) -> DataCube:
+    """
+    Build a water/land mask using Sentinel-2 NDWI only.
+
+    MVP rationale:
+    Multiple selectable methods were intentionally removed from this UDP.
+    Selecting between whole DataCubes through nested openEO `if_()` expressions
+    turns the selected result into a ProcessBuilder rather than a DataCube.
+    That breaks the next step of the workflow, because `raster_to_vector()` is
+    used as a DataCube method when preparing input for the vector-based
+    waterline UDF.
+
+    S2_NDWI was chosen for the MVP because it is a standard water-detection
+    index, fits the existing index-mask pipeline, and allows validation of the
+    complete end-to-end workflow without introducing graph-selection complexity.
+
+    Future extensions can add the other methods either as separate UDPs or by
+    refactoring the waterline UDF to work directly on raster input.
+    """
+    _, cube = s2_index_mask(
+        con=con,
+        collection_id=DEFAULT_S2_COLLECTION,
+        bbox=bbox,
+        time_range=time_range,
+        index_name="S2_NDWI",
+        threshold=ndwi_threshold,
+        mode="gt",
+        max_cloud_coverage=max_cloud_coverage,
+    )
+    return apply_morphology(cube, iterations)
+
+
+def generate() -> dict:
+    """
+    Create the MVP UDP for extracting waterlines from Sentinel-2 imagery.
+
+    Workflow:
+    1. Load Sentinel-2 data
+    2. Create water/land mask using S2_NDWI
+    3. Apply morphology
+    4. Vectorize the mask
+    5. Extract waterlines
+
+    Why only S2_NDWI?
+    The original multi-method design used a runtime UDP parameter to choose
+    between several masking methods. In practice, selecting between whole cubes
+    with openEO graph logic (`if_`) produced a ProcessBuilder instead of a
+    DataCube. Because the downstream workflow needs `raster_to_vector()`, that
+    design blocked the current implementation.
+
+    Restricting the MVP to a single method keeps the graph in DataCube form and
+    allows the existing vector-based waterline UDF to work unchanged.
+    """
+
+    conn = openeo.connect(url="openeo.dataspace.copernicus.eu")
+
+    spatial_extent = Parameter.bounding_box(
+        name="spatial_extent",
+        description="Bounding box of the area of interest. Defined as west, south, east, north in EPSG:4326.",
+    )
+
+    temporal_extent = Parameter.temporal_interval(
+        name="temporal_extent",
+        default=["2025-01-01", "2025-12-31"],
+        description="Date range over which to extract waterlines.",
+    )
+
+    max_cloud_coverage = Parameter.number(
+        name="max_cloud_coverage",
+        default=DEFAULT_MAX_CLOUD_COVER,
+        description="Maximum allowed cloud coverage.",
+    )
+
+    iterations = Parameter.integer(
+        name="iterations",
+        default=2,
+        description="Number of iterations for morphological operations.",
+    )
+
+    ndwi_threshold = Parameter.number(
+        name="ndwi_threshold",
+        default=WATERLAND_THRESHOLDS["S2_NDWI"].defaults["threshold"],
+        description=WATERLAND_THRESHOLDS["S2_NDWI"].description,
+    )
+
+    simplify_tolerance = Parameter.number(
+        name="simplify_tolerance",
+        default=10,
+        description="Tolerance used to simplify vectorized water polygons before extracting waterlines.",
+    )
+
+    water_land_mask = build_water_land_mask_cube(
+        con=conn,
+        bbox=spatial_extent,
+        time_range=temporal_extent,
+        max_cloud_coverage=max_cloud_coverage,
+        iterations=iterations,
+        ndwi_threshold=ndwi_threshold,
+    )
+
+    waterlines_cube = create_waterlines(water_land_mask, simplify_tolerance=simplify_tolerance)
+
+    return build_process_dict(
+        process_graph=waterlines_cube,
+        process_id="waterlines_v1",
+        summary="Waterlines extracted from Sentinel-2 using NDWI.",
+        description=(Path(__file__).parent / "README.md").read_text(),
+        parameters=[
+            spatial_extent,
+            temporal_extent,
+            max_cloud_coverage,
+            iterations,
+            ndwi_threshold,
+            simplify_tolerance,
+        ],
+        categories=["sentinel-2", "coastline", "waterlines"],
+    )
+
+
+if __name__ == "__main__":
+    with open(Path(__file__).parent / "waterlines.json", "w") as f:
+        json.dump(generate(), f, indent=2)