ai.nextbillion.kits.turf

Class TurfMeasurement

java.lang.Object

ai.nextbillion.kits.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.

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

See Also:

Turf Bearing documentation

destination

@NonNull
public static ai.nextbillion.kits.geojson.Point destination(@NonNull
                                                                     ai.nextbillion.kits.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

See Also:

Turf Destination documetation

distance

public static double distance(@NonNull
                              ai.nextbillion.kits.geojson.Point point1,
                              @NonNull
                              ai.nextbillion.kits.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

See Also:

Turf distance documentation

distance

public static double distance(@NonNull
                              ai.nextbillion.kits.geojson.Point point1,
                              @NonNull
                              ai.nextbillion.kits.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

See Also:

Turf distance documentation

length

public static double length(@NonNull
                            ai.nextbillion.kits.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

See Also:

Turf Line Distance documentation

length

public static double length(@NonNull
                            ai.nextbillion.kits.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

See Also:

Turf Line Distance documentation

length

public static double length(@NonNull
                            ai.nextbillion.kits.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

See Also:

Turf Line Distance documentation

length

public static double length(@NonNull
                            ai.nextbillion.kits.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

See Also:

Turf Line Distance documentation

length

public static double length(java.util.List<ai.nextbillion.kits.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

See Also:

Turf Line Distance documentation

midpoint

public static ai.nextbillion.kits.geojson.Point midpoint(@NonNull
                                                         ai.nextbillion.kits.geojson.Point from,
                                                         @NonNull
                                                         ai.nextbillion.kits.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

See Also:

Turf Midpoint documentation

along

public static ai.nextbillion.kits.geojson.Point along(@NonNull
                                                      ai.nextbillion.kits.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

along

public static ai.nextbillion.kits.geojson.Point along(@NonNull
                                                      java.util.List<ai.nextbillion.kits.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

bbox

public static double[] bbox(@NonNull
                            ai.nextbillion.kits.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]

bbox

public static double[] bbox(@NonNull
                            ai.nextbillion.kits.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]

bbox

public static double[] bbox(@NonNull
                            ai.nextbillion.kits.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]

bbox

public static double[] bbox(@NonNull
                            ai.nextbillion.kits.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]

bbox

public static double[] bbox(@NonNull
                            ai.nextbillion.kits.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]

bbox

public static double[] bbox(ai.nextbillion.kits.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]

bbox

public static double[] bbox(ai.nextbillion.kits.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]

bbox

public static double[] bbox(ai.nextbillion.kits.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]

bbox

public static double[] bbox(ai.nextbillion.kits.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]

bbox

public static double[] bbox(ai.nextbillion.kits.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]

bboxPolygon

public static ai.nextbillion.kits.geojson.Feature bboxPolygon(@NonNull
                                                              ai.nextbillion.kits.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

See Also:

Turf BoundingBox Polygon documentation

bboxPolygon

public static ai.nextbillion.kits.geojson.Feature bboxPolygon(@NonNull
                                                              ai.nextbillion.kits.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

See Also:

Turf BoundingBox Polygon documentation

bboxPolygon

public static ai.nextbillion.kits.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

See Also:

Turf BoundingBox Polygon documentation

bboxPolygon

public static ai.nextbillion.kits.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

See Also:

Turf BoundingBox Polygon documentation

envelope

public static ai.nextbillion.kits.geojson.Polygon envelope(ai.nextbillion.kits.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

square

public static ai.nextbillion.kits.geojson.BoundingBox square(@NonNull
                                                             ai.nextbillion.kits.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

area

public static double area(@NonNull
                          ai.nextbillion.kits.geojson.Feature feature)

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

Parameters:

feature - input Feature

Returns:

area in square meters

area

public static double area(@NonNull
                          ai.nextbillion.kits.geojson.FeatureCollection featureCollection)

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

Parameters:

featureCollection - input FeatureCollection

Returns:

area in square meters

area

public static double area(@NonNull
                          ai.nextbillion.kits.geojson.Geometry geometry)

Takes one Geometry and returns its area in square meters.

Parameters:

geometry - input Geometry

Returns:

area in square meters

center

public static ai.nextbillion.kits.geojson.Feature center(ai.nextbillion.kits.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.

center

public static ai.nextbillion.kits.geojson.Feature center(ai.nextbillion.kits.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.

center

public static ai.nextbillion.kits.geojson.Feature center(ai.nextbillion.kits.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.

center

public static ai.nextbillion.kits.geojson.Feature center(ai.nextbillion.kits.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.