Welcome to the envector’s documentation!
This is the documentation of the envector Python package version 0.3.1 for Python3-only released on Sep 18, 2024.
Bleeding edge available at: https://github.com/mhogan-nwra/envector.
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) 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 Tutorials to help you maximize the utility of envector.
Questions and Answers
If you are coming from the nvector package, these Q-and-A can quickly explain this package.
What is the difference between this package and nvector?
Virtually none! The envector package is a fork of nvector with mostly aesthetic changes.
No methods and functions have been removed, but documented deprecated methods in nvector will be removed.
If your Python software worked with nvector, then there is a good chance envector will also work. The caveats are that this package abandons Python2 and extends to Python3.9+ support.
Why did you call this package “envector”?
The name honors the original nvector Python package and the progenitor MATLAB n-vector toolbox. There are adaptations in other languages as noted in the nvector downloads page.
The names nvector and envector are homophones (pronounced the same), so the name invokes the original n-vector origin.
Why did you fork nvector?
Primarily because the nvector Python package is broken with NumPy version 2.
There is no indication that the situation will change.
What changes are there with from nvector?
The major difference is the namespace. Any place where your project have statements like:
import nvector as nv from nvector import GeoPoint
You would replace them:
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.
When is the appropriate to switch to envector?
If your Python software must support NumPy version 2,
If your Python software also stops supporting Python versions after its end-of-life cycle.
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.
envector>=0
- pip: - envector>=0
# PEP 508 compliant [project] dependencies = [ "envector>=0" ] # Poetry (not PEP 508 compliant) [tool.poetry.dependencies] envector = ">=0"
install_requires=['envector>=0', ... ]
Your Python code will now need to import envector
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.
# 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" }
install_requires=['envector>=0; python_version >= "3.9"', 'nvector>=0; python_version < "3.9"', ... ]
Contents: