org.apache.lucene.spatial
Class DistanceUtils

java.lang.Object
  extended by 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.