@spatial/helpers
v2.0.0
Published
turf helpers module
Downloads
4,188
Readme
@spatial/helpers
earthRadius
Earth Radius used with the Harvesine formula and approximates using a spherical (non-ellipsoid) Earth.
factors
Unit of measurement factors using a spherical (non-ellipsoid) earth radius.
unitsFactors
Units of measurement factors based on 1 meter.
areaFactors
Area of measurement factors based on 1 square meter.
feature
Wraps a GeoJSON Geometry in a GeoJSON Feature.
Parameters
geometry
Geometry input geometryproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var geometry = {
"type": "Point",
"coordinates": [110, 50]
};
var feature = turf.feature(geometry);
//=feature
Returns Feature a GeoJSON Feature
geometry
Creates a GeoJSON Geometry from a Geometry string type & coordinates.
For GeometryCollection type use helpers.geometryCollection
Parameters
type
string Geometry Typecoordinates
Array<number> Coordinatesoptions
Object Optional Parameters (optional, default{}
)
Examples
var type = 'Point';
var coordinates = [110, 50];
var geometry = turf.geometry(type, coordinates);
//=geometry
Returns Geometry a GeoJSON Geometry
point
Creates a Point Feature from a Position.
Parameters
coordinates
Array<number> longitude, latitude position (each in decimal degrees)properties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var point = turf.point([-75.343, 39.984]);
//=point
Returns Feature<Point> a Point feature
points
Creates a Point FeatureCollection from an Array of Point coordinates.
Parameters
coordinates
Array<Array<number>> an array of Pointsproperties
Object Translate these properties to each Feature (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var points = turf.points([
[-75, 39],
[-80, 45],
[-78, 50]
]);
//=points
Returns FeatureCollection<Point> Point Feature
polygon
Creates a Polygon Feature from an Array of LinearRings.
Parameters
coordinates
Array<Array<Array<number>>> an array of LinearRingsproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var polygon = turf.polygon([[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]], { name: 'poly1' });
//=polygon
Returns Feature<Polygon> Polygon Feature
polygons
Creates a Polygon FeatureCollection from an Array of Polygon coordinates.
Parameters
coordinates
Array<Array<Array<Array<number>>>> an array of Polygon coordinatesproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var polygons = turf.polygons([
[[[-5, 52], [-4, 56], [-2, 51], [-7, 54], [-5, 52]]],
[[[-15, 42], [-14, 46], [-12, 41], [-17, 44], [-15, 42]]],
]);
//=polygons
Returns FeatureCollection<Polygon> Polygon FeatureCollection
lineString
Creates a LineString Feature from an Array of Positions.
Parameters
coordinates
Array<Array<number>> an array of Positionsproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var linestring1 = turf.lineString([[-24, 63], [-23, 60], [-25, 65], [-20, 69]], {name: 'line 1'});
var linestring2 = turf.lineString([[-14, 43], [-13, 40], [-15, 45], [-10, 49]], {name: 'line 2'});
//=linestring1
//=linestring2
Returns Feature<LineString> LineString Feature
lineStrings
Creates a LineString FeatureCollection from an Array of LineString coordinates.
Parameters
coordinates
Array<Array<number>> an array of LinearRingsproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var linestrings = turf.lineStrings([
[[-24, 63], [-23, 60], [-25, 65], [-20, 69]],
[[-14, 43], [-13, 40], [-15, 45], [-10, 49]]
]);
//=linestrings
Returns FeatureCollection<LineString> LineString FeatureCollection
featureCollection
Takes one or more Features and creates a FeatureCollection.
Parameters
Examples
var locationA = turf.point([-75.343, 39.984], {name: 'Location A'});
var locationB = turf.point([-75.833, 39.284], {name: 'Location B'});
var locationC = turf.point([-75.534, 39.123], {name: 'Location C'});
var collection = turf.featureCollection([
locationA,
locationB,
locationC
]);
//=collection
Returns FeatureCollection FeatureCollection of Features
multiLineString
Creates a Feature<MultiLineString> based on a coordinate array. Properties can be added optionally.
Parameters
coordinates
Array<Array<Array<number>>> an array of LineStringsproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var multiLine = turf.multiLineString([[[0,0],[10,10]]]);
//=multiLine
- Throws Error if no coordinates are passed
Returns Feature<MultiLineString> a MultiLineString feature
multiPoint
Creates a Feature<MultiPoint> based on a coordinate array. Properties can be added optionally.
Parameters
coordinates
Array<Array<number>> an array of Positionsproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var multiPt = turf.multiPoint([[0,0],[10,10]]);
//=multiPt
- Throws Error if no coordinates are passed
Returns Feature<MultiPoint> a MultiPoint feature
multiPolygon
Creates a Feature<MultiPolygon> based on a coordinate array. Properties can be added optionally.
Parameters
coordinates
Array<Array<Array<Array<number>>>> an array of Polygonsproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]);
//=multiPoly
- Throws Error if no coordinates are passed
Returns Feature<MultiPolygon> a multipolygon feature
geometryCollection
Creates a Feature<GeometryCollection> based on a coordinate array. Properties can be added optionally.
Parameters
geometries
Array<Geometry> an array of GeoJSON Geometriesproperties
Object an Object of key-value pairs to add as properties (optional, default{}
)options
Object Optional Parameters (optional, default{}
)
Examples
var pt = {
"type": "Point",
"coordinates": [100, 0]
};
var line = {
"type": "LineString",
"coordinates": [ [101, 0], [102, 1] ]
};
var collection = turf.geometryCollection([pt, line]);
//=collection
Returns Feature<GeometryCollection> a GeoJSON GeometryCollection Feature
round
Round number to precision
Parameters
Examples
turf.round(120.4321)
//=120
turf.round(120.4321, 2)
//=120.43
Returns number rounded number
radiansToLength
Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
Parameters
radians
number in radians across the sphereunits
string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default'kilometers'
)
Returns number distance
lengthToRadians
Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
Parameters
distance
number in real unitsunits
string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default'kilometers'
)
Returns number radians
lengthToDegrees
Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
Parameters
distance
number in real unitsunits
string can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. (optional, default'kilometers'
)
Returns number degrees
bearingToAzimuth
Converts any bearing angle from the north line direction (positive clockwise) and returns an angle between 0-360 degrees (positive clockwise), 0 being the north line
Parameters
bearing
number angle, between -180 and +180 degrees
Returns number angle between 0 and 360 degrees
radiansToDegrees
Converts an angle in radians to degrees
Parameters
radians
number angle in radians
Returns number degrees between 0 and 360 degrees
degreesToRadians
Converts an angle in degrees to radians
Parameters
degrees
number angle between 0 and 360 degrees
Returns number angle in radians
convertLength
Converts a length to the requested unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
Parameters
length
number to be convertedoriginalUnit
string of the lengthfinalUnit
string returned unit (optional, default'kilometers'
)
Returns number the converted length
convertArea
Converts a area to the requested unit. Valid units: kilometers, kilometres, meters, metres, centimetres, millimeters, acres, miles, yards, feet, inches
Parameters
area
number to be convertedoriginalUnit
string of the distance (optional, default'meters'
)finalUnit
string returned unit (optional, default'kilometers'
)
Returns number the converted distance
isNumber
isNumber
Parameters
num
any Number to validate
Examples
turf.isNumber(123)
//=true
turf.isNumber('foo')
//=false
Returns boolean true/false
isObject
isObject
Parameters
input
any variable to validate
Examples
turf.isObject({elevation: 10})
//=true
turf.isObject('foo')
//=false
Returns boolean true/false
This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.
Installation
Install this module individually:
$ npm install @spatial/helpers
Or install the Turf module that includes it as a function:
$ npm install @turf/turf