BhuManthan Drainage Extraction Pipeline

A geospatial pipeline for extracting probable drainage channels from reference imagery and DEM data using thresholding, morphology, skeletonization, and vector export.

Project structure

BhuManthan-Drainage/
├── .streamlit/
├── docs/
├── notebook/
│   └── BhuManthan_Drainage_Pipeline.ipynb
├── outputs/
├── src/
│   └── pipeline_engine.py
├── .gitignore
├── README.md
├── requirements.txt
└── app.py

This repository is organized as a buildable project instead of a notebook-only dump, with the notebook kept for experimentation and pipeline_engine.py used as the main execution file.

What the pipeline does

The starter pipeline reads a reference imagery raster and a DEM raster, aligns the DEM to the imagery grid, derives slope, detects likely drainage pixels, cleans the mask, extracts a skeleton, and exports both raster and vector outputs.

Core processing stages:

• Load reference imagery.
• Reproject and align DEM to the imagery extent and resolution.
• Normalize imagery and DEM values.
• Generate candidate drainage regions using dark-pixel and low-elevation logic.
• Apply ensemble thresholding.
• Clean the mask with morphology operations.
• Skeletonize and filter connected components.
• Prune the network using elevation and slope constraints.
• Export GeoTIFF, GeoJSON, and JSON statistics outputs.

Main file

The current project is centered on src/pipeline_engine.py, which acts as the orchestrator for the end-to-end drainage extraction workflow.

Suggested future split:

• src/preprocess.py for raster loading, alignment, and normalization.
• src/vector_export.py for polygon and line conversion.
• src/utils.py for reusable save, stats, and helper functions.
• app.py for a Streamlit interface over the pipeline outputs.

Input data

Expected raw input layout:

data/
└── raw/
    ├── imagery/
    │   └── reference_imagery.tif
    └── dem/
        └── reference_dem.tif

The default paths in the starter engine currently point to data/raw/imagery/reference_imagery.tif and data/raw/dem/reference_dem.tif, so those paths should be updated if the project uses different filenames or folder names.

Output data

The pipeline writes outputs into the outputs/ directory and separates processed rasters, vectors, and summary statistics into subfolders.

Typical outputs include:

• outputs/processed/dem_aligned.tif
• outputs/processed/slope.tif
• outputs/processed/drainage_mask.tif
• outputs/processed/drainage_skeleton.tif
• outputs/vectors/drainage_polygons.geojson
• outputs/vectors/drainage_lines.geojson
• outputs/stats.json

Run locally

1. Clone the repository.
2. Create and activate a Python virtual environment.
3. Install dependencies from requirements.txt.
4. Place the imagery and DEM files in the expected raw-data folders.
5. Run the pipeline engine.

Example commands:

git clone <your-repo-url>
cd BhuManthan-Drainage
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python src/pipeline_engine.py

If Windows is being used, activate the environment with .venv\\Scripts\\activate instead of the Unix source command.

Notes

• The current pipeline_engine.py is a starter version meant to mirror the notebook workflow in a cleaner project format.
• The notebook can remain in the repository for testing, debugging, and experimentation while the source files become the primary codebase.
• Large rasters, generated outputs, and local environment files should stay out of version control through .gitignore.

Roadmap

Planned improvements for the next revision:

• Split the monolithic pipeline into smaller modules.
• Add a Streamlit dashboard in app.py.
• Add preview images and richer summary metrics.
• Add configurable thresholds through CLI arguments or UI controls.
• Add documentation in the docs/ folder.