s2-geometry.js/README.md

217 lines
4.3 KiB
Markdown
Raw Normal View History

2016-07-26 04:42:53 +00:00
s2-geometry (JavaScript/ES5.1)
2014-01-23 17:05:56 +00:00
======================
2016-07-28 09:23:39 +00:00
A pure JavaScript/ES5.1 port of Google/Niantic's S2 Geometry library (as used by **Ingress**, **Pokemon GO**)
2014-01-23 17:10:43 +00:00
Currently contains basic support for S2Cell
2016-08-03 22:48:49 +00:00
<table>
<tr>
<td></td>
<td>
2016-08-03 23:59:48 +00:00
Face 2
<br>
Orientation A
2016-08-03 22:48:49 +00:00
2016-08-03 22:54:02 +00:00
<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>
2016-08-03 23:54:58 +00:00
2016-08-04 00:00:49 +00:00
<br>
2016-08-03 23:59:48 +00:00
The North Pole<br>(and Canada / Europe)
2016-08-03 22:48:49 +00:00
</td>
<td></td>
</tr>
<tr>
<td>
2016-08-03 23:59:48 +00:00
Face 0
<br>
Orientation A
2016-08-03 22:48:49 +00:00
2016-08-03 22:54:02 +00:00
<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>
2016-08-03 23:54:58 +00:00
2016-08-04 00:00:49 +00:00
<br>
2016-08-03 23:59:48 +00:00
Africa
2016-08-03 22:48:49 +00:00
</td>
<td>
2016-08-03 23:59:48 +00:00
Face 1
<br>
Orientation D
2016-08-03 22:48:49 +00:00
2016-08-03 22:54:02 +00:00
<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>
2016-08-03 23:54:58 +00:00
2016-08-04 00:00:49 +00:00
<br>
2016-08-03 23:59:48 +00:00
Asia
2016-08-03 22:48:49 +00:00
</td>
<td>
2016-08-03 23:59:48 +00:00
Face 3
<br>
Orientation D
2016-08-03 22:48:49 +00:00
2016-08-03 22:54:02 +00:00
<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>
2016-08-03 23:54:58 +00:00
2016-08-04 00:00:49 +00:00
<br>
2016-08-03 23:59:48 +00:00
Nothing<br>(and Australia)
2016-08-03 22:48:49 +00:00
</td>
<td>
2016-08-03 23:59:48 +00:00
Face 4
<br>
Orientation A
2016-08-03 22:48:49 +00:00
2016-08-03 22:54:02 +00:00
<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>
2016-08-03 23:54:58 +00:00
2016-08-04 00:00:49 +00:00
<br>
2016-08-03 23:59:48 +00:00
The Americas<br>(and Provo, UT)
2016-08-03 22:48:49 +00:00
</td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td>
2016-08-03 23:59:48 +00:00
Face 5
<br>
Orientation D
2016-08-03 22:48:49 +00:00
2016-08-03 22:54:02 +00:00
<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>
2016-08-03 23:54:58 +00:00
2016-08-04 00:00:49 +00:00
<br>
2016-08-03 23:59:48 +00:00
Antarctica
2016-08-03 22:48:49 +00:00
</td>
</tr>
</table>
2016-07-28 09:23:39 +00:00
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)
2016-07-26 04:42:53 +00:00
Simple Examples
---------------
```javascript
2016-08-03 23:43:35 +00:00
'use strict';
var S2 = require('s2-geometry').S2;
var lat = 40.2574448;
var lng = -111.7089464;
2016-07-26 04:42:53 +00:00
var level = 15;
2016-07-28 06:25:17 +00:00
2016-08-03 23:43:35 +00:00
//
// Convert from Lat / Lng
//
var key = S2.latLngToKey(lat, lng, level);
// '4/032212303102210'
//
// Convert between Hilbert Curve Quadtree Key and S2 Cell Id
//
var id = S2.keyToId(key);
// '9749618446378729472'
var key = S2.idToKey(id);
// '9749618446378729472'
2016-08-18 05:35:20 +00:00
//
// Convert between Quadkey and Id
//
var latlng = S2.keyToLatLng(key);
var latlng = S2.idToLatLng(id);
2016-08-03 23:43:35 +00:00
//
// Neighbors
//
var neighbors = S2.latLngToNeighborKeys(lat, lng, level);
// [ keyLeft, keyDown, keyRight, keyUp ]
//
// Previous, Next, and Step
//
var nextKey = S2.nextKey(key);
var prevKey = S2.prevKey(key);
var backTenKeys = S2.stepKey(key, -10);
2016-07-28 06:25:17 +00:00
```
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)
2016-07-28 09:17:53 +00:00
```javascript
2016-08-03 23:43:35 +00:00
var key = S2.latLngToKey(40.2574448, -111.7089464, 15); // '4/032212303102210'
var id = S2.keyToId(key); // '9749618446378729472'
2016-07-28 06:25:17 +00:00
var nextKey = S2.nextKey(key);
2016-08-03 23:43:35 +00:00
var nextId = S2.keyToId(nextKey);
2016-07-28 06:25:17 +00:00
var prevKey = S2.prevKey(key);
2016-08-03 23:43:35 +00:00
var prevId = S2.keyToId(prevKey);
var backTenKeys = S2.stepKey(key, -10);
2016-07-28 06:25:17 +00:00
// See it
2016-07-28 09:21:24 +00:00
console.log(prevKey); // '4/032212303102203'
console.log(key); // '4/032212303102210'
console.log(nextKey); // '4/032212303102211'
2016-07-28 06:25:17 +00:00
console.log(nextId);
```
2016-07-28 00:41:04 +00:00
2016-08-03 23:43:35 +00:00
convert Cell Id to Hilbert Curve Quad Tree
2016-07-28 00:41:04 +00:00
------------------
Convert from base 10 (decimal) `S2 Cell Id` to base 4 `quadkey` (aka hilbert curve quadtree id)
Example '4/032212303102210' becomes '9749618446378729472'
2016-07-28 09:17:53 +00:00
```javascript
2016-07-28 00:41:04 +00:00
'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
2016-08-03 23:43:35 +00:00
var cellId = S2.facePosLevelToId(face, position, level);
2016-07-28 00:41:04 +00:00
console.log(cellId);
```
Convert from hilbert quadtree id to s2 cell id:
Example '9749618446378729472' becomes '4/032212303102210'
2016-07-28 09:21:24 +00:00
```javascript
2016-07-28 00:41:04 +00:00
'use strict';
var cellId = '9749618446378729472';
2016-08-03 23:43:35 +00:00
var hilbertQuadkey = S2.idToKey(cellId);
2016-07-28 00:41:04 +00:00
console.log(hilbertQuadkey);
```
2016-08-18 05:35:20 +00:00
Convert Key and Id to LatLng
---------------------
```javascript
var latlng = S2.keyToLatLng('4/032212303102210');
var latlng = S2.idToLatLng('9749618446378729472');
```