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 >}
of the 'property' values
Point
grid and returns a correspondent matrix {ArrayExample:
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];
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};
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
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:
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. |