Package com.mapbox.turf

Class TurfMeasurement

java.lang.Object
com.mapbox.turf.TurfMeasurement
public final class TurfMeasurement extends Object
Class contains an assortment of methods used to calculate measurements such as bearing, destination, midpoint, etc.
Since:
1.2.0
See Also:

  • Field Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    static com.mapbox.geojson.Point
    along(com.mapbox.geojson.LineString line, double distance, String units)
    Takes a line and returns a point at a specified distance along the line.
    static com.mapbox.geojson.Point
    along(List<com.mapbox.geojson.Point> coords, double distance, 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(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, String id)
    Takes a bbox and uses its coordinates to create a Polygon geometry.
    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, String id)
    Takes a BoundingBox 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, 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, 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, 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, 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, String units)
    Takes a LineString and measures its length in the specified units.
    static double
    length(com.mapbox.geojson.MultiLineString multiLineString, String units)
    Takes a MultiLineString and measures its length in the specified units.
    static double
    length(com.mapbox.geojson.MultiPolygon multiPolygon, String units)
    Takes a MultiPolygon and measures each polygons perimeter in the specified units.
    static double
    length(com.mapbox.geojson.Polygon polygon, String units)
    Takes a Polygon and measures its perimeter in the specified units.
    static double
    length(List<com.mapbox.geojson.Point> coords, String units)
    Takes a List of Point and measures its length 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 Details

    • EARTH_RADIUS

      public static double EARTH_RADIUS
      Earth's radius in meters.

  • Method Details

    • 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:

    • destination

      @NonNull public static com.mapbox.geojson.Point destination(@NonNull com.mapbox.geojson.Point point, double distance, double bearing, @NonNull 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:

    • 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:

    • distance

      public static double distance(@NonNull com.mapbox.geojson.Point point1, @NonNull com.mapbox.geojson.Point point2, @NonNull 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:

    • length

      public static double length(@NonNull com.mapbox.geojson.LineString lineString, @NonNull 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:

    • length

      public static double length(@NonNull com.mapbox.geojson.MultiLineString multiLineString, @NonNull 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:

    • length

      public static double length(@NonNull com.mapbox.geojson.Polygon polygon, @NonNull 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:

    • length

      public static double length(@NonNull com.mapbox.geojson.MultiPolygon multiPolygon, @NonNull 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:

    • length

      public static double length(List<com.mapbox.geojson.Point> coords, 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:

    • 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:

    • along

      public static com.mapbox.geojson.Point along(@NonNull com.mapbox.geojson.LineString line, double distance, @NonNull 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 List<com.mapbox.geojson.Point> coords, double distance, @NonNull 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:

    • bboxPolygon

      public static com.mapbox.geojson.Feature bboxPolygon(@NonNull com.mapbox.geojson.BoundingBox boundingBox, @Nullable com.google.gson.JsonObject properties, @Nullable 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:

    • 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:

    • bboxPolygon

      public static com.mapbox.geojson.Feature bboxPolygon(@NonNull double[] bbox, @Nullable com.google.gson.JsonObject properties, @Nullable 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:

    • 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 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 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