GeoUtils (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.geo, class: GeoUtils

Package org.apache.lucene.geo

# Class GeoUtils

java.lang.Object
org.apache.lucene.geo.GeoUtils

public final class GeoUtils extends Object
Utility methods for geo-spatial calculations and coordinate validation.

This class provides:

- Coordinate validation methods
- Earth model constants
- Common geometric calculations
- Coordinate normalization utilities

Important Constants:

- Earth's mean radius: 6,371,008.7714 meters
- Latitude range: -90° to +90°
- Longitude range: -180° to +180°

Note: This class uses a spherical Earth model for simplicity and performance. For applications requiring higher precision, consider using a geodetic library that implements the WGS84 ellipsoid model.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `GeoUtils.WindingOrder`
  used to define the orientation of 3 points -1 = Clockwise 0 = Colinear 1 = Counter-clockwise

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final double`
  `EARTH_MEAN_RADIUS_METERS`
  mean earth axis in meters
  `static final double`
  `MAX_LAT_INCL`
  Maximum latitude value.
  `static final double`
  `MAX_LAT_RADIANS`
  max latitude value in radians
  `static final double`
  `MAX_LON_INCL`
  Maximum longitude value.
  `static final double`
  `MAX_LON_RADIANS`
  max longitude value in radians
  `static final double`
  `MIN_LAT_INCL`
  Minimum latitude value.
  `static final double`
  `MIN_LAT_RADIANS`
  min latitude value in radians
  `static final double`
  `MIN_LON_INCL`
  Minimum longitude value.
  `static final double`
  `MIN_LON_RADIANS`
  min longitude value in radians

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `checkLatitude(double latitude)`
  validates latitude value is within standard +/-90 coordinate bounds
  `static void`
  `checkLongitude(double longitude)`
  validates longitude value is within standard +/-180 coordinate bounds
  `static double`
  `distanceQuerySortKey(double radius)`
  binary search to find the exact sortKey needed to match the specified radius any sort key lte this is a query match.
  `static boolean`
  `lineCrossesLine(double a1x, double a1y, double b1x, double b1y, double a2x, double a2y, double b2x, double b2y)`
  uses orient method to compute whether two line segments cross
  `static boolean`
  `lineCrossesLineWithBoundary(double a1x, double a1y, double b1x, double b1y, double a2x, double a2y, double b2x, double b2y)`
  uses orient method to compute whether two line segments cross; boundaries included - returning true for lines that terminate on each other.
  `static boolean`
  `lineOverlapLine(double a1x, double a1y, double b1x, double b1y, double a2x, double a2y, double b2x, double b2y)`
  uses orient method to compute whether two line overlap each other
  `static int`
  `orient(double ax, double ay, double bx, double by, double cx, double cy)`
  Returns a positive value if points a, b, and c are arranged in counter-clockwise order, negative value if clockwise, zero if collinear.
  `static PointValues.Relation`
  `relate(double minLat, double maxLat, double minLon, double maxLon, double lat, double lon, double distanceSortKey, double axisLat)`
  Compute the relation between the provided box and distance query.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### MIN_LON_INCL

    public static final double MIN_LON_INCL
    Minimum longitude value.
    See Also:
      - Constant Field Values

  - ### MAX_LON_INCL

    public static final double MAX_LON_INCL
    Maximum longitude value.
    See Also:
      - Constant Field Values

  - ### MIN_LAT_INCL

    public static final double MIN_LAT_INCL
    Minimum latitude value.
    See Also:
      - Constant Field Values

  - ### MAX_LAT_INCL

    public static final double MAX_LAT_INCL
    Maximum latitude value.
    See Also:
      - Constant Field Values

  - ### MIN_LON_RADIANS

    public static final double MIN_LON_RADIANS
    min longitude value in radians

  - ### MIN_LAT_RADIANS

    public static final double MIN_LAT_RADIANS
    min latitude value in radians

  - ### MAX_LON_RADIANS

    public static final double MAX_LON_RADIANS
    max longitude value in radians

  - ### MAX_LAT_RADIANS

    public static final double MAX_LAT_RADIANS
    max latitude value in radians

  - ### EARTH_MEAN_RADIUS_METERS

    public static final double EARTH_MEAN_RADIUS_METERS
    mean earth axis in meters
    See Also:
      - Constant Field Values

- ## Method Details

  - ### checkLatitude

    public static void checkLatitude(double latitude)
    validates latitude value is within standard +/-90 coordinate bounds

  - ### checkLongitude

    public static void checkLongitude(double longitude)
    validates longitude value is within standard +/-180 coordinate bounds

  - ### distanceQuerySortKey

    public static double distanceQuerySortKey(double radius)
    binary search to find the exact sortKey needed to match the specified radius any sort key lte this is a query match.

  - ### relate

    public static PointValues.Relation relate(double minLat, double maxLat, double minLon, double maxLon, double lat, double lon, double distanceSortKey, double axisLat)
    Compute the relation between the provided box and distance query. This only works for boxes that do not cross the dateline.

  - ### orient

    public static int orient(double ax, double ay, double bx, double by, double cx, double cy)
    Returns a positive value if points a, b, and c are arranged in counter-clockwise order, negative value if clockwise, zero if collinear.

  - ### lineCrossesLine

    public static boolean lineCrossesLine(double a1x, double a1y, double b1x, double b1y, double a2x, double a2y, double b2x, double b2y)
    uses orient method to compute whether two line segments cross

  - ### lineOverlapLine

    public static boolean lineOverlapLine(double a1x, double a1y, double b1x, double b1y, double a2x, double a2y, double b2x, double b2y)
    uses orient method to compute whether two line overlap each other

  - ### lineCrossesLineWithBoundary

    public static boolean lineCrossesLineWithBoundary(double a1x, double a1y, double b1x, double b1y, double a2x, double a2y, double b2x, double b2y)
    uses orient method to compute whether two line segments cross; boundaries included - returning true for lines that terminate on each other.

    e.g., (plus sign) + == true, and (capital 't') T == true

    Use `lineCrossesLine(double, double, double, double, double, double, double, double)` to exclude lines that terminate on each other from the truth table