A Python implementation of the npm geogrids library - 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.
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 >, <Location >, <Location >] >>> vertices.latitude, vertices.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)
pip install geogrids
geogrids doesn’t have any third party library requirements
This is licensed under the Do What The Fuck You Want Public License as is the original JS implementation. So enjoy!
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|