Feature/floodfill from seed point

[wilfchun]

Seed-Based Constrained Flood Fill for Sea Cell Identification

Closes #159

Summary

Implements a seed-based constrained flood-fill algorithm to fix incorrect identification of sea cells in landward depressions.
Previously, the algorithm could mark isolated depressions behind dunes as "sea" even when water could not physically reach them. The new approach only expands through cells below still water level (SWL) from validated seed points, ensuring hydrological connectivity.

Problem Addressed

Before: Simple flood-fill used topological connectivity (adjacent cells) rather than hydrological connectivity (water can flow there), causing depressions behind barriers to be incorrectly flagged as sea.

After: Constrained flood-fill validates that water can physically reach cells by only expanding from known sea locations through cells below SWL.

Implementation

Two-Phase Algorithm

Phase 1: Seed Point Identification

• Option A (preferred): User-specified seed points from shapefile
  • Allows precise control of sea locations
  • Validates each point is below SWL and within grid
• Option B (fallback): Grid edge cells below SWL
  • Maintains backward compatibility
  • Respects existing omit_search_*_edge configuration

Phase 2: Constrained Flood-Fill

• Performs scanline flood-fill from each validated seed
• Key constraint: Only expands to adjacent cells below SWL
• Prevents water "climbing over" elevation barriers

Configuration

New optional parameter in .dat/.yaml files:

# Optional: Specify shapefile with point features marking sea locations
sea_flood_seed_location_shapefile: "path/to/sea_seeds.shp"

If not specified, algorithm uses grid edges (original behavior with enhanced constraints).

Changes

Modified Files

• src/locate_coast.cpp (~236 lines modified)

  • Refactored FindAllSeaCells() to use seed-based approach
  • Updated CellByCellFillSea() with elevation constraint enforcement
  • Added detailed documentation linking to DEPRESSION_FLOODING_BUG_FIX.md

• src/gis_vector.cpp (+101 lines)

  • Added nReadSeaFloodSeedShapefile() to parse seed point shapefile
  • Validates point geometry and converts to grid coordinates

• src/read_input.cpp (+31 lines)

  • Added parsing for SEA_FLOOD_SEED_LOCATION_SHAPEFILE parameter

• src/configuration.h (+13 lines)

  • Added m_strSeaFloodSeedShapefile (shapefile path)
  • Added m_VSeaFloodSeedPoint (vector of seed points in grid CRS)

• src/simulation.h (+7 lines)

  • Declared nReadSeaFloodSeedShapefile() method

• src/simulation.cpp (+10 lines)

  • Initialize seed point structures

Total: +275 insertions, -123 deletions

Benefits

1. Physically correct: Depressions behind barriers correctly identified as land
2. Flexible: User can specify exact sea locations via shapefile
3. Backward compatible: Falls back to edge-based seeding if no shapefile provided
4. Well-documented: Links to comprehensive analysis in DEPRESSION_FLOODING_BUG_FIX.md
5. Minimal performance impact: Same O(N) complexity as original algorithm

Testing Recommendations

Synthetic Test Cases

1. Simple depression: Beach → Dune → Depression

   • Verify depression NOT marked as sea when continuous barrier present

2. Dune with breach: Beach → Dune with gap → Depression

   • Verify depression IS marked as sea when accessible via gap

3. Seed point validation: Place seed in elevated area

   • Verify algorithm rejects invalid seeds (above SWL)

Example Configuration

# Specify known sea location(s) to seed flood-fill
sea_flood_seed_location_shapefile: "in/initial_sea_seeds.shp"

# Or rely on grid edges (omit specific edges if needed)
omit_coast_search_north: false  # North edge = sea
omit_coast_search_south: true   # South edge = land
omit_coast_search_east: true    # East/West = land
omit_coast_search_west: true

Migration Notes

Breaking change: Results may differ from previous versions as isolated depressions will no longer be incorrectly identified as sea.

To reproduce old behavior: Not recommended (was a bug), but algorithm maintains same edge-based seeding if no shapefile specified.

---

Commit: 6fb03ebf - "Added seep point based flood fill for sea cells"
Date: 2025-11-03
Files changed: 6 files (+275, -123)