simplepolygon

simplepolygon(feature)FeatureCollection

Takes a complex (i.e. self-intersecting) geojson polygon, and breaks it down into its composite simple, non-self-intersecting one-ring polygons.
Name Type Description
feature Feature Input polygon. This polygon may be unconform the Simple Features standard in the sense that it's inner and outer rings may cross-intersect or self-intersect, that the outer ring must not contain the optional inner rings and that the winding number must not be positive for the outer and negative for the inner rings.
Returns:
Feature collection containing the simple, non-self-intersecting one-ring polygon features that the complex polygon is composed of. These simple polygons have properties such as their parent polygon, winding number and net winding number.
Example:
var poly = {
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[0,0],[2,0],[0,2],[2,2],[0,0]]]
  }
};

var result = simplepolygon(poly);

// =result
// which will be a featureCollection of two polygons, one with coordinates [[[0,0],[2,0],[1,1],[0,0]]], parent -1, winding 1 and net winding 1, and one with coordinates [[[1,1],[0,2],[2,2],[1,1]]], parent -1, winding -1 and net winding -1

Members

Takes a Feature and a bbox and clips the feature to the bbox using [lineclip](https://github.com/mapbox/lineclip). May result in degenerate edges when clipping Polygons.
Example:
var bbox = [0, 0, 10, 10];
var poly = turfEx.polygon([[[2, 2], [8, 4], [12, 8], [3, 7], [2, 2]]]);

var clipped = turfEx.bboxClip(poly, bbox);

//addToMap
var addToMap = [bbox, poly, clipped]
Takes a ring and return true or false whether or not the ring is clockwise or counter-clockwise.
Example:
var clockwiseRing = turfEx.lineString([[0,0],[1,1],[1,0],[0,0]]);
var counterClockwiseRing = turfEx.lineString([[0,0],[1,0],[1,1],[0,0]]);

turfEx.booleanClockwise(clockwiseRing)
//=true
turfEx.booleanClockwise(counterClockwiseRing)
//=false
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 `@turfEx/boolean-within`.
Example:
var line = turfEx.lineString([[1, 1], [1, 2], [1, 3], [1, 4]]);
var point = turfEx.point([1, 2]);

turfEx.booleanContains(line, point);
//=true
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.
Example:
var line1 = turfEx.lineString([[-2, 2], [4, 2]]);
var line2 = turfEx.lineString([[1, 1], [1, 2], [1, 3], [1, 4]]);

var cross = turfEx.booleanCrosses(line1, line2);
//=true
Boolean-disjoint returns (TRUE) if the intersection of the two geometries is an empty set.
Example:
var point = turfEx.point([2, 2]);
var line = turfEx.lineString([[1, 1], [1, 2], [1, 3], [1, 4]]);

turfEx.booleanDisjoint(line, point);
//=true
Determine whether two geometries of the same type have identical X,Y coordinate values. See http://edndoc.esri.com/arcsde/9.0/general_topics/understand_spatial_relations.htm
Example:
var pt1 = turfEx.point([0, 0]);
var pt2 = turfEx.point([0, 0]);
var pt3 = turfEx.point([1, 1]);

turfEx.booleanEqual(pt1, pt2);
//= true
turfEx.booleanEqual(pt2, pt3);
//= false
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.
Example:
var poly1 = turfEx.polygon([[[0,0],[0,5],[5,5],[5,0],[0,0]]]);
var poly2 = turfEx.polygon([[[1,1],[1,6],[6,6],[6,1],[1,1]]]);
var poly3 = turfEx.polygon([[[10,10],[10,15],[15,15],[15,10],[10,10]]]);

turfEx.booleanOverlap(poly1, poly2)
//=true
turfEx.booleanOverlap(poly2, poly3)
//=false
Boolean-Parallel returns True if each segment of `line1` is parallel to the correspondent segment of `line2`
Example:
var line1 = turfEx.lineString([[0, 0], [0, 1]]);
var line2 = turfEx.lineString([[1, 0], [1, 1]]);

turfEx.booleanParallel(line1, line2);
//=true
Takes a Feature or FeatureCollection and returns the mean center. Can be weighted.
Example:
var features = turfEx.featureCollection([
  turfEx.point([-97.522259, 35.4691], {weight: 10}),
  turfEx.point([-97.502754, 35.463455], {weight: 3}),
  turfEx.point([-97.508269, 35.463245], {weight: 5})
]);

var options = {weight: "weight"}
var mean = turfEx.centerMean(features, options);

//addToMap
var addToMap = [features, mean]
mean.properties['marker-size'] = 'large';
mean.properties['marker-color'] = '#000';
Takes a FeatureCollection of points and calculates the median center, algorithimically. The median center is understood as the point that is requires the least total travel from all other points. turfExjs has four different functions for calculating the center of a set of data. Each is useful depending on circumstance. `@turfEx/center` finds the simple center of a dataset, by finding the midpoint between the extents of the data. That is, it divides in half the farthest east and farthest west point as well as the farthest north and farthest south. `@turfEx/center-of-mass` imagines that the dataset is a sheet of paper. The center of mass is where the sheet would balance on a fingertip. `@turfEx/center-mean` takes the averages of all the coordinates and produces a value that respects that. Unlike `@turfEx/center`, it is sensitive to clusters and outliers. It lands in the statistical middle of a dataset, not the geographical. It can also be weighted, meaning certain points are more important than others. `@turfEx/center-median` takes the mean center and tries to find, iteratively, a new point that requires the least amount of travel from all the points in the dataset. It is not as sensitive to outliers as `@turfEx/center`, but it is attracted to clustered data. It, too, can be weighted. **Bibliography** Harold W. Kuhn and Robert E. Kuenne, “An Efficient Algorithm for the Numerical Solution of the Generalized Weber Problem in Spatial Economics,” _Journal of Regional Science_ 4, no. 2 (1962): 21–33, doi:https://doi.org/10.1111/j.1467-9787.1962.tb00902.x. James E. Burt, Gerald M. Barber, and David L. Rigby, _Elementary Statistics for Geographers_, 3rd ed., New York: The Guilford Press, 2009, 150–151.
Example:
var points = turfEx.points([[0, 0], [1, 0], [0, 1], [5, 8]]);
var medianCenter = turfEx.centerMedian(points);

//addToMap
var addToMap = [points, medianCenter]
clusterEach
Example:
var geojson = turfEx.featureCollection([
    turfEx.point([0, 0]),
    turfEx.point([2, 4]),
    turfEx.point([3, 6]),
    turfEx.point([5, 1]),
    turfEx.point([4, 2])
]);

// Create a cluster using K-Means (adds `cluster` to GeoJSON properties)
var clustered = turfEx.clustersKmeans(geojson);

// Iterate over each cluster
turfEx.clusterEach(clustered, 'cluster', function (cluster, clusterValue, currentIndex) {
    //= cluster
    //= clusterValue
    //= currentIndex
})

// Calculate the total number of clusters
var total = 0
turfEx.clusterEach(clustered, 'cluster', function () {
    total++;
});

// Create an Array of all the values retrieved from the 'cluster' property
var values = []
turfEx.clusterEach(clustered, 'cluster', function (cluster, clusterValue) {
    values.push(clusterValue);
});
Reduce clusters in GeoJSON Features, similar to Array.reduce()
Example:
var geojson = turfEx.featureCollection([
    turfEx.point([0, 0]),
    turfEx.point([2, 4]),
    turfEx.point([3, 6]),
    turfEx.point([5, 1]),
    turfEx.point([4, 2])
]);

// Create a cluster using K-Means (adds `cluster` to GeoJSON properties)
var clustered = turfEx.clustersKmeans(geojson);

// Iterate over each cluster and perform a calculation
var initialValue = 0
turfEx.clusterReduce(clustered, 'cluster', function (previousValue, cluster, clusterValue, currentIndex) {
    //=previousValue
    //=cluster
    //=clusterValue
    //=currentIndex
    return previousValue++;
}, initialValue);

// Calculate the total number of clusters
var total = turfEx.clusterReduce(clustered, 'cluster', function (previousValue) {
    return previousValue++;
}, 0);

// Create an Array of all the values retrieved from the 'cluster' property
var values = turfEx.clusterReduce(clustered, 'cluster', function (previousValue, cluster, clusterValue) {
    return previousValue.concat(clusterValue);
}, []);
Takes a set of points and partition them into clusters according to https://en.wikipedia.org/wiki/DBSCAN data clustering algorithm.
Example:
// create random points with random z-values in their properties
var points = turfEx.randomPoint(100, {bbox: [0, 30, 20, 50]});
var maxDistance = 100;
var clustered = turfEx.clustersDbscan(points, maxDistance);

//addToMap
var addToMap = [clustered];
Takes a set of points and partition them into clusters using the k-mean . It uses the [k-means algorithm](https://en.wikipedia.org/wiki/K-means_clustering)
Example:
// create random points with random z-values in their properties
var points = turfEx.randomPoint(100, {bbox: [0, 30, 20, 50]});
var options = {numberOfClusters: 7};
var clustered = turfEx.clustersKmeans(points, options);

//addToMap
var addToMap = [clustered];
Get Cluster
Example:
var geojson = turfEx.featureCollection([
    turfEx.point([0, 0], {'marker-symbol': 'circle'}),
    turfEx.point([2, 4], {'marker-symbol': 'star'}),
    turfEx.point([3, 6], {'marker-symbol': 'star'}),
    turfEx.point([5, 1], {'marker-symbol': 'square'}),
    turfEx.point([4, 2], {'marker-symbol': 'circle'})
]);

// Create a cluster using K-Means (adds `cluster` to GeoJSON properties)
var clustered = turfEx.clustersKmeans(geojson);

// Retrieve first cluster (0)
var cluster = turfEx.getCluster(clustered, {cluster: 0});
//= cluster

// Retrieve cluster based on custom properties
turfEx.getCluster(clustered, {'marker-symbol': 'circle'}).length;
//= 2
turfEx.getCluster(clustered, {'marker-symbol': 'square'}).length;
//= 1
Calculate great circles routes as LineString
Example:
var start = turfEx.point([-122, 48]);
var end = turfEx.point([-77, 39]);

var greatCircle = turfEx.greatCircle(start, end, {'name': 'Seattle to DC'});

//addToMap
var addToMap = [start, end, greatCircle]
Takes a Point grid and returns a correspondent matrix {Array>} of the 'property' values
Example:
var extent = [-70.823364, -33.553984, -70.473175, -33.302986];
  var cellSize = 3;
  var grid = turfEx.pointGrid(extent, cellSize);
  // add a random property to each point between 0 and 60
  for (var i = 0; i < grid.features.length; i++) {
    grid.features[i].properties.elevation = (Math.random() * 60);
  }
  gridToMatrix(grid);
  //= [
    [ 1, 13, 10,  9, 10, 13, 18],
    [34,  8,  5,  4,  5,  8, 13],
    [10,  5,  2,  1,  2,  5,  4],
    [ 0,  4, 56, 19,  1,  4,  9],
    [10,  5,  2,  1,  2,  5, 10],
    [57,  8,  5,  4,  5,  0, 57],
    [ 3, 13, 10,  9,  5, 13, 18],
    [18, 13, 10,  9, 78, 13, 18]
  ]
Takes a grid FeatureCollection of Point features with z-values and an array of value breaks and generates filled contour isobands.
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.
Example:
var center = turfEx.point([-75, 40]);
var radius = 5;
var bearing1 = 25;
var bearing2 = 47;

var arc = turfEx.lineArc(center, radius, bearing1, bearing2);

//addToMap
var addToMap = [center, arc]
Takes a line and returns a line at offset by the specified distance.
Example:
var line = turfEx.lineString([[-83, 30], [-84, 36], [-78, 41]], { "stroke": "#F00" });

var offsetLine = turfEx.lineOffset(line, 2, {units: 'miles'});

//addToMap
var addToMap = [offsetLine, line]
offsetLine.properties.stroke = "#00F"
Takes any LineString or Polygon and returns the overlapping lines between both features.
Example:
var line1 = turfEx.lineString([[115, -35], [125, -30], [135, -30], [145, -35]]);
var line2 = turfEx.lineString([[115, -25], [125, -30], [135, -30], [145, -25]]);

var overlapping = turfEx.lineOverlap(line1, line2);

//addToMap
var addToMap = [line1, line2, overlapping]
Split a LineString by another GeoJSON Feature.
Example:
var line = turfEx.lineString([[120, -25], [145, -25]]);
var splitter = turfEx.lineString([[130, -15], [130, -35]]);

var split = turfEx.lineSplit(line, splitter);

//addToMap
var addToMap = [line, splitter]
Converts (Multi)LineString(s) to Polygon(s).
Example:
var line = turfEx.lineString([[125, -30], [145, -30], [145, -20], [125, -20], [125, -30]]);

var polygon = turfEx.lineToPolygon(line);

//addToMap
var addToMap = [polygon];
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.
Finds the tangents of a (Multi)Polygon from a Point.
Example:
var polygon = turfEx.polygon([[[11, 0], [22, 4], [31, 0], [31, 11], [21, 15], [11, 11], [11, 0]]]);
var point = turfEx.point([61, 5]);

var tangents = turfEx.polygonTangents(point, polygon)

//addToMap
var addToMap = [tangents, point, polygon];
Converts a Polygon to (Multi)LineString or MultiPolygon to a FeatureCollection of (Multi)LineString.
Example:
var poly = turfEx.polygon([[[125, -30], [145, -30], [145, -20], [125, -20], [125, -30]]]);

var line = turfEx.polygonToLine(poly);

//addToMap
var addToMap = [line];
Returns a random linestring.
Example:
var lineStrings = turfEx.randomLineString(25, {bbox: [-180, -90, 180, 90]})
//=lineStrings
Returns a random point.
Example:
var points = turfEx.randomPoint(25, {bbox: [-180, -90, 180, 90]})
//=points
Returns a random polygon.
Example:
var polygons = turfEx.randomPolygon(25, {bbox: [-180, -90, 180, 90]})
//=polygons
Returns a random position within a box.
Example:
var position = turfEx.randomPosition([-180, -90, 180, 90])
//=position
Rewind (Multi)LineString or (Multi)Polygon outer ring counterclockwise and inner rings clockwise (Uses Shoelace Formula).
Example:
var polygon = turfEx.polygon([[[121, -29], [138, -29], [138, -18], [121, -18], [121, -29]]]);

var rewind = turfEx.rewind(polygon);

//addToMap
var addToMap = [rewind];
Returns the destination Point having travelled the given distance along a Rhumb line from the origin Point with the (varant) given bearing.
Example:
var pt = turfEx.point([-75.343, 39.984], {"marker-color": "F00"});
var distance = 50;
var bearing = 90;
var options = {units: 'miles'};

var destination = turfEx.rhumbDestination(pt, distance, bearing, options);

//addToMap
var addToMap = [pt, destination]
destination.properties['marker-color'] = '#00F';
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.
Example:
var center = turfEx.point([-75, 40]);
var radius = 5;
var bearing1 = 25;
var bearing2 = 45;

var sector = turfEx.sector(center, radius, bearing1, bearing2);

//addToMap
var addToMap = [center, sector];
Returns the shortest path from start to end without colliding with any Feature in FeatureCollection.<Polygon>
Example:
var start = [-5, -6];
var end = [9, -6];
var options = {
  obstacles: turfEx.polygon([[[0, -7], [5, -7], [5, -3], [0, -3], [0, -7]]])
};

var path = turfEx.shortestPath(start, end, options);

//addToMap
var addToMap = [start, end, options.obstacles, path];

innerstandardDeviationalEllipse

Takes a FeatureCollection and returns a standard deviational ellipse, also known as a “directional distribution.” The standard deviational ellipse aims to show the direction and the distribution of a dataset by drawing an ellipse that contains about one standard deviation’s worth (~ 70%) of the data. This module mirrors the functionality of [Directional Distribution](http://desktop.arcgis.com/en/arcmap/10.3/tools/spatial-statistics-toolbox/directional-distribution.htm) in ArcGIS and the [QGIS Standard Deviational Ellipse Plugin](http://arken.nmbu.no/~havatv/gis/qgisplugins/SDEllipse/) **Bibliography** • Robert S. Yuill, “The Standard Deviational Ellipse; An Updated Tool for Spatial Description,” _Geografiska Annaler_ 53, no. 1 (1971): 28–39, doi:10.2307/490885. • Paul Hanly Furfey, “A Note on Lefever’s “Standard Deviational Ellipse,” _American Journal of Sociology_ 33, no. 1 (1927): 94—98, doi:10.1086/214336.
Example:
var bbox = [-74, 40.72, -73.98, 40.74];
var points = turfEx.randomPoint(400, {bbox: bbox});
var sdEllipse = turfEx.standardDeviationalEllipse(points);

//addToMap
var addToMap = [points, sdEllipse];
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
Example:
var poly = turfEx.polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]);
var options = {pivot: [0, 25]};
var rotatedPoly = turfEx.transformRotate(poly, 10, options);

//addToMap
var addToMap = [poly, rotatedPoly];
rotatedPoly.properties = {stroke: '#F00', 'stroke-width': 4};
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.
Example:
var poly = turfEx.polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]);
var scaledPoly = turfEx.transformScale(poly, 3);

//addToMap
var addToMap = [poly, scaledPoly];
scaledPoly.properties = {stroke: '#F00', 'stroke-width': 4};

innertransformTranslate

Moves any geojson Feature or Geometry of a specified distance along a Rhumb Line on the provided direction angle.
Example:
var poly = turfEx.polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]);
var translatedPoly = turfEx.transformTranslate(poly, 100, 35);

//addToMap
var addToMap = [poly, translatedPoly];
translatedPoly.properties = {stroke: '#F00', 'stroke-width': 4};
Takes a kinked polygon and returns a feature collection of polygons that have no kinks. Uses [simplepolygon](https://github.com/mclaeysb/simplepolygon) internally.
Example:
var poly = turfEx.polygon([[[0, 0], [2, 0], [0, 2], [2, 2], [0, 0]]]);

var result = turfEx.unkinkPolygon(poly);

//addToMap
var addToMap = [poly, result]
Takes a FeatureCollection of points, and a bounding box, and returns a FeatureCollection of Voronoi polygons. The Voronoi algorithim used comes from the d3-voronoi package.
Example:
var options = {
  bbox: [-70, 40, -60, 60]
};
var points = turfEx.randomPoint(100, options);
var voronoiPolygons = turfEx.voronoi(points, options);

//addToMap
var addToMap = [voronoiPolygons, points];

Type Definitions

clusterEachCallback(cluster, clusterValue, currentIndex)void

Callback for clusterEach
Name Type Description
cluster FeatureCollection optional The current cluster being processed.
clusterValue * optional Value used to create cluster being processed.
currentIndex number optional The index of the current element being processed in the array.Starts at index 0
Returns:

clusterReduceCallback(previousValue, cluster, clusterValue, currentIndex)

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.
Name Type Description
previousValue * optional The accumulated value previously returned in the last invocation of the callback, or initialValue, if supplied.
cluster FeatureCollection optional The current cluster being processed.
clusterValue * optional Value used to create cluster being processed.
currentIndex number optional 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.