@terraformer/spatial

@terraformer/spatial

Spatial predicates for GeoJSON.

Install

npm install @terraformer/spatial

API Reference

Terraformer

• Terraformer
  • .MercatorCRS
  • .GeographicCRS
  • .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

Terraformer.MercatorCRS

WKID 3857

Kind: static constant of Terraformer

Terraformer.GeographicCRS

WKID 4326

Kind: static constant of Terraformer

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]

Param	Type	Description
GeoJSON	object	The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection.

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, }

Param	Type	Description
GeoJSON	object	The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection.

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  ]

Param	Type	Description
CoordinatePair	Array.<Number, Number>	An X,Y position.

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  ]

Param	Type	Description
CoordinatePair	Array.<Number, Number>	An X,Y position.

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 }

Param	Type	Description
GeoJSON	object	The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection.

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 ] ]
  ]
}

Param	Type	Description
GeoJSON	object	The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection.

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

Param	Type	Description
GeoJSON	Object	The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection.

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

Param	Type	Description
GeoJSON	Object	GeoJSON Polygon coordinates.
GeoJSON	Object	GeoJSON Point coordinates.

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

Param	Type	Description
GeoJSON	Object	GeoJSON that may be within the second input.
GeoJSON	Object	GeoJSON that may contain the first input.

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

Param	Type	Description
GeoJSON	Object	GeoJSON that may contain the second input.
GeoJSON	Object	GeoJSON that may be contained by the first input.

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

Param	Type	Description
GeoJSON	Object	The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection.
GeoJSON	Object	The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection.

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: [...] }

Param	Type	Default	Description
CoordinatePair	Array.<Number, Number>		A GeoJSON Coordinate in [x,y] format.
[Radius]	Number	250	The radius of the circle (in meters).
[Steps]	Number	64	The number of sides the output polygon will contain.

---

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>

Contributing

LICENSE