Package Exports

@turf/helpers
@turf/helpers/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@turf/helpers) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@turf/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 geometry
properties Object an Object of key-value pairs to add as properties (optional, default {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

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 Type
coordinates Array<number> Coordinates
bbox Array<number>? BBox [west, south, east, north]

Examples

var type = 'Point';
var coordinates = [110, 50];

var geometry = turf.geometry(type, coordinates);

//=geometry

Returns Geometry a GeoJSON Geometry

point

Takes coordinates and properties (optional) and returns a new Point feature.

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 {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

Examples

var point = turf.point([-75.343, 39.984]);

//=point

Returns Feature<Point> a Point feature

polygon

Takes an array of LinearRings and optionally an Object with properties and returns a Polygon feature.

Parameters

coordinates Array<Array<Array<number>>> an array of LinearRings
properties Object an Object of key-value pairs to add as properties (optional, default {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

Examples

var polygon = turf.polygon([[
  [-2.275543, 53.464547],
  [-2.275543, 53.489271],
  [-2.215118, 53.489271],
  [-2.215118, 53.464547],
  [-2.275543, 53.464547]
]], { name: 'poly1', population: 400});

//=polygon

Throws Error throw an error if a LinearRing of the polygon has too few positions or if a LinearRing of the Polygon does not have matching Positions at the beginning & end.

Returns Feature<Polygon> a Polygon feature

lineString

Creates a LineString based on a coordinate array. Properties can be added optionally.

Parameters

coordinates Array<Array<number>> an array of Positions
properties Object an Object of key-value pairs to add as properties (optional, default {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

Examples

var linestring1 = turf.lineString([
  [-21.964416, 64.148203],
  [-21.956176, 64.141316],
  [-21.93901, 64.135924],
  [-21.927337, 64.136673]
]);
var linestring2 = turf.lineString([
  [-21.929054, 64.127985],
  [-21.912918, 64.134726],
  [-21.916007, 64.141016],
  [-21.930084, 64.14446]
], {name: 'line 1', distance: 145});

//=linestring1

//=linestring2

Throws Error if no coordinates are passed

Returns Feature<LineString> a LineString feature

featureCollection

Takes one or more Features and creates a FeatureCollection.

Parameters

features Array<Feature> input features
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

Examples

var features = [
 turf.point([-75.343, 39.984], {name: 'Location A'}),
 turf.point([-75.833, 39.284], {name: 'Location B'}),
 turf.point([-75.534, 39.123], {name: 'Location C'})
];

var collection = turf.featureCollection(features);

//=collection

Returns FeatureCollection a FeatureCollection of input 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 LineStrings
properties Object an Object of key-value pairs to add as properties (optional, default {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

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 Positions
properties Object an Object of key-value pairs to add as properties (optional, default {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

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 Polygons
properties Object an Object of key-value pairs to add as properties (optional, default {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

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 Geometries
properties Object an Object of key-value pairs to add as properties (optional, default {})
bbox Array<number>? BBox [west, south, east, north]
id (string | number)? Identifier

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

num number Number
precision number Precision (optional, default 0)

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 sphere
units 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 units
units 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 units
units 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 converted
originalUnit string of the length
finalUnit 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, millimeter, acre, mile, yard, foot, inch

Parameters

area number to be converted
originalUnit string of the distance (optional, default 'meters')
finalUnit string returned unit (optional, default 'kilometers')

Returns number the converted distance

isNumber

Parameters

num any Number to validate

Examples

turf.isNumber(123)
//=true
turf.isNumber('foo')
//=false

Returns boolean true/false

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 @turf/helpers

Or install the Turf module that includes it as a function:

$ npm install @turf/turf