## org.apache.lucene.spatial
Class DistanceUtils

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

    public class DistanceUtils

extends 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)` distance/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

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

### DEG_45_AS_RADS

    public static final double DEG_45_AS_RADS

See Also:
  Constant Field Values

### SIN_45_AS_RADS

    public static final double SIN_45_AS_RADS

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

    public static final double DEG_225_AS_RADS

See Also:
  Constant Field Values

### DEG_270_AS_RADS

    public static final double DEG_270_AS_RADS

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

### EARTH_EQUATORIAL_RADIUS_KM

    public static final double EARTH_EQUATORIAL_RADIUS_KM

See Also:
  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,
                                         double radius)

  distance/radius.

  Parameters:
    `distance` - The distance travelled
    `radius` - The radius of the sphere
  Returns:
    The angular distance, in radians

### 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
  See Also:
    `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,
                                            double sphereRadius)

  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
  See Also:
    `latLonCorner(double, double, double, double[], boolean, double)`

### latLonCorner

    public 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. 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:
    The Lat/Lon in Radians

### pointOnBearing

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

  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,
                                   double radius)

  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

Copyright © 2000-2011 Apache Software Foundation. All Rights Reserved.