Package org.elasticsearch.common.geo

Class GeoUtils

java.lang.Object
org.elasticsearch.common.geo.GeoUtils
public class GeoUtils extends 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 String
    GEOHASH
     
    static String
    LATITUDE
     
    static 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​(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​(String val)
    Parse a GeoPoint from a string.
    static GeoPoint
    parseGeoPoint​(Object value, boolean ignoreZValue)
    Parses the value as a geopoint.
    static GeoPoint
    parseGeoPoint​(Object value, GeoPoint point, boolean ignoreZValue)
    Parses the value as a geopoint.
    static GeoPoint
    parseGeoPoint​(org.elasticsearch.common.xcontent.XContentParser parser)
    Parse a GeoPoint with a XContentParser:
    static GeoPoint
    parseGeoPoint​(org.elasticsearch.common.xcontent.XContentParser parser, GeoPoint point)
     
    static GeoPoint
    parseGeoPoint​(org.elasticsearch.common.xcontent.XContentParser parser, GeoPoint point, boolean ignoreZValue)
    Parse a geopoint represented as an object, string or an array.
    static GeoPoint
    parseGeoPoint​(org.elasticsearch.common.xcontent.XContentParser parser, GeoPoint point, boolean ignoreZValue, GeoUtils.EffectivePoint effectivePoint)
    Parse a GeoPoint with a XContentParser.
    static int
    parsePrecision​(org.elasticsearch.common.xcontent.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​(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 Details

    • 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

    • LATITUDE

      public static final String LATITUDE
      See Also:
      Constant Field Values

    • LONGITUDE

      public static final String LONGITUDE
      See Also:
      Constant Field Values

    • GEOHASH

      public static final String GEOHASH
      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 Details

    • 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​(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​(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​(org.elasticsearch.common.xcontent.XContentParser parser) throws IOException, ElasticsearchParseException
      Parse a GeoPoint with a XContentParser:
      Parameters:
      parser - XContentParser to parse the value from
      Returns:
      new GeoPoint parsed from the parse
      Throws:
      IOException
      ElasticsearchParseException

    • parseGeoPoint

      public static GeoPoint parseGeoPoint​(org.elasticsearch.common.xcontent.XContentParser parser, GeoPoint point) throws IOException, ElasticsearchParseException
      Throws:
      IOException
      ElasticsearchParseException

    • parseGeoPoint

      public static GeoPoint parseGeoPoint​(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​(Object value, GeoPoint point, 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​(org.elasticsearch.common.xcontent.XContentParser parser, GeoPoint point, boolean ignoreZValue) throws 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:
      IOException
      ElasticsearchParseException

    • parseGeoPoint

      public static GeoPoint parseGeoPoint​(org.elasticsearch.common.xcontent.XContentParser parser, GeoPoint point, boolean ignoreZValue, GeoUtils.EffectivePoint effectivePoint) throws IOException, ElasticsearchParseException
      Parse a GeoPoint with a XContentParser. A geopoint has one of the following forms:
      • Object: 
        {"lat": <latitude>, "lon": <longitude>}
      • String: 
        "<latitude>,<longitude>"
      • Geohash: 
        "<geohash>"
      • Array: 
        [<longitude>,<latitude>]
      Parameters:
      parser - XContentParser to parse the value from
      point - A GeoPoint that will be reset by the values parsed
      Returns:
      new GeoPoint parsed from the parse
      Throws:
      IOException
      ElasticsearchParseException

    • parseFromString

      public static GeoPoint parseFromString​(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​(org.elasticsearch.common.xcontent.XContentParser parser) throws 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:
      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

    • distanceValues

      public 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.