DistanceUtils (Spatial4J 0.5 API)

java.lang.Object
- com.spatial4j.core.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 and Description
`static double`	`DEG_180_AS_RADS`
`static double`	`DEG_225_AS_RADS` Deprecated.
`static double`	`DEG_270_AS_RADS` Deprecated.
`static double`	`DEG_45_AS_RADS` Deprecated.
`static double`	`DEG_90_AS_RADS`
`static double`	`DEG_TO_KM` Equivalent to degrees2Dist(1, EARTH_MEAN_RADIUS_KM)
`static double`	`DEGREES_TO_RADIANS`
`static double`	`EARTH_EQUATORIAL_RADIUS_KM`
`static double`	`EARTH_EQUATORIAL_RADIUS_MI`
`static 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 double`	`EARTH_MEAN_RADIUS_MI`
`static double`	`KM_TO_DEG`
`static double`	`KM_TO_MILES`
`static double`	`MILES_TO_KM`
`static double`	`RADIANS_TO_DEGREES`
`static double`	`SIN_45_AS_RADS` Deprecated.

Method Summary

Methods
Modifier and Type	Method and 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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEG_45_AS_RADS
```
@Deprecated
public static final double DEG_45_AS_RADS
```
    Deprecated.
    
    See Also:
    Constant Field Values
  - SIN_45_AS_RADS
```
@Deprecated
public static final double SIN_45_AS_RADS
```
    Deprecated.
  - DEG_90_AS_RADS
```
public static final double DEG_90_AS_RADS
```
    See Also:
    Constant Field Values
  - DEG_180_AS_RADS
```
public static final double DEG_180_AS_RADS
```
    See Also:
    Constant Field Values
  - DEG_225_AS_RADS
```
@Deprecated
public static final double DEG_225_AS_RADS
```
    Deprecated.
    
    See Also:
    Constant Field Values
  - DEG_270_AS_RADS
```
@Deprecated
public static final double DEG_270_AS_RADS
```
    Deprecated.
    
    See Also:
    Constant Field Values
  - DEGREES_TO_RADIANS
```
public static final double DEGREES_TO_RADIANS
```
    See Also:
    Constant Field Values
  - RADIANS_TO_DEGREES
```
public static final double RADIANS_TO_DEGREES
```
    See Also:
    Constant Field Values
  - KM_TO_MILES
```
public static final double KM_TO_MILES
```
    See Also:
    Constant Field Values
  - MILES_TO_KM
```
public static final double MILES_TO_KM
```
    See Also:
    Constant Field Values
  - EARTH_MEAN_RADIUS_KM
```
public 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
    
    See Also:
    Constant Field Values
  - EARTH_EQUATORIAL_RADIUS_KM
```
public static final double EARTH_EQUATORIAL_RADIUS_KM
```
    See Also:
    Constant Field Values
  - DEG_TO_KM
```
public static final double DEG_TO_KM
```
    Equivalent to degrees2Dist(1, EARTH_MEAN_RADIUS_KM)
    
    See Also:
    Constant Field Values
  - KM_TO_DEG
```
public static final double KM_TO_DEG
```
    See Also:
    Constant Field Values
  - EARTH_MEAN_RADIUS_MI
```
public static final double EARTH_MEAN_RADIUS_MI
```
    See Also:
    Constant Field Values
  - EARTH_EQUATORIAL_RADIUS_MI
```
public static final double EARTH_EQUATORIAL_RADIUS_MI
```
    See Also:
    Constant Field Values
- Method Detail
  - 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(double[], double[], double, double)
  - 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).
    ctx -
    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.

Class DistanceUtils

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEG_45_AS_RADS

SIN_45_AS_RADS

DEG_90_AS_RADS

DEG_180_AS_RADS

DEG_225_AS_RADS

DEG_270_AS_RADS

DEGREES_TO_RADIANS

RADIANS_TO_DEGREES

KM_TO_MILES

MILES_TO_KM

EARTH_MEAN_RADIUS_KM

EARTH_EQUATORIAL_RADIUS_KM

DEG_TO_KM

KM_TO_DEG

EARTH_MEAN_RADIUS_MI

EARTH_EQUATORIAL_RADIUS_MI

Method Detail

vectorDistance

vectorDistance

vectorBoxCorner

pointOnBearingRAD

normLonDEG

normLatDEG

calcBoxByDistFromPtDEG

calcBoxByDistFromPt_deltaLonDEG

calcBoxByDistFromPt_latHorizAxisDEG

calcLonDegreesAtLat

distSquaredCartesian

distHaversineRAD

distLawOfCosinesRAD

distVincentyRAD

dist2Degrees

degrees2Dist

dist2Radians

radians2Dist

toRadians

toDegrees