@terraformer/spatial

Spatial predicates for GeoJSON.

Install

npm install @terraformer/spatial

API Reference

Terraformer

• Terraformer
  • .MercatorCRS
  • .GeographicCRS
  • .applyConverter(GeoJSON, function) ⇒ object
  • .calculateBounds(GeoJSON) ⇒ Array.<Number>
  • .calculateEnvelope(GeoJSON) ⇒ Object
  • .positionToGeographic(CoordinatePair) ⇒ Array.<Number, Number>
  • .positionToMercator(CoordinatePair) ⇒ Array.<Number, Number>
  • .toMercator(GeoJSON) ⇒ object
  • .convexHull(GeoJSON) ⇒ Array.<Coordinates>
  • .isConvex(GeoJSON) ⇒ Boolean
  • .polygonContainsPoint(GeoJSON, GeoJSON) ⇒ Boolean
  • .within(GeoJSON, GeoJSON) ⇒ Boolean
  • .contains(GeoJSON, GeoJSON) ⇒ Boolean
  • .intersects(GeoJSON, GeoJSON) ⇒ Boolean
  • .toCircle(CoordinatePair, [Radius], [Steps]) ⇒ object
  • .toGeographic(GeoJSON) ⇒ object

Terraformer.MercatorCRS

WKID 3857

Kind: static constant of Terraformer

Terraformer.GeographicCRS

WKID 4326

Kind: static constant of Terraformer

Terraformer.applyConverter(GeoJSON, function) ⇒ object

Runs the passed function against every Coordinate in the geojson object.

Kind: static method of Terraformer
Returns: object - GeoJSON - GeoJSON with altered coordinates.

import { applyConverter } from "@terraformer/spatial"

applyConverter({
  type: "Point",
  coordinates: [ 45, 60 ]
}, (coord) => [coord[0] + 1, coord[1] - 1])

>> { type: "Point", coordinates: [ 46, 59 ] }

Terraformer.calculateBounds(GeoJSON) ⇒ Array.<Number>

Calculate the bounding box of the input.

Kind: static method of Terraformer
Returns: Array.<Number> - [ xmin, ymin, xmax, ymax ].

import { calculateBounds } from "@terraformer/spatial"

calculateBounds({
  type: "Point",
  coordinates: [ 45, 60 ]
})

>> [45, 60, 45, 60]

Terraformer.calculateEnvelope(GeoJSON) ⇒ Object

Calculate the envelope surrounding the input.

Kind: static method of Terraformer
Returns: Object - Object in the form { x, y, w, h }.

import { calculateEnvelope } from "@terraformer/spatial"

calculateEnvelope({
  type: "Point",
  coordinates: [ 100, 100 ]
})

>> { x: 100, y: 100, w: 0, h: 0, }

Terraformer.positionToGeographic(CoordinatePair) ⇒ Array.<Number, Number>

Reprojects the passed Coordinate pair to WGS84 (4326) spatial reference.

Kind: static method of Terraformer
Returns: Array.<Number, Number> - CoordinatePair.

import { positionToGeographic } from "@terraformer/spatial"

positionToGeographic([ -13580978, 5621521 ]) // [ 45, 60  ]

Terraformer.positionToMercator(CoordinatePair) ⇒ Array.<Number, Number>

Reprojects the passed Coordinate pair to web mercator (3857) spatial reference.

Kind: static method of Terraformer
Returns: Array.<Number, Number> - CoordinatePair.

import { positionToGeographic } from "@terraformer/spatial"

positionToMercator([ 45, 60 ]) // [ -13580978, 5621521  ]

Terraformer.toMercator(GeoJSON) ⇒ object

Reproject WGS84 (Lat/Lng) GeoJSON to Web Mercator.

Kind: static method of Terraformer
Returns: object - GeoJSON

import { toMercator } from "@terraformer/spatial"

toMercator({
  type: "Point",
  coordinates: [ 45, 60 ]
})

>> { type: "Point", coordinates: [ -13580978, 5621521 ], crs }

Terraformer.convexHull(GeoJSON) ⇒ Array.<Coordinates>

Calculate the convex hull of GeoJSON input.

Kind: static method of Terraformer
Returns: Array.<Coordinates> - An array of GeoJSON coordinates representing the convex hull of the input GeoJSON.

import { convexHull } from "@terraformer/spatial"

convexHull({
  type: "LineString",
  coordinates: [
    [ 100, 0 ], [ -45, 122 ], [ 80, -60 ]
  ]
})

>>
{
  type: "Polygon",
  coordinates: [
    [ [ 100, 0 ], [ -45, 122 ], [ 80, -60 ], [ 100, 0 ] ]
  ]
}

Terraformer.isConvex(GeoJSON) ⇒ Boolean

Determine whether input GeoJSON has a convex shape.

Kind: static method of Terraformer
Returns: Boolean - Yes/No

import { isConvex } from "@terraformer/spatial"

isConvex({
  type: "Polygon",
  coordinates: [
    [ [ 100, 0 ], [ -45, 122 ], [ 80, -60 ], [ 100, 0 ] ]
  ]
})

>> true

Terraformer.polygonContainsPoint(GeoJSON, GeoJSON) ⇒ Boolean

Accepts the geometry of a polygon and point and returns true if the point falls within the polygon.

Kind: static method of Terraformer
Returns: Boolean - Yes/No

import { polygonContainsPoint } from "@terraformer/spatial"

polygonContainsPoint(
  [
    [ [ 1, 2 ], [ 2, 2 ], [ 2, 1 ], [ 1, 1 ], [ 1, 2 ] ]
  ],
  [ 10, 10 ]
)

>> false

Terraformer.within(GeoJSON, GeoJSON) ⇒ Boolean

Returns true if the GeoJSON passed as the first argument is completely inside the GeoJSON object passed in the second position.

Kind: static method of Terraformer
Returns: Boolean - Yes/No

import { within } from "@terraformer/spatial"

within({
  type: "Point",
  coordinates: [ 10, 10 ]
},
{
  type: "Polygon",
  coordinates: [
    [ [ 5, 5 ], [ 5, 15 ], [ 15, 15 ], [ 15, 5 ], [ 5, 5 ] ]
  ]
})

>> true

Terraformer.contains(GeoJSON, GeoJSON) ⇒ Boolean

Returns true if the GeoJSON passed as the second argument is completely inside the GeoJSON object passed in the first position.

Kind: static method of Terraformer
Returns: Boolean - Yes/No

import { contains } from "@terraformer/spatial"

contains({
  type: "Polygon",
  coordinates: [
    [ [ 5, 5 ], [ 5, 15 ], [ 15, 15 ], [ 15, 5 ], [ 5, 5 ] ]
]},
{
  type: "Point",
  coordinates: [ 10, 10 ]
})

>> true

Terraformer.intersects(GeoJSON, GeoJSON) ⇒ Boolean

Returns true if the two input GeoJSON objects intersect one another.

Kind: static method of Terraformer
Returns: Boolean - Yes/No

import { intersects } from "@terraformer/spatial"

intersects({
  type: "Point",
  coordinates: [ 10, 10 ]
},
{
  type: "Polygon",
  coordinates: [
    [ [ 5, 5 ], [ 5, 15 ], [ 15, 15 ], [ 15, 5 ], [ 5, 5 ] ]
  ]
})

>> true

Terraformer.toCircle(CoordinatePair, [Radius], [Steps]) ⇒ object

Uses an input Coordinate pair to create a GeoJSON Feature containing a Polygon representing a circle with a discrete number of sides.

Kind: static method of Terraformer
Returns: object - GeoJSON

import { toCircle } from "@terraformer/spatial"

toCircle([ -118, 34 ], 500)

>> { type: "Feature", geometry: { type: "Polygon"}, coordinates: [...] }

Terraformer.toGeographic(GeoJSON) ⇒ object

Reproject Web Mercator GeoJSON to WGS84 (Lat/Long).

Kind: static method of Terraformer
Returns: object - GeoJSON

import { toGeographic } from "@terraformer/spatial"

toGeographic({
  type: "Point",
  coordinates: [ -13580978, 5621521 ]
})

>> { type: "Point", coordinates: [ 45, 60 ] }

Usage

Browser (from CDN)

This package is distributed as a UMD module and can also be used in AMD based systems or as a global under the Terraformer namespace.

<script src="https://unpkg.com/@terraformer/spatial"></script>

const input = {
  'type': 'Polygon',
  'coordinates': [
    [ [41.83, 71.01], [56.95, 33.75], [21.79, 36.56], [41.83, 71.01] ]
  ]
};

Terraformer.isConvex(input.coordinates[0]); // true

Node.js

const Terraformer = require('@terraformer/spatial');

Terraformer.isConvex(/* ... */);

ES module in the browser

<script type='module'>
  import { isConvex } from 'https://unpkg.com/@terraformer/spatial?module';

  // look ma, no build step!
  isConvex(/* ... */);
</script>

FAQ

Contributing

LICENSE

Change log

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.

Unreleased

[2.2.1]

Added

• @terraformer/wkt
  • Errors parsing WKT are now surfaced instead of swallowed. (:pray: @mpalmerlee :pray:)

2.2.0

Added

• @terraformer/wkt
  • Parse WKT Geometry Collection to GeoJSON Geomtery Collection. (:pray: @Zakhmaster :pray:)

2.1.2

Fixed

• @terraformer/spatial
  • fix intersects for multipolygons
  • start exporting applyConverter

    2.1.1 - 2022-05-31

Fixed

• ensure Z values of 0 are carried through when converting GeoJSON to ArcGIS Geometries.

2.1.0 - 2021-07-22

Added

• added support for Z values when converting GeoJSON to ArcGIS Geometries.

2.0.7 - 2020-05-18

Fixed

• all UMD and ESM files are now transpiled to make them safe to use in older browsers.

2.0.5 - 2020-05-17

Fixed

• @terraformer/spatial
  • toCircle() now returns polygons of equal area, regardless of their latitude

2.0.0 - 2020-04-15

Changed

• New Package names:

  • terraformer > @terraformer/spatial.
  • terraformer-arcgis-parser > @terraformer/arcgis.
  • terraformer-wkt-parser > @terraformer/wkt.

• All packages are now standalone.