scgraph 2.8.2__tar.gz → 2.10.0__tar.gz

{scgraph-2.8.2/scgraph.egg-info → scgraph-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scgraph
-Version: 2.8.2
+Version: 2.10.0
 Summary: Determine an approximate route between two points on earth.
 Author-email: Connor Makowski <conmak@mit.edu>
 Project-URL: Homepage, https://github.com/connor-makowski/scgraph
@@ -131,6 +131,24 @@ output = marnet_geograph.get_shortest_path(
 print('Length: ',output['length']) #=> Length:  19596.4653
 ```
 
+Adding in a few additional parameters to the `get_shortest_path` function can change the output format and performance of the calculation.
+```py
+# Use a maritime network geograph
+from scgraph.geographs.marnet import marnet_geograph
+
+# Get the shortest maritime path between Shanghai, China and Savannah, Georgia, USA
+output = marnet_geograph.get_shortest_path(
+    origin_node={"latitude": 31.23,"longitude": 121.47},
+    destination_node={"latitude": 32.08,"longitude": -81.09},
+    output_units='km',
+    node_addition_lat_lon_bound=180, # Optional: The maximum distance in degrees to consider nodes when attempting to add the origin and destination nodes to the graph
+    node_addition_type='quadrant', # Optional: Instead of connecting the origin node to the graph by the closest node, connect it to the closest node in each direction (NE, NW, SE, SW) if found within the node_addition_lat_lon_bound
+    destination_node_addition_type='all', # Optional: Instead of connecting the destination node to the graph by the closest node, connect it to all nodes found within the node_addition_lat_lon_bound
+    # When destination_node_addition_type='all' is set with a node_addition_lat_lon_bound=180, this will guarantee a solution can be found since the destination node will also connect to the origin node
+)
+print('Length: ',output['length']) #=> Length:  19596.4653
+```
+
 In the above example, the `output` variable is a dictionary with two keys: `length` and `coordinate_path`.
 
 - `length`: The distance between the passed origin and destination when traversing the graph along the shortest path
@@ -258,6 +276,74 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
+### Building your own Geographs from Open Source Data
+You can build your own geographs using various tools and data sources. For example, you can use OpenStreetMap data to create a high fidelity geograph for a specific area.
+
+Expand the secion below for a step by step guide on how to create a geograph from OpenStreetMap data.
+<details>
+<summary>Click to see an example for Michigan, USA</summary>
+
+For this example, we will use some various tools to create a geograph for highways (including seconday highways) in Michigan, USA.
+
+Download an OSM PBF file using the AWS CLI:
+- Geofabrik is a good source for smaller OSM PBF files. See: https://download.geofabrik.de/
+- To keep things generalizable, you can also download the entire planet OSM PBF file using AWS. But you should consider downloading a smaller region if you are only interested in a specific area. 
+    - Note: For this, you will need to install the AWS CLI.
+    - Note: The planet OSM PBF file is very large (About 100GB)
+        ```
+        aws s3 cp s3://osm-pds/planet-latest.osm.pbf .
+        ```
+- Use Osmium to filter and extract the highways from the OSM PBF file.
+    - Install osmium on macOS:
+        ```
+        brew install osmium-tool
+        ```
+    - Install osmium on Ubuntu:
+        ```
+        sudo apt-get install osmium-tool
+        ```
+- Download a Poly file for the area you are interested in. This is a polygon file that defines the area you want to extract from the OSM PBF file.
+    - For Michigan, you can download the poly file from Geofabrik:
+        ```
+        curl https://download.geofabrik.de/north-america/us/michigan.poly > michigan.poly
+        ```
+    - Google around to find an appropriate poly file for your area of interest.
+- Filter and extract as GeoJSON (EG: Michigan) substituting the poly and pbf file names as needed:
+    ```
+    osmium extract -p michigan.poly --overwrite -o michigan.osm.pbf planet-latest.osm.pbf
+    ```
+- Filter the OSM PBF file to only areas of interest and export to GeoJSON:
+    - See: https://wiki.openstreetmap.org/wiki/
+    - EG For Highways, see: https://wiki.openstreetmap.org/wiki/Key:highway
+    ```
+    osmium tags-filter michigan.osm.pbf w/highway=motorway,trunk,primary,motorway_link,trunk_link,primary_link,secondary,secondary_link,tertiary,tertiary_link -t --overwrite -o michigan_roads.osm.pbf
+    osmium export michigan_roads.osm.pbf -f geojson --overwrite -o michigan_roads.geojson
+    ``` 
+
+- Simplify the geojson
+    - This uses some tools in the SCGraph library as well as Mapshaper to simplify the geojson files.
+    - Mapshaper is a CLI and web tool for simplifying and editing geojson files.
+    - To install Mapshaper for CLI use, use NPM:
+        ```
+        npm install -g mapshaper
+        ```
+    - Mapshaper is particularly helpful since it repairs intersections in the lines which is crutial for geographs to work properly.
+    - Mapshaper, however, does not handle larger files very well, so it is recommended to simplify the geojson file first using the `scgraph.helpers.geojson.simplify_geojson` function first to reduce the size of the file.
+    - Make sure to tailor the parameters to your needs.
+    ```
+    python -c "from scgraph.helpers.geojson import simplify_geojson; simplify_geojson('michigan_roads.geojson', 'michigan_roads_simple.geojson', precision=4, pct_to_keep=100, min_points=3, silent=False)"
+    mapshaper michigan_roads_simple.geojson -simplify 10% -filter-fields -o force michigan_roads_simple.geojson
+    mapshaper michigan_roads_simple.geojson -snap -clean -o force michigan_roads_simple.geojson
+    ```
+- Load the newly created geojson file as a geograph:
+    - Note: The `GeoGraph.load_from_geojson` function is used to load the geojson file as a geograph.
+    - This will create a geograph that can be used to calculate shortest paths between points on the graph.
+    ```
+    from scgraph import GeoGraph
+    michigan_roads_geograph = GeoGraph.load_from_geojson('michigan_roads_simple.geojson')
+    ```
+</details>
+
 ### Custom Graphs and Geographs
 Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
 

{scgraph-2.8.2 → scgraph-2.10.0}/README.md

@@ -115,6 +115,24 @@ output = marnet_geograph.get_shortest_path(
 print('Length: ',output['length']) #=> Length:  19596.4653
 ```
 
+Adding in a few additional parameters to the `get_shortest_path` function can change the output format and performance of the calculation.
+```py
+# Use a maritime network geograph
+from scgraph.geographs.marnet import marnet_geograph
+
+# Get the shortest maritime path between Shanghai, China and Savannah, Georgia, USA
+output = marnet_geograph.get_shortest_path(
+    origin_node={"latitude": 31.23,"longitude": 121.47},
+    destination_node={"latitude": 32.08,"longitude": -81.09},
+    output_units='km',
+    node_addition_lat_lon_bound=180, # Optional: The maximum distance in degrees to consider nodes when attempting to add the origin and destination nodes to the graph
+    node_addition_type='quadrant', # Optional: Instead of connecting the origin node to the graph by the closest node, connect it to the closest node in each direction (NE, NW, SE, SW) if found within the node_addition_lat_lon_bound
+    destination_node_addition_type='all', # Optional: Instead of connecting the destination node to the graph by the closest node, connect it to all nodes found within the node_addition_lat_lon_bound
+    # When destination_node_addition_type='all' is set with a node_addition_lat_lon_bound=180, this will guarantee a solution can be found since the destination node will also connect to the origin node
+)
+print('Length: ',output['length']) #=> Length:  19596.4653
+```
+
 In the above example, the `output` variable is a dictionary with two keys: `length` and `coordinate_path`.
 
 - `length`: The distance between the passed origin and destination when traversing the graph along the shortest path
@@ -242,6 +260,74 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
+### Building your own Geographs from Open Source Data
+You can build your own geographs using various tools and data sources. For example, you can use OpenStreetMap data to create a high fidelity geograph for a specific area.
+
+Expand the secion below for a step by step guide on how to create a geograph from OpenStreetMap data.
+<details>
+<summary>Click to see an example for Michigan, USA</summary>
+
+For this example, we will use some various tools to create a geograph for highways (including seconday highways) in Michigan, USA.
+
+Download an OSM PBF file using the AWS CLI:
+- Geofabrik is a good source for smaller OSM PBF files. See: https://download.geofabrik.de/
+- To keep things generalizable, you can also download the entire planet OSM PBF file using AWS. But you should consider downloading a smaller region if you are only interested in a specific area. 
+    - Note: For this, you will need to install the AWS CLI.
+    - Note: The planet OSM PBF file is very large (About 100GB)
+        ```
+        aws s3 cp s3://osm-pds/planet-latest.osm.pbf .
+        ```
+- Use Osmium to filter and extract the highways from the OSM PBF file.
+    - Install osmium on macOS:
+        ```
+        brew install osmium-tool
+        ```
+    - Install osmium on Ubuntu:
+        ```
+        sudo apt-get install osmium-tool
+        ```
+- Download a Poly file for the area you are interested in. This is a polygon file that defines the area you want to extract from the OSM PBF file.
+    - For Michigan, you can download the poly file from Geofabrik:
+        ```
+        curl https://download.geofabrik.de/north-america/us/michigan.poly > michigan.poly
+        ```
+    - Google around to find an appropriate poly file for your area of interest.
+- Filter and extract as GeoJSON (EG: Michigan) substituting the poly and pbf file names as needed:
+    ```
+    osmium extract -p michigan.poly --overwrite -o michigan.osm.pbf planet-latest.osm.pbf
+    ```
+- Filter the OSM PBF file to only areas of interest and export to GeoJSON:
+    - See: https://wiki.openstreetmap.org/wiki/
+    - EG For Highways, see: https://wiki.openstreetmap.org/wiki/Key:highway
+    ```
+    osmium tags-filter michigan.osm.pbf w/highway=motorway,trunk,primary,motorway_link,trunk_link,primary_link,secondary,secondary_link,tertiary,tertiary_link -t --overwrite -o michigan_roads.osm.pbf
+    osmium export michigan_roads.osm.pbf -f geojson --overwrite -o michigan_roads.geojson
+    ``` 
+
+- Simplify the geojson
+    - This uses some tools in the SCGraph library as well as Mapshaper to simplify the geojson files.
+    - Mapshaper is a CLI and web tool for simplifying and editing geojson files.
+    - To install Mapshaper for CLI use, use NPM:
+        ```
+        npm install -g mapshaper
+        ```
+    - Mapshaper is particularly helpful since it repairs intersections in the lines which is crutial for geographs to work properly.
+    - Mapshaper, however, does not handle larger files very well, so it is recommended to simplify the geojson file first using the `scgraph.helpers.geojson.simplify_geojson` function first to reduce the size of the file.
+    - Make sure to tailor the parameters to your needs.
+    ```
+    python -c "from scgraph.helpers.geojson import simplify_geojson; simplify_geojson('michigan_roads.geojson', 'michigan_roads_simple.geojson', precision=4, pct_to_keep=100, min_points=3, silent=False)"
+    mapshaper michigan_roads_simple.geojson -simplify 10% -filter-fields -o force michigan_roads_simple.geojson
+    mapshaper michigan_roads_simple.geojson -snap -clean -o force michigan_roads_simple.geojson
+    ```
+- Load the newly created geojson file as a geograph:
+    - Note: The `GeoGraph.load_from_geojson` function is used to load the geojson file as a geograph.
+    - This will create a geograph that can be used to calculate shortest paths between points on the graph.
+    ```
+    from scgraph import GeoGraph
+    michigan_roads_geograph = GeoGraph.load_from_geojson('michigan_roads_simple.geojson')
+    ```
+</details>
+
 ### Custom Graphs and Geographs
 Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
 

{scgraph-2.8.2 → scgraph-2.10.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scgraph"
-version = "2.8.2"
+version = "2.10.0"
 description = "Determine an approximate route between two points on earth."
 authors = [
     {name="Connor Makowski", email="conmak@mit.edu"}

{scgraph-2.8.2 → scgraph-2.10.0}/scgraph/__init__.py

@@ -116,6 +116,24 @@ output = marnet_geograph.get_shortest_path(
 print('Length: ',output['length']) #=> Length:  19596.4653
 ```
 
+Adding in a few additional parameters to the `get_shortest_path` function can change the output format and performance of the calculation.
+```py
+# Use a maritime network geograph
+from scgraph.geographs.marnet import marnet_geograph
+
+# Get the shortest maritime path between Shanghai, China and Savannah, Georgia, USA
+output = marnet_geograph.get_shortest_path(
+    origin_node={"latitude": 31.23,"longitude": 121.47},
+    destination_node={"latitude": 32.08,"longitude": -81.09},
+    output_units='km',
+    node_addition_lat_lon_bound=180, # Optional: The maximum distance in degrees to consider nodes when attempting to add the origin and destination nodes to the graph
+    node_addition_type='quadrant', # Optional: Instead of connecting the origin node to the graph by the closest node, connect it to the closest node in each direction (NE, NW, SE, SW) if found within the node_addition_lat_lon_bound
+    destination_node_addition_type='all', # Optional: Instead of connecting the destination node to the graph by the closest node, connect it to all nodes found within the node_addition_lat_lon_bound
+    # When destination_node_addition_type='all' is set with a node_addition_lat_lon_bound=180, this will guarantee a solution can be found since the destination node will also connect to the origin node
+)
+print('Length: ',output['length']) #=> Length:  19596.4653
+```
+
 In the above example, the `output` variable is a dictionary with two keys: `length` and `coordinate_path`.
 
 - `length`: The distance between the passed origin and destination when traversing the graph along the shortest path
@@ -243,6 +261,74 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
+### Building your own Geographs from Open Source Data
+You can build your own geographs using various tools and data sources. For example, you can use OpenStreetMap data to create a high fidelity geograph for a specific area.
+
+Expand the secion below for a step by step guide on how to create a geograph from OpenStreetMap data.
+<details>
+<summary>Click to see an example for Michigan, USA</summary>
+
+For this example, we will use some various tools to create a geograph for highways (including seconday highways) in Michigan, USA.
+
+Download an OSM PBF file using the AWS CLI:
+- Geofabrik is a good source for smaller OSM PBF files. See: https://download.geofabrik.de/
+- To keep things generalizable, you can also download the entire planet OSM PBF file using AWS. But you should consider downloading a smaller region if you are only interested in a specific area. 
+    - Note: For this, you will need to install the AWS CLI.
+    - Note: The planet OSM PBF file is very large (About 100GB)
+        ```
+        aws s3 cp s3://osm-pds/planet-latest.osm.pbf .
+        ```
+- Use Osmium to filter and extract the highways from the OSM PBF file.
+    - Install osmium on macOS:
+        ```
+        brew install osmium-tool
+        ```
+    - Install osmium on Ubuntu:
+        ```
+        sudo apt-get install osmium-tool
+        ```
+- Download a Poly file for the area you are interested in. This is a polygon file that defines the area you want to extract from the OSM PBF file.
+    - For Michigan, you can download the poly file from Geofabrik:
+        ```
+        curl https://download.geofabrik.de/north-america/us/michigan.poly > michigan.poly
+        ```
+    - Google around to find an appropriate poly file for your area of interest.
+- Filter and extract as GeoJSON (EG: Michigan) substituting the poly and pbf file names as needed:
+    ```
+    osmium extract -p michigan.poly --overwrite -o michigan.osm.pbf planet-latest.osm.pbf
+    ```
+- Filter the OSM PBF file to only areas of interest and export to GeoJSON:
+    - See: https://wiki.openstreetmap.org/wiki/
+    - EG For Highways, see: https://wiki.openstreetmap.org/wiki/Key:highway
+    ```
+    osmium tags-filter michigan.osm.pbf w/highway=motorway,trunk,primary,motorway_link,trunk_link,primary_link,secondary,secondary_link,tertiary,tertiary_link -t --overwrite -o michigan_roads.osm.pbf
+    osmium export michigan_roads.osm.pbf -f geojson --overwrite -o michigan_roads.geojson
+    ``` 
+
+- Simplify the geojson
+    - This uses some tools in the SCGraph library as well as Mapshaper to simplify the geojson files.
+    - Mapshaper is a CLI and web tool for simplifying and editing geojson files.
+    - To install Mapshaper for CLI use, use NPM:
+        ```
+        npm install -g mapshaper
+        ```
+    - Mapshaper is particularly helpful since it repairs intersections in the lines which is crutial for geographs to work properly.
+    - Mapshaper, however, does not handle larger files very well, so it is recommended to simplify the geojson file first using the `scgraph.helpers.geojson.simplify_geojson` function first to reduce the size of the file.
+    - Make sure to tailor the parameters to your needs.
+    ```
+    python -c "from scgraph.helpers.geojson import simplify_geojson; simplify_geojson('michigan_roads.geojson', 'michigan_roads_simple.geojson', precision=4, pct_to_keep=100, min_points=3, silent=False)"
+    mapshaper michigan_roads_simple.geojson -simplify 10% -filter-fields -o force michigan_roads_simple.geojson
+    mapshaper michigan_roads_simple.geojson -snap -clean -o force michigan_roads_simple.geojson
+    ```
+- Load the newly created geojson file as a geograph:
+    - Note: The `GeoGraph.load_from_geojson` function is used to load the geojson file as a geograph.
+    - This will create a geograph that can be used to calculate shortest paths between points on the graph.
+    ```
+    from scgraph import GeoGraph
+    michigan_roads_geograph = GeoGraph.load_from_geojson('michigan_roads_simple.geojson')
+    ```
+</details>
+
 ### Custom Graphs and Geographs
 Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)