Class DistanceUtils

    • 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 latitude lat to cover a distance dist.
      static double degrees2Dist​(double degrees, double radius)
      Converts degrees (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 of radius (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)
      Converts radians (multiples of the radius) to distance in the units of the radius (e.g.
      static double toDegrees​(double radians)
      Same as Math.toDegrees(double) but 3x faster (multiply vs.
      static double toRadians​(double degrees)
      Same as Math.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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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_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
      • 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
      • EARTH_EQUATORIAL_RADIUS_MI

        public static final double EARTH_EQUATORIAL_RADIUS_MI
        See Also:
        Constant Field Values
    • Constructor Detail

      • DistanceUtils

        private DistanceUtils()
    • 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 vector
        vec2 - The second vector
        power - 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 vector
        vec2 - The second vector
        power - 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 over vectorDistance(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 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
      • 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 radians
        startLon - The starting point longitude, in radians
        distanceRAD - 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 always from.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 latitude lat to cover a distance dist.

        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 degrees
        dist - 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 point
        vec2 - 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 radians
        lon1 - The x coordinate of the first point, in radians
        lat2 - The y coordinate of the second point, in radians
        lon2 - The x coordinate of the second point, in radians
        Returns:
        The distance between the two points, as determined by the Haversine formula, 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)
        Converts degrees (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 of radius (e.g. kilometers) to radians (multiples of the radius). A spherical earth model is assumed.
      • radians2Dist

        public static double radians2Dist​(double radians,
                                          double radius)
        Converts radians (multiples of the radius) to distance in the units of the radius (e.g. kilometers).
      • toRadians

        public static double toRadians​(double degrees)
        Same as Math.toRadians(double) but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.
      • toDegrees

        public static double toDegrees​(double radians)
        Same as Math.toDegrees(double) but 3x faster (multiply vs. divide). See CompareRadiansSnippet.java in tests.