N-vector Lite

About

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.

Features

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

Installation

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

Usage

Examples

Refer to the test suite, especially any test called test_example.

Development

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