s2-geometry.js/README.md

s2-geometry (JavaScript/ES5.1)
======================

A pure JavaScript/ES5.1 port of Google/Niantic's S2 Geometry library (as used by **Ingress**, **Pokemon GO**)

Currently contains basic support for S2Cell

<table>
<tr>
<td></td>
<td>
Face 2 - The North Pole (and Canada and Europe)

<a href="http://i.imgur.com/SODO4bT.jpg" target="_face2"><img src="http://i.imgur.com/SODO4bTt.jpg" title="Face 2" alt="Face 2"></a>
</td>
<td></td>
</tr>
<tr>
<td>
Face 0 - Africa

<a href="http://i.imgur.com/dLI5Zd1.jpg" target="_face0"><img src="http://i.imgur.com/dLI5Zd1t.jpg" title="Face 0" alt="Face 0"></a>
</td>
<td>
Face 1 - Asia

<a href="http://i.imgur.com/duTLDTV.jpg" target="_face1"><img src="http://i.imgur.com/duTLDTVt.jpg" title="Face 1" alt="Face 1"></a>
</td>
<td>
Face 3 - Nothing... and Australia

<a href="http://i.imgur.com/6Ho35Tc.jpg" target="_face3"><img src="http://i.imgur.com/6Ho35Tct.jpg" title="Face 3" alt="Face 3"></a>
</td>
<td>
Face 4 - The Americas (and Provo, UT)

<a href="http://i.imgur.com/3IBAfqj.jpg" target="_face4"><img src="http://i.imgur.com/3IBAfqjt.jpg" title="Face 4" alt="Face 4"></a>
</td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td>
Face 5 - Antarctica

<a href="http://i.imgur.com/HZCBvgy.jpg" target="_face5"><img src="http://i.imgur.com/HZCBvgyt.jpg" title="Face 5" alt="Face 5"></a>
</td>
</tr>
</table>

Where is this being used?
---------------------

* [pokemap-webapp](https://github.com/Daplie/pokemap-webapp)
* [node-pokemap](https://github.com/Daplie/node-pokemap)
* [Pokemon-GO-node-api](https://github.com/Daplie/Pokemon-GO-node-api)

Simple Examples
---------------

```javascript
var level = 15;
var latlng = { lat: 40.2574448, lng: -111.7089464 };
var cell = S2.S2Cell.FromLatLng(latlng, level);

cell.getNeighbors();  // [ cellLeft, cellDown, cellRight, cellUp ]

cell.getLatLng();     // { lat: 40.2574448, lng: -111.7089464 }

var key = cell.toHilbertQuadkey();
```

Previous and Next
-----------------

You can get the previous and next S2CellId from any given Key:

1. Convert from Lat/Lng to Key (Face and Hilbert Curve Quadtree)
2. Get the Previous or Next Key
3. Convert the Key to an Id (uint64 string)

```javascript
var key = S2.latLngToKey(40.2574448, -111.7089464);   // '4/032212303102210'
var id = S2.toId(key);                                // '9749618446378729472'

var nextKey = S2.nextKey(key);
var nextId = S2.toId(nextKey);

var prevKey = S2.prevKey(key);
var prevId = S2.toId(prevKey);

// See it
console.log(prevKey);                                 // '4/032212303102203'
console.log(key);                                     // '4/032212303102210'
console.log(nextKey);                                 // '4/032212303102211'
console.log(nextId);
```

convert Cell Id to Quadkey
------------------

Convert from base 10 (decimal) `S2 Cell Id` to base 4 `quadkey` (aka hilbert curve quadtree id)

Example '4/032212303102210' becomes '9749618446378729472'

```javascript
'use strict';

var quadkey = '4/032212303102210'
var parts = quadkey.split('/');
var face = parts[0];                  // 4
var position = parts[1];              // '032212303102210';
var level = '032212303102210'.length; // 15

var cellId = S2.fromFacePosLevel(face, position, level);

console.log(cellId);
```

Convert from hilbert quadtree id to s2 cell id:

Example '9749618446378729472' becomes '4/032212303102210'

```javascript
'use strict';

var cellId = '9749618446378729472';

var hilbertQuadkey = S2.toHilbertQuadkey(cellId);

console.log(hilbertQuadkey);
```