Enhancement: Add Nested Basin Polygons Option and Stream-Junction Relationship Attribution

[barne856]

Summary

Add optional nested polygon mode for the basins command and enhance streams output with downstream relationship attribution to enable stream network analysis.

Current Behavior

basins command:

• Outputs raster (.tif) with basin IDs
• Outputs vector (.gpkg) with unnested basin polygons (each polygon includes full upstream area)
• Updates drainage points file in-place with basin_id and ds_basin_id attributes

streams command:

• Outputs GeoPackage with two layers: streams (LineStrings) and junctions (Points)
• Stream segments and junctions lack relationship attribution so we cannot easily relate streams to their downstream junction points

Proposed Enhancement

1. Basins API Improvements

Rename parameters for consistency:

• output_path → raster_output (path for basin raster)
• Add vector_output parameter (optional path for basin polygons)

Add --unnest flag:

• Default (nested): Each polygon contains only its immediate drainage area (non-overlapping)
• With --unnest: Each polygon includes full upstream contributing area (may overlap)
• Only applicable when vector output is requested

CLI:

# Raster only
overflow basins \
    --fdr fdr.tif \
    --drainage-points outlets.gpkg \
    --raster-output basins.tif

# Raster + nested vector
overflow basins \
    --fdr fdr.tif \
    --drainage-points outlets.gpkg \
    --raster-output basins.tif \
    --vector-output basins.gpkg

# Raster + unnested vector (full upstream)
overflow basins \
    --fdr fdr.tif \
    --drainage-points outlets.gpkg \
    --raster-output basins.tif \
    --vector-output basins.gpkg \
    --unnest

Python API:

overflow.basins(
    fdr_path="fdr.tif",
    drainage_points_path="outlets.gpkg",
    raster_output="basins.tif",      # Renamed from output_path
    vector_output="basins.gpkg",     # Optional
    unnest=False                      # Default: nested polygons
)

Behavior:

• When vector_output=None: No vector output created
• When vector_output provided: Creates basin polygons
  • unnest=False (default): Individual basin areas only (nested, non-overlapping)
  • unnest=True: Full upstream area per basin (unnested, may overlap)
• Drainage points file still updated in-place with basin_id and ds_basin_id

2. Streams API Improvements

Make vector outputs optional:

• Add raster_output parameter (required path for stream classification raster)
• Add vector_output parameter (optional path for streams GeoPackage)

Add stream-junction relationship attribution:

• Streams attributed with ds_junction_fid (downstream junction feature ID) and ds_stream_fid (downstream stream feature ID)
• Junctions remain unattributed except for FID

CLI:

# Raster only
overflow streams \
    --fac accum.tif \
    --fdr fdr.tif \
    --raster-output stream_cells.tif \
    --threshold 100

# Both outputs
overflow streams \
    --fac accum.tif \
    --fdr fdr.tif \
    --raster-output stream_cells.tif \
    --vector-output streams.gpkg \
    --threshold 100

Python API:

overflow.streams(
    fac_path="accum.tif",
    fdr_path="fdr.tif",
    raster_output="streams.tif",
    vector_output="streams.gpkg",    # Optional: streams + junctions GeoPackage
    threshold=100
)

This creates consistency between all feature extraction commands (flow_length, streams, and basins) regarding vector/raster output. It also has potential to greatly improve performance and memory usage for certain highly nested watersheds with many contributing upstream subbasins