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.
There are two components of the library:
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
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.fucksas featured in http://www.what3fucks.comgeogrids.encoders.goshdarnitsas featured in http://www.what3goshdarnits.com/geogrids.encoders.pokesas featured in http://www.what3pokemon.com/geogrids.encoders.cheeseswhich doesn't yet feature anywhere (AFAIK)geogrids.encoders.ducksas 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)
pip install geogrids
geogrids doesn't have any third party library requirements
Python 3.5+
This is licensed under the Do What The Fuck You Want Public License as is the original JS implementation. So enjoy!
geogrids was written by Henry Walshaw in Python, translated from the
npm geogrids library by Iván Sánchez Ortega
ducks encoder contributed by Adam Steer