Class GeoUtils


  • public class GeoUtils
    extends java.lang.Object
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  GeoUtils.EffectivePoint
      Represents the point of the geohash cell that should be used as the value of geohash
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double EARTH_AXIS_RATIO
      Earth axis ratio defined by WGS 84 (0.996647189335)
      static double EARTH_EQUATOR
      Earth ellipsoid equator length in meters
      static double EARTH_MEAN_RADIUS
      Earth mean radius defined by WGS 84 in meters
      static double EARTH_POLAR_DISTANCE
      Earth ellipsoid polar distance in meters
      static double EARTH_SEMI_MAJOR_AXIS
      Earth ellipsoid major axis defined by WGS 84 in meters
      static double EARTH_SEMI_MINOR_AXIS
      Earth ellipsoid minor axis defined by WGS 84 in meters
      static java.lang.String GEOHASH  
      static java.lang.String LATITUDE  
      static java.lang.String LONGITUDE  
      static double MAX_LAT
      Maximum valid latitude in degrees.
      static double MAX_LON
      Maximum valid longitude in degrees.
      static double MIN_LAT
      Minimum valid latitude in degrees.
      static double MIN_LON
      Minimum valid longitude in degrees.
      static double TOLERANCE
      rounding error for quantized latitude and longitude values
    • Method Summary

      Modifier and Type Method Description
      static double arcDistance​(double lat1, double lon1, double lat2, double lon2)
      Return the distance (in meters) between 2 lat,lon geo points using the haversine method implemented by lucene
      static double centeredModulus​(double dividend, double divisor)  
      static int checkPrecisionRange​(int precision)
      Checks that the precision is within range supported by elasticsearch - between 1 and 12 Returns the precision value if it is in the range and throws an IllegalArgumentException if it is outside the range.
      static SortedNumericDoubleValues distanceValues​(GeoDistance distance, DistanceUnit unit, MultiGeoPointValues geoPointValues, GeoPoint... fromPoints)
      Return a SortedNumericDoubleValues instance that returns the distances to a list of geo-points for each document.
      static double geoHashCellHeight​(int level)
      Calculate the height (in meters) of geohash cells at a specific level
      static double geoHashCellSize​(int level)
      Calculate the size (in meters) of geohash cells at a specific level
      static double geoHashCellWidth​(int level)
      Calculate the width (in meters) of geohash cells at a specific level
      static int geoHashLevelsForPrecision​(double meters)
      Calculate the number of levels needed for a specific precision.
      static int geoHashLevelsForPrecision​(java.lang.String distance)
      Calculate the number of levels needed for a specific precision.
      static boolean isValidLatitude​(double latitude)
      Returns true if latitude is actually a valid latitude value.
      static boolean isValidLongitude​(double longitude)
      Returns true if longitude is actually a valid longitude value.
      static double maxRadialDistanceMeters​(double centerLat, double centerLon)
      Returns the maximum distance/radius (in meters) from the point 'center' before overlapping
      static double normalizeLat​(double lat)
      Normalize latitude to lie within the -90 to 90 (both inclusive) range.
      static double normalizeLon​(double lon)
      Normalize longitude to lie within the -180 (exclusive) to 180 (inclusive) range.
      static void normalizePoint​(double[] lonLat)  
      static void normalizePoint​(double[] lonLat, boolean normLon, boolean normLat)  
      static void normalizePoint​(GeoPoint point)
      Normalize the geo Point for its coordinates to lie within their respective normalized ranges.
      static void normalizePoint​(GeoPoint point, boolean normLat, boolean normLon)
      Normalize the geo Point for the given coordinates to lie within their respective normalized ranges.
      static GeoPoint parseFromString​(java.lang.String val)
      Parse a GeoPoint from a string.
      static GeoPoint parseGeoPoint​(java.lang.Object value, boolean ignoreZValue)
      Parses the value as a geopoint.
      static GeoPoint parseGeoPoint​(XContentParser parser)
      Parse a GeoPoint with a XContentParser:
      static GeoPoint parseGeoPoint​(XContentParser parser, GeoPoint point)  
      static GeoPoint parseGeoPoint​(XContentParser parser, GeoPoint point, boolean ignoreZValue)
      Parse a geopoint represented as an object, string or an array.
      static GeoPoint parseGeoPoint​(XContentParser parser, GeoPoint point, boolean ignoreZValue, GeoUtils.EffectivePoint effectivePoint)
      Parse a GeoPoint with a XContentParser.
      static int parsePrecision​(XContentParser parser)
      Parse a precision that can be expressed as an integer or a distance measure like "1km", "10m".
      static double planeDistance​(double lat1, double lon1, double lat2, double lon2)
      Return the distance (in meters) between 2 lat,lon geo points using a simple tangential plane this provides a faster alternative to arcDistance(double, double, double, double) but is inaccurate for distances greater than 4 decimal degrees
      static double quadTreeCellHeight​(int level)
      Calculate the height (in meters) of quadtree cells at a specific level
      static double quadTreeCellSize​(int level)
      Calculate the size (in meters) of quadtree cells at a specific level
      static double quadTreeCellWidth​(int level)
      Calculate the width (in meters) of quadtree cells at a specific level
      static int quadTreeLevelsForPrecision​(double meters)
      Calculate the number of levels needed for a specific precision.
      static int quadTreeLevelsForPrecision​(java.lang.String distance)
      Calculate the number of levels needed for a specific precision.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • MAX_LAT

        public static final double MAX_LAT
        Maximum valid latitude in degrees.
        See Also:
        Constant Field Values
      • MIN_LAT

        public static final double MIN_LAT
        Minimum valid latitude in degrees.
        See Also:
        Constant Field Values
      • MAX_LON

        public static final double MAX_LON
        Maximum valid longitude in degrees.
        See Also:
        Constant Field Values
      • MIN_LON

        public static final double MIN_LON
        Minimum valid longitude in degrees.
        See Also:
        Constant Field Values
      • EARTH_SEMI_MAJOR_AXIS

        public static final double EARTH_SEMI_MAJOR_AXIS
        Earth ellipsoid major axis defined by WGS 84 in meters
        See Also:
        Constant Field Values
      • EARTH_SEMI_MINOR_AXIS

        public static final double EARTH_SEMI_MINOR_AXIS
        Earth ellipsoid minor axis defined by WGS 84 in meters
        See Also:
        Constant Field Values
      • EARTH_MEAN_RADIUS

        public static final double EARTH_MEAN_RADIUS
        Earth mean radius defined by WGS 84 in meters
        See Also:
        Constant Field Values
      • EARTH_AXIS_RATIO

        public static final double EARTH_AXIS_RATIO
        Earth axis ratio defined by WGS 84 (0.996647189335)
        See Also:
        Constant Field Values
      • EARTH_EQUATOR

        public static final double EARTH_EQUATOR
        Earth ellipsoid equator length in meters
        See Also:
        Constant Field Values
      • EARTH_POLAR_DISTANCE

        public static final double EARTH_POLAR_DISTANCE
        Earth ellipsoid polar distance in meters
        See Also:
        Constant Field Values
      • TOLERANCE

        public static final double TOLERANCE
        rounding error for quantized latitude and longitude values
        See Also:
        Constant Field Values
    • Method Detail

      • isValidLatitude

        public static boolean isValidLatitude​(double latitude)
        Returns true if latitude is actually a valid latitude value.
      • isValidLongitude

        public static boolean isValidLongitude​(double longitude)
        Returns true if longitude is actually a valid longitude value.
      • geoHashCellWidth

        public static double geoHashCellWidth​(int level)
        Calculate the width (in meters) of geohash cells at a specific level
        Parameters:
        level - geohash level must be greater or equal to zero
        Returns:
        the width of cells at level in meters
      • quadTreeCellWidth

        public static double quadTreeCellWidth​(int level)
        Calculate the width (in meters) of quadtree cells at a specific level
        Parameters:
        level - quadtree level must be greater or equal to zero
        Returns:
        the width of cells at level in meters
      • geoHashCellHeight

        public static double geoHashCellHeight​(int level)
        Calculate the height (in meters) of geohash cells at a specific level
        Parameters:
        level - geohash level must be greater or equal to zero
        Returns:
        the height of cells at level in meters
      • quadTreeCellHeight

        public static double quadTreeCellHeight​(int level)
        Calculate the height (in meters) of quadtree cells at a specific level
        Parameters:
        level - quadtree level must be greater or equal to zero
        Returns:
        the height of cells at level in meters
      • geoHashCellSize

        public static double geoHashCellSize​(int level)
        Calculate the size (in meters) of geohash cells at a specific level
        Parameters:
        level - geohash level must be greater or equal to zero
        Returns:
        the size of cells at level in meters
      • quadTreeCellSize

        public static double quadTreeCellSize​(int level)
        Calculate the size (in meters) of quadtree cells at a specific level
        Parameters:
        level - quadtree level must be greater or equal to zero
        Returns:
        the size of cells at level in meters
      • quadTreeLevelsForPrecision

        public static int quadTreeLevelsForPrecision​(double meters)
        Calculate the number of levels needed for a specific precision. Quadtree cells will not exceed the specified size (diagonal) of the precision.
        Parameters:
        meters - Maximum size of cells in meters (must greater than zero)
        Returns:
        levels need to achieve precision
      • quadTreeLevelsForPrecision

        public static int quadTreeLevelsForPrecision​(java.lang.String distance)
        Calculate the number of levels needed for a specific precision. QuadTree cells will not exceed the specified size (diagonal) of the precision.
        Parameters:
        distance - Maximum size of cells as unit string (must greater or equal to zero)
        Returns:
        levels need to achieve precision
      • geoHashLevelsForPrecision

        public static int geoHashLevelsForPrecision​(double meters)
        Calculate the number of levels needed for a specific precision. GeoHash cells will not exceed the specified size (diagonal) of the precision.
        Parameters:
        meters - Maximum size of cells in meters (must greater or equal to zero)
        Returns:
        levels need to achieve precision
      • geoHashLevelsForPrecision

        public static int geoHashLevelsForPrecision​(java.lang.String distance)
        Calculate the number of levels needed for a specific precision. GeoHash cells will not exceed the specified size (diagonal) of the precision.
        Parameters:
        distance - Maximum size of cells as unit string (must greater or equal to zero)
        Returns:
        levels need to achieve precision
      • normalizeLon

        public static double normalizeLon​(double lon)
        Normalize longitude to lie within the -180 (exclusive) to 180 (inclusive) range.
        Parameters:
        lon - Longitude to normalize
        Returns:
        The normalized longitude.
      • normalizeLat

        public static double normalizeLat​(double lat)
        Normalize latitude to lie within the -90 to 90 (both inclusive) range.

        Note: You should not normalize longitude and latitude separately, because when normalizing latitude it may be necessary to add a shift of 180° in the longitude. For this purpose, you should call the normalizePoint(GeoPoint) function.

        Parameters:
        lat - Latitude to normalize
        Returns:
        The normalized latitude.
        See Also:
        normalizePoint(GeoPoint)
      • normalizePoint

        public static void normalizePoint​(GeoPoint point)
        Normalize the geo Point for its coordinates to lie within their respective normalized ranges.

        Note: A shift of 180° is applied in the longitude if necessary, in order to normalize properly the latitude.

        Parameters:
        point - The point to normalize in-place.
      • normalizePoint

        public static void normalizePoint​(GeoPoint point,
                                          boolean normLat,
                                          boolean normLon)
        Normalize the geo Point for the given coordinates to lie within their respective normalized ranges.

        You can control which coordinate gets normalized with the two flags.

        Note: A shift of 180° is applied in the longitude if necessary, in order to normalize properly the latitude. If normalizing latitude but not longitude, it is assumed that the longitude is in the form x+k*360, with x in ]-180;180], and k is meaningful to the application. Therefore x will be adjusted while keeping k preserved.

        Parameters:
        point - The point to normalize in-place.
        normLat - Whether to normalize latitude or leave it as is.
        normLon - Whether to normalize longitude.
      • normalizePoint

        public static void normalizePoint​(double[] lonLat)
      • normalizePoint

        public static void normalizePoint​(double[] lonLat,
                                          boolean normLon,
                                          boolean normLat)
      • centeredModulus

        public static double centeredModulus​(double dividend,
                                             double divisor)
      • parseGeoPoint

        public static GeoPoint parseGeoPoint​(java.lang.Object value,
                                             boolean ignoreZValue)
                                      throws ElasticsearchParseException
        Parses the value as a geopoint. The following types of values are supported:

        Object: has to contain either lat and lon or geohash fields

        String: expected to be in "latitude, longitude" format or a geohash

        Array: two or more elements, the first element is longitude, the second is latitude, the rest is ignored if ignoreZValue is true

        Throws:
        ElasticsearchParseException
      • parseGeoPoint

        public static GeoPoint parseGeoPoint​(XContentParser parser,
                                             GeoPoint point,
                                             boolean ignoreZValue)
                                      throws java.io.IOException,
                                             ElasticsearchParseException
        Parse a geopoint represented as an object, string or an array. If the geopoint is represented as a geohash, the left bottom corner of the geohash cell is used as the geopoint coordinates.GeoBoundingBoxQueryBuilder.java
        Throws:
        java.io.IOException
        ElasticsearchParseException
      • parseFromString

        public static GeoPoint parseFromString​(java.lang.String val)
        Parse a GeoPoint from a string. The string must have one of the following forms:
        • Latitude, Longitude form:
          "<latitude>,<longitude>"
        • Geohash form::
          "<geohash>"
        Parameters:
        val - a String to parse the value from
        Returns:
        new parsed GeoPoint
      • parsePrecision

        public static int parsePrecision​(XContentParser parser)
                                  throws java.io.IOException,
                                         ElasticsearchParseException
        Parse a precision that can be expressed as an integer or a distance measure like "1km", "10m". The precision is expressed as a number between 1 and 12 and indicates the length of geohash used to represent geo points.
        Parameters:
        parser - XContentParser to parse the value from
        Returns:
        int representing precision
        Throws:
        java.io.IOException
        ElasticsearchParseException
      • checkPrecisionRange

        public static int checkPrecisionRange​(int precision)
        Checks that the precision is within range supported by elasticsearch - between 1 and 12 Returns the precision value if it is in the range and throws an IllegalArgumentException if it is outside the range.
      • maxRadialDistanceMeters

        public static double maxRadialDistanceMeters​(double centerLat,
                                                     double centerLon)
        Returns the maximum distance/radius (in meters) from the point 'center' before overlapping
      • arcDistance

        public static double arcDistance​(double lat1,
                                         double lon1,
                                         double lat2,
                                         double lon2)
        Return the distance (in meters) between 2 lat,lon geo points using the haversine method implemented by lucene
      • planeDistance

        public static double planeDistance​(double lat1,
                                           double lon1,
                                           double lat2,
                                           double lon2)
        Return the distance (in meters) between 2 lat,lon geo points using a simple tangential plane this provides a faster alternative to arcDistance(double, double, double, double) but is inaccurate for distances greater than 4 decimal degrees