Metadata-Version: 2.4
Name: nautipy
Version: 0.2.0
Summary: Coordinate conversion, WGS84 navigation, and position fixing
Author-email: CFW <cfw@pm.me>
Maintainer: NautiPy Developers
License-Expression: MIT
Project-URL: Homepage, https://github.com/cafawo/NautiPy
Project-URL: Documentation, https://wbk.ing/NautiPy/
Project-URL: Issues, https://github.com/cafawo/NautiPy/issues
Project-URL: Source, https://github.com/cafawo/NautiPy
Project-URL: Changelog, https://github.com/cafawo/NautiPy/blob/master/CHANGELOG.md
Project-URL: Contributing, https://github.com/cafawo/NautiPy/blob/master/CONTRIBUTING.md
Project-URL: Code of Conduct, https://github.com/cafawo/NautiPy/blob/master/CODE_OF_CONDUCT.md
Project-URL: Security, https://github.com/cafawo/NautiPy/security/policy
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: geographiclib>=2.1
Requires-Dist: numpy>=1.23.5
Requires-Dist: scipy>=1.14.1
Dynamic: license-file

# NautiPy

[![CI](https://github.com/cafawo/NautiPy/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/cafawo/NautiPy/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/nautipy)](https://pypi.org/project/nautipy/)
[![Python](https://img.shields.io/pypi/pyversions/nautipy)](https://pypi.org/project/nautipy/)
[![Typing](https://img.shields.io/pypi/types/nautipy)](https://pypi.org/project/nautipy/)
[![License](https://img.shields.io/pypi/l/nautipy)](https://github.com/cafawo/NautiPy/blob/master/LICENSE.txt)
[![Docs](https://img.shields.io/badge/docs-online-blue)](https://wbk.ing/NautiPy/)

**Easy coordinate handling, trustworthy WGS84 navigation, and diagnosed
position fixes in one Python package.**

Explore the [educational guide and interactive Fix
Lab](https://wbk.ing/NautiPy/) for visual explanations and worked examples.

NautiPy accepts the coordinate formats people commonly paste or type, converts
them into a validated `Position`, and provides navigation and position-fixing
tools without silently guessing when an input is ambiguous.

## Install

Use a Python version accepted by the
[`requires-python` setting](https://github.com/cafawo/NautiPy/blob/master/pyproject.toml),
then install the complete package from PyPI:

```console
python -m pip install nautipy
```

The installation includes GeographicLib, NumPy, and SciPy, so every feature is
available immediately.

## Quick start

### Parse, inspect, and convert coordinates

```python
from nautipy import convert_position, inspect_positions, parse_position

p1 = parse_position("50.12257, 8.66570")
p2 = parse_position("50° 7.3542' N; 8° 39.942' E")
p3 = parse_position("+50.12257+008.66570/")

assert p1 == p2 == p3
assert convert_position(
    "50.12257, 8.66570",
    to="dms",
) == "50° 7′ 21.25″ N; 8° 39′ 56.52″ E"

batch = inspect_positions(
    [
        "50.12257 N; 8.66570 E",
        "50, 8",
        "not a position",
    ],
    order="auto",
)
assert (
    batch.total_count,
    batch.parsed_count,
    batch.ambiguous_count,
    batch.invalid_count,
) == (3, 1, 1, 1)
```

Detection covers decimal degrees (DD), degrees and decimal minutes (DDM),
degrees/minutes/seconds (DMS), two-dimensional ISO 6709, and NMEA coordinate
field pairs. Use `order="lonlat"` for unmarked longitude-first input.
`order="auto"` accepts hard axis evidence or equivalent source orders;
otherwise it raises `AmbiguousCoordinateError`. Batch inspection preserves
every yielded record's zero-based index and either its `ParseResult` or its
structured coordinate failure.

### Calculate WGS84 navigation values

```python
from nautipy import destination, distance, inverse

start = "50.12257, 8.66570"
end = destination(start, bearing=90, distance=12_000)

assert abs(distance(start, end) - 12_000) < 1e-6

result = inverse(start, end)
print(result.initial_bearing)
print(result.final_bearing)
```

Distances are in metres and bearings are true degrees clockwise from north.
Calculations use WGS84 ellipsoidal geodesics through GeographicLib.

### Estimate a position from observations

```python
from nautipy import Position, RangeObservation, solve_fix

references = (
    Position(50.116135, 8.670277),
    Position(50.112836, 8.666753),
    Position(50.110347, 8.659873),
)
ranges = tuple(
    RangeObservation(reference, measured, uncertainty=2.0)
    for reference, measured in zip(
        references,
        (1_275.251, 1_599.237, 1_917.145),
    )
)

result = solve_fix(ranges=ranges)
if result.success:
    print(result.position)
else:
    print(result.status, result.competing_positions)
```

Bearing, range, and mixed-observation fixes report residuals, convergence, and
geometry diagnostics. A successful optimization does not by itself guarantee
good observation geometry, so callers should inspect the complete result.

### Use the command line

```console
$ nautipy convert "50° 7.3542' N; 8° 39.942' E" --to dd
50.122570, 8.665700

$ nautipy inspect "+50.12257+008.66570/"
```

`inspect` writes deterministic JSON describing the detected format,
normalizations, resolution, and candidate interpretations. `python -m nautipy`
provides the same interface.

## What is included

- coordinate parsing, scalar and batch inspection, formatting, and conversion;
- an immutable, validated `Position` model;
- WGS84 distance, bearing, destination, interpolation, and nearest-position
  calculations;
- diagnosed bearing, range, and mixed-observation fixes;
- GeoJSON Point and FeatureCollection interchange; and
- offline `convert` and `inspect` commands.

NautiPy is deliberately not a general GIS framework, charting application,
route planner, live-data client, or certified navigation system.

## Documentation

The [NautiPy educational guide](https://wbk.ing/NautiPy/) explains coordinate
notation, ellipsoidal navigation, bearing and range fixes, uncertainty, and
how the package fits those ideas together. It includes original diagrams and
an interactive Fix Lab.

The exact behavior specifications remain in the repository:

- [Coordinate input and conversion](https://github.com/cafawo/NautiPy/blob/master/docs/COORDINATES.md)
- [WGS84 navigation](https://github.com/cafawo/NautiPy/blob/master/docs/NAVIGATION.md)
- [Bearing and range position fixes](https://github.com/cafawo/NautiPy/blob/master/docs/FIXES.md)
- [GeoJSON interchange](https://github.com/cafawo/NautiPy/blob/master/docs/GEOJSON.md)
- [Support and API stability](https://github.com/cafawo/NautiPy/blob/master/docs/SUPPORT.md)

For contributing and maintaining the project:

- [Contribution guide](https://github.com/cafawo/NautiPy/blob/master/CONTRIBUTING.md)
- [Product direction](https://github.com/cafawo/NautiPy/blob/master/docs/PRODUCT.md)
- [Architecture and dependency policy](https://github.com/cafawo/NautiPy/blob/master/docs/ARCHITECTURE.md)
- [Implementation roadmap](https://github.com/cafawo/NautiPy/blob/master/ROADMAP.md)
- [Release procedure](https://github.com/cafawo/NautiPy/blob/master/docs/RELEASING.md)
- [Changelog](https://github.com/cafawo/NautiPy/blob/master/CHANGELOG.md)

Please report ordinary bugs through the
[issue tracker](https://github.com/cafawo/NautiPy/issues). Report suspected
security problems through the
[security policy](https://github.com/cafawo/NautiPy/security/policy).
Participation is governed by the
[Code of Conduct](https://github.com/cafawo/NautiPy/blob/master/CODE_OF_CONDUCT.md).

NautiPy is available under the
[MIT License](https://github.com/cafawo/NautiPy/blob/master/LICENSE.txt).
