feat(geojson): encoding/decoding, RegionCoverer

Author: missinglink

geojson/RegionCoverer.ts

@@ -0,0 +1,114 @@
+import type * as geojson from 'geojson'
+import { MAX_LEVEL } from '../s2/cellid_constants'
+import { CellUnion } from '../s2/CellUnion'
+import * as geometry from './geometry'
+import { Polyline } from '../s2/Polyline'
+import { Polygon } from '../s2/Polygon'
+import type { Region } from '../s2/Region'
+import type { RegionCovererOptions as S2RegionCovererOptions } from '../s2/RegionCoverer'
+import { RegionCoverer as S2RegionCoverer } from '../s2/RegionCoverer'
+
+/**
+ * RegionCovererOptions allows the RegionCoverer to be configured.
+ */
+export interface RegionCovererOptions extends S2RegionCovererOptions {
+  /**
+   * the maximum desired number of cells for each member of a multi-member geometry in the approximation.
+   * @default Math.max(Math.floor(maxCells / 10), 8)
+   */
+  memberMaxCells?: number
+
+  /**
+   * the maximum size the approximation may reach before a compaction is triggered.
+   * used to avoid OOM errors.
+   * @default 65536
+   */
+  compactAt?: number
+
+  /**
+   * the maximum area of a shape to be considered for fast covering.
+   * used to speed up covering small shapes.
+   * area values are between 0 and 4*Pi.
+   * @default 1e-6
+   */
+  smallAreaEpsilon?: number
+}
+
+/**
+ * RegionCoverer allows arbitrary GeoJSON geometries to be approximated as unions of cells (CellUnion).
+ *
+ * Typical usage:
+ *
+ * 	feature = loadGeoJSON()
+ * 	rc = new RegionCoverer({ maxCells: 256, memberMaxCells: 64 })
+ * 	covering = rc.covering(feature.geometry)
+ *
+ * @beta unstable API
+ */
+export class RegionCoverer {
+  coverer: S2RegionCoverer
+  memberCoverer: S2RegionCoverer
+  compactAt: number
+  smallAreaEpsilon: number
+
+  /**
+   * Returns a new RegionCoverer with the appropriate defaults.
+   *
+   * @param options - RegionCoverer options
+   *
+   * @category Constructors
+   */
+  constructor({
+    minLevel = 0,
+    maxLevel = MAX_LEVEL,
+    levelMod = 1,
+    maxCells = 8,
+    memberMaxCells = Math.max(Math.floor(maxCells / 10), 8),
+    compactAt = 65536,
+    smallAreaEpsilon = 1e-6
+  }: RegionCovererOptions = {}) {
+    this.coverer = new S2RegionCoverer({ minLevel, maxLevel, levelMod, maxCells })
+    this.memberCoverer = new S2RegionCoverer({ minLevel, maxLevel, levelMod, maxCells: memberMaxCells })
+    this.compactAt = compactAt
+    this.smallAreaEpsilon = smallAreaEpsilon
+  }
+
+  /** Computes the covering of a multi-member geometry (ie. MultiPoint, MultiLineString, MultiPolygon). */
+  private mutliMemberCovering(shapes: Region[]): CellUnion {
+    // sort shapes from largest to smallest
+    shapes.sort((a: Region, b: Region): number => RegionCoverer.area(b) - RegionCoverer.area(a))
+
+    let union = new CellUnion()
+    shapes.forEach((shape: Region) => {
+      // optionally elect to use a fast covering method for small areas
+      const fast = union.length >= this.memberCoverer.maxCells && RegionCoverer.area(shape) < this.smallAreaEpsilon
+
+      // append covering to union
+      union = CellUnion.fromUnion(
+        union,
+        fast ? this.memberCoverer.fastCovering(shape) : this.memberCoverer.covering(shape)
+      )
+
+      // force compact large coverings to avoid OOM errors
+      if (union.length >= this.compactAt) union = this.coverer.covering(union)
+    })
+
+    // reduce the global covering to maxCells
+    if (union.length < this.coverer.maxCells) return union
+    return this.coverer.covering(union)
+  }
+
+  /** Returns a CellUnion that covers the given GeoJSON geometry and satisfies the various restrictions. */
+  covering(geom: geojson.Geometry): CellUnion {
+    const shape = geometry.unmarshal(geom)
+    if (Array.isArray(shape)) return this.mutliMemberCovering(shape as Region[])
+    return this.coverer.covering(shape)
+  }
+
+  /** Computes the area of a shape */
+  static area(shape: Region): number {
+    if (shape instanceof Polygon) return shape.area()
+    if (shape instanceof Polyline) shape.capBound().area()
+    return 0
+  }
+}

geojson/_index.ts

@@ -0,0 +1,23 @@
+/**
+ * Module geojson implements types and functions for working with GeoJSON.
+ * @module geojson
+ */
+// export * as Position from './position'
+// export * as Loop from './loop'
+
+export * as Point from './point'
+export * as Linestring from './linestring'
+export * as Polygon from './polygon'
+
+export * as MultiPoint from './point_multi'
+export * as MultiLineString from './linestring_multi'
+export * as MultiPolygon from './polygon_multi'
+
+export * as Geometry from './geometry'
+
+export * as Rect from './rect'
+export * as Cell from './cell'
+export * as CellID from './cellid'
+
+export { RegionCoverer } from './RegionCoverer'
+export type { RegionCovererOptions } from './RegionCoverer'

geojson/cell.ts

@@ -0,0 +1,24 @@
+import type * as geojson from 'geojson'
+import { Cell } from '../s2/Cell'
+import { Loop } from '../s2/Loop'
+import { Polygon } from '../s2/Polygon'
+import * as polygon from './polygon'
+import * as loop from './loop'
+
+/**
+ * Returns a geojson Polygon given an s2 Cell.
+ * @category Constructors
+ */
+export const marshal = (cell: Cell): geojson.Polygon => {
+  const loop = new Loop([cell.vertex(0), cell.vertex(1), cell.vertex(2), cell.vertex(3)])
+  return polygon.marshal(new Polygon([loop]))
+}
+
+/**
+ * Constructs a Cell from the centroid of a geojson Polygon.
+ * @category Constructors
+ */
+export const unmarshal = (geometry: geojson.Polygon): Cell => {
+  const ring = loop.unmarshal(geometry.coordinates[0], 0)
+  return Cell.fromPoint(ring.capBound().centroid())
+}

geojson/cell_test.ts

@@ -0,0 +1,26 @@
+import { test, describe } from 'node:test'
+import { deepEqual } from 'node:assert/strict'
+import * as cell from './cell'
+import { randomCellIDForLevel } from '../s2/testing'
+import { Cell } from '../s2/Cell'
+
+describe('geojson', () => {
+  test('cell', (t) => {
+    // @todo: test other levels
+    const faceCells: Cell[] = [
+      Cell.fromCellID(randomCellIDForLevel(30)),
+      Cell.fromCellID(randomCellIDForLevel(30)),
+      Cell.fromCellID(randomCellIDForLevel(30)),
+      Cell.fromCellID(randomCellIDForLevel(30)),
+      Cell.fromCellID(randomCellIDForLevel(30)),
+      Cell.fromCellID(randomCellIDForLevel(30)),
+      Cell.fromCellID(randomCellIDForLevel(30))
+    ]
+
+    faceCells.forEach((c) => {
+      const encoded = cell.marshal(c)
+      const decoded = cell.unmarshal(encoded)
+      deepEqual(decoded, c)
+    })
+  })
+})

geojson/cellid.ts

@@ -0,0 +1,23 @@
+import type * as geojson from 'geojson'
+import type { CellID } from '../s2/cellid'
+import { Cell } from '../s2/Cell'
+import * as cellid from '../s2/cellid'
+import * as cell from './cell'
+import * as loop from './loop'
+
+/**
+ * Returns a geojson Polygon given an s2 CellID.
+ * @category Constructors
+ */
+export const marshal = (cid: CellID): geojson.Polygon => {
+  return cell.marshal(Cell.fromCellID(cid))
+}
+
+/**
+ * Constructs the centroid CellID given a geojson Polygon.
+ * @category Constructors
+ */
+export const unmarshal = (geometry: geojson.Polygon): CellID => {
+  const ring = loop.unmarshal(geometry.coordinates[0], 0)
+  return cellid.fromPoint(ring.capBound().centroid())
+}

geojson/cellid_test.ts

@@ -0,0 +1,26 @@
+import { test, describe } from 'node:test'
+import { equal } from 'node:assert/strict'
+import * as cellid from './cellid'
+import type { CellID } from '../s2/cellid'
+import { randomCellIDForLevel } from '../s2/testing'
+
+describe('geojson', () => {
+  test('cellid', (t) => {
+    // @todo: test other levels
+    const faces: CellID[] = [
+      randomCellIDForLevel(30),
+      randomCellIDForLevel(30),
+      randomCellIDForLevel(30),
+      randomCellIDForLevel(30),
+      randomCellIDForLevel(30),
+      randomCellIDForLevel(30),
+      randomCellIDForLevel(30)
+    ]
+
+    faces.forEach((cid) => {
+      const encoded = cellid.marshal(cid)
+      const decoded = cellid.unmarshal(encoded)
+      equal(decoded, cid)
+    })
+  })
+})

geojson/geometry.ts

@@ -0,0 +1,48 @@
+import type * as geojson from 'geojson'
+import { Point } from '../s2/Point'
+import { Polyline } from '../s2/Polyline'
+import { Polygon } from '../s2/Polygon'
+import * as point from './point'
+import * as linestring from './linestring'
+import * as polygon from './polygon'
+import * as point_multi from './point_multi'
+import * as linestring_multi from './linestring_multi'
+import * as polygon_multi from './polygon_multi'
+
+type Geometry = Point | Polyline | Polygon | Geometry[]
+
+/**
+ * Returns a geojson Geometry given a s2 shape(s).
+ * @category Constructors
+ */
+export const marshal = (shape: Geometry): geojson.Geometry => {
+  if (shape instanceof Point) return point.marshal(shape)
+  if (shape instanceof Polyline) return linestring.marshal(shape)
+  if (shape instanceof Polygon) return polygon.marshal(shape)
+
+  if (Array.isArray(shape) && shape.length) {
+    if (shape.every((g) => g instanceof Point)) return point_multi.marshal(shape as Point[])
+    if (shape.every((g) => g instanceof Polyline)) return linestring_multi.marshal(shape as Polyline[])
+    if (shape.every((g) => g instanceof Polygon)) return polygon_multi.marshal(shape as Polygon[])
+  }
+
+  throw new Error(`unsupported: ${shape?.constructor?.name || 'UnknownShape'}`)
+}
+
+/**
+ * Constructs s2 shape(s) given a geojson geometry.
+ * @category Constructors
+ */
+export const unmarshal = (geometry: geojson.Geometry): Geometry => {
+  const t = geometry?.type
+
+  if (t === 'Point') return point.unmarshal(geometry as geojson.Point)
+  if (t === 'LineString') return linestring.unmarshal(geometry as geojson.LineString)
+  if (t === 'Polygon') return polygon.unmarshal(geometry as geojson.Polygon)
+
+  if (t === 'MultiPoint') return point_multi.unmarshal(geometry as geojson.MultiPoint)
+  if (t === 'MultiLineString') return linestring_multi.unmarshal(geometry as geojson.MultiLineString)
+  if (t === 'MultiPolygon') return polygon_multi.unmarshal(geometry as geojson.MultiPolygon)
+
+  throw new Error(`unsupported: ${t || 'UnknownGeometryType'}`)
+}

geojson/linestring.ts

@@ -0,0 +1,22 @@
+import type * as geojson from 'geojson'
+import * as position from './position'
+import { Polyline } from '../s2/Polyline'
+
+/**
+ * Returns a geojson LineString geometry given an s2 Polyline.
+ * @category Constructors
+ */
+export const marshal = (polyline: Polyline): geojson.LineString => {
+  return {
+    type: 'LineString',
+    coordinates: polyline.points.map(position.marshal)
+  }
+}
+
+/**
+ * Constructs an s2 Polyline given a geojson LineString geometry.
+ * @category Constructors
+ */
+export const unmarshal = (geometry: geojson.LineString): Polyline => {
+  return new Polyline(geometry.coordinates.map(position.unmarshal))
+}

geojson/linestring_multi.ts

@@ -0,0 +1,22 @@
+import type * as geojson from 'geojson'
+import * as position from './position'
+import { Polyline } from '../s2/Polyline'
+
+/**
+ * Returns a geojson MultiLineString geometry given s2 Polylines.
+ * @category Constructors
+ */
+export const marshal = (polylines: Polyline[]): geojson.MultiLineString => {
+  return {
+    type: 'MultiLineString',
+    coordinates: polylines.map((polyline) => polyline.points.map(position.marshal))
+  }
+}
+
+/**
+ * Constructs s2 Polylines given a geojson MultiLineString geometry.
+ * @category Constructors
+ */
+export const unmarshal = (geometry: geojson.MultiLineString): Polyline[] => {
+  return geometry.coordinates.map((polyline) => new Polyline(polyline.map(position.unmarshal)))
+}

geojson/linestring_test.ts

@@ -0,0 +1,46 @@
+import { test, describe } from 'node:test'
+import { ok } from 'node:assert/strict'
+import type * as geojson from 'geojson'
+import { approxEqual } from './testing'
+import * as linestring from './linestring'
+
+describe('geojson', () => {
+  test('linestring', (t) => {
+    const geometries: geojson.LineString[] = [
+      {
+        type: 'LineString',
+        coordinates: [
+          [0, 0],
+          [2, 2],
+          [-180, -90],
+          [180, 90]
+        ]
+      },
+      {
+        type: 'LineString',
+        coordinates: [
+          [1, 1],
+          [2, 2],
+          [3, 3],
+          [4, 4],
+          [5, 5]
+        ]
+      },
+      {
+        type: 'LineString',
+        coordinates: [
+          [102.0, 0.0],
+          [103.0, 1.0],
+          [104.0, 0.0],
+          [105.0, 1.0]
+        ]
+      }
+    ]
+
+    geometries.forEach((geometry) => {
+      const decoded = linestring.unmarshal(geometry)
+      const encoded = linestring.marshal(decoded)
+      ok(approxEqual(encoded, geometry), JSON.stringify(geometry) + ' -> ' + JSON.stringify(encoded))
+    })
+  })
+})