@raha-platform/s2-geometry v1.0.0

Geometry on the Sphere - JavaScript Library

A pure JavaScript port of Google's S2 Geometry library for dealing with spatial data.

The S2 Geometry is based on projecting the earth sphere onto a cube, with some scaling of face coordinates to keep things close to approximate equal area for adjacent cells. To convert a lat,lng into a cell id:

• convert lat,lng to x,y,z
• convert x,y,z into face,u,v
• u,v scaled to s,t with quadratic formula
• s,t converted to integer i,j offsets
• i,j converted to a position along a Hilbert space-filling curve
• combine face,position to get the cell id

Implemented APIs

• S2LatLng
• S2Cell

Installation

CDN

Import library from the UNPKG CDN:

<script type="module">
import {S2LatLng, S2Cell} from "//unpkg.com/@raha-platform/s2-geometry";
</script>

NPM registry

Use the package manager npm to install s2-geometry.

$ npm install @raha-platform/s2-geometry

Library will be copied to node_modules/s2-geometry directory

Direct Download

Grab the latest release file.

S2LatLng API

Skeleton of S2LatLng

S2LatLng := ObjectModel {
	@Static S2LatLng from(Number latitude, Number longitude);
	@Static S2LatLng fromInteger(BigInt identifier);
	BigInt toInteger(Level level = MAX_LEVEL);
	Generator<S2Cell> getNeighbors(level);
};
Level := RangeLimit<Number> {
	lower := 1,
	upper := 30
};
MAX_LEVEL := 30;

How to use S2LatLng

let latitude = 40.2574448;
let longitude = -111.7089464;
// Main factory method to create a S2LatLng object from pair (latitude, longitude)
let point = S2LatLng.from(latitude, longitude);

let level = 15; // Range of level is between 1 and 30
let cellId = point.toInteger(level);
console.log(cellId);
// It prints 9749618446378729472n

// Factory method to create a S2LatLng object from BigInt
point = S2LatLng.fromInteger(cellId);
console.log(point);
// It prints {lat: 40.2574448, lng: -111.7089464}

for (let cell of point.getNeighbors(level)) {
	console.log(cell);
}

S2Cell API

The S2 hierarchy is useful for spatial indexing and for approximating regions as a collection of cells. Cells can be used to represent both points and regions: points are generally represented as leaf cells, while regions are represented as collections of cells at any level(s). Each cell is uniquely identified by a 64-bit S2CellId. The S2 cells are numbered in a special way in order to maximize locality of reference when they are used for spatial indexing (compared to other methods of numbering the cells). S2CellId combine face and the hilbert curve position into a single 64 bit integer. this gives efficient space and speed.

Skeleton of S2Cell

S2Cell := ObjectModel {
	@Static from(Face face, OrderedPair ij, Level level = MAX_LEVEL); // Internal use
	
	@Static S2Cell fromLatLng(S2LatLng latLng, Level level = MAX_LEVEL);
	S2LatLng toLatLng();

	@Static S2Cell fromInteger(BigInt identifier);
	BigInt toInteger();
	
	Generator<S2LatLng> getCornerLatLngs();
	Generator<S2Cell> getNeighbors();
	S2Cell move(Number step);
};
Face := RangeLimit<Number> {
	lower := 0,
	upper := 5
};

How to use S2Cell

// Factory method to create a S2Cell object from S2LatLng and level
let cell = S2Cell.fromLatLng(point, level);
console.log(cell.toLatLng(), ` == `, point);
// It prints true

// Factory method to create a S2Cell object from BigInt
cell = S2Cell.fromInteger(cellId);
console.log(cell.toInteger() == point.toInteger());
// It prints true

for (let cell of point.getNeighbors()) {
	console.log(cell);
}
// It prints the neighbors from left, down, right and up.

// You can get the previous and next S2Cell from any given cell:
let nextCell = cell.move(1);
let previousCell = cell.move(-1);

Supported engines

This project has been tested and works on the following engines:

• Node.js 10.4+
• Chrome (desktop & Android) 67+
• Firefox 68+
• Safari 14+ (desktop & iOS)
• Latest version of other web-browsers

Resources

• S2 Geometry Library
• S2Cell Hierarchy
• Presentation of Google's S2 Library
• Spatial indexing with Quadtrees and Hilbert Curves

Alternative projects

• coolaj86 / s2-geometry.js
• Node S2Geometry Typescript

License

This project is licensed by Mahdi NezaratiZadeh under the CC-BY-SA license.