these-3-words/thesethreewords.py

"""
thesethreewords: Human-readable addresses for every 3x3m square of the earth's surface.
The simplest ways to use this module are the `three_words` and `decode`
functions. For more see `WordHasher`.
"""
import random

import geohash


def get_words(fname):
    lines = open(fname)
    words = []
    for word in lines:
        words.append(word.strip())

    lines.close()
    random.seed(634634)
    random.shuffle(words)
    words = words[:2**15]
    assert len(words) == len(set(words))
    return words

# These read like alien races from a sci-fi book
GOOGLE_WORDLIST = get_words("words/google-ngram-list")
# current best list for the three word hash
WORDNET_LEMMAS = get_words("words/wordnet-list")

# Human friendly word list, taken directly from humanhash project
# these are the best words but there are not enough of
# them so we only use them for the six word hash
HUMAN_WORDLIST = (
        'ack', 'alabama', 'alanine', 'alaska', 'alpha', 'angel', 'apart', 'april',
        'arizona', 'arkansas', 'artist', 'asparagus', 'aspen', 'august', 'autumn',
        'avocado', 'bacon', 'bakerloo', 'batman', 'beer', 'berlin', 'beryllium',
        'black', 'blossom', 'blue', 'bluebird', 'bravo', 'bulldog', 'burger',
        'butter', 'california', 'carbon', 'cardinal', 'carolina', 'carpet', 'cat',
        'ceiling', 'charlie', 'chicken', 'coffee', 'cola', 'cold', 'colorado',
        'comet', 'connecticut', 'crazy', 'cup', 'dakota', 'december', 'delaware',
        'delta', 'diet', 'don', 'double', 'early', 'earth', 'east', 'echo',
        'edward', 'eight', 'eighteen', 'eleven', 'emma', 'enemy', 'equal',
        'failed', 'fanta', 'fifteen', 'fillet', 'finch', 'fish', 'five', 'fix',
        'floor', 'florida', 'football', 'four', 'fourteen', 'foxtrot', 'freddie',
        'friend', 'fruit', 'gee', 'georgia', 'glucose', 'golf', 'green', 'grey',
        'hamper', 'happy', 'harry', 'hawaii', 'helium', 'high', 'hot', 'hotel',
        'hydrogen', 'idaho', 'illinois', 'india', 'indigo', 'ink', 'iowa',
        'island', 'item', 'jersey', 'jig', 'johnny', 'juliet', 'july', 'jupiter',
        'kansas', 'kentucky', 'kilo', 'king', 'kitten', 'lactose', 'lake', 'lamp',
        'lemon', 'leopard', 'lima', 'lion', 'lithium', 'london', 'louisiana',
        'low', 'magazine', 'magnesium', 'maine', 'mango', 'march', 'mars',
        'maryland', 'massachusetts', 'may', 'mexico', 'michigan', 'mike',
        'minnesota', 'mirror', 'mississippi', 'missouri', 'mobile', 'mockingbird',
        'monkey', 'montana', 'moon', 'mountain', 'muppet', 'music', 'nebraska',
        'neptune', 'network', 'nevada', 'nine', 'nineteen', 'nitrogen', 'north',
        'november', 'nuts', 'october', 'ohio', 'oklahoma', 'one', 'orange',
        'oranges', 'oregon', 'oscar', 'oven', 'oxygen', 'papa', 'paris', 'pasta',
        'pennsylvania', 'pip', 'pizza', 'pluto', 'potato', 'princess', 'purple',
        'quebec', 'queen', 'quiet', 'red', 'river', 'robert', 'robin', 'romeo',
        'rugby', 'sad', 'salami', 'saturn', 'september', 'seven', 'seventeen',
        'shade', 'sierra', 'single', 'sink', 'six', 'sixteen', 'skylark', 'snake',
        'social', 'sodium', 'solar', 'south', 'spaghetti', 'speaker', 'spring',
        'stairway', 'steak', 'stream', 'summer', 'sweet', 'table', 'tango', 'ten',
        'tennessee', 'tennis', 'texas', 'thirteen', 'three', 'timing', 'triple',
        'twelve', 'twenty', 'two', 'uncle', 'undress', 'uniform', 'uranus', 'utah',
        'vegan', 'venus', 'vermont', 'victor', 'video', 'violet', 'virginia',
        'washington', 'west', 'whiskey', 'white', 'william', 'winner', 'winter',
        'wisconsin', 'wolfram', 'wyoming', 'xray', 'yankee', 'yellow', 'zebra',
        'zulu')


class WordHasher(object):
    def __init__(self):
        """Convert latitude and longitudes into human readable strings."""
        self._symbols = "0123456789bcdefghjkmnpqrstuvwxyz"
        self._decode_symbols = dict((ch, i) for (i, ch) in enumerate(self._symbols))
        self._encode_symbols = dict((i, ch) for (i, ch) in enumerate(self._symbols))
        self.six_wordlist = HUMAN_WORDLIST
        self.three_wordlist = GOOGLE_WORDLIST
        
    def three_words(self, lat_long):
        """Convert coordinate to a combination of three words

        The coordinate is defined by latitude and longitude
        in degrees.
        """
        lat, lon = lat_long
        gh = geohash.encode(lat, lon, 9)
        words = "-".join(self.three_wordlist[p] for p in self.to_rugbits(self.geo_to_int(gh)))
        return words

    def six_words(self, lat_long):
        """Convert coordinate to a combination of six words

        The coordinate is defined by latitude and longitude
        in degrees.

        With six words the word list contains only words
        which are short, easy to pronounce and easy distinguish.
        """
        lat, lon = lat_long
        gh = geohash.encode(lat, lon, 9)
        words = "-".join(self.six_wordlist[p] for p in self.to_bytes(self.pad(gh)))
        return words

    def decode(self, words):
        """Decode words back to latitude and longitude"""
        words = words.split("-")
        if len(words) == 3:
            i = self.rugbits_to_int([self.three_wordlist.index(w) for w in words])

        elif len(words) == 6:
            i = self.bytes_to_int([self.six_wordlist.index(w) for w in words])
            i = self.unpad(i)

        else:
            raise RuntimeError("Do not know how to decode a set of %i words."%(len(words)))

        geo_hash = self.int_to_geo(i)
        return geohash.decode(geo_hash)

    def geo_to_int(self, geo_hash):
        """Decode `geo_hash` to an integer"""
        base = len(self._symbols)
        number = 0
        for symbol in geo_hash:
            number = number*base + self._decode_symbols[symbol]
        
        return number

    def int_to_geo(self, integer):
        """Encode `integer` to a geo hash"""
        base = len(self._symbols)
        symbols = []
        while integer > 0:
            remainder = integer % base
            integer //= base
            symbols.append(self._encode_symbols[remainder])
            
        return ''.join(reversed(symbols))

    def pad(self, geo_hash):
        """Pad nine character `geo_hash` to 48bit integer"""
        assert len(geo_hash) == 9
        return self.geo_to_int(geo_hash) * 8

    def unpad(self, integer):
        """Remove 3bit of padding to get 45bit geo hash"""
        return integer>>3
    
    def to_bytes(self, integer):
        """Convert a 48bit `integer` to a list of 6bytes"""
        bytes = [integer & 0b11111111]
        for n in xrange(1,6):
            div = 2**(n*8)
            bytes.append((integer/div) & 0b11111111)
        
        bytes.reverse()
        return bytes

    def bytes_to_int(self, bytes):
        """Convert a list of 6`bytes` to an integer"""
        assert len(bytes) == 6
        N = 0
        bytes.reverse()
        for n,b in enumerate(bytes):
            N += b * (2**(8*(n)))
            
        return N

    def to_rugbits(self, integer):
        """Convert a 45bit `integer` to a list of 3rugbits
    
        A rugbit is like a byte but with 15bits instead of eight.
        """
        fifteen_bits = 0b111111111111111
        rugbits = [(integer/(2**30)) & fifteen_bits,
                   (integer/(2**15)) & fifteen_bits,
                   integer & fifteen_bits]
        return rugbits

    def rugbits_to_int(self, rugbits):
        """Convert a list of `rugbits` to an integer"""
        assert len(rugbits) == 3
        return (rugbits[0] *(2**30)) + (rugbits[1] *(2**15)) + (rugbits[2])


DEFAULT_HASHER = WordHasher()
three_words = DEFAULT_HASHER.three_words
six_words = DEFAULT_HASHER.six_words
decode = DEFAULT_HASHER.decode