Spatial predicates for GeoJSON.
npm install @terraformer/spatial[![npm][npm-image]][npm-url]
[![travis][travis-image]][travis-url]
[![standard][standard-image]][standard-url]
[npm-image]: https://img.shields.io/npm/v/@terraformer/spatial.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/@terraformer/spatial
[travis-image]: https://app.travis-ci.com/terraformer-js/terraformer.svg?branch=main
[travis-url]: https://app.travis-ci.com/terraformer-js/terraformer
[standard-image]: https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg?style=flat-square
[standard-url]: http://npm.im/semistandard
> Spatial predicates for GeoJSON.
``
npm install @terraformer/spatial
* 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])](#module_Terraformer.toCircle) ⇒ object
* .toGeographic(GeoJSON) ⇒ object
Kind: static constant of Terraformer
Kind: static constant of Terraformer
Kind: static method of Terraformer
Returns: object - GeoJSON - GeoJSON with altered coordinates.
`js
import { applyConverter } from "@terraformer/spatial"
applyConverter({
type: "Point",
coordinates: [ 45, 60 ]
}, (coord) => [coord[0] + 1, coord[1] - 1])
>> { type: "Point", coordinates: [ 46, 59 ] }
`
| Param | Type | Description |
| --- | --- | --- |
| GeoJSON | object | The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection. |
| function | function | Your function will be passed a Coordinate and will be expected to return a Coordinate. |
Kind: static method of Terraformer
Returns: Array.<Number> - [ xmin, ymin, xmax, ymax ].
`js
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. |
Kind: static method of Terraformer
Returns: Object - Object in the form { x, y, w, h }.
`js
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. |
Kind: static method of Terraformer
Returns: Array.<Number, Number> - CoordinatePair.
`js
import { positionToGeographic } from "@terraformer/spatial"
positionToGeographic([ -13580978, 5621521 ]) // [ 45, 60 ]
`
| Param | Type | Description |
| --- | --- | --- |
| CoordinatePair | Array.<Number, Number> | An X,Y position. |
Kind: static method of Terraformer
Returns: Array.<Number, Number> - CoordinatePair.
`js
import { positionToGeographic } from "@terraformer/spatial"
positionToMercator([ 45, 60 ]) // [ -13580978, 5621521 ]
`
| Param | Type | Description |
| --- | --- | --- |
| CoordinatePair | Array.<Number, Number> | An X,Y position. |
Kind: static method of Terraformer
Returns: object - GeoJSON
`js
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. |
Kind: static method of Terraformer
Returns: Array.<Coordinates> - An array of GeoJSON coordinates representing the convex hull of the input GeoJSON.
`js
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. |
Kind: static method of Terraformer
Returns: Boolean - Yes/No
`js
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. |
if the point falls within the polygon.Kind: static method of Terraformer
Returns: Boolean - Yes/No
`js
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. |
$3
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
`js
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. |
$3
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
`js
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. |
$3
Returns true if the two input GeoJSON objects intersect one another.Kind: static method of Terraformer
Returns: Boolean - Yes/No
`js
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. |
$3
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
`js
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. |$3
Reproject Web Mercator GeoJSON to WGS84 (Lat/Long).Kind: static method of Terraformer
Returns: object - GeoJSON
`js
import { toGeographic } from "@terraformer/spatial"toGeographic({
type: "Point",
coordinates: [ -13580978, 5621521 ]
})
>> { type: "Point", coordinates: [ 45, 60 ] }
` | Param | Type | Description |
| --- | --- | --- |
| GeoJSON | object | The input GeoJSON Geometry, Feature, GeometryCollection or FeatureCollection. |
*
Usage
$3
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.`html
`
js
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
`$3
js
const Terraformer = require('@terraformer/spatial');Terraformer.isConvex(/ ... /);
`$3
html
``
What's the difference between this project and Turf.js?
Both libraries work with GeoJSON and share many similar functions. Turf.js relies on JSTS, and some folks have found it to be slower. In the past Turf.js did not include predicates like 'within', 'contains' and 'intersects', but that no longer appears to be the case.