S2 Placewords, or simply Placewords, is a project to uniquely identify
every 5 meter square chunk of the planet with a series of 3 words.

The code here is open source, distibuted under the Apache license,
and does NOT infringe on https://patents.google.com/patent/CA2909524A1/en

The rest of this readme assumes you are somewhat familiar with S2 Cell
IDs, as described in https://s2geometry.io/

For convenience and portability, a minimalist S2 Cell ID implementation
is included, but this could be easily substituted for the real (and much
larger) Google S2 library.

S2 was chosen because the high order bits of the Cell IDs contain coarse
location information, which becomes finer as more bits are added.

S2 is, of course, also open source.

To make the conversion, a Latitude and Longitude pair is first converted
to an S2 Cell ID.  Then the 3 bits of Face information are masked off,
and the following 42 bits (corresponding to a 21 level S2 cell, with
edge lengths in the 3 to 5 meter range) are pushed through a linear
feedback shift register based shuffling algorithm.  The result is used to
generate three 14 bit numbers.  One of each of the Face bits is appended
to those numbers, giving us three 15 bit numbers, which are then mapped
to 3 words from a 32,768 entry wordlist.

This is easily reversable to obtain the original S2 Cell ID.

If additional accuracy is required, an optional 4th word can be appended.
The use of the 4th word adds an additional 14 bits of accuracy to the S2
Cell ID, which puts us in the sub 5cm range.  This 4th optional word can
be omitted if such accuracy is not required.

The wordlist has functionality to replace words (if, for example, one is
found to be offensive and needs to be replaced), so that future versions
of this software can read and interoperate with placewords generated by
older versions.

Functionality for adding wordlists from other languages is also included.

Please direct feedback to adam@wozniakconsulting.com (Adam Wozniak)