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 and features are accepted, but I make no promises about the timeliness of my response.

For an explanation of the n-vector system, refer to the nvector_lite.py docstring.

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.

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

Development

Development requires Hatch.

First, clone the Git repository.

Then, set up our Hatch environments:

hatch python install all
hatch env create dev

Technically this is optional and will be done automatically by hatch run. But it’s nice to have everything set up and ready to avoid a long wait for the first command.

Run tests:

hatch run dev:pytest

Examples

Cross-track distance for every point in a motion track

We are given N origin/destination pairs, and, for each pair, the motion track of an object that travelled from the origin to the destination.

We would like to compute the cross-track distance of every point in each motion track, relative to the geodesic between its origin and destination.

from nvector_lite import nvector_cross_track_distance

origin = ...       # 3 × N
destination = ...  # 3 × N
track = ...        # 3 × N

xt = nvector_cross_track_distance(origin, destination, track)
assert xt.shape == (track.shape[1],)