com.mapbox.turf

Class TurfMeasurement

java.lang.Object

com.mapbox.turf.TurfMeasurement

public final class TurfMeasurement
extends java.lang.Object

Class contains an assortment of methods used to calculate measurements such as bearing, destination, midpoint, etc.

Since:

1.2.0

See Also:

Turf documentation

Field Summary

Fields

Modifier and Type	Field and Description
static double	EARTH_RADIUS Earth's radius in meters.

Method Summary

Modifier and Type	Method and Description
static com.mapbox.geojson.Point	along(com.mapbox.geojson.LineString line, double distance, java.lang.String units) Takes a line and returns a point at a specified distance along the line.
static com.mapbox.geojson.Point	along(java.util.List<com.mapbox.geojson.Point> coords, double distance, java.lang.String units) Takes a list of points and returns a point at a specified distance along the line.
static double	area(com.mapbox.geojson.Feature feature) Takes one Feature and returns it's area in square meters.
static double	area(com.mapbox.geojson.FeatureCollection featureCollection) Takes one FeatureCollection and returns it's area in square meters.
static double	area(com.mapbox.geojson.Geometry geometry) Takes one Geometry and returns its area in square meters.
static double[]	bbox(com.mapbox.geojson.Feature feature) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.FeatureCollection featureCollection) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.GeoJson geoJson) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.Geometry geometry) Takes an arbitrary Geometry and calculates a bounding box.
static double[]	bbox(com.mapbox.geojson.LineString lineString) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.MultiLineString multiLineString) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.MultiPoint multiPoint) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.MultiPolygon multiPolygon) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.Point point) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static double[]	bbox(com.mapbox.geojson.Polygon polygon) Takes a set of features, calculates the bbox of all input features, and returns a bounding box.
static com.mapbox.geojson.Feature	bboxPolygon(com.mapbox.geojson.BoundingBox boundingBox) Takes a BoundingBox and uses its coordinates to create a Polygon geometry.
static com.mapbox.geojson.Feature	bboxPolygon(com.mapbox.geojson.BoundingBox boundingBox, com.google.gson.JsonObject properties, java.lang.String id) Takes a BoundingBox and uses its coordinates to create a Polygon geometry.
static com.mapbox.geojson.Feature	bboxPolygon(double[] bbox) Takes a bbox and uses its coordinates to create a Polygon geometry.
static com.mapbox.geojson.Feature	bboxPolygon(double[] bbox, com.google.gson.JsonObject properties, java.lang.String id) Takes a bbox and uses its coordinates to create a Polygon geometry.
static double	bearing(com.mapbox.geojson.Point point1, com.mapbox.geojson.Point point2) Takes two Points and finds the geographic bearing between them.
static com.mapbox.geojson.Feature	center(com.mapbox.geojson.Feature feature) Takes a Feature and returns the absolute center of the Feature.
static com.mapbox.geojson.Feature	center(com.mapbox.geojson.FeatureCollection featureCollection) Takes FeatureCollection and returns the absolute center of the Features in the FeatureCollection.
static com.mapbox.geojson.Feature	center(com.mapbox.geojson.FeatureCollection featureCollection, com.google.gson.JsonObject properties, java.lang.String id) Takes FeatureCollection and returns the absolute center of the Features in the FeatureCollection.
static com.mapbox.geojson.Feature	center(com.mapbox.geojson.Feature feature, com.google.gson.JsonObject properties, java.lang.String id) Takes a Feature and returns the absolute center of the Feature.
static com.mapbox.geojson.Point	destination(com.mapbox.geojson.Point point, double distance, double bearing, java.lang.String units) Takes a Point and calculates the location of a destination point given a distance in degrees, radians, miles, or kilometers; and bearing in degrees.
static double	distance(com.mapbox.geojson.Point point1, com.mapbox.geojson.Point point2) Calculates the distance between two points in kilometers.
static double	distance(com.mapbox.geojson.Point point1, com.mapbox.geojson.Point point2, java.lang.String units) Calculates the distance between two points in degress, radians, miles, or kilometers.
static com.mapbox.geojson.Polygon	envelope(com.mapbox.geojson.GeoJson geoJson) Takes any number of features and returns a rectangular Polygon that encompasses all vertices.
static double	length(com.mapbox.geojson.LineString lineString, java.lang.String units) Takes a LineString and measures its length in the specified units.
static double	length(java.util.List<com.mapbox.geojson.Point> coords, java.lang.String units) Takes a List of Point and measures its length in the specified units.
static double	length(com.mapbox.geojson.MultiLineString multiLineString, java.lang.String units) Takes a MultiLineString and measures its length in the specified units.
static double	length(com.mapbox.geojson.MultiPolygon multiPolygon, java.lang.String units) Takes a MultiPolygon and measures each polygons perimeter in the specified units.
static double	length(com.mapbox.geojson.Polygon polygon, java.lang.String units) Takes a Polygon and measures its perimeter in the specified units.
static com.mapbox.geojson.Point	midpoint(com.mapbox.geojson.Point from, com.mapbox.geojson.Point to) Takes two Points and returns a point midway between them.
static com.mapbox.geojson.BoundingBox	square(com.mapbox.geojson.BoundingBox boundingBox) Takes a bounding box and calculates the minimum square bounding box that would contain the input.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EARTH_RADIUS

public static double EARTH_RADIUS

Earth's radius in meters.

Method Detail

bearing

public static double bearing(@NonNull
                             com.mapbox.geojson.Point point1,
                             @NonNull
                             com.mapbox.geojson.Point point2)

Takes two Points and finds the geographic bearing between them.

Parameters:

point1 - first point used for calculating the bearing

point2 - second point used for calculating the bearing

Returns:

bearing in decimal degrees

Since:

1.3.0

See Also:

Turf Bearing documentation

destination

@NonNull
public static com.mapbox.geojson.Point destination(@NonNull
                                                            com.mapbox.geojson.Point point,
                                                            double distance,
                                                            double bearing,
                                                            @NonNull
                                                            java.lang.String units)

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.

Parameters:

point - starting point used for calculating the destination

distance - distance from the starting point

bearing - ranging from -180 to 180 in decimal degrees

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

destination Point result where you specified

Since:

1.2.0

See Also:

Turf Destination documetation

distance

public static double distance(@NonNull
                              com.mapbox.geojson.Point point1,
                              @NonNull
                              com.mapbox.geojson.Point point2)

Calculates the distance between two points in kilometers. This uses the Haversine formula to account for global curvature.

Parameters:

point1 - first point used for calculating the bearing

point2 - second point used for calculating the bearing

Returns:

distance between the two points in kilometers

Since:

1.2.0

See Also:

Turf distance documentation

distance

public static double distance(@NonNull
                              com.mapbox.geojson.Point point1,
                              @NonNull
                              com.mapbox.geojson.Point point2,
                              @NonNull
                              java.lang.String units)

Calculates the distance between two points in degress, radians, miles, or kilometers. This uses the Haversine formula to account for global curvature.

Parameters:

point1 - first point used for calculating the bearing

point2 - second point used for calculating the bearing

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

distance between the two points in kilometers

Since:

1.2.0

See Also:

Turf distance documentation

length

public static double length(@NonNull
                            com.mapbox.geojson.LineString lineString,
                            @NonNull
                            java.lang.String units)

Takes a LineString and measures its length in the specified units.

Parameters:

lineString - geometry to measure

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

length of the input line in the units specified

Since:

1.2.0

See Also:

Turf Line Distance documentation

length

public static double length(@NonNull
                            com.mapbox.geojson.MultiLineString multiLineString,
                            @NonNull
                            java.lang.String units)

Takes a MultiLineString and measures its length in the specified units.

Parameters:

multiLineString - geometry to measure

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

length of the input lines combined, in the units specified

Since:

1.2.0

See Also:

Turf Line Distance documentation

length

public static double length(@NonNull
                            com.mapbox.geojson.Polygon polygon,
                            @NonNull
                            java.lang.String units)

Takes a Polygon and measures its perimeter in the specified units. if the polygon contains holes, the perimeter will also be included.

Parameters:

polygon - geometry to measure

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

total perimeter of the input polygon in the units specified

Since:

1.2.0

See Also:

Turf Line Distance documentation

length

public static double length(@NonNull
                            com.mapbox.geojson.MultiPolygon multiPolygon,
                            @NonNull
                            java.lang.String units)

Takes a MultiPolygon and measures each polygons perimeter in the specified units. if one of the polygons contains holes, the perimeter will also be included.

Parameters:

multiPolygon - geometry to measure

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

total perimeter of the input polygons combined, in the units specified

Since:

1.2.0

See Also:

Turf Line Distance documentation

length

public static double length(java.util.List<com.mapbox.geojson.Point> coords,
                            java.lang.String units)

Takes a List of Point and measures its length in the specified units.

Parameters:

coords - geometry to measure

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

length of the input line in the units specified

Since:

5.2.0

See Also:

Turf Line Distance documentation

midpoint

public static com.mapbox.geojson.Point midpoint(@NonNull
                                                com.mapbox.geojson.Point from,
                                                @NonNull
                                                com.mapbox.geojson.Point to)

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.

Parameters:

from - first point used for calculating the midpoint

to - second point used for calculating the midpoint

Returns:

a Point midway between point1 and point2

Since:

1.3.0

See Also:

Turf Midpoint documentation

along

public static com.mapbox.geojson.Point along(@NonNull
                                             com.mapbox.geojson.LineString line,
                                             double distance,
                                             @NonNull
                                             java.lang.String units)

Takes a line and returns a point at a specified distance along the line.

Parameters:

line - that the point should be placed upon

distance - along the linestring geometry which the point should be placed on

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

a Point which is on the linestring provided and at the distance from the origin of that line to the end of the distance

Since:

1.3.0

along

public static com.mapbox.geojson.Point along(@NonNull
                                             java.util.List<com.mapbox.geojson.Point> coords,
                                             double distance,
                                             @NonNull
                                             java.lang.String units)

Takes a list of points and returns a point at a specified distance along the line.

Parameters:

coords - that the point should be placed upon

distance - along the linestring geometry which the point should be placed on

units - one of the units found inside TurfConstants.TurfUnitCriteria

Returns:

a Point which is on the linestring provided and at the distance from the origin of that line to the end of the distance

Since:

5.2.0

bbox

public static double[] bbox(@NonNull
                            com.mapbox.geojson.Point point)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

point - a Point object

Returns:

A double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

2.0.0

bbox

public static double[] bbox(@NonNull
                            com.mapbox.geojson.LineString lineString)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

lineString - a LineString object

Returns:

A double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

2.0.0

bbox

public static double[] bbox(@NonNull
                            com.mapbox.geojson.MultiPoint multiPoint)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

multiPoint - a MultiPoint object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

2.0.0

bbox

public static double[] bbox(@NonNull
                            com.mapbox.geojson.Polygon polygon)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

polygon - a Polygon object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

2.0.0

bbox

public static double[] bbox(@NonNull
                            com.mapbox.geojson.MultiLineString multiLineString)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

multiLineString - a MultiLineString object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

2.0.0

bbox

public static double[] bbox(com.mapbox.geojson.MultiPolygon multiPolygon)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

multiPolygon - a MultiPolygon object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

2.0.0

bbox

public static double[] bbox(com.mapbox.geojson.GeoJson geoJson)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

geoJson - a GeoJson object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

4.8.0

bbox

public static double[] bbox(com.mapbox.geojson.FeatureCollection featureCollection)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

featureCollection - a FeatureCollection object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

4.8.0

bbox

public static double[] bbox(com.mapbox.geojson.Feature feature)

Takes a set of features, calculates the bbox of all input features, and returns a bounding box.

Parameters:

feature - a Feature object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

4.8.0

bbox

public static double[] bbox(com.mapbox.geojson.Geometry geometry)

Takes an arbitrary Geometry and calculates a bounding box.

Parameters:

geometry - a Geometry object

Returns:

a double array defining the bounding box in this order [minX, minY, maxX, maxY]

Since:

2.0.0

bboxPolygon

public static com.mapbox.geojson.Feature bboxPolygon(@NonNull
                                                     com.mapbox.geojson.BoundingBox boundingBox)

Takes a BoundingBox and uses its coordinates to create a Polygon geometry.

Parameters:

boundingBox - a BoundingBox object to calculate with

Returns:

a Feature object

Since:

4.9.0

See Also:

Turf BoundingBox Polygon documentation

bboxPolygon

public static com.mapbox.geojson.Feature bboxPolygon(@NonNull
                                                     com.mapbox.geojson.BoundingBox boundingBox,
                                                     @Nullable
                                                     com.google.gson.JsonObject properties,
                                                     @Nullable
                                                     java.lang.String id)

Takes a BoundingBox and uses its coordinates to create a Polygon geometry.

Parameters:

boundingBox - a BoundingBox object to calculate with

properties - a JsonObject containing the feature properties

id - common identifier of this feature

Returns:

a Feature object

Since:

4.9.0

See Also:

Turf BoundingBox Polygon documentation

bboxPolygon

public static com.mapbox.geojson.Feature bboxPolygon(@NonNull
                                                     double[] bbox)

Takes a bbox and uses its coordinates to create a Polygon geometry.

Parameters:

bbox - a double[] object to calculate with

Returns:

a Feature object

Since:

4.9.0

See Also:

Turf BoundingBox Polygon documentation

bboxPolygon

public static com.mapbox.geojson.Feature bboxPolygon(@NonNull
                                                     double[] bbox,
                                                     @Nullable
                                                     com.google.gson.JsonObject properties,
                                                     @Nullable
                                                     java.lang.String id)

Takes a bbox and uses its coordinates to create a Polygon geometry.

Parameters:

bbox - a double[] object to calculate with

properties - a JsonObject containing the feature properties

id - common identifier of this feature

Returns:

a Feature object

Since:

4.9.0

See Also:

Turf BoundingBox Polygon documentation

envelope

public static com.mapbox.geojson.Polygon envelope(com.mapbox.geojson.GeoJson geoJson)

Takes any number of features and returns a rectangular Polygon that encompasses all vertices.

Parameters:

geoJson - input features

Returns:

a rectangular Polygon feature that encompasses all vertices

Since:

4.9.0

square

public static com.mapbox.geojson.BoundingBox square(@NonNull
                                                    com.mapbox.geojson.BoundingBox boundingBox)

Takes a bounding box and calculates the minimum square bounding box that would contain the input.

Parameters:

boundingBox - extent in west, south, east, north order

Returns:

a square surrounding bbox

Since:

4.9.0

area

public static double area(@NonNull
                          com.mapbox.geojson.Feature feature)

Takes one Feature and returns it's area in square meters.

Parameters:

feature - input Feature

Returns:

area in square meters

Since:

4.10.0

area

public static double area(@NonNull
                          com.mapbox.geojson.FeatureCollection featureCollection)

Takes one FeatureCollection and returns it's area in square meters.

Parameters:

featureCollection - input FeatureCollection

Returns:

area in square meters

Since:

4.10.0

area

public static double area(@NonNull
                          com.mapbox.geojson.Geometry geometry)

Takes one Geometry and returns its area in square meters.

Parameters:

geometry - input Geometry

Returns:

area in square meters

Since:

4.10.0

center

public static com.mapbox.geojson.Feature center(com.mapbox.geojson.Feature feature,
                                                @Nullable
                                                com.google.gson.JsonObject properties,
                                                @Nullable
                                                java.lang.String id)

Takes a Feature and returns the absolute center of the Feature.

Parameters:

feature - the single Feature to find the center of.

properties - a optional JsonObject containing the properties that should be placed in the returned Feature.

id - an optional common identifier that should be placed in the returned Feature.

Returns:

a Feature with a Point geometry type.

Since:

5.3.0

center

public static com.mapbox.geojson.Feature center(com.mapbox.geojson.Feature feature)

Takes a Feature and returns the absolute center of the Feature.

Parameters:

feature - the single Feature to find the center of.

Returns:

a Feature with a Point geometry type.

Since:

5.3.0

center

public static com.mapbox.geojson.Feature center(com.mapbox.geojson.FeatureCollection featureCollection,
                                                @Nullable
                                                com.google.gson.JsonObject properties,
                                                @Nullable
                                                java.lang.String id)

Takes FeatureCollection and returns the absolute center of the Features in the FeatureCollection.

Parameters:

featureCollection - the single FeatureCollection to find the center of.

properties - a optional JsonObject containing the properties that should be placed in the returned Feature.

id - an optional common identifier that should be placed in the returned Feature.

Returns:

a Feature with a Point geometry type.

Since:

5.3.0

center

public static com.mapbox.geojson.Feature center(com.mapbox.geojson.FeatureCollection featureCollection)

Takes FeatureCollection and returns the absolute center of the Features in the FeatureCollection.

Parameters:

featureCollection - the single FeatureCollection to find the center of.

Returns:

a Feature with a Point geometry type.

Since:

5.3.0