A Python implementation of the npm geogrids library - utilities for working with Global Discrete Geodetic Grids (GDGGs)

## Project description

A Python implementation of the npm geogrids library by Iván Sánchez Ortega - utilities for working with Global Discrete Geodetic Grids (GDGGs).

This module contains both a Location object that can be used to generate a hash or take a has and generate a location, along with an encoders module that can transform the code into a (hopefully) useful text string.

This is written with the default encoders from the original library, and can be easily extended to use a text set of your choice.

## Usage

There are two components of the library:

### Representing a location

Given some location with a latitude and longitude, for example: -35.6498, 150.2935 you can easily create a hash as either a simple string or a numeric value:

>>> latitude = -35.6498 >>> longitude = 150.2935 >>> import geogrids >>> geogrids.gdgg.latitude_longitude_to_readable_hash(latitude=latitude, longitude=longitude) '702020210311' >>> geogrids.gdgg.latitude_longitude_to_numeric_hash(latitude=latitude, longitude=longitude) 12108871

Of course you can go the other direction as well:

>>> geogrids.gdgg.numeric_hash_to_latitude_longitude(12108871) (-35.65283203125, 150.2789682218808) >>> geogrids.gdgg.readable_hash_to_latitude_longitude('702020210311') (-35.65283203125, 150.2789682218808)

Notice that the hashes are location approximations depending on a level of precision - the higher the precision the better the accuracy:

>>> numeric_hash = geogrids.gdgg.latitude_longitude_to_numeric_hash(latitude=latitude, longitude=longitude, precision=55) >>> geogrids.gdgg.numeric_hash_to_latitude_longitude(numeric_hash, precision=55) (-35.64979965984821, 150.2934998246466)

Effectively these hashes define a location within a triangular region,
which you can retrieve from either the `numeric_hash_to_area` or the
`readable_hash_to_area` functions, which return a collection of
`Location` objects (usually the three vertices of a triangular region,
but close to the poles for simplification the default is to return a
box):

>>> vertices = geogrids.gdgg.numeric_hash_to_area(numeric_hash) >>> vertices [<Location [702020210311]>, <Location [702020210311]>, <Location [702020210311]>] >>> vertices[0].latitude, vertices[0].longitude (-35.63964843750004, 150.24252223120465)

In general it’s advisable to just stick to the hashes and the latitudes
and longitudes, but the `Location` object does implement a
__geo_feature__
interface which means you can use it with other libraries that work with
this interface for more complicated geometric operations, for example
via the Shapely library:

>>> from shapely import geometry >>> points = [geometry.shape(vertex) for vertex in vertices] >>> line = geometry.LineString(points) >>> line.length 0.11570586750499379 >>> polygon = geometry.Polygon(line) >>> polygon.area 0.0015986572857657128

### Encoding and decoding a hash

The encoders allow you to transform a hash to an easily memorisable string and back again. Out of the box this comes with a number of encoders:

`geogrids.encoders.fucks`as featured in http://www.what3fucks.com`geogrids.encoders.goshdarnits`as featured in http://www.what3goshdarnits.com/`geogrids.encoders.pokes`as featured in http://www.what3pokemon.com/`geogrids.encoders.cheeses`which doesn’t yet feature anywhere (AFAIK)`geogrids.encoders.ducks`as featured in- http://www.what3ducks.com

Given a numeric hash of a location (see above) these are easy to use:

>>> geogrids.encoders.cheeses.hash_to_string(numeric_hash, precision=25) 'Dubliner Requeijão Provolone Telemea' >>> geogrids.encoders.cheeses.hash_to_string(numeric_hash, precision=55) 'Dubliner Requeijão Provolone Telemea Danablu Coulommiers Chevrotin'

Or given the readable encoding it’s simple to go back the other way:

>>> numeric_hash, precision = geogrids.encoders.cheeses.string_to_hash('Dubliner Requeijão Provolone Telemea') >>> numeric_hash, precision (3870868551, 32) >>> geogrids.gdgg.numeric_hash_to_latitude_longitude(numeric_hash, precision) (-35.647064208984375, 150.2948563112389)

If you don’t want to use one of the builtin encoders, you can generate your own easily:

>>> wordlist = list('😀😎🤬😱😈👍🖖⚽🐶🐍🐡🦜🍀🌞🌚🔥')

*Note* the wordlist should be length that is a power of two - the level
used for calculating precisions is rounded down to the closest power of
two - any words after that number will be skipped.

>>> emoji_encoder = geogrids.encoders.Encoder(wordlist, separator='') >>> emoji_encoder.hash_to_string(numeric_hash, precision) '⚽😈😈🍀🐶🦜🖖🌚'

**Warning** One key consideration with the encoders: if you create an
encoding and share it with someone else the wordlist must be in exactly
the same order! Otherwise when decoding you’ll get completely different
results!

>>> numeric_hash, precision = emoji_encoder.string_to_hash('⚽😈😈🍀🐶🦜🖖🌚') >>> geogrids.gdgg.numeric_hash_to_latitude_longitude(numeric_hash, precision) (-35.647064208984375, 150.2948563112389)

## Installation

`pip install geogrids`

### Requirements

`geogrids` doesn’t have any third party library requirements

## Compatibility

Python 3.5+

## Licence

This is licensed under the Do What The Fuck You Want Public License as is the original JS implementation. So enjoy!

## Project details

## Release history Release notifications

## Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help | File type | Python version | Upload date |
---|---|---|---|

geogrids-1.1.0-py3-none-any.whl (21.1 kB) Copy SHA256 hash SHA256 | Wheel | py3 | |

geogrids-1.1.0.tar.gz (22.7 kB) Copy SHA256 hash SHA256 | Source | None |