gisgears 0.1.0__tar.gz

gisgears-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aaronchh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gisgears-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include requirements.txt

gisgears-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: gisgears
+Version: 0.1.0
+Summary: A collection of tools for GIS/hydrology raster and vector analysis
+Author-email: aaronchh <aaronhsu219@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AaronOET/gisgears
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: rasterio
+Requires-Dist: pyshp
+Requires-Dist: whitebox
+Dynamic: license-file
+
+# GISGEARS
+
+A collection of Python tools for GIS/hydrology raster and vector analysis.
+
+> **WhiteboxTools**: `wsdgen` depends on the WhiteboxTools executable, which the `whitebox` Python package downloads automatically the first time it runs.
+
+## Installation
+
+```bash
+pip install gisgears
+```
+
+## Features
+
+- **wsdgen**: Delineate a watershed from a DEM and an outlet layer (point or line)
+
+## Usage
+
+### Command-line
+
+```bash
+# List all available commands
+gisgears-info
+
+# Delineate a watershed from a point outlet
+wsdgen --dem dem.tif --outlet outlet.shp
+
+# Delineate a watershed from a line outlet (e.g. a cross-section), keeping intermediates
+wsdgen --dem dem.tif --outlet crosssection.shp --all-outputs
+
+# Use a coarser/finer boundary-smoothing filter
+wsdgen --dem dem.tif --outlet outlet.shp --smooth-filter 15
+```
+
+### Python API
+
+```python
+from gisgears import wsdgen
+
+# Delineate a watershed (written to WSD/watershed.tif, watershed.shp, watershed_smooth.shp)
+wsdgen.delineate_watershed(dem="dem.tif", outlet="outlet.shp")
+```
+
+## Notes
+
+- The outlet layer may be a point shapefile (a single manually-marked outlet) or a line shapefile (e.g. a cross-section at the watershed outlet); `wsdgen` detects the geometry type automatically.
+- By default only the final `watershed.tif`, `watershed.shp` and `watershed_smooth.shp` are written to the `WSD/` output directory; pass `--all-outputs` to also keep intermediate files (breached DEM, D8 pointer, flow accumulation, snapped outlet, etc.) there instead of a temporary folder.

gisgears-0.1.0/README.md

@@ -0,0 +1,47 @@
+# GISGEARS
+
+A collection of Python tools for GIS/hydrology raster and vector analysis.
+
+> **WhiteboxTools**: `wsdgen` depends on the WhiteboxTools executable, which the `whitebox` Python package downloads automatically the first time it runs.
+
+## Installation
+
+```bash
+pip install gisgears
+```
+
+## Features
+
+- **wsdgen**: Delineate a watershed from a DEM and an outlet layer (point or line)
+
+## Usage
+
+### Command-line
+
+```bash
+# List all available commands
+gisgears-info
+
+# Delineate a watershed from a point outlet
+wsdgen --dem dem.tif --outlet outlet.shp
+
+# Delineate a watershed from a line outlet (e.g. a cross-section), keeping intermediates
+wsdgen --dem dem.tif --outlet crosssection.shp --all-outputs
+
+# Use a coarser/finer boundary-smoothing filter
+wsdgen --dem dem.tif --outlet outlet.shp --smooth-filter 15
+```
+
+### Python API
+
+```python
+from gisgears import wsdgen
+
+# Delineate a watershed (written to WSD/watershed.tif, watershed.shp, watershed_smooth.shp)
+wsdgen.delineate_watershed(dem="dem.tif", outlet="outlet.shp")
+```
+
+## Notes
+
+- The outlet layer may be a point shapefile (a single manually-marked outlet) or a line shapefile (e.g. a cross-section at the watershed outlet); `wsdgen` detects the geometry type automatically.
+- By default only the final `watershed.tif`, `watershed.shp` and `watershed_smooth.shp` are written to the `WSD/` output directory; pass `--all-outputs` to also keep intermediate files (breached DEM, D8 pointer, flow accumulation, snapped outlet, etc.) there instead of a temporary folder.

gisgears-0.1.0/gisgears/__init__.py

@@ -0,0 +1,14 @@
+"""
+GISGEARS - A collection of tools for GIS/hydrology raster and vector analysis.
+"""
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'describe',
+    'wsdgen',
+]
+
+from . import describe
+from . import wsdgen
+from . import cli

gisgears-0.1.0/gisgears/cli.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python
+"""
+Top-level `gisgears` command. Running `gisgears -h` (or with no arguments)
+prints the same information shown by `gisgears-info`. Running `gisgears -v`
+prints the installed gisgears version.
+"""
+
+import sys
+
+from . import __version__, describe
+
+
+def _print_info(tool=None):
+    argv_backup = sys.argv
+    try:
+        sys.argv = ['gisgears-info'] + ([tool] if tool else [])
+        describe.main()
+    finally:
+        sys.argv = argv_backup
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args or args[0] in ('-h', '--help'):
+        _print_info()
+        return
+
+    if args[0] in ('-v', '--version'):
+        print(f"gisgears {__version__}")
+        return
+
+    tool = args[0]
+    if tool in describe.TOOL_DESCRIPTIONS:
+        _print_info(tool)
+        return
+
+    print(f"Unknown option or tool: {tool}", file=sys.stderr)
+    print("Run 'gisgears -h' to see available tools.", file=sys.stderr)
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

gisgears-0.1.0/gisgears/describe.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+"""
+Command-line utility to display descriptions of gisgears functionality.
+"""
+
+import argparse
+import sys
+from textwrap import dedent
+
+TOOL_DESCRIPTIONS = {
+    'wsdgen': """
+        Delineate a watershed from a DEM and an outlet layer (point or line).
+
+        Breaches depressions, computes D8 flow direction/accumulation, snaps
+        the outlet onto the stream, delineates the watershed, and converts
+        the result to polygon shapefiles (raw and boundary-smoothed).
+        Requires the WhiteboxTools executable, downloaded automatically by
+        the `whitebox` Python package on first use.
+
+        Examples:
+            wsdgen --dem dem.tif --outlet outlet.shp                     # Point outlet
+            wsdgen --dem dem.tif --outlet crosssection.shp --all-outputs # Keep intermediates
+    """,
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='gisgears-info',
+        description='Display descriptions of gisgears commands',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        'tool',
+        nargs='?',
+        choices=list(TOOL_DESCRIPTIONS.keys()),
+        help='Tool name to describe (omit to list all tools)',
+    )
+    args = parser.parse_args()
+
+    if args.tool:
+        print(f"\n--- {args.tool} ---")
+        print(dedent(TOOL_DESCRIPTIONS[args.tool]))
+    else:
+        print("\nGISGEARS — GIS/hydrology analysis commands\n")
+        for tool, desc in TOOL_DESCRIPTIONS.items():
+            first_line = dedent(desc).strip().splitlines()[0]
+            print(f"  {tool:<14} {first_line}")
+        print("\nRun 'gisgears-info <tool>' for details on a specific command.")
+
+
+if __name__ == "__main__":
+    main()

gisgears-0.1.0/gisgears/wsdgen.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python
+"""
+wsdgen - Delineate a watershed from a DEM and an outlet layer (point or line).
+
+Given a DEM raster and an outlet (pour point) shapefile - which may be a
+point layer (a single manually-marked outlet) or a line layer (e.g. a
+cross-section at the watershed outlet) - this tool breaches depressions,
+computes D8 flow direction/accumulation, snaps the outlet onto the stream,
+delineates the watershed, and converts the result to polygon shapefiles
+(raw and boundary-smoothed).
+
+Requires the WhiteboxTools executable, which the `whitebox` Python package
+downloads automatically on first use.
+"""
+
+import argparse
+import sys
+import tempfile
+from pathlib import Path
+
+import numpy as np
+import rasterio
+import shapefile
+from whitebox import WhiteboxTools
+
+
+def _snap_raster_pour_points(outlet_raster_path, flow_accum_path, output_path, snap_dist):
+    """
+    Relocate each labeled outlet cell to the highest-flow-accumulation cell
+    within snap_dist, the same way WhiteboxTools' snap_pour_points does for
+    point outlets.
+    """
+    with rasterio.open(outlet_raster_path) as src:
+        outlet = src.read(1)
+        profile = src.profile
+        outlet_nodata = src.nodata
+        cellsize = abs(src.transform.a)
+
+    with rasterio.open(flow_accum_path) as src:
+        flow_accum = src.read(1)
+        fa_nodata = src.nodata
+
+    radius_cells = max(1, round(snap_dist / cellsize))
+    rows, cols = outlet.shape
+    snapped = np.full_like(outlet, outlet_nodata)
+
+    ids = np.unique(outlet)
+    ids = ids[ids != outlet_nodata]
+
+    for outlet_id in ids:
+        ys, xs = np.where(outlet == outlet_id)
+        # Start the search from whichever of this outlet's cells is already
+        # closest to the channel, then look for the true peak nearby
+        seed_r, seed_c = ys[np.argmax(flow_accum[ys, xs])], xs[np.argmax(flow_accum[ys, xs])]
+
+        r0, r1 = max(0, seed_r - radius_cells), min(rows, seed_r + radius_cells + 1)
+        c0, c1 = max(0, seed_c - radius_cells), min(cols, seed_c + radius_cells + 1)
+        window = flow_accum[r0:r1, c0:c1]
+
+        valid = window != fa_nodata if fa_nodata is not None else np.ones_like(window, dtype=bool)
+        if valid.any():
+            masked = np.where(valid, window, -np.inf)
+            local_r, local_c = np.unravel_index(np.argmax(masked), masked.shape)
+            snap_r, snap_c = r0 + local_r, c0 + local_c
+        else:
+            snap_r, snap_c = seed_r, seed_c
+
+        snapped[snap_r, snap_c] = outlet_id
+
+    with rasterio.open(output_path, "w", **profile) as dst:
+        dst.write(snapped, 1)
+
+
+def delineate_watershed(dem, outlet, outdir="WSD", all_outputs=False, smooth_filter=9, cwd=None) -> Path:
+    """
+    Delineate a watershed from a DEM and an outlet layer (point or line).
+
+    Args:
+        dem (str): Path to the input DEM raster
+        outlet (str): Path to the outlet (pour point) shapefile - point or line
+        outdir (str): Output folder name (default: WSD)
+        all_outputs (bool): Keep intermediate files (breach/pointer/flow
+            accumulation/snapped outlet, etc.) in outdir instead of a temp
+            folder that is deleted after processing
+        smooth_filter (int): Boundary smoothing filter size (odd, >=3)
+        cwd (Path): Working directory to resolve relative paths against and
+            to run WhiteboxTools from (defaults to the current directory)
+
+    Returns:
+        Path: Output directory containing watershed.tif, watershed.shp and
+            watershed_smooth.shp
+    """
+    cwd = Path(cwd) if cwd is not None else Path.cwd()
+    dem_path = Path(dem)
+    dem_path = dem_path if dem_path.is_absolute() else cwd / dem_path
+    outlet_path = Path(outlet)
+    outlet_path = outlet_path if outlet_path.is_absolute() else cwd / outlet_path
+
+    for p in (dem_path, outlet_path):
+        if not p.is_file():
+            sys.exit(f"Error: required input file not found: {p}")
+
+    wbt = WhiteboxTools()
+    wbt.set_working_dir(str(cwd))
+
+    # whitebox_tools.exe cannot correctly resolve relative paths to subfolders
+    # on Windows, so input and output files always use absolute paths
+    dem_str = str(dem_path.resolve())
+    outlet_str = str(outlet_path.resolve())
+
+    output_dir = cwd / outdir
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Intermediate files are written to a temp folder by default and deleted
+    # entirely after processing; pass all_outputs=True to keep them in
+    # output_dir for inspection
+    if all_outputs:
+        inter_dir = output_dir
+        tmp_dir = None
+    else:
+        tmp_dir = tempfile.TemporaryDirectory()
+        inter_dir = Path(tmp_dir.name)
+
+    dem_breached = str(inter_dir / "dem_breached.tif")
+    d8_pointer = str(inter_dir / "d8_pointer.tif")
+    flow_accum = str(inter_dir / "flow_accum.tif")
+    outlet_snapped = str(inter_dir / "outlet_snapped.shp")
+    outlet_raster = str(inter_dir / "outlet_raster.tif")
+    outlet_raster_snapped = str(inter_dir / "outlet_raster_snapped.tif")
+    watershed_out = str(output_dir / "watershed.tif")
+    watershed_vector = str(output_dir / "watershed.shp")
+    watershed_vector_smooth = str(output_dir / "watershed_smooth.shp")
+
+    try:
+        with rasterio.open(dem_str) as src:
+            gridsize = abs(src.transform.a)
+
+        wbt.breach_depressions(dem_str, dem_breached)
+        wbt.d8_pointer(dem_breached, d8_pointer)
+        wbt.d8_flow_accumulation(
+            d8_pointer,
+            flow_accum,
+            out_type="cells",
+            pntr=True,
+        )
+
+        # The outlet layer may be a point (single outlet) or a line (e.g. a
+        # cross-section at the watershed outlet); the geometry type of the
+        # shapefile determines the workflow
+        with shapefile.Reader(outlet_str) as sf:
+            is_point_outlet = sf.shapeType in (
+                shapefile.POINT, shapefile.POINTZ, shapefile.POINTM
+            )
+
+        if is_point_outlet:
+            # The outlet point is manually marked and not yet snapped to the
+            # stream, so snap it using the flow accumulation grid first;
+            # snap_dist is set to 3x the DEM cell resolution to capture
+            # nearby cells
+            wbt.snap_pour_points(
+                outlet_str,
+                flow_accum,
+                outlet_snapped,
+                snap_dist=3 * gridsize,
+            )
+            pour_points = outlet_snapped
+        else:
+            # A line cannot be snapped to the stream with snap_pour_points
+            # (which only accepts point layers), so rasterize the line into
+            # outlet cells first, then snap each rasterized outlet cell onto
+            # the nearest high-flow-accumulation cell within snap_dist -
+            # without this, a line that is even one pixel off the true
+            # channel yields a near-empty watershed
+            wbt.vector_lines_to_raster(
+                outlet_str,
+                outlet_raster,
+                field="FID",
+                base=flow_accum,
+            )
+            _snap_raster_pour_points(
+                outlet_raster,
+                flow_accum,
+                outlet_raster_snapped,
+                snap_dist=3 * gridsize,
+            )
+            pour_points = outlet_raster_snapped
+
+        wbt.watershed(
+            d8_pointer,
+            pour_points,
+            watershed_out,
+        )
+
+        # Convert the watershed raster output to a polygon shapefile for
+        # easier viewing in GIS and further analysis
+        wbt.raster_to_vector_polygons(
+            watershed_out,
+            watershed_vector,
+        )
+
+        # Raster-to-polygon boundaries are jagged (following cell edges), so
+        # also output a smoothed version for downstream use/presentation
+        wbt.smooth_vectors(
+            watershed_vector,
+            watershed_vector_smooth,
+            filter=smooth_filter,
+        )
+    finally:
+        if tmp_dir is not None:
+            tmp_dir.cleanup()
+
+    print(f"Wrote watershed.tif, watershed.shp, watershed_smooth.shp to {output_dir}")
+    return output_dir
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="wsdgen",
+        description="Extract a watershed from a DEM and an outlet layer (point or line)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  wsdgen --dem dem.tif --outlet outlet.shp                       # Point outlet
+  wsdgen --dem dem.tif --outlet crosssection.shp --all-outputs   # Keep intermediates
+        """,
+    )
+    parser.add_argument("--dem", required=True, help="Input DEM file path")
+    parser.add_argument(
+        "--outlet",
+        required=True,
+        help="Outlet (pour point) shapefile path, can be a point or line layer",
+    )
+    parser.add_argument("--outdir", default="WSD", help="Output folder name (default: WSD)")
+    parser.add_argument(
+        "--all-outputs",
+        action="store_true",
+        help="Keep all intermediate files (breach/pointer/flow accumulation/snapped outlet, etc.); "
+             "by default only the final watershed.tif and watershed.shp are output",
+    )
+    parser.add_argument(
+        "--smooth-filter",
+        type=int,
+        default=9,
+        help="Boundary smoothing filter size (odd number, >=3, default 9); "
+             "larger values produce smoother boundaries; output is watershed_smooth.shp",
+    )
+    args = parser.parse_args()
+
+    delineate_watershed(
+        dem=args.dem,
+        outlet=args.outlet,
+        outdir=args.outdir,
+        all_outputs=args.all_outputs,
+        smooth_filter=args.smooth_filter,
+    )
+
+
+if __name__ == "__main__":
+    main()

gisgears-0.1.0/gisgears.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: gisgears
+Version: 0.1.0
+Summary: A collection of tools for GIS/hydrology raster and vector analysis
+Author-email: aaronchh <aaronhsu219@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AaronOET/gisgears
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: rasterio
+Requires-Dist: pyshp
+Requires-Dist: whitebox
+Dynamic: license-file
+
+# GISGEARS
+
+A collection of Python tools for GIS/hydrology raster and vector analysis.
+
+> **WhiteboxTools**: `wsdgen` depends on the WhiteboxTools executable, which the `whitebox` Python package downloads automatically the first time it runs.
+
+## Installation
+
+```bash
+pip install gisgears
+```
+
+## Features
+
+- **wsdgen**: Delineate a watershed from a DEM and an outlet layer (point or line)
+
+## Usage
+
+### Command-line
+
+```bash
+# List all available commands
+gisgears-info
+
+# Delineate a watershed from a point outlet
+wsdgen --dem dem.tif --outlet outlet.shp
+
+# Delineate a watershed from a line outlet (e.g. a cross-section), keeping intermediates
+wsdgen --dem dem.tif --outlet crosssection.shp --all-outputs
+
+# Use a coarser/finer boundary-smoothing filter
+wsdgen --dem dem.tif --outlet outlet.shp --smooth-filter 15
+```
+
+### Python API
+
+```python
+from gisgears import wsdgen
+
+# Delineate a watershed (written to WSD/watershed.tif, watershed.shp, watershed_smooth.shp)
+wsdgen.delineate_watershed(dem="dem.tif", outlet="outlet.shp")
+```
+
+## Notes
+
+- The outlet layer may be a point shapefile (a single manually-marked outlet) or a line shapefile (e.g. a cross-section at the watershed outlet); `wsdgen` detects the geometry type automatically.
+- By default only the final `watershed.tif`, `watershed.shp` and `watershed_smooth.shp` are written to the `WSD/` output directory; pass `--all-outputs` to also keep intermediate files (breached DEM, D8 pointer, flow accumulation, snapped outlet, etc.) there instead of a temporary folder.

gisgears-0.1.0/gisgears.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+gisgears/__init__.py
+gisgears/cli.py
+gisgears/describe.py
+gisgears/wsdgen.py
+gisgears.egg-info/PKG-INFO
+gisgears.egg-info/SOURCES.txt
+gisgears.egg-info/dependency_links.txt
+gisgears.egg-info/entry_points.txt
+gisgears.egg-info/requires.txt
+gisgears.egg-info/top_level.txt

gisgears-0.1.0/gisgears.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gisgears-0.1.0/gisgears.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+gisgears = gisgears.cli:main
+gisgears-info = gisgears.describe:main
+wsdgen = gisgears.wsdgen:main

gisgears-0.1.0/gisgears.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy
+rasterio
+pyshp
+whitebox

gisgears-0.1.0/gisgears.egg-info/top_level.txt

@@ -0,0 +1 @@
+gisgears

gisgears-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gisgears"
+version = "0.1.0"
+authors = [
+    { name = "aaronchh", email = "aaronhsu219@gmail.com" },
+]
+description = "A collection of tools for GIS/hydrology raster and vector analysis"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+    "rasterio",
+    "pyshp",
+    "whitebox",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/AaronOET/gisgears"
+
+[tool.setuptools]
+packages = ["gisgears"]
+
+[project.scripts]
+gisgears = "gisgears.cli:main"
+gisgears-info = "gisgears.describe:main"
+wsdgen = "gisgears.wsdgen:main"

gisgears-0.1.0/requirements.txt

@@ -0,0 +1,4 @@
+numpy
+rasterio
+pyshp
+whitebox

gisgears-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+