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

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 KM_TO_MILES

static double MILES_TO_KM

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

Constant Field Values

Constant Field Values

Constant Field Values

Constant Field Values

Constant Field Values

Constant Field Values

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

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

Constant Field Values

Constant Field Values

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