Metadata-Version: 2.1
Name: gapmap
Version: 1.0.3
Summary: Maptools
Author: Paul Gardiner
Author-email: franticstone@gmail.com
License: MIT
Keywords: radius,point,mathlib
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
License-File: LICENSE

[![Release](https://github.com/mooncitizen/gapmap/actions/workflows/pypi.yaml/badge.svg)](https://github.com/mooncitizen/gapmap/actions/workflows/pypi.yaml)


![alt text](https://github.com/mooncitizen/gapmap/blob/main/images/logo150.png?raw=true)

## GAPMAP

A helper library that makes pathing simple in the real world. Point to Point distance finding and even Placename finding.

Roadmap

- [x] Placename finder (City, Country)
- [x] Euclidean Distances
- [] GIS based Pathing
- [] GIS Based timing
- [] Map Generation
- [] Hotswapping hosted maps

# Installation
```pip install gapmap``` or download the latest binary from the releases tab

# Usage

### Get City by name
```python
from gapmap import get_city_by_name

# this is not case sensitive
# Expanded returns continent and country information also
city = get_city_by_name("edinburgh", expanded=True)

# The returning object could be one of just the city information itself or an array of cities
cities = city.get('cities', None)

if cities is None:
    print(city)
else:
    print(cities)

```

This will return 

```json
{
  "id": 2650225,
  "name": "Edinburgh",
  "countrycode": "GB",
  "latitude": 55.95206,
  "longitude": -3.19648,
  "population": 506520,
  "timezone": "Europe/London",
  "country": {
    "id": 2635167,
    "name": "United Kingdom",
    "iso": "GB",
    "iso3": "GBR",
    "isonumeric": 826,
    "fips": "UK",
    "continentcode": "EU",
    "capital": "London"
  },
  "continent": {
    "id": 6255148,
    "name": "Europe",
    "bounding": {
      "north": 80.76416015625,
      "south": 27.6377894797159,
      "east": 41.73303985595703,
      "west": -24.532675386662543
    }
  }
}
```

### Distance between cities

```python

from gapmap import distance_between_cities

distance = distance_between_cities("edinburgh", "glasgow")

```

This will return 

```json
{
  "distances": {
    "miles": 41.67,
    "km": 67.07,
    "meters": 67065.32,
    "yards": 73343.5
  },
  "from": {
    "id": 2650225,
    "name": "Edinburgh",
    "countrycode": "GB",
    "latitude": 55.95206,
    "longitude": -3.19648,
    "population": 506520,
    "timezone": "Europe/London"
  },
  "to": {
    "id": 2648579,
    "name": "Glasgow",
    "countrycode": "GB",
    "latitude": 55.86515,
    "longitude": -4.25763,
    "population": 626410,
    "timezone": "Europe/London"
  }
}
```

### Radius around coords

This will provide a circular radius around the given latitude and longitude the radius from point to circle is in miles. There is an optional radial step that you can draw at each degree around the circle or you can step it up to whatever you want ```1-359``` the default step is every 10 degrees

```python
from gapmap import radius_around_coords

radius = radius_around_coords(55.95206, -3.19648, radial_step=10)

```

This will return 

```json
{
  "id": 2650225,
  "name": "Edinburgh",
  "countrycode": "GB",
  "latitude": 55.95206,
  "longitude": -3.19648,
  "population": 506520,
  "timezone": "Europe/London",
  "range": 15,
  "radius": [
    {
      "latitude": 55.95219485590659,
      "longitude": -3.19648,
      "bearing": 0
    },
    {
      "latitude": 55.952192807135276,
      "longitude": -3.1964381744369734,
      "bearing": 0.17453292519943295
    },
    {
      "latitude": 55.95218672307282,
      "longitude": -3.196397619735461,
      "bearing": 0.3490658503988659
    },
    {
      "latitude": 55.95217678858224,
      "longitude": -3.196359568140929,
      "bearing": 0.5235987755982988
    },
    {
      "latitude": 55.95216330552083,
      "longitude": -3.1963251758402738,
      "bearing": 0.6981317007977318
    },
    {
      "latitude": 55.95214668356804,
      "longitude": -3.196295487830642,
      "bearing": 0.8726646259971648
    },
    {
      "latitude": 55.95212742777716,
      "longitude": -3.1962714061671837,
      "bearing": 1.0471975511965976
    },
    {
      "latitude": 55.95210612322911,
      "longitude": -3.1962536625545614,
      "bearing": 1.2217304763960306
    },
    {
      "latitude": 55.95208341725465,
      "longitude": -3.1962427961150164,
      "bearing": 1.3962634015954636
    },
    {
      "latitude": 55.95205999976514,
      "longitude": -3.196239137008431,
      "bearing": 1.5707963267948966
    },
    {
      "latitude": 55.95203658228979,
      "longitude": -3.196242796401961,
      "bearing": 1.7453292519943295
    },
    {
      "latitude": 55.95201387635612,
      "longitude": -3.196253663093841,
      "bearing": 1.9198621771937625
    },
    {
      "latitude": 55.951992571870555,
      "longitude": -3.196271406893753,
      "bearing": 2.0943951023931953
    },
    {
      "latitude": 55.95197331615633,
      "longitude": -3.196295488656866,
      "bearing": 2.2689280275926285
    },
    {
      "latitude": 55.95195669428511,
      "longitude": -3.1963251766664977,
      "bearing": 2.443460952792061
    },
    {
      "latitude": 55.95194321130033,
      "longitude": -3.1963595688674986,
      "bearing": 2.6179938779914944
    },
    {
      "latitude": 55.951933276872246,
      "longitude": -3.19639762027474,
      "bearing": 2.792526803190927
    },
    {
      "latitude": 55.95192719285057,
      "longitude": -3.1964381747239186,
      "bearing": 2.9670597283903604
    },
    {
      "latitude": 55.951925144093416,
      "longitude": -3.19648,
      "bearing": 3.141592653589793
    },
    {
      "latitude": 55.95192719285057,
      "longitude": -3.196521825276082,
      "bearing": 3.3161255787892263
    },
    {
      "latitude": 55.951933276872246,
      "longitude": -3.1965623797252603,
      "bearing": 3.490658503988659
    },
    {
      "latitude": 55.95194321130033,
      "longitude": -3.196600431132502,
      "bearing": 3.6651914291880923
    },
    {
      "latitude": 55.95195669428511,
      "longitude": -3.1966348233335022,
      "bearing": 3.839724354387525
    },
    {
      "latitude": 55.95197331615633,
      "longitude": -3.1966645113431342,
      "bearing": 4.014257279586958
    },
    {
      "latitude": 55.951992571870555,
      "longitude": -3.1966885931062468,
      "bearing": 4.1887902047863905
    },
    {
      "latitude": 55.95201387635612,
      "longitude": -3.196706336906159,
      "bearing": 4.363323129985824
    },
    {
      "latitude": 55.95203658228979,
      "longitude": -3.1967172035980393,
      "bearing": 4.537856055185257
    },
    {
      "latitude": 55.95205999976514,
      "longitude": -3.1967208629915693,
      "bearing": 4.71238898038469
    },
    {
      "latitude": 55.95208341725465,
      "longitude": -3.1967172038849836,
      "bearing": 4.886921905584122
    },
    {
      "latitude": 55.95210612322911,
      "longitude": -3.1967063374454385,
      "bearing": 5.061454830783556
    },
    {
      "latitude": 55.95212742777716,
      "longitude": -3.1966885938328167,
      "bearing": 5.235987755982989
    },
    {
      "latitude": 55.95214668356804,
      "longitude": -3.196664512169358,
      "bearing": 5.410520681182422
    },
    {
      "latitude": 55.95216330552083,
      "longitude": -3.1966348241597267,
      "bearing": 5.585053606381854
    },
    {
      "latitude": 55.95217678858224,
      "longitude": -3.1966004318590713,
      "bearing": 5.759586531581287
    },
    {
      "latitude": 55.95218672307282,
      "longitude": -3.1965623802645395,
      "bearing": 5.934119456780721
    },
    {
      "latitude": 55.952192807135276,
      "longitude": -3.196521825563027,
      "bearing": 6.1086523819801535
    }
  ]
}
```

### Is out of radius

A helper function to determine if something is out of radius. This is currently straight line.

```python

from gapmap import is_out_of_radius

## Input tuple or dict (55.95206, -3.19648) or object with latitude and longitude in the root { "latitude: ..., "longitude": ....}
## is_out_of_radius(pointA, pointB, radius) - Radius is in miles
radius = is_out_of_radius((55.95206, -3.19648), (55.86515, -4.25763), 40)

```

This will return

```json
{
  "distance": {
    "miles": 41.67,
    "km": 67.07,
    "meters": 67065.32,
    "yards": 73343.5
  },
  "out_of_radius": false
}
```

# Euclidean Distance
This can simply be described as stright line distance or as the crow flys. This will not be accurate in terms of finding ranges where there is a route to be adhered to. Its more of an indication rather than guidance. But can help build a picture between points. For example you could levy a percentage of overage to be applied that could guestimate that an area is out of range. However this is exponentially bad when the direct line distance is great. It might be good for something within 20 miles but not at 100 miles. A great starting resource would be to read [Euclidean Distance Formula - CUEMATH](https://www.cuemath.com/euclidean-distance-formula/)

# Purpose

The purpose of this library is to grow it into a trusted framework of getting real world distance finding for land, sea and air using real world restrictions. The ability to create pathing in a unified form to work with the likes of <b>Google Maps</b> and <b>Mapbox</b>

# End Goal
To create a machine/ai learned process that predict routing, pathing and distance. But got to start somewhere

