org.apache.lucene.spatial Class DistanceUtils

```java.lang.Object
org.apache.lucene.spatial.DistanceUtils
```

`public class DistanceUtilsextends Object`

NOTE: This API is still in flux and might change in incompatible ways in the next release.

Field Summary
`static double` `DEG_180_AS_RADS`

`static double` `DEG_225_AS_RADS`

`static double` `DEG_270_AS_RADS`

`static double` `DEG_45_AS_RADS`

`static double` `DEG_90_AS_RADS`

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

`static double` `MILES_TO_KM`

`static double` `RADIANS_TO_DEGREES`

`static double` `SIN_45_AS_RADS`

Constructor Summary
`DistanceUtils()`

Method Summary
`static double` ```angularDistance(double distance, double radius)```
`static Rectangle` ```getBoundary(double x1, double y1, double miles)```

`static double` ```getDistanceMi(double x1, double y1, double x2, double y2)```

`static double` ```getLLMDistance(double x1, double y1, double x2, double y2)```

`static double` ```haversine(double x1, double y1, double x2, double y2, double radius)```

`static double[]` ```latLonCorner(double latCenter, double lonCenter, double distance, double[] result, boolean upperRight, double sphereRadius)```
Uses Haversine to calculate the corner of a box (upper right or lower left) that is the distance away, given a sphere of the specified radius.
`static double[]` ```latLonCornerDegs(double latCenter, double lonCenter, double distance, double[] result, boolean upperRight, double sphereRadius)```

`static void` `normLat(double[] latLng)`

`static void` `normLng(double[] latLng)`
Returns a normalized Lng rectangle shape for the bounding box
`static double[]` ```parseLatitudeLongitude(double[] latLon, String latLonStr)```
extract (by calling `parsePoint(String[], String, int)` and validate the latitude and longitude contained in the String by making sure the latitude is between 90 & -90 and longitude is between -180 and 180.
`static double[]` `parseLatitudeLongitude(String latLonStr)`

`static String[]` ```parsePoint(String[] out, String externalVal, int dimension)```
Given a string containing dimension values encoded in it, separated by commas, return a String array of length dimension containing the values.
`static double[]` ```parsePointDouble(double[] out, String externalVal, int dimension)```
Given a string containing dimension values encoded in it, separated by commas, return a double array of length dimension containing the values.
`static double[]` ```pointOnBearing(double startLat, double startLon, double distance, double bearing, double[] result, double sphereRadius)```
Given a start point (startLat, startLon) and a bearing on a sphere of radius sphereRadius, return the destination point.
`static double` ```squaredEuclideanDistance(double[] vec1, double[] vec2)```
The square of the Euclidean Distance.
`static double[]` ```vectorBoxCorner(double[] center, double[] result, double distance, boolean upperRight)```
Return the coordinates of a vector that is the corner of a box (upper right or lower left), assuming a Rectangular coordinate system.
`static double` ```vectorDistance(double[] vec1, double[] vec2, double power)```
Calculate the p-norm (i.e.
`static double` ```vectorDistance(double[] vec1, double[] vec2, double power, double oneOverPower)```
Calculate the p-norm (i.e.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

`public static final double DEGREES_TO_RADIANS`
Constant Field Values

`public static final double RADIANS_TO_DEGREES`
Constant Field Values

`public static final double DEG_45_AS_RADS`
Constant Field Values

`public static final double SIN_45_AS_RADS`

`public static final double DEG_90_AS_RADS`
Constant Field Values

`public static final double DEG_180_AS_RADS`
Constant Field Values

`public static final double DEG_225_AS_RADS`
Constant Field Values

`public static final double DEG_270_AS_RADS`
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: [1] http://en.wikipedia.org/wiki/Earth_radius

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

`public static final double EARTH_EQUATORIAL_RADIUS_KM`
Constant Field Values
Constructor Detail

DistanceUtils

`public DistanceUtils()`
Method Detail

getDistanceMi

```public static double getDistanceMi(double x1,
double y1,
double x2,
double y2)```

getBoundary

```public static Rectangle getBoundary(double x1,
double y1,
double miles)```
Parameters:
`x1` -
`y1` -
`miles` -
Returns:
boundary rectangle where getY/getX is top left, getMinY/getMinX is bottom right

getLLMDistance

```public static double getLLMDistance(double x1,
double y1,
double x2,
double y2)```

angularDistance

```public static double angularDistance(double distance,

Parameters:
`distance` - The distance travelled
`radius` - The radius of the sphere
Returns:

vectorDistance

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

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

See http://en.wikipedia.org/wiki/Lp_space

`vectorDistance(double[], double[], double, double)`

vectorDistance

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

Parameters:
`vec1` - The first vector
`vec2` - The second vector
`power` - The power (2 for Euclidean distance, 1 for manhattan, etc.)
`oneOverPower` - If you've precalculated oneOverPower and cached it, use this method to save one division operation over `vectorDistance(double[], double[], double)`.
Returns:
The length.

vectorBoxCorner

```public static double[] vectorBoxCorner(double[] center,
double[] result,
double distance,
boolean upperRight)```
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 approximatation).

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

latLonCornerDegs

```public static double[] latLonCornerDegs(double latCenter,
double lonCenter,
double distance,
double[] result,
boolean upperRight,
Parameters:
`latCenter` - In degrees
`lonCenter` - In degrees
`distance` - The distance
`result` - A preallocated array to hold the results. If null, a new one is constructed.
`upperRight` - If true, calculate the upper right corner, else the lower left
`sphereRadius` - The radius of the sphere to use.
Returns:
The Lat/Lon in degrees
`latLonCorner(double, double, double, double[], boolean, double)`

latLonCorner

```public static double[] latLonCorner(double latCenter,
double lonCenter,
double distance,
double[] result,
boolean upperRight,
Uses Haversine to calculate the corner of a box (upper right or lower left) that is the distance away, given a sphere of the specified radius. NOTE: This is not the same as calculating a box that transcribes a circle of the given distance.

Parameters:
`latCenter` - In radians
`lonCenter` - In radians
`distance` - The distance
`result` - A preallocated array to hold the results. If null, a new one is constructed.
`upperRight` - If true, give lat/lon for the upper right corner, else lower left
`sphereRadius` - The radius to use for the calculation
Returns:

pointOnBearing

```public static double[] pointOnBearing(double startLat,
double startLon,
double distance,
double bearing,
double[] result,
Given a start point (startLat, startLon) and a bearing on a sphere of radius sphereRadius, return the destination point.

Parameters:
`startLat` - The starting point latitude, in radians
`startLon` - The starting point longitude, in radians
`distance` - The distance to travel along the bearing. The units are assumed to be the same as the sphereRadius units, both of which is up to the caller to know
`bearing` - The bearing, in radians. North is a 0 deg. bearing, east is 90 deg, south is 180 deg, west is 270 deg.
`result` - A preallocated array to hold the results. If null, a new one is constructed.
`sphereRadius` - The radius of the sphere to use for the calculation.
Returns:
The destination point, in radians. First entry is latitude, second is longitude

normLat

`public static void normLat(double[] latLng)`
Parameters:
`latLng` - The lat/lon, in radians. lat in position 0, long in position 1

normLng

`public static void normLng(double[] latLng)`
Returns a normalized Lng rectangle shape for the bounding box

Parameters:
`latLng` - The lat/lon, in radians, lat in position 0, long in position 1

squaredEuclideanDistance

```public static double squaredEuclideanDistance(double[] vec1,
double[] vec2)```
The square of the Euclidean 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 Euclidean distance

haversine

```public static double haversine(double x1,
double y1,
double x2,
double y2,
Parameters:
`x1` - The x coordinate of the first point, in radians
`y1` - The y coordinate of the first point, in radians
`x2` - The x coordinate of the second point, in radians
`y2` - The y coordinate of the second point, in radians
`radius` - The radius of the sphere
Returns:
The distance between the two points, as determined by the Haversine formula.

parsePoint

```public static String[] parsePoint(String[] out,
String externalVal,
int dimension)
throws InvalidGeoException```
Given a string containing dimension values encoded in it, separated by commas, return a String array of length dimension containing the values.

Parameters:
`out` - A preallocated array. Must be size dimension. If it is not it will be resized.
`externalVal` - The value to parse
`dimension` - The expected number of values for the point
Returns:
An array of the values that make up the point (aka vector)
Throws:
`InvalidGeoException` - if the dimension specified does not match the number of values in the externalValue.

parsePointDouble

```public static double[] parsePointDouble(double[] out,
String externalVal,
int dimension)
throws InvalidGeoException```
Given a string containing dimension values encoded in it, separated by commas, return a double array of length dimension containing the values.

Parameters:
`out` - A preallocated array. Must be size dimension. If it is not it will be resized.
`externalVal` - The value to parse
`dimension` - The expected number of values for the point
Returns:
An array of the values that make up the point (aka vector)
Throws:
`InvalidGeoException` - if the dimension specified does not match the number of values in the externalValue.

parseLatitudeLongitude

```public static final double[] parseLatitudeLongitude(String latLonStr)
throws InvalidGeoException```
Throws:
`InvalidGeoException`

parseLatitudeLongitude

```public static final double[] parseLatitudeLongitude(double[] latLon,
String latLonStr)
throws InvalidGeoException```
extract (by calling `parsePoint(String[], String, int)` and validate the latitude and longitude contained in the String by making sure the latitude is between 90 & -90 and longitude is between -180 and 180.

The latitude is assumed to be the first part of the string and the longitude the second part.

Parameters:
`latLon` - A preallocated array to hold the result
`latLonStr` - The string to parse. Latitude is the first value, longitude is the second.
Returns:
The lat long
Throws:
`InvalidGeoException` - if there was an error parsing