Spatial4j, 0.7
org.locationtech.spatial4j.distance

## Class DistanceUtils

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

All 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

```@Deprecated
public static final double DEG_45_AS_RADS```
Deprecated.
Constant Field Values

```@Deprecated
public static final double SIN_45_AS_RADS```
Deprecated.

`public static final double DEG_90_AS_RADS`
Constant Field Values

`public static final double DEG_180_AS_RADS`
Constant Field Values

```@Deprecated
public static final double DEG_225_AS_RADS```
Deprecated.
Constant Field Values

```@Deprecated
public static final double DEG_270_AS_RADS```
Deprecated.
Constant Field Values

`public static final double DEGREES_TO_RADIANS`
Constant Field Values

`public static final double RADIANS_TO_DEGREES`
Constant Field Values
• #### KM_TO_MILES

`public static final double KM_TO_MILES`
Constant Field Values
• #### MILES_TO_KM

`public static final double MILES_TO_KM`
Constant Field Values

`public static final double EARTH_MEAN_RADIUS_KM`
The International Union of Geodesy and Geophysics says the Earth's mean radius in KM is:  http://en.wikipedia.org/wiki/Earth_radius
Constant Field Values

`public static final double EARTH_EQUATORIAL_RADIUS_KM`
Constant Field Values
• #### DEG_TO_KM

`public static final double DEG_TO_KM`
Equivalent to degrees2Dist(1, EARTH_MEAN_RADIUS_KM)
Constant Field Values
• #### KM_TO_DEG

`public static final double KM_TO_DEG`
Constant Field Values

`public static final double EARTH_MEAN_RADIUS_MI`
Constant Field Values

`public static final double EARTH_EQUATORIAL_RADIUS_MI`
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.
`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

```public static Point pointOnBearingRAD(double startLat,
double startLon,
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

```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.

```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.

The arguments and return value are in radians.

```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,
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,
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.

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

```public static double radians2Dist(double radians,
Converts `radians` (multiples of the `radius`) to distance in the units of the radius (e.g. kilometers).
`public static double toRadians(double degrees)`
Same as `Math.toRadians(double)` but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.
`public static double toDegrees(double radians)`
Same as `Math.toDegrees(double)` but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.