Skip to content

gwerbin/nvector-lite

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

22 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

About

Simple and flexible n-vector implementation in Numpy

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages