Skip to content

Commit

Permalink
update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@cyschneck
cyschneck committed Jul 9, 2023
1 parent 25060d4 commit 57524fe
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 17 deletions.
41 changes: 24 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
![PyPi](https://img.shields.io/pypi/v/centerline-width)
![license](https://img.shields.io/github/license/cyschneck/centerline-width)
[![NSF-2141064](https://img.shields.io/badge/NSF-2141064-blue)](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2141064&HistoricalAwards=false)
![PyPi-Versions](https://img.shields.io/pypi/pyversions/centerline-width)
[![pytests](https://github.com/cyschneck/centerline-width/actions/workflows/pytests.yml/badge.svg)](https://github.com/cyschneck/centerline-width/actions/workflows/pytests.yml)

Find the centerline and width of rivers based on the latitude and longitude positions from the right and left bank
Expand Down Expand Up @@ -167,11 +168,11 @@ centerline_width.riverCenterline(csv_data=None,
```
* **[REQUIRED]** csv_data (string): File location of the text file to convert
* [OPTIONAL] optional_cutoff (int): Include only the first x number of the data to chart (useful for debugging)
* [OPTIONAL] interpolate_data (bool): Interpolate between existing data by adding additional points
* [OPTIONAL] interpolate_data (boolean): Interpolate between existing data by adding additional points
* [OPTIONAL] interpolate_n (int): Number of additional points to add between existing data, defaults to 5 (note: larger numbers will take exponentially longer to run, recommends less than 15)
* [OPTIONAL] interpolate_n_centerpoints (int): Number of points used to interpolate the Voronoi centerline, defaults to the the length of the data frame (df_len)
* [OPTIONAL] equal_distance (int): Equal distance between points (in meters) used to interpolate the Voronoi centerline, defaults 10 meters
* [OPTIONAL] ellipsoid (string): Ellipsoid definition of Earth to provide size and shape for built-in functions to convert degrees to meters, options include (is sensitive to case): ["GRS80", "airy", "bessel", "clrk66", "intl", "WGS60", "WGS66", "WGS72", "WGS84", "sphere"] for more details: ["Built-in ellpsoid defintions"](https://proj.org/en/9.2/usage/ellipsoids.html#built-in-ellipsoid-definitions), defaults to "WGS84"
* [OPTIONAL] ellipsoid (string): Ellipsoid definition of Earth to provide size and shape for built-in functions to convert degrees to meters, options include (is sensitive to case): ["GRS80", "airy", "bessel", "clrk66", "intl", "WGS60", "WGS66", "WGS72", "WGS84", "sphere"] for more details: ["Built-in ellipsoid defintions"](https://proj.org/en/9.2/usage/ellipsoids.html#built-in-ellipsoid-definitions), defaults to "WGS84"

**Solutions for sparse data:**

Expand All @@ -193,24 +194,24 @@ centerline_width.riverCenterline(csv_data=None,
* rightBankLength (float): Length of the right bank of the river (in km)
* leftBankLength (float): Length of the left bank of the river (in km)

**Object (class) additional atttributes:**
**Object (class) additional attributes:**

* river_name (string): name of object, set to the csv_data string
* left_bank_coordinates (list of tuples): list of coordinates of the left bank generated from the csv file (`[(x, y), (x, y)]`)
* right_bank_coordinates (list of tuples) list of coordinates of the right bank generated from the csv file (`[(x, y), (x, y)]`)
* df_len (int): Length of the data frame of the csv data (spliced by the optional_cutoff)
* equal_distance (int): Distance between points (in meters) used in centerlineEqualDistance, defaults to points every 10 meters
* ellipsoid (string): Built-in ellipsoid defintion of Earth to determine how degrees are converted to meters used by centerlineEqualDistance, defaults to "WGS84"
* bank_polygon (Shapley Polygon): Multi-sided polygon generated to encapsulate river bank (used to define an inside and an outside of the river)
* ellipsoid (string): Built-in ellipsoid definition of Earth to determine how degrees are converted to meters used by centerlineEqualDistance, defaults to "WGS84"
* bank_polygon (Shapley Polygon): Multi-sided polygon generated to encapsulate riverbank (used to define an inside and an outside of the river)
* top_bank (Shapley Linestring): Linestring that represents the top of the river/polygon
* bottom_bank (Shapley Linestring): Linestring that represents the bottom of the river/polygon
* starting_node (tuple): Tuple of the starting position (latitude and longitude) of the centerline path
* ending_node (tuple): Tuple of the end position (latitude and longitude) of the centerline path
* bank_voronoi (scipy Voronoi object): Voronoi generated by left/right banks
* x_voronoi_ridge_point (list of tuples): X positions on Voronoi ridge (starting Latitude position to ending Latitude position)
* y_voronoi_ridge_point (list of tuples): Y position on Voronoi ridge (starting Longitude position to ending Longitude position)
* interpolate_data (bool): if interpolating between existing data, defaults to False
* interpolate_n (int): specifies how many additional points will be added between points along the river bank when interpolating data, defaults to 5
* interpolate_data (boolean): if interpolating between existing data, defaults to False
* interpolate_n (int): specifies how many additional points will be added between points along the riverbank when interpolating data, defaults to 5
* interpolate_n_centerpoints (int): specifies how many points will be used to interpolate the Voronoi centerline, defaults to the length of the data frame (df_len)

```python
Expand Down Expand Up @@ -280,6 +281,8 @@ river_object.saveCenterlineCSV(save_to_csv="centerline_coordinates.csv", centerl
```
Returns a csv with the Latitude and Longitude coordinates of the specified centerline with column headers with centerline type: `Smoothed Centerline Latitude (Deg), Smoothed Centerline Longitude (Deg)`

Note: it is best practice to plot the centerline with `plotCenterline()` to ensure that the results saved are as expected

### Save Centerline Coordinates to a .MAT File
Save the centerline coordinates to a .mat file with columns for latitude and longitude

Expand All @@ -298,6 +301,8 @@ river_object.saveCenterlineMAT(save_to_mat="centerline_coordinates.mat", centerl
```
Returns a .mat file with the Latitude and Longitude coordinates of the specified centerline with column headers with centerline type: `Smoothed_Centerline_Latitude_(Deg), Smoothed_Centerline_Longitude_(Deg)`

Note: it is best practice to plot the centerline with `plotCenterline()` to ensure that the results saved are as expected

### Return Length of Centerline
Return the length of the centerline found between the left and right bank generated by the Voronoi diagram
```
Expand Down Expand Up @@ -357,9 +362,9 @@ plotCenterlineWidth(plot_title=None,
* [OPTIONAL] save_plot_name (string): Save the plot with a given name and location
* [OPTIONAL] display_true_centerline (boolean): Display generated true centerline based on Voronoi diagrams
* [OPTIONAL] transect_span_distance (int): Sum up n number of points around a center point to determine the slope (increase to decrease the impact of sudden changes), defaults to 6, must be greater than 2 (since the slope is found from the difference in position between two points), measured orthogonal to the centerline
* [OPTIONAL] apply_smoothing (bool): Apply a B-spline smoothing to centerline
* [OPTIONAL] flag_intersections (bool): Display intersecting width lines as red in graph, defaults to True
* [OPTIONAL] remove_intersections (bool): Iterative remove intersecting lines, to maintain the most width lines, but return only non-intersecting width lines, defaults to False
* [OPTIONAL] apply_smoothing (boolean): Apply a B-spline smoothing to centerline
* [OPTIONAL] flag_intersections (boolean): Display intersecting width lines as red in graph, defaults to True
* [OPTIONAL] remove_intersections (boolean): Remove intersecting lines (but maintain the most width lines as possible) and only return non-intersecting width lines, defaults to False

**apply_smoothing**

Expand All @@ -371,7 +376,7 @@ apply_smoothing applies a spline to smooth the centerline points created by the

**transect_span_distance**

Transect span describes the number of points that are averaged to generated a width line (example: transect_span_distance=3, average of three slopes)
Transect span describes the number of points that are averaged to generate a width line (example: transect_span_distance=3, average of three slopes)

![transect_span_distance](https://user-images.githubusercontent.com/22159116/227870492-69d105b2-0d3e-4d50-90d9-e938400a58fb.png)
| transect_span_distance=6 | transect_span_distance=30 |
Expand All @@ -380,7 +385,7 @@ Transect span describes the number of points that are averaged to generated a wi

**remove_intersections**

remove_intersections will remove the width lines that intersect other lines (that could be creating unrepresentative long width lines). Intersections are removed first in order from most to least (to ensure that the most width lines as possible are kept) and then, based on the longer of two intersecting lines
remove_intersections will remove the width lines that intersect other lines (that could be creating unrepresentative long width lines). Intersections are removed first in order from most to least number of intersections and then based on the longer of two intersecting lines. This ensures that the most width lines as possible are kept

Intersecting lines are flagged in red by default (flag_intersections=True)

Expand All @@ -406,8 +411,8 @@ riverWidthFromCenterline(transect_span_distance=3,
save_to_csv=None)
```
* [OPTIONAL] transect_span_distance (int): Sum up n number of points around a center point to determine the slope (increase to decrease the impact of sudden changes), defaults to 6, must be greater than 2 (since the slope is found from the difference in position between two points), measured orthogonal to the centerline
* [OPTIONAL] apply_smoothing (bool): Apply a B-spline smoothing to centerline
* [OPTIONAL] remove_intersections (bool): Iterative remove intersecting lines, to maintain the most width lines, but return only non-intersecting width lines, defaults to True
* [OPTIONAL] apply_smoothing (boolean): Apply a B-spline smoothing to centerline
* [OPTIONAL] remove_intersections (boolean): Iterative remove intersecting lines, to maintain the most width lines, but return only non-intersecting width lines, defaults to True
* [OPTIONAL] save_to_csv (string): CSV filename to output width, defaults to None (no file is saved), requires a .csv extension (Column Headers: `Centerline Latitude (Deg)", "Centerline Longitude (Deg)", "Width (<units specified>)`)

Important note, when using `apply_smoothing=True`, the centerline generated is the result of evenly spaced coordinates generated from the original Voronoi coordinates, so the smoothed coordinates may not match exactly to the original centerline coordinates. When `apply_smoothing=False`, width lines are generated from the evenly spaced centerline coordinates
Expand All @@ -421,6 +426,8 @@ river_width_dict = river_object.riverWidthFromCenterline(transect_span_distance=
```
Width dictionary = `{(-92.86792084788995, 30.037769672351182): 0.10969163557087018, (-92.86795038641004, 30.03769867854198): 0.10794219579997719}`

Note: it is best practice to plot the centerline and width with same arguments in `plotCenterlineWidth()` to ensure that the results when `save_to_csv=True` are as expected

## Documentation and Algorithm to Determine Centerline

The centerline is defined by the greatest distance from the right and left bank, created from a Voronoi Diagram. The remaining paths within the river are filtered through Dijkstra's algorithm to find the shortest path that is the centerline
Expand All @@ -443,7 +450,7 @@ With the vertices removed, it is possible to form multiple unconnected graphs wi
![example+png](https://raw.githubusercontent.com/cyschneck/centerline-width/main/data/doc_examples/example7.png)

### Find the shortest path from the starting node to the ending node ([Dijkstra's Algorithm](https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.shortest_paths.generic.shortest_path.html#networkx.algorithms.shortest_paths.generic.shortest_path))
| Points on River Bank | NetworkX Graph of Points on River Bank |
| Points on Riverbank | NetworkX Graph of Points on Riverbank |
| ------------- | ------------- |
| ![example+png](https://raw.githubusercontent.com/cyschneck/centerline-width/main/data/doc_examples/example10.png) | ![example+png](https://raw.githubusercontent.com/cyschneck/centerline-width/main/data/doc_examples/example9.png) |

Expand All @@ -464,7 +471,7 @@ Points that only have one connection are removed, but limiting the number of con
### Wide Start/End of River
If the data starts or ends with a large width, it is possible for the starting/ending nodes to end up in the wrong position
![example+png](https://raw.githubusercontent.com/cyschneck/centerline-width/main/data/doc_examples/invalid_example3.png)
Currently, the starting node is determined by the closest node to the top of the bank (in green) and the ending node is determined by the closest node to the bottom of the bank (in red) that sits along the longest path
Currently, the starting node is determined by the closest node on the path to the top of the bank (in green) and the ending node is determined by the closest node on the path to the bottom of the bank (in red) that sits along the longest path

### Invalid Polygon
A polygon is formed to encapsulate the river with the given data (to determine the inside and outside of the river). The top and bottom are connected by a straight line from the start/end of the available data. As a result, it is possible for this straight line to overlap and create an invalid polygon.
Expand All @@ -483,7 +490,7 @@ If the data is too small, a centerline and its coordinates cannot not be found (
![example+png](https://raw.githubusercontent.com/cyschneck/centerline-width/main/data/doc_examples/invalid_example2.png)
Can be fixed by expanding the data until the polygon is large enough to contain at least two different vertex points

### Invalid Top and Bottom Bank Postions (flipBankDirection = True)
### Invalid Top and Bottom Bank Positions (flipBankDirection = True)
Error: `WARNING: Invalid Polygon Due to Flipped Banks, fix recommendation: rerun convertColumnsToCSV() and set flipBankDirection=True (or reset to default 'False' if currently set to flipBankDirection=True)`

If the data for the left and right riverbanks are generated in reverse order, they will be read in the incorrect order and the graph will find the invalid top and bottom of the bank
Expand Down
Binary file modified data/doc_examples/river_coords_width.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 57524fe

Please sign in to comment.