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
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 | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.