globalwaterbodycalculator 0.1.5

A package for calculating water storage based on global water body depth-area-volume equation and visualizing waterbody geometries.

Global Waterbody Calculator

Global Waterbody Calculator is an open-source Python package for estimating storage curves and bathymetry of freshwater bodies. Given a HydroLAKES ID or geographic coordinates, the tool fits global depth–area–volume (D-A-V) relationships, exports results, and generates high-resolution GeoTIFFs plus interactive 3-D visualizations.

Features

Capability	Details
Global D-A & D-V retrieval	Based on HydroLAKES, GLOBathy, GLRDAV
0.1 m resolution	Area & volume at 0.1 m depth steps
Publication-ready plots	CSV and PNG outputs
Bathymetric GeoTIFF	Raster created from lake polygons
Interactive 3-D view	Matplotlib/Plotly surface rendering

Installation

# PyPI
pip install globalwaterbodycalculator

Requirements

• Python ≥ 3.7
• Required packages (automatically installed via pip):
  • numpy
  • pandas
  • matplotlib
  • scipy
  • rasterio
  • scikit-learn
  • gdal
  • plotly
  • gdown

Ensure GDAL is installed and configured correctly on your system. It is required for raster and vector operations such as shapefile processing and TIFF output.

GDAL on Windows

On Windows, pip install globalwaterbodycalculator may fail while installing gdal with an error like:

fatal error C1083: Cannot open include file: 'gdal.h': No such file or directory

This means pip is trying to compile GDAL from source but cannot find the native GDAL headers and libraries. The simplest Windows path is to install a prebuilt GDAL wheel that matches your Python version and architecture before installing this package. For example, for CPython 3.11 on 64-bit Windows:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install https://wheelhouse.openquake.org/v3/windows/py311/GDAL-3.10.1-cp311-cp311-win_amd64.whl
python -m pip install globalwaterbodycalculator

Verify GDAL with:

python -c "from osgeo import gdal, ogr; print(gdal.VersionInfo())"

If you prefer a managed geospatial stack, install GDAL through OSGeo4W or conda-forge, or install the native GDAL headers/libraries before using pip.

Quick Start (Python API)

from globalwaterbodycalculator.calculator import WaterBodyCalculator

# Initialize the calculator
calculator = WaterBodyCalculator()

# Calculate area-volume relationships by waterbody ID
result_df, water_body_id = calculator.calculate_area_volume(id=7, depth=244)
calculator.save_results_to_csv(result_df, water_body_id, output_dir='.')
calculator.plot_results(result_df, water_body_id, output_dir='.')

# Alternatively, calculate using latitude and longitude
result_df, water_body_id = calculator.calculate_area_volume(latitude=45.59193, longitude=47.71771, depth=10)
calculator.save_results_to_csv(result_df, water_body_id, output_dir='.')
calculator.plot_results(result_df, water_body_id, output_dir='.')

Bathymetric Mapping and 3D Visualization

You can generate bathymetric maps and 3D plots from shapefiles:

# Generate bathymetric GeoTIFF and optionally plot 3D visualization
calculator.generate_bathymetry_tiff(
    lake_id=7,          # Hylak_id of the waterbody
    shapefile='lakes.shp',  # Location of the shp file
    id_field='Hylak_id',    # Name of the id column
    depth=244,          # Max depth of the waterbody
    output_dir='output/',
    plot_3d=True        # Set to True to write the 3D HTML output
)

This will:

• Compute the depth raster from the lake polygon and fitted D-A relationship
• Save the bathymetric map as a GeoTIFF
• Write an interactive 3D HTML surface view of the lake basin
• If "plot_3d" is not set to True (default=False), only a GeoTIFF file will be generated
• To display the Matplotlib 3D view while generating the HTML output, pass show_3d=True

Input & Output

Item	Format	Description
Input
id or latitude, longitude	int / float	HydroLAKES ID or WGS-84 coordinates
depth	float	Maximum depth (m)
Lake polygon (optional)	ESRI Shapefile	Must include an id_field matching Hylak_id
Output
<id>_dav.csv	CSV	Depth, area (m²), volume (m³)
<id>_dav.png	PNG	Area / volume curves
<id>_bathy.tif	GeoTIFF	Bathymetric raster
<id>_3d.html	HTML	Interactive 3-D view (optional)

Directory Layout

globalwaterbodycalculator/
├─ calculator.py       # Python API
├─ cli.py              # command-line entry point
├─ data_manager.py     # equation CSV download/cache helper
└─ __init__.py

HydroLAKES Download & Licence

Global Waterbody Calculator does not redistribute the HydroLAKES shapefiles. To create bathymetric maps and 3D views, you must:

1. Download the dataset from https://www.hydrosheds.org/products/hydrolakes.
2. Unzip it into a local folder, such as ~/data/HydroLAKES/.
3. Point the environment variable HYDROLAKES_DIR to that path or pass the folder to the CLI/API option --hydrolakes_path.

The equation CSV is downloaded on first use and cached under ~/.globalwaterbodycalculator/all_equations.csv.

Citation

Please cite Global Waterbody Calculator in your publications as:

@software{Yu_Wu_Liao_Zhuo_GWC_2025,
  author  = {Shengde Yu and Yukai Wu and Weikun Liao and Zhuo Zhijian},
  title   = {Global Waterbody Calculator},
  year    = {2025},
  version = {0.1.5},
  url     = {https://pypi.org/project/globalwaterbodycalculator/}
}

Yu, S., Wu, Y., Liao, W., & Zhuo, Z. (2025). Global Waterbody Calculator: A Python package for freshwater depth-area-volume estimation (Version 0.1.5) [Software]. https://pypi.org/project/globalwaterbodycalculator/

Authors

Shengde Yu — Ecohydrology Research Group, Department of Earth & Environmental Sciences, University of Waterloo, Waterloo, ON, Canada — [e-mail]

Yukai Wu — The Edward S. Rogers Sr. Department of Electrical & Computer Engineering, University of Toronto, Toronto, ON, Canada — [e-mail]

Weikun Liao — Department of Chemical Engineering & Applied Chemistry, University of Toronto, Toronto, ON, Canada — [e-mail]

Zhijian Zhuo — Department of Chemical Engineering & Applied Chemistry, University of Toronto, Toronto, ON, Canada — [e-mail]

Contributing

We ♥ pull requests! To contribute:

1. Fork the repo and create your feature branch: git checkout -b my-feature.
2. Commit your changes with clear messages: git commit -m "feat: add …".
3. Run tests & linter: pytest and pre-commit run --all-files.
4. Open a Pull Request – describe what you changed and why.

Coding style follows PEP 8; CI (GitHub Actions) must pass on Linux & Windows.