# Watershed Delineation
A Python package for automatic watershed delineation from a Digital Elevation Model (DEM) and a pour point (longitude & latitude).
It uses [WhiteboxTools](https://github.com/jblindsay/whitebox-tools), [GeoPandas](https://geopandas.org/), and [Rasterio](https://rasterio.readthedocs.io/) to perform hydrologic analysis and export shapefiles with watershed attributes.
---
## 📦 Installation
```bash
pip install watershed-delineation
```
Requirements: Python 3.9 or later. Dependencies like `rasterio` and `geopandas` ship wheels for most platforms, but a recent `pip` is recommended.
---
## 🚀 Usage
### From Python
```python
from watershed_delineation.core import delineate_watershed
# Input parameters
dem_path = r"F:\data\dem.tif"
pour_lon = 32.561170
pour_lat = 39.835840
output_dir = r"C:\results"
watershed_name = "my_basin"
# Run delineation
result_path = delineate_watershed(
dem_path=dem_path,
pour_lon=pour_lon,
pour_lat=pour_lat,
output_dir=output_dir,
name=watershed_name,
buffer_km=50.0, # buffer half-size in km for DEM clip box
snap_dist_m=None, # snapping radius in meters (None = auto)
snap_multiplier=20, # multiplier for auto snap distance (default)
export_lfp=True, # also export Longest Flow Path
export_pour_point=True, # export original pour point (WGS84)
export_snapped_pour_point=True,# export snapped pour point (DEM CRS)
export_clip_dem=True, # export basin-clipped DEM
export_flow_direction=True, # export final D8 raster
export_flow_accumulation=True # export final FAC raster
)
print("Watershed shapefile saved at:", result_path)
```
WHAT IS "BUFFER SIZE" (buffer_km)?
----------------------------------
During Stage 1 we clip a square around the pour point to keep the DEM small and
processing fast. buffer_km is **half the side length in kilometers** for that
square (so the full square is 2 * buffer_km on each side). A larger buffer
reduces the risk that the watershed extends beyond the clipped area, but takes
longer and uses more memory. Default: 50 km (safe for most basins).
WHAT IS "SNAP SIZE" (snap_dist_m / snap_multiplier)?
----------------------------------------------------
Pour points rarely sit exactly on the highest-accumulation cell. We "snap" the
pour point to the cell with the highest flow accumulation within a search
radius. If you **don’t** pass snap_dist_m, we estimate it from the DEM’s pixel
size and multiply by snap_multiplier (default 20). This keeps the search window
proportional to DEM resolution (e.g., for a 30 m DEM → ~600 m default radius).
You can override both:
- Pass buffer_km explicitly to widen/narrow the initial DEM clip.
- Pass snap_dist_m explicitly (in meters) or change snap_multiplier (int).
---
### From the Command Line
After installation, run:
```bash
delineate_watershed "F:\data\dem.tif" 32.561170 39.835840 -o "C:\results" -n "my_basin" --buffer-km 50 --snap-dist-m 1500 --export-lfp --export-pour-point --export-snapped-pour-point --export-clip-dem --export-flow-direction --export-flow-accumulation
```
Arguments:
- `dem_file` → Path to DEM raster (`.tif`)
- `pour_lon` → Longitude of pour point
- `pour_lat` → Latitude of pour point
- `-o`, `--output` → Output directory (default: current dir)
- `-n`, `--name` → Base name of shapefile (default: watershed_lat_lon)
- `--buffer-km` → Buffer half-side in kilometers (default: 25)
- `--snap-dist-m` → Snap distance in meters (default: None, uses auto)
- `--snap-multiplier` → Multiplier for estimating snap distance (default: 20)
- `--export-lfp` → Export Longest Flow Path shapefile
- `--export-pour-point` → Export input pour point (WGS84)
- `--export-snapped-pour-point` → Export snapped pour point (DEM CRS)
- `--export-clip-dem` → Export basin-clipped DEM
- `--export-flow-direction` → Export final D8 pointer raster
- `--export-flow-accumulation` → Export final flow accumulation raster
---
## 📂 Output
- **`my_basin.shp`** → Watershed polygon shapefile with attributes:
- Area, perimeter
- Longest flow path length
- Form factor, circularity ratio
- Elevation statistics (min, max, mean)
- Mean slope
- Drainage density
- Pour point coordinates
- UTM zone metadata for delineation & attributes
- **`my_basin_lfp.shp`** *(optional)* → Longest flow path polyline shapefile
- **`my_basin_pourpoint_wgs84.shp`** *(optional)* → Input pour point in WGS84
- **`my_basin_pourpoint_snapped.shp`** *(optional)* → Snapped pour point in DEM CRS
- **`my_basin_dem_clip_basin.tif`** *(optional)* → Basin-clipped DEM raster
- **`my_basin_d8.tif`** *(optional)* → Final D8 pointer raster
- **`my_basin_facc.tif`** *(optional)* → Final flow accumulation raster
---
## 🛠 Development
Clone and install in editable mode:
```bash
git clone https://github.com/fyec/watershed-delineation.git
cd watershed-delineation
pip install -e .
```
Rebuild after code changes with:
```bash
python -m build
```
---
## 📌 Project Links
- [Homepage](https://github.com/fyec/watershed-delineation)
- [Bug Tracker](https://github.com/fyec/watershed-delineation/issues)
---
## 👤 Author
Developed by **FYEC**
Date: August 2025
License: MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "watershed-delineation",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "hydrology, watershed, gis, geospatial, whitebox-tools",
"author": null,
"author_email": "FYEC <f.yunusemre@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/41/15/5adbccabf8a935ad7348c95bc180115fffa31544e00f030c0f4e9873f3bc/watershed_delineation-0.1.3.tar.gz",
"platform": null,
"description": "# Watershed Delineation\r\n\r\nA Python package for automatic watershed delineation from a Digital Elevation Model (DEM) and a pour point (longitude & latitude). \r\nIt uses [WhiteboxTools](https://github.com/jblindsay/whitebox-tools), [GeoPandas](https://geopandas.org/), and [Rasterio](https://rasterio.readthedocs.io/) to perform hydrologic analysis and export shapefiles with watershed attributes.\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install watershed-delineation\r\n```\r\n\r\nRequirements: Python 3.9 or later. Dependencies like `rasterio` and `geopandas` ship wheels for most platforms, but a recent `pip` is recommended.\r\n\r\n---\r\n\r\n## \ud83d\ude80 Usage\r\n\r\n### From Python\r\n\r\n```python\r\nfrom watershed_delineation.core import delineate_watershed\r\n\r\n# Input parameters\r\ndem_path = r\"F:\\data\\dem.tif\"\r\npour_lon = 32.561170\r\npour_lat = 39.835840\r\noutput_dir = r\"C:\\results\"\r\nwatershed_name = \"my_basin\"\r\n\r\n# Run delineation\r\nresult_path = delineate_watershed(\r\n dem_path=dem_path,\r\n pour_lon=pour_lon,\r\n pour_lat=pour_lat,\r\n output_dir=output_dir,\r\n name=watershed_name,\r\n buffer_km=50.0, # buffer half-size in km for DEM clip box\r\n snap_dist_m=None, # snapping radius in meters (None = auto)\r\n snap_multiplier=20, # multiplier for auto snap distance (default)\r\n export_lfp=True, # also export Longest Flow Path\r\n export_pour_point=True, # export original pour point (WGS84)\r\n export_snapped_pour_point=True,# export snapped pour point (DEM CRS)\r\n export_clip_dem=True, # export basin-clipped DEM\r\n export_flow_direction=True, # export final D8 raster\r\n export_flow_accumulation=True # export final FAC raster\r\n)\r\n\r\nprint(\"Watershed shapefile saved at:\", result_path)\r\n```\r\n\r\nWHAT IS \"BUFFER SIZE\" (buffer_km)?\r\n----------------------------------\r\nDuring Stage 1 we clip a square around the pour point to keep the DEM small and\r\nprocessing fast. buffer_km is **half the side length in kilometers** for that\r\nsquare (so the full square is 2 * buffer_km on each side). A larger buffer\r\nreduces the risk that the watershed extends beyond the clipped area, but takes\r\nlonger and uses more memory. Default: 50 km (safe for most basins).\r\n\r\nWHAT IS \"SNAP SIZE\" (snap_dist_m / snap_multiplier)?\r\n----------------------------------------------------\r\nPour points rarely sit exactly on the highest-accumulation cell. We \"snap\" the\r\npour point to the cell with the highest flow accumulation within a search\r\nradius. If you **don\u2019t** pass snap_dist_m, we estimate it from the DEM\u2019s pixel\r\nsize and multiply by snap_multiplier (default 20). This keeps the search window\r\nproportional to DEM resolution (e.g., for a 30 m DEM \u2192 ~600 m default radius).\r\n\r\nYou can override both:\r\n- Pass buffer_km explicitly to widen/narrow the initial DEM clip.\r\n- Pass snap_dist_m explicitly (in meters) or change snap_multiplier (int).\r\n\r\n---\r\n\r\n### From the Command Line\r\n\r\nAfter installation, run:\r\n\r\n```bash\r\ndelineate_watershed \"F:\\data\\dem.tif\" 32.561170 39.835840 -o \"C:\\results\" -n \"my_basin\" --buffer-km 50 --snap-dist-m 1500 --export-lfp --export-pour-point --export-snapped-pour-point --export-clip-dem --export-flow-direction --export-flow-accumulation\r\n```\r\n\r\nArguments:\r\n\r\n- `dem_file` \u2192 Path to DEM raster (`.tif`)\r\n- `pour_lon` \u2192 Longitude of pour point\r\n- `pour_lat` \u2192 Latitude of pour point\r\n- `-o`, `--output` \u2192 Output directory (default: current dir)\r\n- `-n`, `--name` \u2192 Base name of shapefile (default: watershed_lat_lon)\r\n- `--buffer-km` \u2192 Buffer half-side in kilometers (default: 25)\r\n- `--snap-dist-m` \u2192 Snap distance in meters (default: None, uses auto)\r\n- `--snap-multiplier` \u2192 Multiplier for estimating snap distance (default: 20)\r\n- `--export-lfp` \u2192 Export Longest Flow Path shapefile\r\n- `--export-pour-point` \u2192 Export input pour point (WGS84)\r\n- `--export-snapped-pour-point` \u2192 Export snapped pour point (DEM CRS)\r\n- `--export-clip-dem` \u2192 Export basin-clipped DEM\r\n- `--export-flow-direction` \u2192 Export final D8 pointer raster\r\n- `--export-flow-accumulation` \u2192 Export final flow accumulation raster\r\n\r\n---\r\n\r\n## \ud83d\udcc2 Output\r\n\r\n- **`my_basin.shp`** \u2192 Watershed polygon shapefile with attributes:\r\n - Area, perimeter\r\n - Longest flow path length\r\n - Form factor, circularity ratio\r\n - Elevation statistics (min, max, mean)\r\n - Mean slope\r\n - Drainage density\r\n - Pour point coordinates\r\n - UTM zone metadata for delineation & attributes\r\n\r\n- **`my_basin_lfp.shp`** *(optional)* \u2192 Longest flow path polyline shapefile \r\n- **`my_basin_pourpoint_wgs84.shp`** *(optional)* \u2192 Input pour point in WGS84 \r\n- **`my_basin_pourpoint_snapped.shp`** *(optional)* \u2192 Snapped pour point in DEM CRS \r\n- **`my_basin_dem_clip_basin.tif`** *(optional)* \u2192 Basin-clipped DEM raster \r\n- **`my_basin_d8.tif`** *(optional)* \u2192 Final D8 pointer raster \r\n- **`my_basin_facc.tif`** *(optional)* \u2192 Final flow accumulation raster \r\n\r\n---\r\n\r\n## \ud83d\udee0 Development\r\n\r\nClone and install in editable mode:\r\n\r\n```bash\r\ngit clone https://github.com/fyec/watershed-delineation.git\r\ncd watershed-delineation\r\npip install -e .\r\n```\r\n\r\nRebuild after code changes with:\r\n\r\n```bash\r\npython -m build\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udccc Project Links\r\n\r\n- [Homepage](https://github.com/fyec/watershed-delineation) \r\n- [Bug Tracker](https://github.com/fyec/watershed-delineation/issues)\r\n\r\n---\r\n\r\n## \ud83d\udc64 Author\r\n\r\nDeveloped by **FYEC** \r\nDate: August 2025 \r\nLicense: MIT\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for delineating watersheds from a DEM and pour point.",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/fyec/watershed-delineation/issues",
"Homepage": "https://github.com/fyec/watershed-delineation"
},
"split_keywords": [
"hydrology",
" watershed",
" gis",
" geospatial",
" whitebox-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a5ff168dd5b003c39901b1846ea9f22b52452084759a23aa7b1d1c7b5789e3ae",
"md5": "0c1cb8a8df55652fa05d4f221b695405",
"sha256": "21f15be532922d3f47492d8cbb2a1453a51e980309d8e90000b3fd8fb79f80d3"
},
"downloads": -1,
"filename": "watershed_delineation-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c1cb8a8df55652fa05d4f221b695405",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11557,
"upload_time": "2025-08-29T16:27:04",
"upload_time_iso_8601": "2025-08-29T16:27:04.108548Z",
"url": "https://files.pythonhosted.org/packages/a5/ff/168dd5b003c39901b1846ea9f22b52452084759a23aa7b1d1c7b5789e3ae/watershed_delineation-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "41155adbccabf8a935ad7348c95bc180115fffa31544e00f030c0f4e9873f3bc",
"md5": "fccbfaa6dd744e2428eaac6f96abccb9",
"sha256": "c2d6c0ee008d59566f1008bb7c7f16c1dec8ac4af63a0dadc76cbb0a24ce32c3"
},
"downloads": -1,
"filename": "watershed_delineation-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "fccbfaa6dd744e2428eaac6f96abccb9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12354,
"upload_time": "2025-08-29T16:27:05",
"upload_time_iso_8601": "2025-08-29T16:27:05.388103Z",
"url": "https://files.pythonhosted.org/packages/41/15/5adbccabf8a935ad7348c95bc180115fffa31544e00f030c0f4e9873f3bc/watershed_delineation-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 16:27:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fyec",
"github_project": "watershed-delineation",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "watershed-delineation"
}
JSON
