Class DistanceUtils
- java.lang.Object
-
- org.locationtech.spatial4j.distance.DistanceUtils
-
public class DistanceUtils extends java.lang.Object
Various distance calculations and constants. To the extent possible, aDistanceCalculator
, retrieved fromSpatialContext.getDistCalc()
should be used in preference to calling these methods directly.This code came from Apache Lucene, LUCENE-1387, which in turn came from "LocalLucene".
-
-
Field Summary
Fields Modifier and Type Field 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: [1] http://en.wikipedia.org/wiki/Earth_radiusstatic 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.
-
Constructor Summary
Constructors Modifier Constructor Description private
DistanceUtils()
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 latitudelat
to cover a distancedist
.static double
degrees2Dist(double degrees, double radius)
Convertsdegrees
(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 ofradius
(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)
Convertsradians
(multiples of theradius
) to distance in the units of the radius (e.g.static double
toDegrees(double radians)
Same asMath.toDegrees(double)
but 3x faster (multiply vs.static double
toRadians(double degrees)
Same asMath.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.
-
-
-
Field Detail
-
DEG_45_AS_RADS
@Deprecated public static final double DEG_45_AS_RADS
Deprecated.- See Also:
- Constant Field Values
-
SIN_45_AS_RADS
@Deprecated public static final double SIN_45_AS_RADS
Deprecated.
-
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
@Deprecated public static final double DEG_225_AS_RADS
Deprecated.- See Also:
- Constant Field Values
-
DEG_270_AS_RADS
@Deprecated public static final double DEG_270_AS_RADS
Deprecated.- See Also:
- Constant Field Values
-
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
-
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_EQUATORIAL_RADIUS_KM
public static final double EARTH_EQUATORIAL_RADIUS_KM
- See Also:
- Constant Field Values
-
DEG_TO_KM
public static final double DEG_TO_KM
Equivalent to degrees2Dist(1, EARTH_MEAN_RADIUS_KM)- See Also:
- Constant Field Values
-
KM_TO_DEG
public static final double KM_TO_DEG
- 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
-
-
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 vectorvec2
- The second vectorpower
- The power (2 for cartesian distance, 1 for manhattan, etc.)- Returns:
- The length.
- See Also:
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 vectorvec2
- The second vectorpower
- 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 overvectorDistance(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 pointresult
- Holds the result, potentially resizing if needed.distance
- The d from the center to the cornerupperRight
- 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
-
pointOnBearingRAD
public 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.- Parameters:
startLat
- The starting point latitude, in radiansstartLon
- The starting point longitude, in radiansdistanceRAD
- The distance to travel along the bearing in radians.bearingRAD
- The bearing, in radians. North is a 0, moving clockwise till radians(360).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 alwaysfrom.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 latitudelat
to cover a distancedist
.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 degreesdist
- 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 pointvec2
- The second point- Returns:
- The squared cartesian distance
-
distHaversineRAD
public static double distHaversineRAD(double lat1, double lon1, double lat2, double lon2)
- Parameters:
lat1
- The y coordinate of the first point, in radianslon1
- The x coordinate of the first point, in radianslat2
- The y coordinate of the second point, in radianslon2
- The x coordinate of the second point, in radians- Returns:
- The distance between the two points, as determined by the Haversine formula, in radians.
-
distLawOfCosinesRAD
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.
-
distVincentyRAD
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, double radius)
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, double radius)
Convertsdegrees
(1/360th of circumference of a circle) into a distance as measured by the units of the radius. A spherical earth model is assumed.
-
dist2Radians
public static double dist2Radians(double dist, double radius)
Converts a distance in the units ofradius
(e.g. kilometers) to radians (multiples of the radius). A spherical earth model is assumed.
-
radians2Dist
public static double radians2Dist(double radians, double radius)
Convertsradians
(multiples of theradius
) to distance in the units of the radius (e.g. kilometers).
-
toRadians
public static double toRadians(double degrees)
Same asMath.toRadians(double)
but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.
-
toDegrees
public static double toDegrees(double radians)
Same asMath.toDegrees(double)
but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.
-
-