Metadata-Version: 2.1
Name: seafarer
Version: 0.1.0
Summary: Taxicab metric on the sphere!
Home-page: https://github.com/maasglobal/seafarer
Author: Markus Schepke
Author-email: markus.schepke@maas.global
License: MIT
Project-URL: Documentation, https://github.com/maasglobal/seafarer/blob/master/README.md
Project-URL: Source, https://github.com/maasglobal/seafarer
Project-URL: Tracker, https://github.com/maasglobal/seafarer/issues
Keywords: metric,distance,sphere,taxicab,manhattan
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown


# Seafarer ⛵

Taxicab metric on the sphere! Install via

```bash
pip install seafarer
```

This library calculates the "seafarer distance" between two points on Earth:
Travel parallel to latitude and longitude instead of "as the crow flies" –
like in the old days...

## Usage

Calculate the distance between Schwerin and Helsinki:

```python
from seafarer import seafarer_metric

schwerin = (53.629722, 11.414722) # (lat, lon)
helsinki = (60.170278, 24.952222)

seafarer_metric(schwerin, helsinki)
# 1474.7398906623202 kilometres
```

You can also obtain the result in different units:

```python
seafarer_metric(schwerin, helsinki, unit="mi")
# 916.3608837507956 miles
seafarer_metric(schwerin, helsinki, unit="ft")
# 4838385.468052049 feet
```

Seafarer is using the [haversine](https://github.com/mapado/haversine) library
under the hood and you can use their `Unit` directly:

```python
from haversine import Unit
seafarer_metric(schwerin, helsinki, unit=Unit.NAUTICAL_MILES)
# 796.2958366185961 nautical miles
```

## What is this? Why Seafarer?

On a 2-dimensional plane, the metric obtained when travelling along the axes
is known as [taxicab](https://en.wikipedia.org/wiki/Taxicab_geometry),
Manhattan, or L1 metric. What is the equivalent on a 3-dimensional sphere?

We calculate the distance when travelling along the grid of longitudinal and
latitudinal lines. When travelling from Schwerin (53°N 11°E) to Helsinki
(60°N 24°E) in the example above, there are two possiblities: travel via
53°N 24°E or 60°N 11°E. Unlike the 2D case, these two distances are
(generally) different, so we use the short one.

Before navigation improved to a sufficient degree, this is how ships were
sailing: parallel to the equator until they hit the target meridian, then
North or South to their final destination. Hence seafarer metric! ⛵


