@turf/helpers

What is @turf/helpers?

The @turf/helpers package is part of the Turf.js library, which is a modular geospatial engine written in JavaScript. It provides functions to create various simple geometrical features such as points, lines, and polygons, and to manipulate these geometries in various ways. This package is particularly useful for developers working with geographic information systems (GIS) and spatial analysis in web applications.

What are @turf/helpers's main functionalities?

Creating Points

This function creates a GeoJSON Point feature using the provided coordinates. It is useful for representing locations on a map.

const point = turf.point([5, 10]);

Creating LineStrings

This function creates a GeoJSON LineString feature from an array of positions. It is useful for mapping routes or paths.

const line = turf.lineString([[5, 10], [20, 40]]);

Creating Polygons

This function creates a GeoJSON Polygon feature from an array of linear rings. It is used to represent areas such as city boundaries or lakes.

const polygon = turf.polygon([[[5, 10], [20, 40], [40, 0], [5, 10]]]);

Other packages similar to @turf/helpers

leaflet

Leaflet is a leading open-source JavaScript library for mobile-friendly interactive maps. While Leaflet itself focuses more on map interactions and overlays, it can be used in conjunction with other tools for creating and manipulating geographic data, similar to @turf/helpers.

openlayers

OpenLayers is another powerful open-source JavaScript library that handles various map-related tasks. It provides more comprehensive features for handling complex spatial operations compared to @turf/helpers, which is more focused on creating and manipulating simple geometrical features.

README

@turf/helpers

feature

Wraps a GeoJSON Geometry in a GeoJSON Feature.

Parameters

• geometry Geometry input geometry
• properties Object properties

Examples

var geometry = {
  "type": "Point",
  "coordinates": [110, 50]
};

var feature = turf.feature(geometry);

//=feature

Returns Feature a GeoJSON Feature

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 that is used as the Feature's properties

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] a properties object

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

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

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

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

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

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

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

radiansToDistance

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

distanceToRadians

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

distanceToDegrees

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

bearingToAngle

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

radians2degrees

Converts an angle in radians to degrees

Parameters

• radians number angle in radians

Returns number degrees between 0 and 360 degrees

degrees2radians

Converts an angle in degrees to radians

Parameters

• degrees number angle between 0 and 360 degrees

Returns number angle in radians

convertDistance

Converts a distance to the requested unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet

Parameters

• distance number to be converted
• originalUnit string of the distance
• finalUnit [string] returned unit (optional, default kilometers)

Returns number the converted distance

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

---

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

Changelog

4.6.0

🚀 New Modules

• @turf/clean-coords Removes redundant coordinates from any GeoJSON Geometry. (PR https://github.com/Turfjs/turf/pull/875 - Author @stebogit)
• @turf/interpolate Takes a set of points and estimates their 'property' values on a grid using the Inverse Distance Weighting (IDW) method.. (PR https://github.com/Turfjs/turf/pull/832 - Author @stebogit)
• @turf/clusters-dbscan Takes a set of Points and partition them into clusters according to DBSCAN's data clustering algorithm. (PR https://github.com/Turfjs/turf/pull/812 and https://github.com/Turfjs/turf/pull/851 - Author @DenisCarriere)

  special mention to this incredibly instructive and fun interactive map by @DenisCarriere 😎👏

• @turf/clusters Provides getCluster, clusterEach, and clusterReduce functions. (PR https://github.com/Turfjs/turf/pull/847 - Author @DenisCarriere)
• @turf/boolean-point-on-line Returns true if a point is on a line. Accepts a optional parameter to ignore the start and end vertices of the linestring. (PR https://github.com/Turfjs/turf/pull/858 - Author @rowanwins)
• @turf/boolean-overlap Takes two features and returns true or false whether or not they overlap, i.e. whether any pair of edges on the two polygons intersect. If there are any edge intersections, the polygons overlap. (PR https://github.com/Turfjs/turf/pull/856 and https://github.com/Turfjs/turf/pull/868 - Author @stebogit @tcql)
• @turf/boolean-equal Determine whether two geometries of the same type have identical X,Y coordinate values. (PR https://github.com/Turfjs/turf/pull/869 - Author @stebogit @tcql)

🏅 New Features/Enhancements

• Sets centered param default to true in @turf/point-grid (PR https://github.com/Turfjs/turf/pull/836 - Contributor @stebogit)
• Adds MultiLineString support for @turf/point-on-line (PR https://github.com/Turfjs/turf/pull/838 - Contributor @stebogit)
• Renames @turf/clusters => @turf/clusters-kmeans, plus adds deprecated warning message to @turf/clusters@4.5.2 (See Issue https://github.com/Turfjs/turf/issues/845)
• Changes output type of @turf/clusters-kmeans (See Issue https://github.com/Turfjs/turf/issues/850 - Contributor @DenisCarriere)
• Adds segmentEach and segmentReduce functions to @turf/meta (See Issue https://github.com/Turfjs/turf/issues/850 - Contributor @DenisCarriere)
• Adds tests and linting on JSDoc in TurfJS core from turf-www; see Issue https://github.com/Turfjs/turf/issues/859 (PR https://github.com/Turfjs/turf/issues/857 + https://github.com/Turfjs/turf/issues/864 + https://github.com/Turfjs/turf/issues/870 - Contributor @DenisCarriere @stebogit)
• Introduces null Geometry support across TurfJS modules (See Issue https://github.com/Turfjs/turf/issues/853) (PR https://github.com/Turfjs/turf/issues/866 - Contributor @DenisCarriere)
• Includes feature(Sub)Index in coordEach/coordReduce (@turf/meta) 🎉 (PR https://github.com/Turfjs/turf/issues/872 - Contributor @DenisCarriere)
• Adds bbox and id params plus geometry method to @turf/helpers (PR https://github.com/Turfjs/turf/issues/877 - Contributor @DenisCarriere)

🐛 Bug Fixes

• Applies @turf/truncate to @turf/line-split splitter input to avoid approximation errors. Fixed #852 (PR https://github.com/Turfjs/turf/pull/855)
• Fixes @turf-mask error (See Issue https://github.com/Turfjs/turf/issues/837) (PR https://github.com/Turfjs/turf/pull/865 - Contributor @thiagoxvo)
• Fixes create-new-module script error on LICENSE file creation (See Issue https://github.com/Turfjs/turf/issues/861) (commit df6986e)
• Fixes @turf/isobands error on commonProperties (See Issue https://github.com/Turfjs/turf/issues/831) (commit 1663f07)