Merge pull request jiawlu#19 from xyluo25/master

v0.7.4

.gitignore

@@ -1,3 +1,136 @@
 *.vscode/*
+*.pyc
+
+# Byte-compiled / optimized / DLL files
 *__pycache__/*
-*.pyc
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+sources/*
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.

README.rst

@@ -17,9 +17,9 @@ and applications on traffic modeling.
 Publication
 ====================================
 
-Lu, J., & Zhou, X.S. (2023). Virtual track networks: A hierarchical modeling framework and 
-open-source tools for simplified and efficient connected and automated mobility (CAM) system 
-design based on general modeling network specification (GMNS). Transportation Research 
+Lu, J., & Zhou, X.S. (2023). Virtual track networks: A hierarchical modeling framework and
+open-source tools for simplified and efficient connected and automated mobility (CAM) system
+design based on general modeling network specification (GMNS). Transportation Research
 Part C: Emerging Technologies, 153, 104223. `paper link`_
 
 
@@ -88,10 +88,35 @@ You can use the following code to get the relation id of a place of interest and
     # e.g. "Tempe, Arizona, United States"
     # e.g. "Arizona, US"
     # e.g. "Beijing Jiaotong University, Beijing, China"
-    >>> rel = og.OSM_RelationID_Finder('Arizona State University')
+    >>> rel_id = og.getOSMRelationID('Arizona State University')
+    >>> rel_id
+        Info: Found relation id 3444656 from web
+        Info: location of the place of interest:
+        {
+            "place_id": 318528634,
+            "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
+            "osm_type": "relation",
+            "osm_id": 3444656,
+            "lat": "33.4213174",
+            "lon": "-111.93316305413154",
+            "class": "amenity",
+            "type": "university",
+            "place_rank": 30,
+            "importance": 0.5547365758311374,
+            "addresstype": "amenity",
+            "name": "Arizona State University",
+            "display_name": "Arizona State University, 1151, South Forest Avenue, Tempe Junction, Tempe, Maricopa County, Arizona, 85281, United States",
+            "boundingbox": [
+                "33.4102062",
+                "33.4329786",
+                "-111.9411651",
+                "-111.9092447"
+            ]
+        }
+    3444656
 
     # download the corresponding osm file
-    >>> og.downloadOSMdata(rel.rel_id, 'asu.osm')
+    >>> og.downloadOSMData(rel_id, 'asu.osm')
 
 
 Visualization

docs/source/acknowledgement.rst

@@ -7,11 +7,11 @@ Grant No. CMMI 1663657 "Collaborative Research: Real-time Management of Large Fl
 Self-Driving Vehicles Using Virtual CyberTracks"
 
 The second author also thanks for the early support from FHWA project titled "The Effective
-Integration of Analysis, Modeling, and Simulation Tools - AMS Data hub Concept of Opeartions".
+Integration of Analysis, Modeling, and Simulation Tools - AMS Data hub Concept of Operations".
 https://www.fhwa.dot.gov/publications/research/operations/13036/004.cfm
 
-Many thanks for GMNS specification efforts led by Scott Smith and Ian Berg from Volpe Center, 
-USDOT. Their TRB poster can be found at https://github.com/zephyr-data-specs/GMNS/blob/TRB/TRBPoster_22-02127.pdf  
+Many thanks for GMNS specification efforts led by Scott Smith and Ian Berg from Volpe Center,
+USDOT. Their TRB poster can be found at https://github.com/zephyr-data-specs/GMNS/blob/TRB/TRBPoster_22-02127.pdf
 
 This document is prepared with the help from `Entai Wang`_ and `Chongnan Li`_.
 

docs/source/conf.py

@@ -23,11 +23,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'osm2gmns'
-copyright = '2020-2022, Jiawei Lu, Xuesong (Simon) Zhou'
-author = 'Jiawei Lu, Xuesong (Simon) Zhou'
+copyright = '2020-, Jiawei Lu, Xiangyong Luo, Xuesong (Simon) Zhou'
+author = 'Jiawei Lu, Xiangyong Luo, Xuesong (Simon) Zhou'
 
 # The full version, including alpha/beta/rc tags
-release = '0.7.3'
+release = '0.7.4'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/quick-start.rst

@@ -14,6 +14,47 @@ osm files to extract useful network information. As a result, the first step is
 Thanks to the open-source nature of OpenStreetMap, there are lots of APIs and mirror sites that we can use to
 download osm map data. We list several popular sites here for users to choose.
 
+0) osm2gmns built-in class: OSM_RelationID_Finder
+Get the relation id of a place of interest, eg. "Arizona State University", "Arizona, United States", "Tempe, AZ"...
+
+-- code-block:: python
+
+    >>> import osm2gmns as og
+    # get relation id of a place of interest
+    # For the place of interest, e.g. Arizona State University
+    # e.g. "Tempe, Arizona, United States"
+    # e.g. "Arizona, US"
+    # e.g. "Beijing Jiaotong University, Beijing, China"
+    >>> rel_id = og.getOSMRelationID('Arizona State University')
+    >>> rel_id
+        Info: Found relation id 3444656 from web
+        Info: location of the place of interest:
+        {
+            "place_id": 318528634,
+            "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
+            "osm_type": "relation",
+            "osm_id": 3444656,
+            "lat": "33.4213174",
+            "lon": "-111.93316305413154",
+            "class": "amenity",
+            "type": "university",
+            "place_rank": 30,
+            "importance": 0.5547365758311374,
+            "addresstype": "amenity",
+            "name": "Arizona State University",
+            "display_name": "Arizona State University, 1151, South Forest Avenue, Tempe Junction, Tempe, Maricopa County, Arizona, 85281, United States",
+            "boundingbox": [
+                "33.4102062",
+                "33.4329786",
+                "-111.9411651",
+                "-111.9092447"
+            ]
+        }
+    3444656
+
+    # download the corresponding osm file
+    >>> og.downloadOSMData(rel_id, 'asu.osm')
+
 
 1) OpenStreetMap Homepage
 
@@ -180,7 +221,7 @@ Consolidate Intersections
 =========================
 
 In OpenStreetMap, one large intersection is often represented by multiple nodes. This structure brings some
-difficulties when performing traffic-oriented modelings. osm2gmns enables users to consolidate intersections 
+difficulties when performing traffic-oriented modelings. osm2gmns enables users to consolidate intersections
 that are originally represented by multiple nodes into a single node. Note that osm2gmns only identifies and
 consolidates signalized intersections.
 
@@ -197,9 +238,9 @@ consolidates signalized intersections.
 
     Complex intersection consolidation
 
-Users can visualize the consolidated network in `QGIS`_ or `NeXTA`_. 
-For complex interestions that were not successfully identified and consolidated by osm2gmns, users can manually specify 
-them by revising the column "intersection_id" in node.csv and utilize the commands below to do the re-consolidation. 
+Users can visualize the consolidated network in `QGIS`_ or `NeXTA`_.
+For complex interestions that were not successfully identified and consolidated by osm2gmns, users can manually specify
+them by revising the column "intersection_id" in node.csv and utilize the commands below to do the re-consolidation.
 Nodes assgined with the same "intersection_id" will be consolidated into a new node.
 
 .. code-block:: python

osm2gmns/__init__.py

@@ -10,13 +10,32 @@
 from osm2gmns.io.downloader import downloadOSMData
 from osm2gmns.io.writefile import outputNetToCSV
 from osm2gmns.utils.util import config
-from osm2gmns.func_lib.extract_relation_id import OSM_RelationID_Finder
+from osm2gmns.func_lib.extract_relation_id import getOSMRelationID
 import osm2gmns.settings as og_settings
 
 
-__version__ = '0.7.3'
+__version__ = '0.7.4'
 print(f'osm2gmns, {__version__}')
 
+__all__ = [
+    'getNetFromFile',
+    'combineShortLinks',
+    'consolidateComplexIntersections',
+    'generateNodeActivityInfo',
+    'generateLinkVDFInfo',
+    'connectPOIWithNet',
+    'show',
+    'saveFig',
+    'generateMovements',
+    'buildMultiResolutionNets',
+    'loadNetFromCSV',
+    'downloadOSMData',
+    'outputNetToCSV',
+    'config',
+    'getOSMRelationID',
+    'og_settings'
+]
+
 
 
 # todo: railway allowed_use

osm2gmns/func_lib/__init__.py

@@ -6,4 +6,7 @@
 ##############################################################
 
 # Please note,
-# All countries, states, and cities in global_rel_id.json file are from https://github.com/dr5hn/countries-states-cities-database/tree/master
+# All countries, states, and cities in global_rel_id.json file are from https://github.com/dr5hn/countries-states-cities-database/tree/master
+from .extract_relation_id import getOSMRelationID
+
+__all__ = ['getOSMRelationID']