N-vector Lite is a simple, flexible, and permissively-licensed implementation of the "n-vector" horizontal position system in Python and Numpy. It is currently alpha quality.
Note that this project is developed/maintained as a side project in my spare
time. See LICENSE.txt
for license terms, including a total disclaimer of
warranty. Contributions of bugfixes/corrections, features, tests, and
documentation are accepted, but I make no promises about the timeliness of my
response.
For an explanation of the n-vector system and additional design details, refer
to the nvector_lite.py
docstring.
I have no plans to support non-spherical Earth models for the time being, in
part because the math is beyond me and in part because I want to focus on the
core feature set first.
This library is designed to work with arbitrary-shape/size Numpy arrays. By
comparison, the original nvector
implementation has inconsistent and unclear support for arrays of multiple
points, i.e. anything other than shape (3, 1)
.
N-vector Lite is meant to be useful for "batch" computation over datasets of
points stored in Numpy arrays, Pandas data frames, etc. — with much faster
performance than you would be able to achieve with the original nvector
library.
This is also useful for SQL-like database/query engines that support batched/vectorized Python UDFs, such as PySpark, DuckDB, and Snowflake.
In progress or completed:
-
N-vector operations:
-
Conversion from lon,lat to n-vector
-
Conversion from n-vector to lon,lat
-
Unit normal vector of the great circle formed by two n-vectors
-
Arc angle between two n-vectors
-
Interpolation along the great circle arc between two n-vectors
-
"Direct"/"forward" geodesic problem: obtain a new n-vector from a starting point, distance, and azimuth
-
Intersection n-vector between two arcs formed by two pairs of n-vectors
-
Cross-track arc angle of an n-vector with respect to the great circle arc between two n-vectors
-
Along-track arc angle of an n-vector with respect to the great circle arc between two n-vectors
-
Check if a polygon of n-vectors contains the North Pole or South Pole
-
Extensive test coverage
Planned:
-
More n-vector operations
-
More test coverage
-
Continuous integration
-
Distribution and automation thereof:
-
PyPI
-
Conda Forge
-
Documentation:
-
Tutorials / usage guides
-
API reference
-
Usage comparison with other implementations
-
Benchmark suite, including comparison with other implementations
I will set up PyPI publishing and a stable versioning scheme eventually. For now, install directly from Git using Pip:
pip install git+https://github.com/gwerbin/nvector-lite
Development requires Hatch.
Then, just clone the Git repository. Hatch will automatically set up the project environment when you run a command for the first time.
Run tests:
hatch run dev:pytest
Run an interactive Python console with hot-reloading enabled:
hatch run dev:repl
Run any other command (e.g. Python) in the dev environment:
hatch run dev:python ...
hatch run dev:python -m pdb ...
hatch run dev:/bin/sh ...
watch -n 60 hatch run dev:pytest -k test_example