Measurement
npm install @turf/along
along
Arguments
| Argument | Type | Description |
| line | Feature<LineString> | input line |
| distance | number | distance along the line |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers |
Returns
Feature<Point>: Point
distance
units
along the line
Example
var line = turf.lineString([[-83, 30], [-84, 36], [-78, 41]]); var along = turf.along(line, 200, 'miles');
npm install @turf/area
area
Takes one or more features and returns their area in square meters.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature<any>) | input GeoJSON feature(s) |
Returns
number: area in square meters
Example
var polygon = turf.polygon([[[125, -15], [113, -22], [154, -27], [144, -15], [125, -15]]]); var area = turf.area(polygon);
npm install @turf/bbox
bbox
Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature<any>) | input features |
Returns
Array<number>: bbox extent in [ minX, minY, maxX, maxY ] order
Example
var line = turf.lineString([[-74, 40], [-78, 42], [-82, 35]]); var bbox = turf.bbox(line); var bboxPolygon = turf.bboxPolygon(bbox);
npm install @turf/bbox-polygon
bboxPolygon
Takes a bbox and returns an equivalent polygon.
Arguments
Returns
Feature<Polygon>: a Polygon representation of the bounding box
Example
var bbox = [0, 0, 10, 10]; var poly = turf.bboxPolygon(bbox);
npm install @turf/bearing
bearing
Takes two points and finds the geographic bearing between them, i.e. the angle measured in degrees from the north line (0 degrees)
Arguments
| Argument | Type | Description |
| start | (Geometry | Feature<Point> | Array<number>) | starting Point |
| end | (Geometry | Feature<Point> | Array<number>) | ending Point |
| final | boolean? (default false) | calculates the final bearing if true |
Returns
number: bearing in decimal degrees, between -180 and 180 degrees (positive clockwise)
Example
var point1 = turf.point([-75.343, 39.984]); var point2 = turf.point([-75.534, 39.123]); var bearing = turf.bearing(point1, point2);
npm install @turf/center
center
Takes a Feature or FeatureCollection and returns the absolute center point of all features.
Arguments
| Argument | Type | Description |
| geojson | GeoJSON | GeoJSON to be centered |
| properties | Object? | an Object that is used as the Feature 's properties |
Returns
Feature<Point>: a Point feature at the absolute center point of all input features
Example
var features = turf.featureCollection([ turf.point( [-97.522259, 35.4691]), turf.point( [-97.502754, 35.463455]), turf.point( [-97.508269, 35.463245]) ]); var center = turf.center(features);
npm install @turf/center-of-mass
centerOfMass
Takes any Feature or a FeatureCollection and returns its center of mass using this formula: Centroid of Polygon.
Arguments
| Argument | Type | Description |
| geojson | GeoJSON | GeoJSON to be centered |
| properties | Object? | an Object that is used as the Feature 's properties |
Returns
Feature<Point>: the center of mass
Example
var polygon = turf.polygon([[[-81, 41], [-88, 36], [-84, 31], [-80, 33], [-77, 39], [-81, 41]]]); var center = turf.centerOfMass(polygon);
npm install @turf/centroid
centroid
Takes one or more features and calculates the centroid using the mean of all vertices. This lessens the effect of small islands and artifacts when calculating the centroid of a set of polygons.
Arguments
| Argument | Type | Description |
| geojson | GeoJSON | GeoJSON to be centered |
| properties | Object? | an Object that is used as the Feature 's properties |
Returns
Feature<Point>: the centroid of the input features
Example
var polygon = turf.polygon([[[-81, 41], [-88, 36], [-84, 31], [-80, 33], [-77, 39], [-81, 41]]]); var centroid = turf.centroid(polygon);
npm install @turf/destination
destination
Takes a Point and calculates the location of a destination point given a distance in degrees, radians, miles, or kilometers; and bearing in degrees. This uses the Haversine formula to account for global curvature.
Arguments
| Argument | Type | Description |
| origin | (Geometry | Feature<Point> | Array<number>) | starting point |
| distance | number | distance from the origin point |
| bearing | number | ranging from -180 to 180 |
| units | string? (default kilometers) | miles, kilometers, degrees, or radians |
Returns
Feature<Point>: destination point
Example
var point = turf.point([-75.343, 39.984]); var distance = 50; var bearing = 90; var units = 'miles'; var destination = turf.destination(point, distance, bearing, units);
npm install @turf/distance
distance
Calculates the distance between two points in degrees, radians, miles, or kilometers. This uses the Haversine formula to account for global curvature.
Arguments
| Argument | Type | Description |
| from | (Geometry | Feature<Point> | Array<number>) | origin point |
| to | (Geometry | Feature<Point> | Array<number>) | destination point |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers |
Returns
number: distance between the two points
Example
var from = turf.point([-75.343, 39.984]); var to = turf.point([-75.534, 39.123]); var distance = turf.distance(from, to, "miles");
npm install @turf/envelope
envelope
Takes any number of features and returns a rectangular Polygon that encompasses all vertices.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature<any>) | input features |
Returns
Feature<Polygon>: a rectangular Polygon feature that encompasses all vertices
Example
var features = turf.featureCollection([ 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 enveloped = turf.envelope(features);
npm install @turf/line-distance
lineDistance
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature | Geometry) | GeoJSON to measure |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers |
Returns
number: length of GeoJSON
Example
var line = turf.lineString([[115, -32], [131, -22], [143, -25], [150, -34]]); var length = turf.lineDistance(line, 'miles');
npm install @turf/midpoint
midpoint
Takes two points and returns a point midway between them. The midpoint is calculated geodesically, meaning the curvature of the earth is taken into account.
Arguments
| Argument | Type | Description |
| point1 | (Geometry | Feature<Point> | Array<number>) | first point |
| point2 | (Geometry | Feature<Point> | Array<number>) | second point |
Returns
Feature<Point>: a point midway between
pt1
and
pt2
Example
var point1 = turf.point([144.834823, -37.771257]); var point2 = turf.point([145.14244, -37.830937]); var midpoint = turf.midpoint(point1, point2);
npm install @turf/point-on-surface
pointOnSurface
Takes a feature and returns a Point guaranteed to be on the surface of the feature.
- Given a Polygon, the point will be in the area of the polygon
- Given a LineString, the point will be along the string
- Given a Point, the point will the same as the input
Arguments
| Argument | Type | Description |
| fc | (Feature | FeatureCollection) | any feature or set of features |
Returns
Feature: a point on the surface of
input
Example
// create a random polygon var polygon = turf.random('polygon'); var pointOnPolygon = turf.pointOnSurface(polygon);
npm install @turf/polygon-tangents
polygonTangents
Finds the tangents of a (Multi)Polygon from a Point.
Arguments
| Argument | Type | Description |
| point | Feature<Point> | to calculate the tangent points from |
| polygon | Feature<(Polygon | MultiPolygon)> | to get tangents from |
Returns
FeatureCollection<Point>: Feature Collection containing the two tangent points
Example
var polygon = turf.polygon([[[11, 0], [22, 4], [31, 0], [31, 11], [21, 15], [11, 11], [11, 0]]]); var point = turf.point([61, 5]); var tangents = turf.polygonTangents(point, polygon)
npm install @turf/rhumb-bearing
rhumbBearing
Takes two points and finds the bearing angle between them along a Rhumb line i.e. the angle measured in degrees start the north line (0 degrees)
Arguments
| Argument | Type | Description |
| start | (Geometry | Feature<Point> | Array<number>) | starting Point |
| end | (Geometry | Feature<Point> | Array<number>) | ending Point |
| final | boolean? (default false) | calculates the final bearing if true |
Returns
number: bearing from north in decimal degrees, between -180 and 180 degrees (positive clockwise)
Example
var point1 = turf.point([-75.343, 39.984], {"marker-color": "#F00"}); var point2 = turf.point([-75.534, 39.123], {"marker-color": "#00F"}); var bearing = turf.rhumbBearing(point1, point2);
npm install @turf/rhumb-destination
rhumbDestination
Returns the destination Point having travelled the given distance along a Rhumb line from the origin Point with the (constant) given bearing.
Arguments
| Argument | Type | Description |
| origin | (Geometry | Feature<Point> | Array<number>) | starting point |
| distance | number | distance from the starting point |
| bearing | number | constant bearing angle ranging from -180 to 180 degrees from north |
| units | string? (default kilometers) | miles, kilometers, degrees, or radians |
Returns
Feature<Point>: Destination point.
Example
var point = turf.point([-75.343, 39.984], {"marker-color": "F00"}); var distance = 50; var bearing = 90; var units = 'miles'; var destination = turf.rhumbDestination(point, distance, bearing, units);
npm install @turf/rhumb-distance
rhumbDistance
Calculates the distance along a rhumb line between two points in degrees, radians, miles, or kilometers.
Arguments
| Argument | Type | Description |
| from | (Geometry | Feature<Point> | Array<number>) | origin point |
| to | (Geometry | Feature<Point> | Array<number>) | destination point |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers |
Returns
number: distance between the two points
Example
var from = turf.point([-75.343, 39.984]); var to = turf.point([-75.534, 39.123]); var distance = turf.rhumbDistance(from, to, "miles");
npm install @turf/square
square
Takes a bounding box and calculates the minimum square bounding box that would contain the input.
Arguments
Returns
Array<number>: a square surrounding
bbox
Example
var bbox = [-20,-20,-15,0]; var squared = turf.square(bbox); var features = turf.featureCollection([ turf.bboxPolygon(bbox), turf.bboxPolygon(squared) ]);
npm install @turf/great-circle
greatCircle
Calculate great circles routes as LineString
Arguments
| Argument | Type | Description |
| start | (Geometry | Feature<Point> | Array<number>) | source point feature |
| end | (Geometry | Feature<Point> | Array<number>) | destination point feature |
| properties | Object? (default {}) | line feature properties |
| npoints | number? (default 100) | number of points |
| offset | number? (default 10) | offset controls the likelyhood that lines will be split which cross the dateline. The higher the number the more likely. |
Returns
Feature<LineString>: great circle line feature
Example
var start = turf.point([-122, 48]); var end = turf.point([-77, 39]); var greatCircle = turf.greatCircle(start, end, {'name': 'Seattle to DC'});
Coordinate Mutation
npm install @turf/flip
flip
Takes input features and flips all of their coordinates from [x, y]
to [y, x]
.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature<any>) | input features |
| mutate | boolean? (default false) | allows GeoJSON input to be mutated (significant performance increase if true) |
Returns
(FeatureCollection | Feature<any>): a feature or set of features of the same type as
input
with flipped coordinates
Example
var serbia = turf.point([20.566406, 43.421008]); var saudiArabia = turf.flip(serbia);
npm install @turf/rewind
rewind
Rewind (Multi)LineString or (Multi)Polygon outer ring counterclockwise and inner rings clockwise (Uses Shoelace Formula).
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Geometry | Feature<(Polygon | MultiPolygon | LineString | MultiLineString)>) | input GeoJSON Polygon |
| reverse | Boolean? (default false) | enable reverse winding |
| mutate | boolean? (default false) | allows GeoJSON input to be mutated (significant performance increase if true) |
Returns
(FeatureCollection | Geometry | Feature<(Polygon | MultiPolygon | LineString | MultiLineString)>): rewind Polygon
Example
var polygon = turf.polygon([[[121, -29], [138, -29], [138, -18], [121, -18], [121, -29]]]); var rewind = turf.rewind(polygon);
npm install @turf/helpers
round
Round number to precision
Note: round is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the round method.
Arguments
Returns
number: rounded number
Example
turf.round(120.4321) //=120 turf.round(120.4321, 2) //=120.43
npm install @turf/truncate
truncate
Takes a GeoJSON Feature or FeatureCollection and truncates the precision of the geometry.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature<any>) | any GeoJSON Feature, FeatureCollection, Geometry or GeometryCollection. |
| precision | number? (default 6) | coordinate decimal precision |
| coordinates | number? (default 3) | maximum number of coordinates (primarly used to remove z coordinates) |
| mutate | boolean? (default false) | allows GeoJSON input to be mutated (significant performance increase if true) |
Returns
(FeatureCollection | Feature<any>): layer with truncated geometry
Example
var point = turf.point([ 70.46923055566859, 58.11088890802906, 1508 ]); var truncated = turf.truncate(point);
Transformation
npm install @turf/bbox-clip
bboxClip
Takes a Feature and a bbox and clips the feature to the bbox using lineclip. May result in degenerate edges when clipping Polygons.
Arguments
| Argument | Type | Description |
| feature | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)> | feature to clip to the bbox |
| bbox | Array<number> | extent in [ minX, minY, maxX, maxY ] order |
Returns
Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>: clipped Feature
Example
var bbox = [0, 0, 10, 10]; var poly = turf.polygon([[[2, 2], [8, 4], [12, 8], [3, 7], [2, 2]]]); var clipped = turf.bboxClip(poly, bbox);
npm install @turf/bezier
bezier
Takes a line and returns a curved version by applying a Bezier spline algorithm.
The bezier spline implementation is by Leszek Rybicki.
Arguments
| Argument | Type | Description |
| line | Feature<LineString> | input LineString |
| resolution | number? (default 10000) | time in milliseconds between points |
| sharpness | number? (default 0.85) | a measure of how curvy the path should be between splines |
Returns
Feature<LineString>: curved line
Example
var line = turf.lineString([ [-76.091308, 18.427501], [-76.695556, 18.729501], [-76.552734, 19.40443], [-74.61914, 19.134789], [-73.652343, 20.07657], [-73.157958, 20.210656] ]); var curved = turf.bezier(line);
npm install @turf/buffer
buffer
Calculates a buffer for input features for a given radius. Units supported are miles, kilometers, and degrees.
When using a negative radius, the resulting geometry may be invalid if it's too small compared to the radius magnitude. If the input is a FeatureCollection, only valid members will be returned in the output FeatureCollection - i.e., the output collection may have fewer members than the input, or even be empty.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Geometry | Feature<any>) | input to be buffered |
| radius | number | distance to draw the buffer (negative values are allowed) |
| units | string? (default kilometers) | any of the options supported by turf units |
| steps | number? (default 64) | number of steps |
Returns
(FeatureCollection | Feature<(Polygon | MultiPolygon)> | undefined): buffered features
Example
var point = turf.point([-90.548630, 14.616599]); var buffered = turf.buffer(point, 500, 'miles');
npm install @turf/circle
circle
Takes a Point and calculates the circle polygon given a radius in degrees, radians, miles, or kilometers; and steps for precision.
Arguments
| Argument | Type | Description |
| center | (Feature<Point> | Array<number>) | center point |
| radius | number | radius of the circle |
| steps | number? (default 64) | number of steps |
| units | string? (default kilometers) | miles, kilometers, degrees, or radians |
| properties | Object? (default {}) | properties |
Returns
Feature<Polygon>: circle polygon
Example
var center = [-75.343, 39.984]; var radius = 5; var steps = 10; var units = 'kilometers'; var properties = {foo: 'bar'}; var circle = turf.circle(center, radius, steps, units, properties);
npm install @turf/clone
clone
Returns a cloned copy of the passed GeoJSON Object.
By default it duplicates only the standard GeoJSON fields of the object; if cloneAll
is set to true
all
fields of the Object, thus including 'Foreign Members', will be cloned (3-20x slower).
Arguments
| Argument | Type | Description |
| geojson | GeoJSON | GeoJSON Object |
| cloneAll | Boolean? (default false) | clones entire GeoJSON object, using JSON.parse(JSON.stringify(geojson)) |
Returns
GeoJSON: cloned GeoJSON Object
Example
var line = turf.lineString([[-74, 40], [-78, 42], [-82, 35]]); var lineCloned = turf.clone(line);
npm install @turf/concave
concave
Takes a set of points and returns a concave hull polygon. Internally, this uses turf-tin to generate geometries.
Arguments
| Argument | Type | Description |
| points | FeatureCollection<Point> | input points |
| maxEdge | number | the size of an edge necessary for part of the hull to become concave (in miles) |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers |
Returns
Feature<Polygon>: a concave hull
Throws
Error: if maxEdge parameter is missing or unable to compute hull
Example
var points = turf.featureCollection([ turf.point([-63.601226, 44.642643]), turf.point([-63.591442, 44.651436]), turf.point([-63.580799, 44.648749]), turf.point([-63.573589, 44.641788]), turf.point([-63.587665, 44.64533]), turf.point([-63.595218, 44.64765]) ]); var hull = turf.concave(points, 1, 'miles');
npm install @turf/convex
convex
Takes a Feature or a FeatureCollection and returns a convex hull Polygon.
Internally this uses the convex-hull module that implements a monotone chain hull.
Arguments
| Argument | Type | Description |
| feature | (Feature | FeatureCollection) | input Feature or FeatureCollection |
Returns
Feature<Polygon>: a convex hull
Example
var points = turf.featureCollection([ turf.point([10.195312, 43.755225]), turf.point([10.404052, 43.8424511]), turf.point([10.579833, 43.659924]), turf.point([10.360107, 43.516688]), turf.point([10.14038, 43.588348]), turf.point([10.195312, 43.755225]) ]); var hull = turf.convex(points);
npm install @turf/difference
difference
Finds the difference between two polygons by clipping the second polygon from the first.
Arguments
| Argument | Type | Description |
| polygon1 | Feature<(Polygon | MultiPolygon)> | input Polygon feature |
| polygon2 | Feature<(Polygon | MultiPolygon)> | Polygon feature to difference from polygon1 |
Returns
(Feature<(Polygon | MultiPolygon)> | undefined): a Polygon or MultiPolygon feature showing the area of
polygon1
excluding the area of
polygon2
(if empty returns
undefined
)
Example
var polygon1 = turf.polygon([[ [128,-26], [141,-26], [141,-21], [128,-21], [128,-26] ]], { "fill": "#F00", "fill-opacity": 0.1 }); var polygon2 = turf.polygon([[ [126, -28], [140, -28], [140, -20], [126, -20], [126, -28] ]], { "fill": "#00F", "fill-opacity": 0.1 }); var difference = turf.difference(polygon1, polygon2);
npm install @turf/dissolve
dissolve
Dissolves a FeatureCollection of polygons based on a property. Note that multipart features within the collection are not supported
Arguments
| Argument | Type | Description |
| featureCollection | FeatureCollection<Polygon> | input feature collection to be dissolved |
| propertyName | string? | property name on which to dissolve features |
Returns
FeatureCollection<Polygon>: a FeatureCollection containing the dissolved polygons
Example
var features = turf.featureCollection([ turf.polygon([[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]], {"combine": "yes"}), turf.polygon([[[0, -1], [0, 0], [1, 0], [1, -1], [0,-1]]], {"combine": "yes"}), turf.polygon([[[1,-1],[1, 0], [2, 0], [2, -1], [1, -1]]], {"combine": "no"}), ]); var dissolved = turf.dissolve(features, 'combine');
npm install @turf/intersect
intersect
Takes two polygons and finds their intersection. If they share a border, returns the border; if they don't intersect, returns undefined.
Arguments
| Argument | Type | Description |
| poly1 | Feature<Polygon> | the first polygon |
| poly2 | Feature<Polygon> | the second polygon |
Returns
(Feature | undefined): returns a feature representing the point(s) they share (in case of a
Point
or
MultiPoint
), the borders they share (in case of a
LineString
or a
MultiLineString
), the area they share (in case of
Polygon
or
MultiPolygon
). If they do not share any point, returns
undefined
.
Example
var poly1 = turf.polygon([[ [-122.801742, 45.48565], [-122.801742, 45.60491], [-122.584762, 45.60491], [-122.584762, 45.48565], [-122.801742, 45.48565] ]]); var poly2 = turf.polygon([[ [-122.520217, 45.535693], [-122.64038, 45.553967], [-122.720031, 45.526554], [-122.669906, 45.507309], [-122.723464, 45.446643], [-122.532577, 45.408574], [-122.487258, 45.477466], [-122.520217, 45.535693] ]]); var intersection = turf.intersect(poly1, poly2);
npm install @turf/line-offset
lineOffset
Arguments
| Argument | Type | Description |
| geojson | (Geometry | Feature<(LineString | MultiLineString)>) | input GeoJSON |
| distance | number | distance to offset the line (can be of negative value) |
| units | string? (default kilometers) | can be degrees, radians, miles, kilometers, inches, yards, meters |
Returns
Feature<(LineString | MultiLineString)>: Line offset from the input line
Example
var line = turf.lineString([[-83, 30], [-84, 36], [-78, 41]], { "stroke": "#F00" }); var offsetLine = turf.lineOffset(line, 2, "miles");
npm install @turf/simplify
simplify
Takes a LineString or Polygon and returns a simplified version. Internally uses simplify-js to perform simplification.
Arguments
| Argument | Type | Description |
| feature | (Feature<(LineString | Polygon | MultiLineString | MultiPolygon)> | FeatureCollection | GeometryCollection) | feature to be simplified |
| tolerance | number? (default 1) | simplification tolerance |
| highQuality | boolean? (default false) | whether or not to spend more time to create a higher-quality simplification with a different algorithm |
Returns
(Feature<(LineString | Polygon | MultiLineString | MultiPolygon)> | FeatureCollection | GeometryCollection): a simplified feature
Example
var feature = turf.polygon([[ [-70.603637, -33.399918], [-70.614624, -33.395332], [-70.639343, -33.392466], [-70.659942, -33.394759], [-70.683975, -33.404504], [-70.697021, -33.419406], [-70.701141, -33.434306], [-70.700454, -33.446339], [-70.694274, -33.458369], [-70.682601, -33.465816], [-70.668869, -33.472117], [-70.646209, -33.473835], [-70.624923, -33.472117], [-70.609817, -33.468107], [-70.595397, -33.458369], [-70.587158, -33.442901], [-70.587158, -33.426283], [-70.590591, -33.414248], [-70.594711, -33.406224], [-70.603637, -33.399918] ]]); var tolerance = 0.01; var simplified = turf.simplify(feature, tolerance, false);
npm install @turf/tesselate
tesselate
Tesselates a Feature<Polygon> into a FeatureCollection<Polygon> of triangles using earcut.
Arguments
Returns
FeatureCollection<Polygon>: a geometrycollection feature
Example
var poly = turf.polygon([[[11, 0], [22, 4], [31, 0], [31, 11], [21, 15], [11, 11], [11, 0]]]); var triangles = turf.tesselate(poly);
npm install @turf/transform-rotate
transformRotate
Rotates any geojson Feature or Geometry of a specified angle, around its centroid
or a given pivot
point;
all rotations follow the right-hand rule: https://en.wikipedia.org/wiki/Right-hand_rule
Arguments
| Argument | Type | Description |
| geojson | GeoJSON | object to be rotated |
| angle | number | of rotation (along the vertical axis), from North in decimal degrees, negative clockwise |
| pivot | (Geometry | Feature<Point> | Array<number>)? (default `centroid`) | point around which the rotation will be performed |
| mutate | boolean? (default false) | allows GeoJSON input to be mutated (significant performance increase if true) |
Returns
GeoJSON: the rotated GeoJSON feature
Example
var poly = turf.polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]); var rotatedPoly = turf.transformRotate(poly, 10, [0, 25]);
npm install @turf/transform-translate
transformTranslate
Moves any geojson Feature or Geometry of a specified distance along a Rhumb Line on the provided direction angle.
Arguments
| Argument | Type | Description |
| geojson | GeoJSON | object to be translated |
| distance | number | length of the motion; negative values determine motion in opposite direction |
| direction | number | of the motion; angle from North in decimal degrees, positive clockwise |
| units | string? (default kilometers) | in which
distance
will be express; miles, kilometers, degrees, or radians
|
| zTranslation | number? (default 0) | length of the vertical motion, same unit of distance |
| mutate | boolean? (default false) | allows GeoJSON input to be mutated (significant performance increase if true) |
Returns
GeoJSON: the translated GeoJSON object
Example
var poly = turf.polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]); var translatedPoly = turf.transformTranslate(poly, 100, 35);
npm install @turf/transform-scale
transformScale
Scale a GeoJSON from a given point by a factor of scaling (ex: factor=2 would make the GeoJSON 200% larger). If a FeatureCollection is provided, the origin point will be calculated based on each individual Feature.
Arguments
| Argument | Type | Description |
| geojson | GeoJSON | GeoJSON to be scaled |
| factor | number | of scaling, positive or negative values greater than 0 |
| origin | (string | Geometry | Feature<Point> | Array<number>)? (default "centroid") | Point from which the scaling will occur (string options: sw/se/nw/ne/center/centroid) |
| mutate | boolean? (default false) | allows GeoJSON input to be mutated (significant performance increase if true) |
Returns
GeoJSON: scaled GeoJSON
Example
var poly = turf.polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]); var scaledPoly = turf.transformScale(poly, 3);
npm install @turf/union
union
Takes two or more polygons and returns a combined polygon. If the input polygons are not contiguous, this function returns a MultiPolygon feature.
Arguments
Returns
Feature<(Polygon | MultiPolygon)>: a combined Polygon or MultiPolygon feature
Example
var poly1 = turf.polygon([[ [-82.574787, 35.594087], [-82.574787, 35.615581], [-82.545261, 35.615581], [-82.545261, 35.594087], [-82.574787, 35.594087] ]], {"fill": "#0f0"}); var poly2 = turf.polygon([[ [-82.560024, 35.585153], [-82.560024, 35.602602], [-82.52964, 35.602602], [-82.52964, 35.585153], [-82.560024, 35.585153] ]], {"fill": "#00f"}); var union = turf.union(poly1, poly2);
Feature Conversion
npm install @turf/combine
combine
Combines a FeatureCollection of Point, LineString, or Polygon features into MultiPoint, MultiLineString, or MultiPolygon features.
Arguments
| Argument | Type | Description |
| fc | FeatureCollection<(Point | LineString | Polygon)> | a FeatureCollection of any type |
Returns
FeatureCollection<(MultiPoint | MultiLineString | MultiPolygon)>: a FeatureCollection of corresponding type to input
Example
var fc = turf.featureCollection([ turf.point([19.026432, 47.49134]), turf.point([19.074497, 47.509548]) ]); var combined = turf.combine(fc);
npm install @turf/explode
explode
Takes a feature or set of features and returns all positions as points.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature<any>) | input features |
Returns
FeatureCollection<point>: points representing the exploded input features
Throws
Error: if it encounters an unknown geometry type
Example
var polygon = turf.polygon([[[-81, 41], [-88, 36], [-84, 31], [-80, 33], [-77, 39], [-81, 41]]]); var explode = turf.explode(polygon);
npm install @turf/flatten
flatten
Flattens any GeoJSON to a FeatureCollection inspired by geojson-flatten.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Geometry | Feature<any>) | any valid GeoJSON Object |
Returns
FeatureCollection<any>: all Multi-Geometries are flattened into single Features
Example
var multiGeometry = turf.multiPolygon([ [[[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]]], [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]], [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]]] ]); var flatten = turf.flatten(multiGeometry);
npm install @turf/linestring-to-polygon
lineStringToPolygon
Converts (Multi)LineString(s) to Polygon(s).
Arguments
| Argument | Type | Description |
| lines | (FeatureCollection | Feature<(LineString | MultiLineString)>) | Features to convert |
| properties | Object? | translates GeoJSON properties to Feature |
| autoComplete | boolean? (default true) | auto complete linestrings (matches first & last coordinates) |
| orderCoords | boolean? (default true) | sorts linestrings to place outer ring at the first position of the coordinates |
Returns
Feature<(Polygon | MultiPolygon)>: converted to Polygons
Example
var line = turf.lineString([[125, -30], [145, -30], [145, -20], [125, -20], [125, -30]]); var polygon = turf.lineStringToPolygon(line);
npm install @turf/polygonize
polygonize
Polygonizes (Multi)LineString(s) into Polygons.
Implementation of GEOSPolygonize function (geos::operation::polygonize::Polygonizer
).
Polygonizes a set of lines that represents edges in a planar graph. Edges must be correctly noded, i.e., they must only meet at their endpoints.
The implementation correctly handles:
- Dangles: edges which have one or both ends which are not incident on another edge endpoint.
- Cut Edges (bridges): edges that are connected at both ends but which do not form part of a polygon.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Geometry | Feature<(LineString | MultiLineString)>) | Lines in order to polygonize |
Returns
FeatureCollection<Polygon>: Polygons created
Throws
Error: if GeoJSON is invalid.
npm install @turf/polygon-to-linestring
polygonToLineString
Converts a Polygon to (Multi)LineString or MultiPolygon to a FeatureCollection of (Multi)LineString.
Arguments
| Argument | Type | Description |
| polygon | Feature<(Polygon | MultiPolygon)> | Feature to convert |
| properties | Object? | translates GeoJSON properties to Feature |
Returns
(FeatureCollection | Feature<(LineString | MultiLinestring)>): converted (Multi)Polygon to (Multi)LineString
Example
var poly = turf.polygon([[[125, -30], [145, -30], [145, -20], [125, -20], [125, -30]]]); var line = turf.polygonToLineString(poly);
Misc
npm install @turf/kinks
kinks
Takes a linestring, multi-linestring, multi-polygon, or polygon and returns points at all self-intersections.
Arguments
| Argument | Type | Description |
| featureIn | Feature<(LineString | MultiLineString | MultiPolygon | Polygon)> | input feature |
Returns
FeatureCollection<Point>: self-intersections
Example
var poly = turf.polygon([[ [-12.034835, 8.901183], [-12.060413, 8.899826], [-12.03638, 8.873199], [-12.059383, 8.871418], [-12.034835, 8.901183] ]]); var kinks = turf.kinks(poly);
npm install @turf/line-arc
lineArc
Creates a circular arc, of a circle of the given radius and center point, between bearing1 and bearing2; 0 bearing is North of center point, positive clockwise.
Arguments
| Argument | Type | Description |
| center | Feature<Point> | center point |
| radius | number | radius of the circle |
| bearing1 | number | angle, in decimal degrees, of the first radius of the arc |
| bearing2 | number | angle, in decimal degrees, of the second radius of the arc |
| steps | number? (default 64) | number of steps |
| units | string? (default kilometers) | miles, kilometers, degrees, or radians |
Returns
Feature<LineString>: line arc
Example
var center = turf.point([-75, 40]); var radius = 5; var bearing1 = 25; var bearing2 = 47; var arc = turf.lineArc(center, radius, bearing1, bearing2);
npm install @turf/line-chunk
lineChunk
Divides a LineString into chunks of a specified length. If the line is shorter than the segment length then the original line is returned.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Geometry | Feature<(LineString | MultiLineString)>) | the lines to split |
| segmentLength | number | how long to make each segment |
| units | string? (default 'kilometers') | units can be degrees, radians, miles, or kilometers |
| reverse | boolean? (default false) | reverses coordinates to start the first chunked segment at the end |
Returns
FeatureCollection<LineString>: collection of line segments
Example
var line = turf.lineString([[-95, 40], [-93, 45], [-85, 50]]); var chunk = turf.lineChunk(line, 15, 'miles');
npm install @turf/line-intersect
lineIntersect
Takes any LineString or Polygon GeoJSON and returns the intersecting point(s).
Arguments
| Argument | Type | Description |
| line1 | (Geometry | FeatureCollection | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) | any LineString or Polygon |
| line2 | (Geometry | FeatureCollection | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) | any LineString or Polygon |
Returns
FeatureCollection<Point>: point(s) that intersect both
Example
var line1 = turf.lineString([[126, -11], [129, -21]]); var line2 = turf.lineString([[123, -18], [131, -14]]); var intersects = turf.lineIntersect(line1, line2);
npm install @turf/line-overlap
lineOverlap
Takes any LineString or Polygon and returns the overlapping lines between both features.
Arguments
| Argument | Type | Description |
| line1 | (Geometry | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) | any LineString or Polygon |
| line2 | (Geometry | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) | any LineString or Polygon |
Returns
FeatureCollection<LineString>: lines(s) that are overlapping between both features
Example
var line1 = turf.lineString([[115, -35], [125, -30], [135, -30], [145, -35]]); var line2 = turf.lineString([[115, -25], [125, -30], [135, -30], [145, -25]]); var overlapping = turf.lineOverlap(line1, line2);
npm install @turf/line-segment
lineSegment
Creates a FeatureCollection of 2-vertex LineString segments from a (Multi)LineString or (Multi)Polygon.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature<(LineString | MultiLineString | MultiPolygon | Polygon)>) | GeoJSON Polygon or LineString |
Returns
FeatureCollection<LineString>: 2-vertex line segments
Example
var polygon = turf.polygon([[[-50, 5], [-40, -10], [-50, -10], [-40, 5], [-50, 5]]]); var segments = turf.lineSegment(polygon);
npm install @turf/line-slice
lineSlice
Takes a line, a start Point, and a stop point and returns a subsection of the line in-between those points. The start & stop points don't need to fall exactly on the line.
This can be useful for extracting only the part of a route between waypoints.
Arguments
| Argument | Type | Description |
| startPt | Feature<Point> | starting point |
| stopPt | Feature<Point> | stopping point |
| line | (Feature<LineString> | LineString) | line to slice |
Returns
Feature<LineString>: sliced line
Example
var line = turf.lineString([ [-77.031669, 38.878605], [-77.029609, 38.881946], [-77.020339, 38.884084], [-77.025661, 38.885821], [-77.021884, 38.889563], [-77.019824, 38.892368] ]); var start = turf.point([-77.029609, 38.881946]); var stop = turf.point([-77.021884, 38.889563]); var sliced = turf.lineSlice(start, stop, line);
npm install @turf/line-slice-along
lineSliceAlong
Takes a line, a specified distance along the line to a start Point, and a specified distance along the line to a stop point and returns a subsection of the line in-between those points.
This can be useful for extracting only the part of a route between two distances.
Arguments
| Argument | Type | Description |
| line | (Feature<LineString> | LineString) | input line |
| startDist | number | distance along the line to starting point |
| stopDist | number | distance along the line to ending point |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers |
Returns
Feature<LineString>: sliced line
Example
var line = turf.lineString([[7, 45], [9, 45], [14, 40], [14, 41]]); var start = 12.5; var stop = 25; var sliced = turf.lineSliceAlong(line, start, stop, 'miles');
npm install @turf/line-split
lineSplit
Split a LineString by another GeoJSON Feature.
Arguments
| Argument | Type | Description |
| line | Feature<LineString> | LineString Feature to split |
| splitter | Feature<(Point | MultiPoint | LineString | MultiLineString | Polygon | MultiPolygon)> | Feature used to split line |
Returns
FeatureCollection<LineString>: Split LineStrings
Example
var line = turf.lineString([[120, -25], [145, -25]]); var splitter = turf.lineString([[130, -15], [130, -35]]); var split = turf.lineSplit(line, splitter);
npm install @turf/mask
mask
Arguments
| Argument | Type | Description |
| polygon | (FeatureCollection | Feature<(Polygon | MultiPolygon)>) | GeoJSON Polygon used as interior rings or holes. |
| mask | Feature<Polygon>? | GeoJSON Polygon used as the exterior ring (if undefined, the world extent is used) |
Returns
Feature<Polygon>: Masked Polygon (exterior ring with holes).
Example
var polygon = turf.polygon([[[112, -21], [116, -36], [146, -39], [153, -24], [133, -10], [112, -21]]]); var mask = turf.polygon([[[90, -55], [170, -55], [170, 10], [90, 10], [90, -55]]]); var masked = turf.mask(polygon, mask);
npm install @turf/point-on-line
pointOnLine
Takes a Point and a LineString and calculates the closest Point on the (Multi)LineString.
Arguments
| Argument | Type | Description |
| lines | (Geometry | Feature<(LineString | MultiLineString)>) | lines to snap to |
| pt | (Geometry | Feature<Point> | Array<number>) | point to snap from |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers |
Returns
Feature<Point>: closest point on the
line
to
point
. The properties object will contain three values:
index
: closest point was found on nth line part,
dist
: distance between pt and the closest point,
location
: distance along the line between start and the closest point.
Example
var line = turf.lineString([ [-77.031669, 38.878605], [-77.029609, 38.881946], [-77.020339, 38.884084], [-77.025661, 38.885821], [-77.021884, 38.889563], [-77.019824, 38.892368] ]); var pt = turf.point([-77.037076, 38.884017]); var snapped = turf.pointOnLine(line, pt, 'miles');
npm install @turf/sector
sector
Creates a circular sector of a circle of given radius and center Point, between (clockwise) bearing1 and bearing2; 0 bearing is North of center point, positive clockwise.
Arguments
| Argument | Type | Description |
| center | Feature<Point> | center point |
| radius | number | radius of the circle |
| bearing1 | number | angle, in decimal degrees, of the first radius of the sector |
| bearing2 | number | angle, in decimal degrees, of the second radius of the sector |
| steps | number? (default 64) | number of steps |
| units | string? (default kilometers) | miles, kilometers, degrees, or radians |
Returns
Feature<Polygon>: sector polygon
Example
var center = turf.point([-75, 40]); var radius = 5; var bearing1 = 25; var bearing2 = 45; var sector = turf.sector(center, radius, bearing1, bearing2);
npm install @turf/unkink-polygon
unkinkPolygon
Takes a kinked polygon and returns a feature collection of polygons that have no kinks. Uses simplepolygon internally.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature<(Polygon | MultiPolygon)>) | GeoJSON Polygon or MultiPolygon |
Returns
FeatureCollection<Polygon>: Unkinked polygons
Example
var poly = turf.polygon([[[0, 0], [2, 0], [0, 2], [2, 2], [0, 0]]]); var result = turf.unkinkPolygon(poly);
Helper
npm install @turf/helpers
featureCollection
Takes one or more Features and creates a FeatureCollection.
Note: featureCollection is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the featureCollection method.
Arguments
Returns
FeatureCollection: a FeatureCollection of input features
Example
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
npm install @turf/helpers
feature
Note: feature is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the feature method.
Arguments
Returns
Feature: a GeoJSON Feature
Example
var geometry = { "type": "Point", "coordinates": [110, 50] }; var feature = turf.feature(geometry); //=feature
npm install @turf/helpers
geometryCollection
Creates a Feature<GeometryCollection> based on a coordinate array. Properties can be added optionally.
Note: geometryCollection is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the geometryCollection method.
Arguments
| Argument | Type | Description |
| geometries | Array<{Geometry}> | an array of GeoJSON Geometries |
| properties | Object? | an Object of key-value pairs to add as properties |
Returns
Feature<GeometryCollection>: a GeoJSON GeometryCollection Feature
Example
var pt = { "type": "Point", "coordinates": [100, 0] }; var line = { "type": "LineString", "coordinates": [ [101, 0], [102, 1] ] }; var collection = turf.geometryCollection([pt, line]); //=collection
npm install @turf/helpers
lineString
Creates a LineString based on a coordinate array. Properties can be added optionally.
Note: lineString is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the lineString method.
Arguments
| Argument | Type | Description |
| coordinates | Array<Array<number>> | an array of Positions |
| properties | Object? | an Object of key-value pairs to add as properties |
Returns
Feature<LineString>: a LineString feature
Throws
Error: if no coordinates are passed
Example
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
npm install @turf/helpers
multiLineString
Creates a Feature<MultiLineString> based on a coordinate array. Properties can be added optionally.
Note: multiLineString is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the multiLineString method.
Arguments
| Argument | Type | Description |
| coordinates | Array<Array<Array<number>>> | an array of LineStrings |
| properties | Object? | an Object of key-value pairs to add as properties |
Returns
Feature<MultiLineString>: a MultiLineString feature
Throws
Error: if no coordinates are passed
Example
var multiLine = turf.multiLineString([[[0,0],[10,10]]]); //=multiLine
npm install @turf/helpers
multiPoint
Creates a Feature<MultiPoint> based on a coordinate array. Properties can be added optionally.
Note: multiPoint is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the multiPoint method.
Arguments
| Argument | Type | Description |
| coordinates | Array<Array<number>> | an array of Positions |
| properties | Object? | an Object of key-value pairs to add as properties |
Returns
Feature<MultiPoint>: a MultiPoint feature
Throws
Error: if no coordinates are passed
Example
var multiPt = turf.multiPoint([[0,0],[10,10]]); //=multiPt
npm install @turf/helpers
multiPolygon
Creates a Feature<MultiPolygon> based on a coordinate array. Properties can be added optionally.
Note: multiPolygon is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the multiPolygon method.
Arguments
| Argument | Type | Description |
| coordinates | Array<Array<Array<Array<number>>>> | an array of Polygons |
| properties | Object? | an Object of key-value pairs to add as properties |
Returns
Feature<MultiPolygon>: a multipolygon feature
Throws
Error: if no coordinates are passed
Example
var multiPoly = turf.multiPolygon([[[[0,0],[0,10],[10,10],[10,0],[0,0]]]]); //=multiPoly
npm install @turf/helpers
point
Takes coordinates and properties (optional) and returns a new Point feature.
Note: point is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the point method.
Arguments
| Argument | Type | Description |
| coordinates | Array<number> | longitude, latitude position (each in decimal degrees) |
| properties | Object? | an Object that is used as the Feature 's properties |
Returns
Feature<Point>: a Point feature
Example
var point = turf.point([-75.343, 39.984]); //=point
npm install @turf/helpers
polygon
Takes an array of LinearRings and optionally an Object with properties and returns a Polygon feature.
Note: polygon is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the polygon method.
Arguments
| Argument | Type | Description |
| coordinates | Array<Array<Array<number>>> | an array of LinearRings |
| properties | Object? | a properties object |
Returns
Feature<Polygon>: a Polygon feature
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.
Example
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
Data
npm install @turf/random
random
Arguments
| Argument | Type | Description |
| type | string? (default 'point') | type of features desired: 'points' or 'polygons' |
| count | number? (default 1) | how many geometries should be generated. |
| options | Object | options relevant to the feature desired. Can include: |
Returns
FeatureCollection: generated random features
Example
var points = turf.random('points', 100, { bbox: [-70, 40, -60, 60] }); var polygons = turf.random('polygons', 4, { bbox: [-70, 40, -60, 60] });
npm install @turf/sample
sample
Takes a FeatureCollection and returns a FeatureCollection with given number of features at random.
Arguments
| Argument | Type | Description |
| featurecollection | FeatureCollection | set of input features |
| num | number | number of features to select |
Returns
FeatureCollection: a FeatureCollection with
n
features
Example
var points = turf.random('points', 300, { bbox: [-80, 30, -60, 60] }); var sample = turf.sample(points, 10);
Interpolation
npm install @turf/interpolate
interpolate
Takes a set of points and estimates their 'property' values on a grid using the Inverse Distance Weighting (IDW) method.
Arguments
| Argument | Type | Description |
| points | FeatureCollection<Point> | with known value |
| cellSize | number | the distance across each grid point |
| gridType | string? (default 'square') | defines the output format based on a Grid Type (options: 'square' | 'point' | 'hex' | 'triangle') |
| property | string? (default 'elevation') | the property name in
points
from which z-values will be pulled, zValue fallbacks to 3rd coordinate if no property exists.
|
| units | string? (default kilometers) | used in calculating cellSize, can be degrees, radians, miles, or kilometers |
| weight | number? (default 1) | exponent regulating the distance-decay weighting |
Returns
FeatureCollection<(Point | Polygon)>: grid of points or polygons with interpolated 'property'
Example
var points = turf.random('points', 30, { bbox: [50, 30, 70, 50] }); // add a random property to each point turf.featureEach(points, function(point) { point.properties.solRad = Math.random() * 50; }); var grid = turf.interpolate(points, 100, 'points', 'solRad', 'miles');
npm install @turf/isobands
isobands
Takes a grid FeatureCollection of Point features with z-values and an array of value breaks and generates filled contour isobands.
Arguments
| Argument | Type | Description |
| pointGrid | FeatureCollection<Point> | input points |
| breaks | Array<number> | where to draw contours |
| zProperty | string? (default 'elevation') | the property name in
points
from which z-values will be pulled
|
| options | Object? (default {}) | options on output |
Returns
FeatureCollection<MultiPolygon>: a FeatureCollection of MultiPolygon features representing isobands
Example
// create a grid of points with random z-values in their properties var extent = [-70.823364, -33.553984, -69.823364, -32.553984]; var cellWidth = 5; var units = 'miles'; var pointGrid = turf.pointGrid(extent, cellWidth, units); for (var i = 0; i < pointGrid.features.length; i++) { pointGrid.features[i].properties.elevation = Math.random() * 10; } var breaks = [0, 5, 8.5]; var isobands = turf.isobands(pointGrid, breaks);
npm install @turf/isolines
isolines
Takes a grid FeatureCollection of Point features with z-values and an array of value breaks and generates isolines.
Arguments
| Argument | Type | Description |
| pointGrid | FeatureCollection<Point> | input points |
| breaks | Array<number> | values of
zProperty
where to draw isolines
|
| zProperty | string? (default 'elevation') | the property name in
points
from which z-values will be pulled
|
| propertiesToAllIsolines | Object? (default {}) | GeoJSON properties passed to ALL isolines |
| propertiesPerIsoline | Array<Object>? (default []) | GeoJSON properties passed, in order, to the correspondent isoline; the breaks array will define the order in which the isolines are created |
Returns
FeatureCollection<MultiLineString>: a FeatureCollection of MultiLineString features representing isolines
Example
// create a grid of points with random z-values in their properties var extent = [0, 30, 20, 50]; var cellWidth = 100; var units = 'miles'; var pointGrid = turf.pointGrid(extent, cellWidth, units); for (var i = 0; i < pointGrid.features.length; i++) { pointGrid.features[i].properties.temperature = Math.random() * 10; } var breaks = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; var isolines = turf.isolines(pointGrid, breaks, 'temperature');
npm install @turf/planepoint
planepoint
Takes a triangular plane as a Polygon
and a Point within that triangle and returns the z-value
at that point. The Polygon should have properties a
, b
, and c
that define the values at its three corners. Alternatively, the z-values
of each triangle point can be provided by their respective 3rd coordinate
if their values are not provided as properties.
Arguments
| Argument | Type | Description |
| point | (Geometry | Feature<Point> | Array<number>) | the Point for which a z-value will be calculated |
| triangle | (Geometry | Feature<Polygon>) | a Polygon feature with three vertices |
Returns
number: the z-value for
interpolatedPoint
Example
var point = turf.point([-75.3221, 39.529]); // "a", "b", and "c" values represent the values of the coordinates in order. var triangle = turf.polygon([[ [-75.1221, 39.57], [-75.58, 39.18], [-75.97, 39.86], [-75.1221, 39.57] ]], { "a": 11, "b": 122, "c": 44 }); var zValue = turf.planepoint(point, triangle); point.properties.zValue = zValue;
npm install @turf/tin
tin
Takes a set of points and creates a Triangulated Irregular Network, or a TIN for short, returned as a collection of Polygons. These are often used for developing elevation contour maps or stepped heat visualizations.
If an optional z-value property is provided then it is added as properties called a
, b
,
and c
representing its value at each of the points that represent the corners of the
triangle.
Arguments
| Argument | Type | Description |
| points | FeatureCollection<Point> | input points |
| z | String? | name of the property from which to pull z values This is optional: if not given, then there will be no extra data added to the derived triangles. |
Returns
FeatureCollection<Polygon>: TIN output
Example
// generate some random point data var points = turf.random('points', 30, { bbox: [50, 30, 70, 50] }); // add a random property to each point between 0 and 9 for (var i = 0; i < points.features.length; i++) { points.features[i].properties.z = ~~(Math.random() * 9); } var tin = turf.tin(points, 'z');
npm install @turf/idw
idw
Takes a FeatureCollection of points with known value, a power parameter, a cell depth, a unit of measurement and returns a FeatureCollection of polygons in a square-grid with an interpolated value property "IDW" for each grid cell. It finds application when in need of creating a continuous surface (i.e. rainfall, temperature, chemical dispersion surface...) from a set of spatially scattered points.
Arguments
| Argument | Type | Description |
| controlPoints | FeatureCollection<Point> | Sampled points with known value |
| valueField | string | GeoJSON field containing the known value to interpolate on |
| weight | number | Exponent regulating the distance-decay weighting |
| cellWidth | number | The distance across each cell |
| units | string? (default kilometers) | used in calculating cellSize, can be degrees, radians, miles, or kilometers |
Returns
FeatureCollection<Polygon>: grid A grid of polygons with a property field named as
valueField
Joins
npm install @turf/inside
inside
Takes a Point and a Polygon or MultiPolygon and determines if the point resides inside the polygon. The polygon can be convex or concave. The function accounts for holes.
Arguments
| Argument | Type | Description |
| point | Feature<Point> | input point |
| polygon | Feature<(Polygon | MultiPolygon)> | input polygon or multipolygon |
| ignoreBoundary | boolean? (default false) | True if polygon boundary should be ignored when determining if the point is inside the polygon otherwise false. |
Returns
boolean: true
if the Point is inside the Polygon;
false
if the Point is not inside the Polygon
Example
var pt = turf.point([-77, 44]); var poly = turf.polygon([[ [-81, 41], [-81, 47], [-72, 47], [-72, 41], [-81, 41] ]]); turf.inside(pt, poly); //= true
npm install @turf/within
within
Arguments
| Argument | Type | Description |
| points | FeatureCollection<Point> | input points |
| polygons | FeatureCollection<Polygon> | input polygons |
Returns
FeatureCollection<Point>: points that land within at least one polygon
Example
var searchWithin = turf.featureCollection([ turf.polygon([[ [-46.653,-23.543], [-46.634,-23.5346], [-46.613,-23.543], [-46.614,-23.559], [-46.631,-23.567], [-46.653,-23.560], [-46.653,-23.543] ]]) ]); var points = turf.featureCollection([ turf.point([-46.6318, -23.5523]), turf.point([-46.6246, -23.5325]), turf.point([-46.6062, -23.5513]), turf.point([-46.663, -23.554]), turf.point([-46.643, -23.557]) ]); var ptsWithin = turf.within(points, searchWithin);
npm install @turf/tag
tag
Arguments
| Argument | Type | Description |
| points | FeatureCollection<Point> | input points |
| polygons | FeatureCollection<Polygon> | input polygons |
| field | string | property in
polygons
to add to joined {
|
| outField | string | property in
points
in which to store joined property from
polygons
|
Returns
FeatureCollection<Point>: points with
containingPolyId
property containing values from
polyId
Example
var pt1 = turf.point([-77, 44]); var pt2 = turf.point([-77, 38]); var poly1 = turf.polygon([[ [-81, 41], [-81, 47], [-72, 47], [-72, 41], [-81, 41] ]], {pop: 3000}); var poly2 = turf.polygon([[ [-81, 35], [-81, 41], [-72, 41], [-72, 35], [-81, 35] ]], {pop: 1000}); var points = turf.featureCollection([pt1, pt2]); var polygons = turf.featureCollection([poly1, poly2]); var tagged = turf.tag(points, polygons, 'pop', 'population');
Grids
npm install @turf/hex-grid
hexGrid
Takes a bounding box and the diameter of the cell and returns a FeatureCollection of flat-topped hexagons or triangles (Polygon features) aligned in an "odd-q" vertical grid as described in Hexagonal Grids.
Arguments
| Argument | Type | Description |
| bbox | Array<number> | extent in [ minX, minY, maxX, maxY ] order |
| cellDiameter | number | diameter of the circumcircle of the hexagons, in specified units |
| units | string? (default kilometers) | used in calculating cell size, can be degrees, radians, miles, or kilometers |
| triangles | boolean? (default false) | whether to return as triangles instead of hexagons |
Returns
FeatureCollection<Polygon>: a hexagonal grid
Example
var bbox = [-96,31,-84,40]; var cellDiameter = 50; var units = 'miles'; var hexgrid = turf.hexGrid(bbox, cellDiameter, units);
npm install @turf/point-grid
pointGrid
Creates a Point grid from a bounding box, FeatureCollection or Feature.
Arguments
| Argument | Type | Description |
| bbox | (Array<number> | FeatureCollection | Feature<any>) | extent in [ minX, minY, maxX, maxY ] order |
| cellSide | number | the distance between points |
| units | string? (default kilometers) | used in calculating cellSide, can be degrees, radians, miles, or kilometers |
| centered | boolean? (default true) | adjust points position to center the grid into bbox. This parameter is going to be removed in the next major release, having the output always centered into bbox. |
| bboxIsMask | boolean? (default false) | if true, and bbox is a Polygon or MultiPolygon, the grid Point will be created only if inside the bbox Polygon(s) |
Returns
FeatureCollection<Point>: grid of points
Example
var extent = [-70.823364, -33.553984, -70.473175, -33.302986]; var cellSide = 3; var units = 'miles'; var grid = turf.pointGrid(extent, cellSide, units);
npm install @turf/square-grid
squareGrid
Creates a square grid from a bounding box, Feature or FeatureCollection.
Arguments
| Argument | Type | Description |
| bbox | (Array<number> | FeatureCollection | Feature<any>) | extent in [ minX, minY, maxX, maxY ] order |
| cellSize | number | width of each cell |
| units | string? (default kilometers) | used in calculating cellSize, can be degrees, radians, miles, or kilometers |
| completelyWithin | boolean? (default false) | adjust width & height cellSize to fit exactly within bbox |
Returns
FeatureCollection<Polygon>: grid a grid of polygons
Example
var bbox = [-95, 30 ,-85, 40]; var cellSize = 50; var units = 'miles'; var squareGrid = turf.squareGrid(bbox, cellSize, units);
npm install @turf/triangle-grid
triangleGrid
Takes a bounding box and a cell depth and returns a set of triangular polygons in a grid.
Arguments
| Argument | Type | Description |
| bbox | Array<number> | extent in [ minX, minY, maxX, maxY ] order |
| cellSize | number | dimension of each cell |
| units | string? (default kilometers) | used in calculating cellSize, can be degrees, radians, miles, or kilometers |
Returns
FeatureCollection<Polygon>: grid of polygons
Example
var bbox = [-95, 30 ,-85, 40]; var cellSize = 50; var units = 'miles'; var triangleGrid = turf.triangleGrid(bbox, cellSize, units);
Classification
npm install @turf/nearest
nearest
Takes a reference point and a FeatureCollection of Features with Point geometries and returns the point from the FeatureCollection closest to the reference. This calculation is geodesic.
Arguments
| Argument | Type | Description |
| targetPoint | (Geometry | Feature<Point> | Array<number>) | the reference point |
| points | FeatureCollection<Point> | against input point set |
Returns
Feature<Point>: the closest point in the set to the reference point
Example
var targetPoint = turf.point([28.965797, 41.010086], {"marker-color": "#0F0"}); var points = turf.featureCollection([ turf.point([28.973865, 41.011122]), turf.point([28.948459, 41.024204]), turf.point([28.938674, 41.013324]) ]); var nearest = turf.nearest(targetPoint, points);
Aggregation
npm install @turf/collect
collect
Merges a specified property from a FeatureCollection of points into a
FeatureCollection of polygons. Given an inProperty
on points and an outProperty
for polygons, this finds every point that lies within each polygon, collects the
inProperty
values from those points, and adds them as an array to outProperty
on the polygon.
Arguments
| Argument | Type | Description |
| polygons | FeatureCollection<Polygon> | polygons with values on which to aggregate |
| points | FeatureCollection<Point> | points to be aggregated |
| inProperty | string | property to be nested from |
| outProperty | string | property to be nested into |
Returns
FeatureCollection<Polygon>: polygons with properties listed based on
outField
Example
var poly1 = turf.polygon([[[0,0],[10,0],[10,10],[0,10],[0,0]]]); var poly2 = turf.polygon([[[10,0],[20,10],[20,20],[20,0],[10,0]]]); var polyFC = turf.featureCollection([poly1, poly2]); var pt1 = turf.point([5,5], {population: 200}); var pt2 = turf.point([1,3], {population: 600}); var pt3 = turf.point([14,2], {population: 100}); var pt4 = turf.point([13,1], {population: 200}); var pt5 = turf.point([19,7], {population: 300}); var pointFC = turf.featureCollection([pt1, pt2, pt3, pt4, pt5]); var collected = turf.collect(polyFC, pointFC, 'population', 'values'); var values = collected.features[0].properties.values //=values => [200, 600]
npm install @turf/clusters-dbscan
clustersDbscan
Takes a set of points and partition them into clusters according to https://en.wikipedia.org/wiki/DBSCAN data clustering algorithm.
Arguments
| Argument | Type | Description |
| points | FeatureCollection<Point> | to be clustered |
| maxDistance | number | Maximum Distance between any point of the cluster to generate the clusters (kilometers only) |
| units | string? (default kilometers) | in which
maxDistance
is expressed, can be degrees, radians, miles, or kilometers
|
| minPoints | number? (default 3) | Minimum number of points to generate a single cluster, points which do not meet this requirement will be classified as an 'edge' or 'noise'. |
Returns
FeatureCollection<Point>: Clustered Points with an additional two properties associated to each Feature:
- {number} cluster - the associated clusterId
- {string} dbscan - type of point it has been classified as ('core'|'edge'|'noise')
Example
// create random points with random z-values in their properties var points = turf.random('point', 100, { bbox: [0, 30, 20, 50] }); var distance = 100; var clustered = turf.clustersDbscan(points, distance);
npm install @turf/clusters-kmeans
clustersKmeans
Takes a set of points and partition them into clusters using the k-mean . It uses the k-means algorithm
Arguments
| Argument | Type | Description |
| points | FeatureCollection<Point> | to be clustered |
| numberOfClusters | number? (default Math.sqrt(numberOfPoints/2)) | numberOfClusters that will be generated |
| mutate | boolean? (default false) | allows GeoJSON input to be mutated (significant performance increase if true) |
Returns
FeatureCollection<Point>: Clustered Points with an additional two properties associated to each Feature:
- {number} cluster - the associated clusterId
- {[number, number]} centroid - Centroid of the cluster [Longitude, Latitude]
Example
// create random points with random z-values in their properties var points = turf.random('point', 100, { bbox: [0, 30, 20, 50] }); var numberOfClusters = 7; var clustered = turf.clustersKmeans(points, numberOfClusters);
Meta
npm install @turf/meta
coordAll
Get all coordinates from any GeoJSON object.
Note: coordAll is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordAll method.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature) | any GeoJSON object |
Returns
Array<Array<number>>: coordinate position array
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.point([36, 53], {hello: 'world'}) ]); var coords = turf.coordAll(features); //= [[26, 37], [36, 53]]
npm install @turf/meta
coordEach
Iterate over coordinates in any GeoJSON object, similar to Array.forEach()
Note: coordEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordEach method.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Geometry | Feature) | any GeoJSON object |
| callback | Function | a method that takes (currentCoord, coordIndex) |
| excludeWrapCoord | boolean? (default false) | whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. |
Example
var features = turf.featureCollection([ turf.point([26, 37], {"foo": "bar"}), turf.point([36, 53], {"hello": "world"}) ]); turf.coordEach(features, function (currentCoord, coordIndex) { //=currentCoord //=coordIndex });
npm install @turf/meta
coordReduce
Reduce coordinates in any GeoJSON object, similar to Array.reduce()
Note: coordReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordReduce method.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Geometry | Feature) | any GeoJSON object |
| callback | Function | a method that takes (previousValue, currentCoord, coordIndex) |
| initialValue | any? | Value to use as the first argument to the first call of the callback. |
| excludeWrapCoord | boolean? (default false) | whether or not to include the final coordinate of LinearRings that wraps the ring in its iteration. |
Returns
any: The value that results from the reduction.
Example
var features = turf.featureCollection([ turf.point([26, 37], {"foo": "bar"}), turf.point([36, 53], {"hello": "world"}) ]); turf.coordReduce(features, function (previousValue, currentCoord, coordIndex) { //=previousValue //=currentCoord //=coordIndex return currentCoord; });
npm install @turf/meta
featureEach
Iterate over features in any GeoJSON object, similar to Array.forEach.
Note: featureEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the featureEach method.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (currentFeature, featureIndex) |
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.point([36, 53], {hello: 'world'}) ]); turf.featureEach(features, function (currentFeature, featureIndex) { //=currentFeature //=featureIndex });
npm install @turf/meta
featureReduce
Reduce features in any GeoJSON object, similar to Array.reduce().
Note: featureReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the featureReduce method.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (previousValue, currentFeature, featureIndex) |
| initialValue | any? | Value to use as the first argument to the first call of the callback. |
Returns
any: The value that results from the reduction.
Example
var features = turf.featureCollection([ turf.point([26, 37], {"foo": "bar"}), turf.point([36, 53], {"hello": "world"}) ]); turf.featureReduce(features, function (previousValue, currentFeature, featureIndex) { //=previousValue //=currentFeature //=featureIndex return currentFeature });
npm install @turf/meta
flattenEach
Iterate over flattened features in any GeoJSON object, similar to Array.forEach.
Note: flattenEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the flattenEach method.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (currentFeature, featureIndex, featureSubIndex) |
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.multiPoint([[40, 30], [36, 53]], {hello: 'world'}) ]); turf.flattenEach(features, function (currentFeature, featureIndex, featureSubIndex) { //=currentFeature //=featureIndex //=featureSubIndex });
npm install @turf/meta
flattenReduce
Reduce flattened features in any GeoJSON object, similar to Array.reduce().
Note: flattenReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the flattenReduce method.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (previousValue, currentFeature, featureIndex, featureSubIndex) |
| initialValue | any? | Value to use as the first argument to the first call of the callback. |
Returns
any: The value that results from the reduction.
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.multiPoint([[40, 30], [36, 53]], {hello: 'world'}) ]); turf.flattenReduce(features, function (previousValue, currentFeature, featureIndex, featureSubIndex) { //=previousValue //=currentFeature //=featureIndex //=featureSubIndex return currentFeature });
npm install @turf/invariant
getCoord
Unwrap a coordinate from a Point Feature, Geometry or a single coordinate.
Note: getCoord is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the getCoord method.
Arguments
Returns
Example
var pt = turf.point([10, 10]); var coord = turf.getCoord(pt); //= [10, 10]
npm install @turf/invariant
getCoords
Unwrap coordinates from a Feature, Geometry Object or an Array of numbers
Note: getCoords is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the getCoords method.
Arguments
Returns
Example
var poly = turf.polygon([[[119.32, -8.7], [119.55, -8.69], [119.51, -8.54], [119.32, -8.7]]]); var coord = turf.getCoords(poly); //= [[[119.32, -8.7], [119.55, -8.69], [119.51, -8.54], [119.32, -8.7]]]
npm install @turf/invariant
getGeom
Get Geometry from Feature or Geometry Object
Note: getGeom is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the getGeom method.
Arguments
Returns
(Geometry | null): GeoJSON Geometry Object
Throws
Error: if geojson is not a Feature or Geometry Object
Example
var point = { "type": "Feature", "properties": {}, "geometry": { "type": "Point", "coordinates": [110, 40] } } var geom = turf.getGeom(point) //={"type": "Point", "coordinates": [110, 40]}
npm install @turf/invariant
getGeomType
Get Geometry Type from Feature or Geometry Object
Note: getGeomType is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the getGeomType method.
Arguments
Returns
string: GeoJSON Geometry Type
Throws
Error: if geojson is not a Feature or Geometry Object
Example
var point = { "type": "Feature", "properties": {}, "geometry": { "type": "Point", "coordinates": [110, 40] } } var geom = turf.getGeom(point) //="Point"
npm install @turf/meta
geomEach
Iterate over each geometry in any GeoJSON object, similar to Array.forEach()
Note: geomEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the geomEach method.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (currentGeometry, featureIndex, currentProperties) |
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.point([36, 53], {hello: 'world'}) ]); turf.geomEach(features, function (currentGeometry, featureIndex, currentProperties) { //=currentGeometry //=featureIndex //=currentProperties });
npm install @turf/meta
geomReduce
Reduce geometry in any GeoJSON object, similar to Array.reduce().
Note: geomReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the geomReduce method.
Arguments
| Argument | Type | Description |
| geojson | (Geometry | FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (previousValue, currentGeometry, featureIndex, currentProperties) |
| initialValue | any? | Value to use as the first argument to the first call of the callback. |
Returns
any: The value that results from the reduction.
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.point([36, 53], {hello: 'world'}) ]); turf.geomReduce(features, function (previousValue, currentGeometry, featureIndex, currentProperties) { //=previousValue //=currentGeometry //=featureIndex //=currentProperties return currentGeometry });
npm install @turf/meta
propEach
Iterate over properties in any GeoJSON object, similar to Array.forEach()
Note: propEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the propEach method.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (currentProperties, featureIndex) |
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.point([36, 53], {hello: 'world'}) ]); turf.propEach(features, function (currentProperties, featureIndex) { //=currentProperties //=featureIndex });
npm install @turf/meta
propReduce
Reduce properties in any GeoJSON object into a single value, similar to how Array.reduce works. However, in this case we lazily run the reduction, so an array of all properties is unnecessary.
Note: propReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the propReduce method.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature) | any GeoJSON object |
| callback | Function | a method that takes (previousValue, currentProperties, featureIndex) |
| initialValue | any? | Value to use as the first argument to the first call of the callback. |
Returns
any: The value that results from the reduction.
Example
var features = turf.featureCollection([ turf.point([26, 37], {foo: 'bar'}), turf.point([36, 53], {hello: 'world'}) ]); turf.propReduce(features, function (previousValue, currentProperties, featureIndex) { //=previousValue //=currentProperties //=featureIndex return currentProperties });
npm install @turf/meta
segmentEach
Iterate over 2-vertex line segment in any GeoJSON object, similar to Array.forEach() (Multi)Point geometries do not contain segments therefore they are ignored during this operation.
Note: segmentEach is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the segmentEach method.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature | Geometry) | any GeoJSON |
| callback | Function | a method that takes (currentSegment, featureIndex, featureSubIndex) |
Returns
void:
Example
var polygon = turf.polygon([[[-50, 5], [-40, -10], [-50, -10], [-40, 5], [-50, 5]]]); // Iterate over GeoJSON by 2-vertex segments turf.segmentEach(polygon, function (currentSegment, featureIndex, featureSubIndex) { //= currentSegment //= featureIndex //= featureSubIndex }); // Calculate the total number of segments var total = 0; var initialValue = 0; turf.segmentEach(polygon, function () { total++; }, initialValue);
npm install @turf/meta
segmentReduce
Reduce 2-vertex line segment in any GeoJSON object, similar to Array.reduce() (Multi)Point geometries do not contain segments therefore they are ignored during this operation.
Note: segmentReduce is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the segmentReduce method.
Arguments
| Argument | Type | Description |
| geojson | (FeatureCollection | Feature | Geometry) | any GeoJSON |
| callback | Function | a method that takes (previousValue, currentSegment, currentIndex) |
| initialValue | any? | Value to use as the first argument to the first call of the callback. |
Returns
void:
Example
var polygon = turf.polygon([[[-50, 5], [-40, -10], [-50, -10], [-40, 5], [-50, 5]]]); // Iterate over GeoJSON by 2-vertex segments turf.segmentReduce(polygon, function (previousSegment, currentSegment, currentIndex, currentSubIndex) { //= previousSegment //= currentSegment //= currentIndex //= currentSubIndex return currentSegment }); // Calculate the total number of segments var initialValue = 0 var total = turf.segmentReduce(polygon, function (previousValue) { previousValue++; return previousValue; }, initialValue);
npm install @turf/clusters
getCluster
Get Cluster
Arguments
| Argument | Type | Description |
| geojson | FeatureCollection | GeoJSON Features |
| filter | any | Filter used on GeoJSON properties to get Cluster |
Returns
FeatureCollection: Single Cluster filtered by GeoJSON Properties
Example
var geojson = turf.featureCollection([ turf.point([0, 0], {'marker-symbol': 'circle'}), turf.point([2, 4], {'marker-symbol': 'star'}), turf.point([3, 6], {'marker-symbol': 'star'}), turf.point([5, 1], {'marker-symbol': 'square'}), turf.point([4, 2], {'marker-symbol': 'circle'}) ]); // Create a cluster using K-Means (adds `cluster` to GeoJSON properties) var clustered = turf.clustersKmeans(geojson); // Retrieve first cluster (0) var cluster = turf.getCluster(clustered, {cluster: 0}); //= cluster // Retrieve cluster based on custom properties turf.getCluster(clustered, {'marker-symbol': 'circle'}).length; //= 2 turf.getCluster(clustered, {'marker-symbol': 'square'}).length; //= 1
npm install @turf/clusters
clusterEach
clusterEach
Arguments
| Argument | Type | Description |
| geojson | FeatureCollection | GeoJSON Features |
| property | (string | number) | GeoJSON property key/value used to create clusters |
| callback | Function | a method that takes (cluster, clusterValue, currentIndex) |
Returns
void:
Example
var geojson = turf.featureCollection([ turf.point([0, 0]), turf.point([2, 4]), turf.point([3, 6]), turf.point([5, 1]), turf.point([4, 2]) ]); // Create a cluster using K-Means (adds `cluster` to GeoJSON properties) var clustered = turf.clustersKmeans(geojson); // Iterate over each cluster clusterEach(clustered, 'cluster', function (cluster, clusterValue, currentIndex) { //= cluster //= clusterValue //= currentIndex }) // Calculate the total number of clusters var total = 0 turf.clusterEach(clustered, 'cluster', function () { total++; }); // Create an Array of all the values retrieved from the 'cluster' property var values = [] turf.clusterEach(clustered, 'cluster', function (cluster, clusterValue) { values.push(clusterValue); });
npm install @turf/clusters
clusterReduce
Reduce clusters in GeoJSON Features, similar to Array.reduce()
Arguments
| Argument | Type | Description |
| geojson | FeatureCollection | GeoJSON Features |
| property | (string | number) | GeoJSON property key/value used to create clusters |
| callback | Function | a method that takes (previousValue, cluster, clusterValue, currentIndex) |
| initialValue | any? | Value to use as the first argument to the first call of the callback. |
Returns
any: The value that results from the reduction.
Example
var geojson = turf.featureCollection([ turf.point([0, 0]), turf.point([2, 4]), turf.point([3, 6]), turf.point([5, 1]), turf.point([4, 2]) ]); // Create a cluster using K-Means (adds `cluster` to GeoJSON properties) var clustered = turf.clustersKmeans(geojson); // Iterate over each cluster and perform a calculation var initialValue = 0 turf.clusterReduce(clustered, 'cluster', function (previousValue, cluster, clusterValue, currentIndex) { //=previousValue //=cluster //=clusterValue //=currentIndex return previousValue++; }, initialValue); // Calculate the total number of clusters var total = turf.clusterReduce(clustered, 'cluster', function (previousValue) { return previousValue++; }, 0); // Create an Array of all the values retrieved from the 'cluster' property var values = turf.clusterReduce(clustered, 'cluster', function (previousValue, cluster, clusterValue) { return previousValue.push(clusterValue); }, []);
Assertions
npm install @turf/invariant
collectionOf
Enforce expectations about types of FeatureCollection inputs for Turf. Internally this uses geojsonType to judge geometry types.
Note: collectionOf is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the collectionOf method.
Arguments
| Argument | Type | Description |
| featureCollection | FeatureCollection | a FeatureCollection for which features will be judged |
| type | string | expected GeoJSON type |
| name | string | name of calling function |
Throws
Error: if value is not the expected type.
npm install @turf/invariant
containsNumber
Checks if coordinates contains a number
Note: containsNumber is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the containsNumber method.
Arguments
| Argument | Type | Description |
| coordinates | Array<any> | GeoJSON Coordinates |
Returns
boolean: true if Array contains a number
npm install @turf/invariant
geojsonType
Enforce expectations about types of GeoJSON objects for Turf.
Note: geojsonType is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the geojsonType method.
Arguments
| Argument | Type | Description |
| value | GeoJSON | any GeoJSON object |
| type | string | expected GeoJSON type |
| name | string | name of calling function |
Throws
Error: if value is not the expected type.
npm install @turf/invariant
featureOf
Enforce expectations about types of Feature inputs for Turf. Internally this uses geojsonType to judge geometry types.
Note: featureOf is part of the @turf/invariant module. To use it directly you will need to import the @turf/invariant and call the featureOf method.
Arguments
| Argument | Type | Description |
| feature | Feature | a feature with an expected geometry type |
| type | string | expected GeoJSON type |
| name | string | name of calling function |
Throws
Error: error if value is not the expected type.
Booleans
npm install @turf/boolean-clockwise
booleanClockwise
Takes a ring and return true or false whether or not the ring is clockwise or counter-clockwise.
Arguments
| Argument | Type | Description |
| line | (Geometry | Feature<LineString> | Array<Array<number>>) | to be evaluated |
Returns
Boolean: true/false
Example
var clockwiseRing = turf.lineString([[0,0],[1,1],[1,0],[0,0]]); var counterClockwiseRing = turf.lineString([[0,0],[1,0],[1,1],[0,0]]); turf.booleanClockwise(clockwiseRing) //=true turf.booleanClockwise(counterClockwiseRing) //=false
npm install @turf/boolean-contains
booleanContains
Boolean-contains returns True if the second geometry is completely contained by the first geometry.
The interiors of both geometries must intersect and, the interior and boundary of the secondary (geometry b)
must not intersect the exterior of the primary (geometry a).
Boolean-contains returns the exact opposite result of the @turf/boolean-within
.
Arguments
| Argument | Type | Description |
| feature1 | (Geometry | Feature<any>) | GeoJSON Feature or Geometry |
| feature2 | (Geometry | Feature<any>) | GeoJSON Feature or Geometry |
Returns
boolean: true/false
Example
const line = turf.lineString([[1, 1], [1, 2], [1, 3], [1, 4]]); const point = turf.point([1, 2]); turf.booleanContains(line, point); //=true
npm install @turf/boolean-crosses
booleanCrosses
Boolean-Crosses returns True if the intersection results in a geometry whose dimension is one less than the maximum dimension of the two source geometries and the intersection set is interior to both source geometries.
Boolean-Crosses returns t (TRUE) for only multipoint/polygon, multipoint/linestring, linestring/linestring, linestring/polygon, and linestring/multipolygon comparisons.
Arguments
| Argument | Type | Description |
| feature1 | (Geometry | Feature<any>) | GeoJSON Feature or Geometry |
| feature2 | (Geometry | Feature<any>) | GeoJSON Feature or Geometry |
Returns
boolean: true/false
Example
var line1 = turf.lineString([[-2, 2], [4, 2]]); var line2 = turf.lineString([[1, 1], [1, 2], [1, 3], [1, 4]]); var cross = turf.booleanCrosses(line1, line2); //=true
npm install @turf/boolean-disjoint
booleanDisjoint
Boolean-disjoint returns (TRUE) if the intersection of the two geometries is an empty set.
Arguments
| Argument | Type | Description |
| feature1 | (Geometry | Feature<any>) | GeoJSON Feature or Geometry |
| feature2 | (Geometry | Feature<any>) | GeoJSON Feature or Geometry |
Returns
Boolean: true/false
Example
const point = turf.point([2, 2]); const line = turf.lineString([[1, 1], [1, 2], [1, 3], [1, 4]]); turf.booleanDisjoint(line, point); //=true
npm install @turf/boolean-overlap
booleanOverlap
Compares two geometries of the same dimension and returns true if their intersection set results in a geometry different from both but of the same dimension. It applies to Polygon/Polygon, LineString/LineString, Multipoint/Multipoint, MultiLineString/MultiLineString and MultiPolygon/MultiPolygon.
Arguments
| Argument | Type | Description |
| feature1 | (Geometry | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) | input |
| feature2 | (Geometry | Feature<(LineString | MultiLineString | Polygon | MultiPolygon)>) | input |
Returns
boolean: true/false
Example
var poly1 = turf.polygon([[[0,0],[0,5],[5,5],[5,0],[0,0]]]); var poly2 = turf.polygon([[[1,1],[1,6],[6,6],[6,1],[1,1]]]); var poly3 = turf.polygon([[[10,10],[10,15],[15,15],[15,10],[10,10]]]); turf.booleanOverlap(poly1, poly2) //=true turf.booleanOverlap(poly2, poly3) //=false
npm install @turf/boolean-point-on-line
booleanPointOnLine
Returns true if a point is on a line. Accepts a optional parameter to ignore the start and end vertices of the linestring.
Arguments
| Argument | Type | Description |
| point | (Geometry | Feature<Point>) | GeoJSON Feature or Geometry |
| linestring | (Geometry | Feature<LineString>) | GeoJSON Feature or Geometry |
| ignoreEndVertices | boolean? (default false) | whether to ignore the start and end vertices. |
Returns
boolean: true/false
Example
var pt = turf.point([0, 0]); var line = turf.lineString([[-1, -1],[1, 1],[1.5, 2.2]]); var isPointOnLine = turf.booleanPointOnLine(pt, line); //=true
Unit Conversion
npm install @turf/helpers
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
Note: bearingToAngle is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the bearingToAngle method.
Arguments
| Argument | Type | Description |
| bearing | number | angle, between -180 and +180 degrees |
Returns
number: angle between 0 and 360 degrees
npm install @turf/helpers
convertArea
Converts a area to the requested unit. Valid units: kilometers, kilometres, meters, metres, centimetres, millimeter, acre, mile, yard, foot, inch
Note: convertArea is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the convertArea method.
Arguments
| Argument | Type | Description |
| area | number | to be converted |
| originalUnit | string? (default meters) | of the distance |
| finalUnit | string? (default kilometers) | returned unit |
Returns
number: the converted distance
npm install @turf/helpers
convertDistance
Converts a distance to the requested unit. Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
Note: convertDistance is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the convertDistance method.
Arguments
| Argument | Type | Description |
| distance | number | to be converted |
| originalUnit | string | of the distance |
| finalUnit | string? (default kilometers) | returned unit |
Returns
number: the converted distance
npm install @turf/helpers
degrees2radians
Converts an angle in degrees to radians
Note: degrees2radians is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the degrees2radians method.
Arguments
| Argument | Type | Description |
| degrees | number | angle between 0 and 360 degrees |
Returns
number: angle in radians
npm install @turf/helpers
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
Note: distanceToRadians is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the distanceToRadians method.
Arguments
| Argument | Type | Description |
| distance | number | in real units |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. |
Returns
number: radians
npm install @turf/helpers
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
Note: distanceToDegrees is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the distanceToDegrees method.
Arguments
| Argument | Type | Description |
| distance | number | in real units |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. |
Returns
number: degrees
npm install @turf/helpers
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
Note: radiansToDistance is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the radiansToDistance method.
Arguments
| Argument | Type | Description |
| radians | number | in radians across the sphere |
| units | string? (default kilometers) | can be degrees, radians, miles, or kilometers inches, yards, metres, meters, kilometres, kilometers. |
Returns
number: distance
npm install @turf/helpers
radians2degrees
Converts an angle in radians to degrees
Note: radians2degrees is part of the @turf/helpers module. To use it directly you will need to import the @turf/helpers and call the radians2degrees method.
Arguments
| Argument | Type | Description |
| radians | number | angle in radians |
Returns
number: degrees between 0 and 360 degrees
npm install @turf/clusters
clusterEachCallback
Callback for clusterEach
Arguments
| Argument | Type | Description |
| cluster | FeatureCollection? | The current cluster being processed. |
| clusterValue | any? | Value used to create cluster being processed. |
| currentIndex | number? | The index of the current element being processed in the array.Starts at index 0 |
| geojson | any | |
| property | any | |
| callback | any |
Returns
void:
npm install @turf/clusters
clusterReduceCallback
Callback for clusterReduce
The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.
If an initialValue is provided to the reduce method:
- The previousValue argument is initialValue.
- The currentValue argument is the value of the first element present in the array.
If an initialValue is not provided:
- The previousValue argument is the value of the first element present in the array.
- The currentValue argument is the value of the second element present in the array.
Arguments
| Argument | Type | Description |
| previousValue | any? | The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. |
| cluster | FeatureCollection? | The current cluster being processed. |
| clusterValue | any? | Value used to create cluster being processed. |
| currentIndex | number? | The index of the current element being processed in the array. Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| geojson | any | |
| property | any | |
| callback | any | |
| initialValue | any |
npm install @turf/difference
removeEmptyPolygon
Detect Empty Polygon
Arguments
| Argument | Type | Description |
| geom | Geometry<(Polygon | MultiPolygon)> | Geometry Object |
Returns
(Geometry<(Polygon | MultiPolygon)> | undefined): removed any polygons with no areas
npm install @turf/line-offset
ab
https://github.com/rook2pawn/node-intersection
Author @rook2pawn
Arguments
| Argument | Type | Description |
| segment | any |
npm install @turf/meta
coordEachCallback
Callback for coordEach
Note: coordEachCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordEachCallback method.
Arguments
npm install @turf/meta
coordReduceCallback
Callback for coordReduce
The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.
If an initialValue is provided to the reduce method:
- The previousValue argument is initialValue.
- The currentValue argument is the value of the first element present in the array.
If an initialValue is not provided:
- The previousValue argument is the value of the first element present in the array.
- The currentValue argument is the value of the second element present in the array.
Note: coordReduceCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the coordReduceCallback method.
Arguments
| Argument | Type | Description |
| previousValue | any | The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. |
| currentCoord | Array<number> | The current coordinate being processed. |
| coordIndex | number | The index of the current element being processed in the array.Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| geojson | any | |
| callback | any | |
| initialValue | any | |
| excludeWrapCoord | any |
npm install @turf/meta
propEachCallback
Callback for propEach
Note: propEachCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the propEachCallback method.
Arguments
npm install @turf/meta
propReduceCallback
Callback for propReduce
The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.
If an initialValue is provided to the reduce method:
- The previousValue argument is initialValue.
- The currentValue argument is the value of the first element present in the array.
If an initialValue is not provided:
- The previousValue argument is the value of the first element present in the array.
- The currentValue argument is the value of the second element present in the array.
Note: propReduceCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the propReduceCallback method.
Arguments
| Argument | Type | Description |
| previousValue | any | The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. |
| currentProperties | any | The current properties being processed. |
| featureIndex | number | The index of the current element being processed in the array.Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| geojson | any | |
| callback | any | |
| initialValue | any |
npm install @turf/meta
featureEachCallback
Callback for featureEach
Note: featureEachCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the featureEachCallback method.
Arguments
npm install @turf/meta
featureReduceCallback
Callback for featureReduce
The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.
If an initialValue is provided to the reduce method:
- The previousValue argument is initialValue.
- The currentValue argument is the value of the first element present in the array.
If an initialValue is not provided:
- The previousValue argument is the value of the first element present in the array.
- The currentValue argument is the value of the second element present in the array.
Note: featureReduceCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the featureReduceCallback method.
Arguments
| Argument | Type | Description |
| previousValue | any | The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. |
| currentFeature | Feature | The current Feature being processed. |
| featureIndex | number | The index of the current element being processed in the array.Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| geojson | any | |
| callback | any | |
| initialValue | any |
npm install @turf/meta
geomEachCallback
Callback for geomEach
Note: geomEachCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the geomEachCallback method.
Arguments
| Argument | Type | Description |
| currentGeometry | Geometry | The current geometry being processed. |
| currentIndex | number | The index of the current element being processed in the array. Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| currentProperties | number | The current feature properties being processed. |
| geojson | any | |
| callback | any |
npm install @turf/meta
geomReduceCallback
Callback for geomReduce
The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.
If an initialValue is provided to the reduce method:
- The previousValue argument is initialValue.
- The currentValue argument is the value of the first element present in the array.
If an initialValue is not provided:
- The previousValue argument is the value of the first element present in the array.
- The currentValue argument is the value of the second element present in the array.
Note: geomReduceCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the geomReduceCallback method.
Arguments
| Argument | Type | Description |
| previousValue | any | The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. |
| currentGeometry | Geometry | The current Feature being processed. |
| currentIndex | number | The index of the current element being processed in the array.Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| currentProperties | Object | The current feature properties being processed. |
| geojson | any | |
| callback | any | |
| initialValue | any |
npm install @turf/meta
flattenEachCallback
Callback for flattenEach
Note: flattenEachCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the flattenEachCallback method.
Arguments
| Argument | Type | Description |
| currentFeature | Feature | The current flattened feature being processed. |
| featureIndex | number | The index of the current element being processed in the array. Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| featureSubIndex | number | The subindex of the current element being processed in the array. Starts at index 0 and increases if the flattened feature was a multi-geometry. |
| geojson | any | |
| callback | any |
npm install @turf/meta
flattenReduceCallback
Callback for flattenReduce
The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.
If an initialValue is provided to the reduce method:
- The previousValue argument is initialValue.
- The currentValue argument is the value of the first element present in the array.
If an initialValue is not provided:
- The previousValue argument is the value of the first element present in the array.
- The currentValue argument is the value of the second element present in the array.
Note: flattenReduceCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the flattenReduceCallback method.
Arguments
| Argument | Type | Description |
| previousValue | any | The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. |
| currentFeature | Feature | The current Feature being processed. |
| featureIndex | number | The index of the current element being processed in the array.Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| featureSubIndex | number | The subindex of the current element being processed in the array. Starts at index 0 and increases if the flattened feature was a multi-geometry. |
| geojson | any | |
| callback | any | |
| initialValue | any |
npm install @turf/meta
segmentEachCallback
Callback for segmentEach
Note: segmentEachCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the segmentEachCallback method.
Arguments
| Argument | Type | Description |
| currentSegment | Feature<LineString> | The current segment being processed. |
| featureIndex | number | The index of the current element being processed in the array, starts at index 0. |
| featureSubIndex | number | The subindex of the current element being processed in the array. Starts at index 0 and increases for each iterating line segment. |
| geojson | any | |
| callback | any |
Returns
void:
npm install @turf/meta
segmentReduceCallback
Callback for segmentReduce
The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.
If an initialValue is provided to the reduce method:
- The previousValue argument is initialValue.
- The currentValue argument is the value of the first element present in the array.
If an initialValue is not provided:
- The previousValue argument is the value of the first element present in the array.
- The currentValue argument is the value of the second element present in the array.
Note: segmentReduceCallback is part of the @turf/meta module. To use it directly you will need to import the @turf/meta and call the segmentReduceCallback method.
Arguments
| Argument | Type | Description |
| previousValue | any? | The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied. |
| currentSegment | Feature<LineString>? | The current segment being processed. |
| currentIndex | number? | The index of the current element being processed in the array. Starts at index 0, if an initialValue is provided, and at index 1 otherwise. |
| currentSubIndex | number? | The subindex of the current element being processed in the array. Starts at index 0 and increases for each iterating line segment. |
| geojson | any | |
| callback | any | |
| initialValue | any |