s2js

s2js is a Javascript port of the s2 spherical geometry library.

| github | npm | documentation | demo |

Installation

npm install s2js

Usage

The library is available as both ESM & CJS modules:

ESM

import { s2 } from 's2js'

CJS

const { s2 } = require('s2js')

CDN

<script type="module">
  import { s2 } from 'https://esm.sh/s2js'
</script>

Features

s2js is a full-featured JavaScript/TypeScript port of Google's S2 Geometry library. It supports:

| Feature | Supported? | Notes | | ----------------------------------- | :--------: | :----------------------------------------- | | CellId, Cell | ✅ | Encoding, decoding, neighbors | | Point, LatLng | ✅ | Spherical & Planar projections | | Loop, Polygon | ✅ | Polygons, potentially with holes | | Polyline | ✅ | Represents linear paths | | RegionCoverer | ✅ | Cover regions (loops, polys) with S2 cells | | GeoJSON <> S2 conversions | ✅ | Supports all GeoJSON geometry types | | Polygon contains/intersects | ✅ | Point-in-polygon & shape intersection | | Union, Intersection, Difference | ✅ | Basic boolean polygon operations | | BigInt cell/token conversion | ✅ | Handles full 64-bit cell IDs | | CellIndex, ClosestCellQuery | ✅ | Query a list of cells with various shapes |

TODO: ADD CLOSESTEDGEQUERY HERE

Feature Completeness

The library is essentially feature compatible with the Golang library: https://github.com/golang/geo

Typescript Support

The library is written in Typescript and exports type definitions.

GeoJSON support

The supplementary geojson module provides convenience functions for working with GeoJSON data in S2:

import { geojson } from 's2js'

const s2Polyline = geojson.fromGeoJSON({
  type: 'LineString',
  coordinates: [
    [102.0, 0.0],
    [103.0, 1.0],
    [104.0, 0.0],
    [105.0, 1.0]
  ]
})

The RegionCoverer supports all geometry types including multi-geometries:

const coverer = new geojson.RegionCoverer({ maxCells: 30 })

const union = coverer.covering({
  type: 'Polygon',
  coordinates: [
    [
      [100.0, 0.0],
      [101.0, 0.0],
      [101.0, 1.0],
      [100.0, 1.0],
      [100.0, 0.0]
    ]
  ]
})

Contributing

If you'd like to contribute a module please open an Issue to discuss.

Copyright

© 2024 Peter Johnson <github:missinglink>

This source code is published under the Apache-2.0 license.