Class DistanceUtils

java.lang.Object
org.locationtech.spatial4j.distance.DistanceUtils
public class DistanceUtils extends Object
Various distance calculations and constants. To the extent possible, a DistanceCalculator, retrieved from SpatialContext.getDistCalc() should be used in preference to calling these methods directly.

This code came from Apache Lucene, LUCENE-1387, which in turn came from "LocalLucene".

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    DEG_180_AS_RADS
     
    static final double
    DEG_225_AS_RADS
    Deprecated.
    static final double
    DEG_270_AS_RADS
    Deprecated.
    static final double
    DEG_45_AS_RADS
    Deprecated.
    static final double
    DEG_90_AS_RADS
     
    static final double
    DEG_TO_KM
    Equivalent to degrees2Dist(1, EARTH_MEAN_RADIUS_KM)
    static final double
    DEGREES_TO_RADIANS
     
    static final double
    EARTH_EQUATORIAL_RADIUS_KM
     
    static final double
    EARTH_EQUATORIAL_RADIUS_MI
     
    static final double
    EARTH_MEAN_RADIUS_KM
    The International Union of Geodesy and Geophysics says the Earth's mean radius in KM is: [1] http://en.wikipedia.org/wiki/Earth_radius
    static final double
    EARTH_MEAN_RADIUS_MI
     
    static final double
    KM_TO_DEG
     
    static final double
    KM_TO_MILES
     
    static final double
    MILES_TO_KM
     
    static final double
    RADIANS_TO_DEGREES
     
    static final double
    SIN_45_AS_RADS
    Deprecated.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    DistanceUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    calcBoxByDistFromPt_deltaLonDEG(double lat, double lon, double distDEG)
    The delta longitude of a point-distance.
    static double
    calcBoxByDistFromPt_latHorizAxisDEG(double lat, double lon, double distDEG)
    The latitude of the horizontal axis (e.g.
    static Rectangle
    calcBoxByDistFromPtDEG(double lat, double lon, double distDEG, SpatialContext ctx, Rectangle reuse)
    Calculates the bounding box of a circle, as specified by its center point and distance.
    static double
    calcLonDegreesAtLat(double lat, double dist)
    Calculates the degrees longitude distance at latitude lat to cover a distance dist.
    static double
    degrees2Dist(double degrees, double radius)
    Converts degrees (1/360th of circumference of a circle) into a distance as measured by the units of the radius.
    static double
    dist2Degrees(double dist, double radius)
    Converts a distance in the units of the radius to degrees (360 degrees are in a circle).
    static double
    dist2Radians(double dist, double radius)
    Converts a distance in the units of radius (e.g.
    static double
    distHaversineRAD(double lat1, double lon1, double lat2, double lon2)
     
    static double
    distLawOfCosinesRAD(double lat1, double lon1, double lat2, double lon2)
    Calculates the distance between two lat-lon's using the Law of Cosines.
    static double
    distSquaredCartesian(double[] vec1, double[] vec2)
    Deprecated.
    static double
    distVincentyRAD(double lat1, double lon1, double lat2, double lon2)
    Calculates the great circle distance using the Vincenty Formula, simplified for a spherical model.
    static double
    normLatDEG(double lat_deg)
    Puts in range -90 <= lat_deg <= 90.
    static double
    normLonDEG(double lon_deg)
    Puts in range -180 <= lon_deg <= +180.
    static Point
    pointOnBearingRAD(double startLat, double startLon, double distanceRAD, double bearingRAD, SpatialContext ctx, Point reuse)
    Given a start point (startLat, startLon), distance, and a bearing on a sphere, return the destination point.
    static double
    radians2Dist(double radians, double radius)
    Converts radians (multiples of the radius) to distance in the units of the radius (e.g.
    static double
    toDegrees(double radians)
    Same as Math.toDegrees(double) but 3x faster (multiply vs.
    static double
    toRadians(double degrees)
    Same as Math.toRadians(double) but 3x faster (multiply vs.
    static double[]
    vectorBoxCorner(double[] center, double[] result, double distance, boolean upperRight)
    Deprecated.
    static double
    vectorDistance(double[] vec1, double[] vec2, double power)
    Deprecated.
    static double
    vectorDistance(double[] vec1, double[] vec2, double power, double oneOverPower)
    Deprecated.

    Methods inherited from class Object

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

  • Field Details

  • Constructor Details

    • DistanceUtils

      private DistanceUtils()

  • Method Details

    • vectorDistance

      @Deprecated public static double vectorDistance(double[] vec1, double[] vec2, double power)
      Deprecated.
      Calculate the p-norm (i.e. length) between two vectors.

      See Lp space

      Parameters:
      vec1 - The first vector
      vec2 - The second vector
      power - The power (2 for cartesian distance, 1 for manhattan, etc.)
      Returns:
      The length.
      See Also:

    • vectorDistance

      @Deprecated public static double vectorDistance(double[] vec1, double[] vec2, double power, double oneOverPower)
      Deprecated.
      Calculate the p-norm (i.e. length) between two vectors.
      Parameters:
      vec1 - The first vector
      vec2 - The second vector
      power - The power (2 for cartesian distance, 1 for manhattan, etc.)
      oneOverPower - If you've pre-calculated oneOverPower and cached it, use this method to save one division operation over vectorDistance(double[], double[], double).
      Returns:
      The length.

    • vectorBoxCorner

      @Deprecated public static double[] vectorBoxCorner(double[] center, double[] result, double distance, boolean upperRight)
      Deprecated.
      Return the coordinates of a vector that is the corner of a box (upper right or lower left), assuming a Rectangular coordinate system. Note, this does not apply for points on a sphere or ellipse (although it could be used as an approximation).
      Parameters:
      center - The center point
      result - Holds the result, potentially resizing if needed.
      distance - The d from the center to the corner
      upperRight - If true, return the coords for the upper right corner, else return the lower left.
      Returns:
      The point, either the upperLeft or the lower right

    • pointOnBearingRAD

      public static Point pointOnBearingRAD(double startLat, double startLon, double distanceRAD, double bearingRAD, SpatialContext ctx, Point reuse)
      Given a start point (startLat, startLon), distance, and a bearing on a sphere, return the destination point.
      Parameters:
      startLat - The starting point latitude, in radians
      startLon - The starting point longitude, in radians
      distanceRAD - The distance to travel along the bearing in radians.
      bearingRAD - The bearing, in radians. North is a 0, moving clockwise till radians(360).
      reuse - A preallocated object to hold the results.
      Returns:
      The destination point, IN RADIANS.

    • normLonDEG

      public static double normLonDEG(double lon_deg)
      Puts in range -180 <= lon_deg <= +180.

    • normLatDEG

      public static double normLatDEG(double lat_deg)
      Puts in range -90 <= lat_deg <= 90.

    • calcBoxByDistFromPtDEG

      public static Rectangle calcBoxByDistFromPtDEG(double lat, double lon, double distDEG, SpatialContext ctx, Rectangle reuse)
      Calculates the bounding box of a circle, as specified by its center point and distance. reuse is an optional argument to store the results to avoid object creation.

    • calcBoxByDistFromPt_deltaLonDEG

      public static double calcBoxByDistFromPt_deltaLonDEG(double lat, double lon, double distDEG)
      The delta longitude of a point-distance. In other words, half the width of the bounding box of a circle.

    • calcBoxByDistFromPt_latHorizAxisDEG

      public static double calcBoxByDistFromPt_latHorizAxisDEG(double lat, double lon, double distDEG)
      The latitude of the horizontal axis (e.g. left-right line) of a circle. The horizontal axis of a circle passes through its furthest left-most and right-most edges. On a 2D plane, this result is always from.getY() but, perhaps surprisingly, on a sphere it is going to be slightly different.

    • calcLonDegreesAtLat

      public static double calcLonDegreesAtLat(double lat, double dist)
      Calculates the degrees longitude distance at latitude lat to cover a distance dist.

      Used to calculate a new expanded buffer distance to account for skewing effects for shapes that use the lat-lon space as a 2D plane instead of a sphere. The expanded buffer will be sure to cover the intended area, but the shape is still skewed and so it will cover a larger area. For latitude 0 (the equator) the result is the same buffer. At 60 (or -60) degrees, the result is twice the buffer, meaning that a shape at 60 degrees is twice as high as it is wide when projected onto a lat-lon plane even if in the real world it's equal all around.

      If the result added to abs(lat) is >= 90 degrees, then skewing is so severe that the caller should consider tossing the shape and substituting a spherical cap instead.

      Parameters:
      lat - latitude in degrees
      dist - distance in degrees
      Returns:
      longitudinal degrees (x delta) at input latitude that is >= dist distance. Will be >= dist and <= 90.

    • distSquaredCartesian

      @Deprecated public static double distSquaredCartesian(double[] vec1, double[] vec2)
      Deprecated.
      The square of the cartesian Distance. Not really a distance, but useful if all that matters is comparing the result to another one.
      Parameters:
      vec1 - The first point
      vec2 - The second point
      Returns:
      The squared cartesian distance

    • distHaversineRAD

      public static double distHaversineRAD(double lat1, double lon1, double lat2, double lon2)
      Parameters:
      lat1 - The y coordinate of the first point, in radians
      lon1 - The x coordinate of the first point, in radians
      lat2 - The y coordinate of the second point, in radians
      lon2 - The x coordinate of the second point, in radians
      Returns:
      The distance between the two points, as determined by the Haversine formula, in radians.

    • distLawOfCosinesRAD

      public static double distLawOfCosinesRAD(double lat1, double lon1, double lat2, double lon2)
      Calculates the distance between two lat-lon's using the Law of Cosines. Due to numeric conditioning errors, it is not as accurate as the Haversine formula for small distances. But with double precision, it isn't that bad -- allegedly 1 meter.

      See Why is law of cosines more preferable than haversine when calculating distance between two latitude-longitude points?

      The arguments and return value are in radians.

    • distVincentyRAD

      public static double distVincentyRAD(double lat1, double lon1, double lat2, double lon2)
      Calculates the great circle distance using the Vincenty Formula, simplified for a spherical model. This formula is accurate for any pair of points. The equation was taken from Wikipedia.

      The arguments are in radians, and the result is in radians.

    • dist2Degrees

      public static double dist2Degrees(double dist, double radius)
      Converts a distance in the units of the radius to degrees (360 degrees are in a circle). A spherical earth model is assumed.

    • degrees2Dist

      public static double degrees2Dist(double degrees, double radius)
      Converts degrees (1/360th of circumference of a circle) into a distance as measured by the units of the radius. A spherical earth model is assumed.

    • dist2Radians

      public static double dist2Radians(double dist, double radius)
      Converts a distance in the units of radius (e.g. kilometers) to radians (multiples of the radius). A spherical earth model is assumed.

    • radians2Dist

      public static double radians2Dist(double radians, double radius)
      Converts radians (multiples of the radius) to distance in the units of the radius (e.g. kilometers).

    • toRadians

      public static double toRadians(double degrees)
      Same as Math.toRadians(double) but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.

    • toDegrees

      public static double toDegrees(double radians)
      Same as Math.toDegrees(double) but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.