From 7ff3313b8d6cbdaf2c0602cbf66d675efc29822c Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Thu, 12 Sep 2024 09:20:47 -0600 Subject: [PATCH 1/8] DOC: Try to use recommended alias for the badge to PyPI --- README.rst | 2 +- src/envector/_images.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index d42c773..f9a5e6b 100644 --- a/README.rst +++ b/README.rst @@ -629,7 +629,7 @@ to do the calculations. .. _nvector downloads: https://www.ffi.no/en/research/n-vector/n-vector-downloads .. _MATLAB n-vector toolbox: https://github.com/FFI-no/n-vector .. |pkg_img| image:: https://badge.fury.io/py/envector.svg - :target: https://pypi.python.org/pypi/envector/ + :target: https://badge.fury.io/py/envector .. |docs_img| image:: https://readthedocs.org/projects/pip/badge/?version=stable :target: http://envector.readthedocs.org/en/stable/ .. |versions_img| image:: https://img.shields.io/pypi/pyversions/envector.svg diff --git a/src/envector/_images.py b/src/envector/_images.py index 4c92c03..bb7af75 100644 --- a/src/envector/_images.py +++ b/src/envector/_images.py @@ -2,7 +2,7 @@ .. only:: html .. |pkg_img| image:: https://badge.fury.io/py/envector.svg - :target: https://pypi.python.org/pypi/envector/ + :target: ttps://badge.fury.io/py/envector .. |docs_img| image:: https://readthedocs.org/projects/pip/badge/?version=stable :target: http://envector.readthedocs.org/en/stable/ From ee80958f4e5784787c6bc7c600ae75bd42d56319 Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Thu, 12 Sep 2024 10:11:16 -0600 Subject: [PATCH 2/8] DOC: Expand the Q-and-A about how to migrate to envector from nvector --- README.rst | 105 +++++++++++++++++++++++++++++++++++++++++++++++-- docs/index.rst | 100 ++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 198 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index f9a5e6b..8b9d861 100644 --- a/README.rst +++ b/README.rst @@ -53,9 +53,23 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t 4. *What changes are there with from nvector*? - * Any place there is a `import nvector` or `from nvector` statement, replace it with `import envector` or - `from envector`, respectively. - * The envector_ package is a Python3-only package as it embraces type-hints in most cases. + * The major difference is the namespace. Any place where your project have statements like: + + .. code-block:: python + :caption: Importing the nvector package + + import nvector as nv + from nvector import GeoPoint + + You would replace them: + + .. code-block:: python + :caption: Importing the envector package instead + + import envector as nv + from envector import GeoPoint + + * The envector_ package is a Python3-only package as it embraces static typing in most cases. * Documentation is expanded in some cases. * The docstrings have been refactored to utilize the Napoleon docstring style. @@ -64,6 +78,89 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t * If your Python software must support NumPy version 2, * If your Python software also stops supporting Python versions after its end-of-life cycle. +6. *How do I make the switch to envector*? + + * If your project utilizes CPython3.9 through 3.12, inclusive, then you can simply change your `requirements.txt`, + `environment.yml`, `pyproject.toml`, or `setup.py` file to specify envector_. + + .. code-block:: text + :caption: `requirements.txt` format + + envector>=0 + + .. code-block:: yaml + :caption: Anaconda `environment.yml` format + + - pip: + - envector>=0 + + .. code-block:: toml + :caption: `pyproject.toml` format + + # PEP 508 compliant + [project] + dependencies = [ + "envector>=0" + ] + + # Poetry (not PEP 508 compliant) + [tool.poetry.dependencies] + envector = ">=0" + + .. code-block:: python + :caption: `setup.py` format + + install_requires=['envector>=0', + ... + ] + + * Your Python code will now need to import envector_ + + .. code-block:: python + :caption: Importing envector into your module + + import envector as nv + + * If your project uses anything less than CPython3.9, then it depends on how your project is specified. If you are + using `pyproject.toml` or `setup.py`, then the changes are relatively simple as shown below. The other common + Anaconda `environment.yml` and `requirements.txt` formats require you to pick one depending on the Python + version. For Python2 to 3.8, you cannot use envector_. + + .. code-block:: toml + :caption: `pyproject.toml` format to specify both nvector and envector + + # PEP 508 compliant + [project] + dependencies = [ + "envector>=0; python_version >= '3.9'", + "nvector>=0; python_version < '3.9'", + ] + + # Poetry (not PEP 508 compliant) + [tool.poetry.dependencies] + envector = { version = ">=0", python = ">=3.9" } + nvector = { version = ">=0", python = "<3.9" } + + .. code-block:: python + :caption: `setup.py` format to specify both nvector and envector + + install_requires=['envector>=0; python_version >= "3.9"', + 'nvector>=0; python_version < "3.9"', + ... + ] + + * Your Python code will now need to import both envector_ and nvector_ + + .. code-block:: python + :caption: Code block to import either nvector or envector + + try: + import nvector as nv + except (ImportError,): + import envector as nv + + + Description @@ -136,7 +233,7 @@ Then at the Python prompt, try to import envector: >>> import envector as nv >>> print(nv.__version__) - 0.2.0 + 0.3.1 To test if the toolbox is working correctly paste the following in an interactive diff --git a/docs/index.rst b/docs/index.rst index cec8974..4b7754a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,9 +40,23 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t 4. *What changes are there with from nvector*? - * Any place there is a `import nvector` or `from nvector` statement, replace it with `import envector` or - `from envector`, respectively. - * The envector_ package is a Python3-only package as it embraces type-hints in most cases. + * The major difference is the namespace. Any place where your project have statements like: + + .. code-block:: python + :caption: Importing the nvector package + + import nvector as nv + from nvector import GeoPoint + + You would replace them: + + .. code-block:: python + :caption: Importing the envector package instead + + import envector as nv + from envector import GeoPoint + + * The envector_ package is a Python3-only package as it embraces static typing in most cases. * Documentation is expanded in some cases. * The docstrings have been refactored to utilize the Napoleon docstring style. @@ -51,6 +65,86 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t * If your Python software must support NumPy version 2, * If your Python software also stops supporting Python versions after its end-of-life cycle. +6. *How do I make the switch to envector*? + + * If your project utilizes CPython3.9 through 3.12, inclusive, then you can simply change your `requirements.txt`, + `environment.yml`, `pyproject.toml`, or `setup.py` file to specify envector_. + + .. code-block:: text + :caption: `requirements.txt` format + + envector>=0 + + .. code-block:: yaml + :caption: Anaconda `environment.yml` format + + - pip: + - envector>=0 + + .. code-block:: toml + :caption: `pyproject.toml` format + + # PEP 508 compliant + [project] + dependencies = [ + "envector>=0" + ] + + # Poetry (not PEP 508 compliant) + [tool.poetry.dependencies] + envector = ">=0" + + .. code-block:: python + :caption: `setup.py` format + + install_requires=['envector>=0', + ... + ] + + * Your Python code will now need to import envector_ + + .. code-block:: python + :caption: Importing envector into your module + + import envector as nv + + * If your project uses anything less than CPython3.9, then it depends on how your project is specified. If you are + using `pyproject.toml` or `setup.py`, then the changes are relatively simple as shown below. The other common + Anaconda `environment.yml` and `requirements.txt` formats require you to pick one depending on the Python + version. For Python2 to 3.8, you cannot use envector_. + + .. code-block:: toml + :caption: `pyproject.toml` format to specify both nvector and envector + + # PEP 508 compliant + [project] + dependencies = [ + "envector>=0; python_version >= '3.9'", + "nvector>=0; python_version < '3.9'", + ] + + # Poetry (not PEP 508 compliant) + [tool.poetry.dependencies] + envector = { version = ">=0", python = ">=3.9" } + nvector = { version = ">=0", python = "<3.9" } + + .. code-block:: python + :caption: `setup.py` format to specify both nvector and envector + + install_requires=['envector>=0; python_version >= "3.9"', + 'nvector>=0; python_version < "3.9"', + ... + ] + + * Your Python code will now need to import both envector_ and nvector_ + + .. code-block:: python + :caption: Code block to import either nvector or envector + + try: + import nvector as nv + except (ImportError,): + import envector as nv .. toctree:: From ee94745f9c4d570a9db19d39890a9d4080dc6f28 Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Thu, 12 Sep 2024 10:24:21 -0600 Subject: [PATCH 3/8] DOC: Use a consistent description with that on GitHub repo home --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index a766092..a75bb39 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "envector" dynamic = ["version"] -description = "The envector library is a suite of tools written in Python to solve geographical position calculations forked from nvector." +description = "The envector package is a suite of tools written in Python forked from the nvector package to solve geographical position calculations powered by means of n-vector." authors = [ {name = "Matt Hogan", email = "mhogan@nwra.com"}, {name = "Kenneth Gade, FFI"}, From a82b327f68c021c491a19e00c97db4becff59d05 Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Thu, 12 Sep 2024 16:11:20 -0600 Subject: [PATCH 4/8] DOC: Fix unintended repeated words in README --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 8b9d861..8216f70 100644 --- a/README.rst +++ b/README.rst @@ -7,7 +7,7 @@ envector The envector library is a suite of tools written in Python to solve geographical position calculations. This is -an open-source fork of the original nvector_ Python package based on the MATLAB nvector `MATLAB n-vector toolbox`_. +an open-source fork of the original nvector_ Python package based on the `MATLAB n-vector toolbox`_. Currently the following operations are implemented: From 558c1fe8f15acbba931e7d02c774bf0eb9d034f1 Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Thu, 12 Sep 2024 16:33:03 -0600 Subject: [PATCH 5/8] DOC: Add less intimidating explanation for the use cases of envector. --- README.rst | 57 ++++++++++++++++++++++++++---------------- docs/index.rst | 32 ++++++++++++++++++++++++ src/envector/_intro.py | 5 ++-- 3 files changed, 70 insertions(+), 24 deletions(-) diff --git a/README.rst b/README.rst index 8216f70..07dc70d 100644 --- a/README.rst +++ b/README.rst @@ -9,23 +9,36 @@ envector The envector library is a suite of tools written in Python to solve geographical position calculations. This is an open-source fork of the original nvector_ Python package based on the `MATLAB n-vector toolbox`_. -Currently the following operations are implemented: - -* Calculate the surface distance between two geographical positions. - -* Convert positions given in one reference frame into another reference frame. - -* Find the destination point given start point, azimuth/bearing and distance. - -* Find the mean position (center/midpoint) of several geographical positions. - -* Find the intersection between two paths. - -* Find the cross track distance between a path and a position. - +Explanation of Intent +===================== -Using envector, the calculations become simple and non-singular. -Full accuracy is achieved for any global position (and for any distance). +This is a Python package that will assist you in calculating the distance between two points anywhere on, above, or +below the Earth's surface. This can also be between two, three, or many points. This is quite useful in many areas from +logistics, tracking, navigation, data analytics, data science, and research. The calculations are simple and +non-singular. Full accuracy is achieved for any global position (and for any distance). + +Use Cases +========= + +A use case in logistics is when you need to recommend to your customers the closest facilities or store +locations given an address or GPS coordinates. Your customers usually provide an address and you can convert that to GPS +coordinates, or geographic location in latitude and longitude. Given this information, you need to recommend the closest +locations and approximate distance in kilometers (km) or miles. You can implement the Haversine formula, which is a +reasonable estimate if you are concerned with relatively short distances less than 100 km. However, you might meed to be +aware of the difference in altitudes between two locations. On top of all that, the Haversine formula is not accurate +for longer distances as the Earth is not exactly a sphere. You can properly account for all these issues using our +envector_ package. + +Another use case is for navigation and tracking. Imagine that you +have a vehicle like a ship, airplane, or off-road vehicle on a fixed course. The vehicle has an unreliable and +inaccurate GPS unit, and it is your job to ensure that the vehicle stays on course. This makes your job much harder if +you want to minimize the trip duration and vehicle fuel to maximize the number of trips possible for the day. +Fortunately, the envector_ package can help you 1) aggregate measurements to estimate the mean position, 2) interpolate +the next expected position in a fixed time interval, and 3) ensure that the vehicle is staying on-track by minimizing +the cross-track distance from the intended path. + +These use cases and more are well supported by the envector_ package. We encourage you to check out the +examples_ to help you maximize the utility of envector_. Questions and Answers ===================== @@ -160,11 +173,9 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t import envector as nv +Technical Description +===================== - - -Description -=========== In this library, we represent position with an "n-vector", which is the normal vector to the Earth model (the same reference ellipsoid that is used for latitude and longitude). When using n-vector, all Earth-positions are @@ -243,8 +254,10 @@ python session:: nv.test('--doctest-modules') -Getting Started -=============== +.. _examples: + +Getting Started with Examples +============================= Below the object-oriented solution to some common geodesic problems are given. In the first example the functional solution is also given. diff --git a/docs/index.rst b/docs/index.rst index 4b7754a..0c22d36 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,38 @@ Official releases are available at: http://pypi.python.org/pypi/envector. Official homepage are available at: http://www.navlab.net/nvector/ +Explanation of Intent +--------------------- + +This is a Python package that will assist you in calculating the distance between two points anywhere on, above, or +below the Earth's surface. This can also be between two, three, or many points. This is quite useful in many areas from +logistics, tracking, navigation, data analytics, data science, and research. The calculations are simple and +non-singular. Full accuracy is achieved for any global position (and for any distance). + +Use Cases +--------- + +A use case in logistics is when you need to recommend to your customers the closest facilities or store +locations given an address or GPS coordinates. Your customers usually provide an address and you can convert that to GPS +coordinates, or geographic location in latitude and longitude. Given this information, you need to recommend the closest +locations and approximate distance in kilometers (km) or miles. You can implement the Haversine formula, which is a +reasonable estimate if you are concerned with relatively short distances less than 100 km. However, you might meed to be +aware of the difference in altitudes between two locations. On top of all that, the Haversine formula is not accurate +for longer distances as the Earth is not exactly a sphere. You can properly account for all these issues using our +envector_ package. + +Another use case is for navigation and tracking. Imagine that you +have a vehicle like a ship, airplane, or off-road vehicle on a fixed course. The vehicle has an unreliable and +inaccurate GPS unit, and it is your job to ensure that the vehicle stays on course. This makes your job much harder if +you want to minimize the trip duration and vehicle fuel to maximize the number of trips possible for the day. +Fortunately, the envector_ package can help you 1) aggregate measurements to estimate the mean position, 2) interpolate +the next expected position in a fixed time interval, and 3) ensure that the vehicle is staying on-track by minimizing +the cross-track distance from the intended path. + +These use cases and more are well supported by the envector_ package. We encourage you to check out the +:doc:`/tutorials/index` to help you maximize the utility of envector_. + + Questions and Answers --------------------- diff --git a/src/envector/_intro.py b/src/envector/_intro.py index b832413..5dacc82 100644 --- a/src/envector/_intro.py +++ b/src/envector/_intro.py @@ -26,8 +26,9 @@ -Description -=========== +Technical Description +===================== + In this library, we represent position with an "n-vector", which is the normal vector to the Earth model (the same reference ellipsoid that is used for latitude and longitude). When using n-vector, all Earth-positions are From a9bb5825610a12ac7220ba23eeb782bc39a2b707 Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Thu, 12 Sep 2024 16:39:47 -0600 Subject: [PATCH 6/8] DOC: Remove link as GitHub RST engine does not properly link internal document links. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 07dc70d..98939c5 100644 --- a/README.rst +++ b/README.rst @@ -38,7 +38,7 @@ the next expected position in a fixed time interval, and 3) ensure that the vehi the cross-track distance from the intended path. These use cases and more are well supported by the envector_ package. We encourage you to check out the -examples_ to help you maximize the utility of envector_. +examples below to help you maximize the utility of envector_. Questions and Answers ===================== From 8356d27b688d1f3b76262996bd1a7e4a5e2ac146 Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Fri, 13 Sep 2024 19:54:07 -0600 Subject: [PATCH 7/8] DOC: Add comments into code-blocks as GitHub does not render the :caption: --- README.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 98939c5..1b80e46 100644 --- a/README.rst +++ b/README.rst @@ -99,17 +99,20 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t .. code-block:: text :caption: `requirements.txt` format + # requirements.txt format envector>=0 .. code-block:: yaml :caption: Anaconda `environment.yml` format + # environment.yml format - pip: - envector>=0 .. code-block:: toml :caption: `pyproject.toml` format + # pyproject.toml format # PEP 508 compliant [project] dependencies = [ @@ -123,17 +126,13 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t .. code-block:: python :caption: `setup.py` format + # setup.py format install_requires=['envector>=0', ... ] * Your Python code will now need to import envector_ - .. code-block:: python - :caption: Importing envector into your module - - import envector as nv - * If your project uses anything less than CPython3.9, then it depends on how your project is specified. If you are using `pyproject.toml` or `setup.py`, then the changes are relatively simple as shown below. The other common Anaconda `environment.yml` and `requirements.txt` formats require you to pick one depending on the Python @@ -142,6 +141,7 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t .. code-block:: toml :caption: `pyproject.toml` format to specify both nvector and envector + # pyproject.toml format # PEP 508 compliant [project] dependencies = [ @@ -157,16 +157,18 @@ If you are coming from the nvector_ package, these Q-and-A can quickly explain t .. code-block:: python :caption: `setup.py` format to specify both nvector and envector + # setup.py format install_requires=['envector>=0; python_version >= "3.9"', 'nvector>=0; python_version < "3.9"', ... ] - * Your Python code will now need to import both envector_ and nvector_ + * Your Python code will now need to try and import envector_ or nvector_ in a try-except block. .. code-block:: python :caption: Code block to import either nvector or envector + # Code block to import either nvector or envector try: import nvector as nv except (ImportError,): From b4f118adfa9b9ac175138f46789b43731221ae03 Mon Sep 17 00:00:00 2001 From: Matt Hogan Date: Fri, 13 Sep 2024 20:16:54 -0600 Subject: [PATCH 8/8] DOC: Decided on different language in the use-case discussion --- README.rst | 2 +- docs/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 1b80e46..4657b8b 100644 --- a/README.rst +++ b/README.rst @@ -34,7 +34,7 @@ have a vehicle like a ship, airplane, or off-road vehicle on a fixed course. The inaccurate GPS unit, and it is your job to ensure that the vehicle stays on course. This makes your job much harder if you want to minimize the trip duration and vehicle fuel to maximize the number of trips possible for the day. Fortunately, the envector_ package can help you 1) aggregate measurements to estimate the mean position, 2) interpolate -the next expected position in a fixed time interval, and 3) ensure that the vehicle is staying on-track by minimizing +the next expected position in a fixed time interval, and 3) determine if the vehicle is veering off-course by measuring the cross-track distance from the intended path. These use cases and more are well supported by the envector_ package. We encourage you to check out the diff --git a/docs/index.rst b/docs/index.rst index 0c22d36..bdbff63 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,7 +39,7 @@ have a vehicle like a ship, airplane, or off-road vehicle on a fixed course. The inaccurate GPS unit, and it is your job to ensure that the vehicle stays on course. This makes your job much harder if you want to minimize the trip duration and vehicle fuel to maximize the number of trips possible for the day. Fortunately, the envector_ package can help you 1) aggregate measurements to estimate the mean position, 2) interpolate -the next expected position in a fixed time interval, and 3) ensure that the vehicle is staying on-track by minimizing +the next expected position in a fixed time interval, and 3) determine if the vehicle is veering off-course by measuring the cross-track distance from the intended path. These use cases and more are well supported by the envector_ package. We encourage you to check out the