# HydroSurvey Tools
This is a groundup rewrite using modern pydata tools of algorithms originally described in my 2011 SciPy Talk - [Improving efficiency and repeatability of lake volume estimates using Python](https://proceedings.scipy.org/articles/Majora-ebaa42b7-013).
## Installation
1. Download this code with git or download a zip file (click the green code icon) and unzip
2. Download and install pixi from https://prefix.dev/
3. Open a cmd/terminal window and navigate to the folder that contains this software
4. run `pixi install` to install the software
## Usage
1. Open a cmd/terminal window in the folder with the code
2. run `pixi shell` in the terminal to activate the environment
3. now you will have a tool called hstools, if you type `hstools` you will get a help message.
4. `hstools new-config <config.toml>` will help you created a new config file with a guided wizard
5. `hstools interpolate-lake <config.toml>` will run the interpolation
6. `hstools compute-eac <dem.tif> <output.csv>` will create an elevation area capacity table from a dem
7. `hstools gui` launches a gui version of the tool
## Anisotropic Elliptical Inverse Distance Weighting (AEIDW) Lake Interpolation Algorithm
### Input files and parameters required
- CSV file with survey data, fields: x-coord, y-coord, current surface elevation, preimpoundment elevation (optional)
- elevation: lake elevation at the boundary
- max segment length: this is used to add more vertices to the centerline to improve interpolation accuracy
- Shapefile of Lake boundary at a particular elevation. Elevation value set in the attribute table
- Interpolation Centerline Shapefile: This defines the direction of interpolation in a particular polygon
- polygon id: foreign key used to math centerlines with polygons
- max segment lenght: this is used to add more vertices to the centerline to improve interpolation accuracy
- Interpolation Polygons Shapefile, in the attribute table the following values are set for each polygon
- polygon id: foreign key used to connect polygons to centerlines
- grid spacing: density of generated target points in each polygon that the survey data is interpolated to
- priority: priority of the polygon, when polygons overlap target points in the overlap region use survey points from the higher priority polygon
- interpolation method: type of interpolation used in the polygon (currently AEIDW or CONSTANT)
- interpolation params: parameters needed by interpolation methos (currently ellipsivity for AEIDW or elevation value for CONSTANT)
- Polygon Buffer: Use some survey data in the buffer region around the polygon to avoid interpolation artifacts near the polygon boundaries
- nearest nieghbors: how many neighbors to include in the interpolation to each target point
### Algorithm
The essential idea of AEIDW algorithm is that along channel bathymetric depths are likely to be more similar to each other than across channel. So we transform the data into a coordinate system that follows the channel and then scale the across channel coordinate by an ellipsivity factor. After this we do a regular inverse distance wieghting. Since the across channel points are now further away, this causes the interpolation to weight along channel survey data higher than across channel survey data.
1. Add boundary data to survey data
2. iterate through polygons
3. Generate target points in each polygon
4. Convert survey data and target points in each polygon into "S-N" coordinates, where S=distance along centerline and N-perpendicular distance from centerline
5. Multiply "N" coordinate by "ellipsivity" factor.
6. Interpolate data using Inverse Distance Weighting algorithm
7. merge the target points with the original survey data
Raw data
{
"_id": null,
"home_page": null,
"name": "hydrosurvey",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Dharhas Pothina <dharhas@gmail.com>",
"keywords": "GIS, bathymetry, hydroacoustic, interpolation, lakes, reservoirs, sediment, survey",
"author": null,
"author_email": "Dharhas Pothina <dharhas@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/de/0e/0333f97ae7c54b55dbec4b890b67e5d40482b448bf98d004ad017bfd6bf3/hydrosurvey-0.4.1.tar.gz",
"platform": null,
"description": "# HydroSurvey Tools\n\nThis is a groundup rewrite using modern pydata tools of algorithms originally described in my 2011 SciPy Talk - [Improving efficiency and repeatability of lake volume estimates using Python](https://proceedings.scipy.org/articles/Majora-ebaa42b7-013).\n\n## Installation\n\n1. Download this code with git or download a zip file (click the green code icon) and unzip\n2. Download and install pixi from https://prefix.dev/\n3. Open a cmd/terminal window and navigate to the folder that contains this software\n4. run `pixi install` to install the software\n\n## Usage\n\n1. Open a cmd/terminal window in the folder with the code\n2. run `pixi shell` in the terminal to activate the environment\n3. now you will have a tool called hstools, if you type `hstools` you will get a help message.\n4. `hstools new-config <config.toml>` will help you created a new config file with a guided wizard\n5. `hstools interpolate-lake <config.toml>` will run the interpolation\n6. `hstools compute-eac <dem.tif> <output.csv>` will create an elevation area capacity table from a dem\n7. `hstools gui` launches a gui version of the tool\n\n## Anisotropic Elliptical Inverse Distance Weighting (AEIDW) Lake Interpolation Algorithm\n\n### Input files and parameters required\n\n- CSV file with survey data, fields: x-coord, y-coord, current surface elevation, preimpoundment elevation (optional)\n - elevation: lake elevation at the boundary\n - max segment length: this is used to add more vertices to the centerline to improve interpolation accuracy\n- Shapefile of Lake boundary at a particular elevation. Elevation value set in the attribute table\n- Interpolation Centerline Shapefile: This defines the direction of interpolation in a particular polygon\n - polygon id: foreign key used to math centerlines with polygons\n - max segment lenght: this is used to add more vertices to the centerline to improve interpolation accuracy\n- Interpolation Polygons Shapefile, in the attribute table the following values are set for each polygon\n - polygon id: foreign key used to connect polygons to centerlines\n - grid spacing: density of generated target points in each polygon that the survey data is interpolated to\n - priority: priority of the polygon, when polygons overlap target points in the overlap region use survey points from the higher priority polygon\n - interpolation method: type of interpolation used in the polygon (currently AEIDW or CONSTANT)\n - interpolation params: parameters needed by interpolation methos (currently ellipsivity for AEIDW or elevation value for CONSTANT)\n - Polygon Buffer: Use some survey data in the buffer region around the polygon to avoid interpolation artifacts near the polygon boundaries\n - nearest nieghbors: how many neighbors to include in the interpolation to each target point\n\n### Algorithm\n\nThe essential idea of AEIDW algorithm is that along channel bathymetric depths are likely to be more similar to each other than across channel. So we transform the data into a coordinate system that follows the channel and then scale the across channel coordinate by an ellipsivity factor. After this we do a regular inverse distance wieghting. Since the across channel points are now further away, this causes the interpolation to weight along channel survey data higher than across channel survey data.\n\n1. Add boundary data to survey data\n2. iterate through polygons\n3. Generate target points in each polygon\n4. Convert survey data and target points in each polygon into \"S-N\" coordinates, where S=distance along centerline and N-perpendicular distance from centerline\n5. Multiply \"N\" coordinate by \"ellipsivity\" factor.\n6. Interpolate data using Inverse Distance Weighting algorithm\n7. merge the target points with the original survey data\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tools for processing and analyzing hydroacoustic survey data from lakes and reservoirs",
"version": "0.4.1",
"project_urls": {
"Changelog": "https://github.com/dharhas/hydrosurvey/releases",
"Documentation": "https://github.com/dharhas/hydrosurvey#readme",
"Homepage": "https://github.com/dharhas/hydrosurvey",
"Issues": "https://github.com/dharhas/hydrosurvey/issues",
"Repository": "https://github.com/dharhas/hydrosurvey"
},
"split_keywords": [
"gis",
" bathymetry",
" hydroacoustic",
" interpolation",
" lakes",
" reservoirs",
" sediment",
" survey"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "92b33d8a233e2ebd5685c3a1209b318c97f810e17d60ef2df8bae074236c0d88",
"md5": "1a0c0113a1502ab0c85f146aad55a4fa",
"sha256": "0a4b9070891a2026df5350abff3d3dce88e855e23066bbb41eb0bf4ad45139a8"
},
"downloads": -1,
"filename": "hydrosurvey-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a0c0113a1502ab0c85f146aad55a4fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 34402,
"upload_time": "2025-07-28T04:16:27",
"upload_time_iso_8601": "2025-07-28T04:16:27.188131Z",
"url": "https://files.pythonhosted.org/packages/92/b3/3d8a233e2ebd5685c3a1209b318c97f810e17d60ef2df8bae074236c0d88/hydrosurvey-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "de0e0333f97ae7c54b55dbec4b890b67e5d40482b448bf98d004ad017bfd6bf3",
"md5": "aad168979419288af81beff81fdfa478",
"sha256": "849aa35bc7f78fac313e1c877e159eee6f2040b26b654c2421eaeeb0ef9cea3f"
},
"downloads": -1,
"filename": "hydrosurvey-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "aad168979419288af81beff81fdfa478",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 79689391,
"upload_time": "2025-07-28T04:23:13",
"upload_time_iso_8601": "2025-07-28T04:23:13.478953Z",
"url": "https://files.pythonhosted.org/packages/de/0e/0333f97ae7c54b55dbec4b890b67e5d40482b448bf98d004ad017bfd6bf3/hydrosurvey-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 04:23:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dharhas",
"github_project": "hydrosurvey",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hydrosurvey"
}
JSON
