Merge pull request #25 from DHI/feature/swot_pixel

Add SWOT Pixel Cloud (PIXC) flow as fourth project direction; refactor: restructure README to consolidate duplications and document SWOT Pixel Cloud.

Author: kzalite

.gitignore

@@ -154,5 +154,7 @@ run.py
 config.yaml
 config_river.yaml
 config_raster.yaml
+config_pixel_cloud.yaml
 notebooks/SWOT_Download.ipynb
-notebooks/swot_examples/*
+notebooks/swot_examples/*
+notebooks/swot_pixel_examples/*

HydroEO/cli/__init__.py

@@ -258,7 +258,7 @@ def fetch_swot_raster(
     end: str = typer.Option(..., "--end", help="End date (YYYY-MM-DD)."),
     aoi_name: str = typer.Option("aoi", "--aoi-name", help="Label for the AOI."),
     product: str = typer.Option(
-        "SWOT_L2_HR_PIXC_D", "--product", help="SWOT raster product short name."
+        "SWOT_L2_HR_PIXC_2.0", "--product", help="SWOT raster product short name."
     ),
     output: str = typer.Option(
         "hydroeo_output", "--output", "-o", help="Output directory (created if absent)."
@@ -300,6 +300,99 @@ def fetch_swot_raster(
     typer.echo(f"SWOT raster download complete. Output: {output}")
 
 
+# ---------------------------------------------------------------------------
+# fetch swot-pixc
+# ---------------------------------------------------------------------------
+
+
+@fetch_app.command("swot-pixc")
+def fetch_swot_pixc(
+    bbox: str = typer.Option(
+        ...,
+        "--bbox",
+        help="Bounding box as a quoted string: 'MINLON MINLAT MAXLON MAXLAT'.",
+    ),
+    start: str = typer.Option(..., "--start", help="Start date (YYYY-MM-DD)."),
+    end: str = typer.Option(..., "--end", help="End date (YYYY-MM-DD)."),
+    aoi_name: str = typer.Option("aoi", "--aoi-name", help="Label for the AOI."),
+    product: str = typer.Option(
+        "SWOT_L2_HR_PIXC_D", "--product", help="SWOT pixel cloud product short name."
+    ),
+    output: str = typer.Option(
+        "hydroeo_output", "--output", "-o", help="Output directory (created if absent)."
+    ),
+    classes: Optional[str] = typer.Option(
+        None,
+        "--classes",
+        help="Comma-separated water classes to include (e.g., 'open_water,water_near_land'). "
+        "Default: open_water,water_near_land.",
+    ),
+    fields: Optional[str] = typer.Option(
+        None,
+        "--fields",
+        help="Comma-separated fields to grid (e.g., 'heightEGM,height'). Default: heightEGM.",
+    ),
+    grid_resolution: int = typer.Option(
+        100, "--grid-resolution", help="Grid resolution in meters. Default: 100."
+    ),
+    stat_method: str = typer.Option(
+        "median",
+        "--stat-method",
+        help="Binning statistic method (median, mean, min, max, count). Default: median.",
+    ),
+    username: Optional[str] = typer.Option(
+        None, "--username", help="EarthAccess username (or set EARTHACCESS_USERNAME)."
+    ),
+    password: Optional[str] = typer.Option(
+        None,
+        "--password",
+        help="EarthAccess password (or set EARTHACCESS_PASSWORD).",
+        hide_input=True,
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Enable debug logging."
+    ),
+):
+    """Download SWOT pixel cloud data, preprocess, and grid to rasters.
+
+    Point cloud data is filtered by water class, extracted with heightEGM computation,
+    and gridded to regular GeoTIFF rasters using specified statistics.
+    """
+    _configure_logging(verbose)
+    parsed_bbox = _parse_bbox(bbox)
+    startdate = _parse_date(start, "--start")
+    enddate = _parse_date(end, "--end")
+    u, p = _resolve_earthaccess_creds(username, password)
+
+    # Parse optional classes and fields
+    classes_list = (
+        [c.strip() for c in classes.split(",")]
+        if classes
+        else ["open_water", "water_near_land"]
+    )
+    fields_list = [f.strip() for f in fields.split(",")] if fields else ["heightEGM"]
+
+    config = {
+        "aoi": {
+            "name": aoi_name,
+            "type": "bbox",
+            "bbox": parsed_bbox,
+        },
+        "product": product,
+        "startdate": [startdate.year, startdate.month, startdate.day],
+        "enddate": [enddate.year, enddate.month, enddate.day],
+        "classes": classes_list,
+        "fields": fields_list,
+        "grid_resolution": grid_resolution,
+        "stat_method": stat_method,
+    }
+
+    from HydroEO.satellites.swot.pixc import download_pixc
+
+    download_pixc(config=config, project_dir=output, credentials=(u, p))
+    typer.echo(f"SWOT pixel cloud download complete. Output: {output}")
+
+
 # ---------------------------------------------------------------------------
 # fetch swot-lake
 # ---------------------------------------------------------------------------

HydroEO/flows.py

@@ -974,6 +974,7 @@ def generate_reservoirs_summaries(
             reservoir_type=prj.reservoirs.type,
             show=show,
             save=save,
+            products=getattr(prj, "to_process", None),
         )
 
         logger.info("Summarizing merged results")

HydroEO/plotting.py

@@ -145,6 +145,7 @@ def plot_cleaning(
     reservoir_type="reservoirs",
     show=True,
     save=False,
+    products=None,
 ):
     """Plot cleaning progression for a reservoir (unfiltered, cleaned, merged).
 
@@ -166,6 +167,8 @@ def plot_cleaning(
         Whether to display the plot.
     save : bool
         Whether to save the plot to PNG.
+    products : list, optional
+        List of products to filter on. Passed to get_*_fn functions.
     """
     sns.set()
     cmap = cm.batlow.resampled(5)
@@ -181,7 +184,7 @@ def plot_cleaning(
     fig.suptitle(f"{reservoir_type}: {reservoir_id}")
 
     # plot unfiltered timeseries
-    df = get_unfiltered_fn(reservoir_id)
+    df = get_unfiltered_fn(reservoir_id, products)
     if df is not None:
         df = df[["date", "height", "platform", "product"]]
 
@@ -207,7 +210,7 @@ def plot_cleaning(
         ax.tick_params(axis="x", rotation=45)
 
         # now plot cleaned timeseries
-        df = get_cleaned_fn(reservoir_id)
+        df = get_cleaned_fn(reservoir_id, products)
         df = df[["date", "height", "platform", "product"]]
 
         ax = main_ax[1]

HydroEO/project.py

@@ -14,6 +14,7 @@
 from HydroEO.waterbody import Reservoirs, Rivers
 from HydroEO import flows
 from HydroEO.satellites.swot.raster import download_raster
+from HydroEO.satellites.swot.pixc import download_pixc
 from HydroEO.utils import general
 from HydroEO.constants import MISSION_DEFAULTS
 from HydroEO.validation import validate_config
@@ -217,6 +218,12 @@ def __post_init__(self):
             # Will be instantiated in download() when needed
             self.swot_raster_config = self.config["swot_raster"]
 
+        if "swot_pixc" in self.config.keys() and self.config["swot_pixc"].get(
+            "enabled", True
+        ):
+            # Store the SWOT Pixel Cloud config for later use in download/preprocess
+            self.swot_pixc_config = self.config["swot_pixc"]
+
         ### make sure we have a local crs (If we were not able to set it up from the config, grab it from one of the elements)
         if self.local_crs is None:
             if hasattr(self, "rivers"):
@@ -242,6 +249,9 @@ def __post_init__(self):
             elif hasattr(self, "swot_raster_config"):
                 # For swot_raster, use global CRS as local if no local CRS specified
                 self.local_crs = self.global_crs
+            elif hasattr(self, "swot_pixc_config"):
+                # For swot_pixc, use global CRS as local if no local CRS specified
+                self.local_crs = self.global_crs
             else:
                 raise UserWarning(
                     "Must provide a local crs or a river or reservoir shapefile to determine local crs"
@@ -371,6 +381,12 @@ def download(self):
                 credentials=(self.earthdata_user, self.earthdata_pass),
                 global_crs=self.global_crs,
             )
+        if hasattr(self, "swot_pixc_config"):
+            download_pixc(
+                config=self.swot_pixc_config,
+                project_dir=self.dirs["main"],
+                credentials=(self.earthdata_user, self.earthdata_pass),
+            )
 
     def update(self):
         # get the current date of the system