Module org.elasticsearch.server
Package org.elasticsearch.common.geo

Class GeoUtils

java.lang.Object
org.elasticsearch.common.geo.GeoUtils
public class GeoUtils extends Object

  • Field Details

    • MAX_LAT

      public static final double MAX_LAT
      Maximum valid latitude in degrees.
      See Also:

    • MIN_LAT

      public static final double MIN_LAT
      Minimum valid latitude in degrees.
      See Also:

    • MAX_LON

      public static final double MAX_LON
      Maximum valid longitude in degrees.
      See Also:

    • MIN_LON

      public static final double MIN_LON
      Minimum valid longitude in degrees.
      See Also:

    • EARTH_SEMI_MAJOR_AXIS

      public static final double EARTH_SEMI_MAJOR_AXIS
      Earth ellipsoid major axis defined by WGS 84 in meters
      See Also:

    • EARTH_SEMI_MINOR_AXIS

      public static final double EARTH_SEMI_MINOR_AXIS
      Earth ellipsoid minor axis defined by WGS 84 in meters
      See Also:

    • EARTH_MEAN_RADIUS

      public static final double EARTH_MEAN_RADIUS
      Earth mean radius defined by WGS 84 in meters
      See Also:

    • EARTH_EQUATOR

      public static final double EARTH_EQUATOR
      Earth ellipsoid equator length in meters
      See Also:

    • EARTH_POLAR_DISTANCE

      public static final double EARTH_POLAR_DISTANCE
      Earth ellipsoid polar distance in meters
      See Also:

    • TOLERANCE

      public static final double TOLERANCE
      rounding error for quantized latitude and longitude values
      See Also:

  • 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

      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)

    • needsNormalizeLat

      public static boolean needsNormalizeLat(double lat)

    • needsNormalizeLon

      public static boolean needsNormalizeLon(double lon)

    • 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(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(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 or type and coordinates 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, 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(XContentParser parser, boolean ignoreZValue, GeoUtils.EffectivePoint effectivePoint) throws IOException, ElasticsearchParseException
      Parse a GeoPoint with a XContentParser. A geo_point has one of the following forms:
      • Object: 
        {"lat": <latitude>, "lon": <longitude>}
      • Object: 
        {"type": Point, "coordinates": <array of doubles>}
      • String: 
        "<latitude>,<longitude>"
      • Geohash: 
        "<geohash>"
      • Array: 
        [<longitude>,<latitude>]
      Parameters:
      parser - XContentParser to parse the value from
      ignoreZValue - XContentParser to not throw an error if 3 dimensional data is provided
      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(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.

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