Geo3DPoint (Lucene 10.5.0 spatial3d API)
Description: declaration: package: org.apache.lucene.spatial3d, class: Geo3DPoint

Package org.apache.lucene.spatial3d

# Class Geo3DPoint

java.lang.Object
org.apache.lucene.document.Field
org.apache.lucene.spatial3d.Geo3DPoint

All Implemented Interfaces:
  `IndexableField`

public final class Geo3DPoint extends Field
Add this to a document to index lat/lon or x/y/z point, indexed as a 3D point. Multiple values are allowed: just add multiple Geo3DPoint to the document with the same field name.

This field defines static factory methods for creating a shape query:

- `newShapeQuery()` for matching all points inside a specified shape

See Also:
  - `PointValues`
WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.document.Field

  `Field.Store`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final PlanetModel`
  `planetModel`
  Planet Model for this Geo3DPoint
  `static final FieldType`
  `TYPE`
  Indexing `FieldType`.

  ### Fields inherited from class org.apache.lucene.document.Field

  `fieldsData, name, type`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Geo3DPoint(String name, double lat, double lon)`
  Creates a new Geo3DPoint field with the specified latitude, longitude (in degrees), with default WGS84 PlanetModel.
  `Geo3DPoint(String name, double x, double y, double z)`
  Creates a new Geo3DPoint field with the specified x,y,z, using default WGS84 planet model.
  `Geo3DPoint(String name, PlanetModel planetModel, double latitude, double longitude)`
  Creates a new Geo3DPoint field with the specified latitude, longitude (in degrees), given a planet model.
  `Geo3DPoint(String name, PlanetModel planetModel, double x, double y, double z)`
  Creates a new Geo3DPoint field with the specified x,y,z, and given planet model.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static double`
  `decodeDimension(byte[] value, int offset, PlanetModel planetModel)`
  Decode single dimension
  `static void`
  `encodeDimension(double value, byte[] bytes, int offset, PlanetModel planetModel)`
  Encode single dimension
  `static Query`
  `newBoxQuery(String field, PlanetModel planetModel, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude)`
  Create a query for matching a box.
  `static Query`
  `newDistanceQuery(String field, PlanetModel planetModel, double latitude, double longitude, double radiusMeters)`
  Create a query for matching points within the specified distance of the supplied location.
  `static Query`
  `newLargePolygonQuery(String field, PlanetModel planetModel, Polygon... polygons)`
  Create a query for matching a large polygon.
  `static Query`
  `newPathQuery(String field, double[] pathLatitudes, double[] pathLongitudes, double pathWidthMeters, PlanetModel planetModel)`
  Create a query for matching a path.
  `static Query`
  `newPolygonQuery(String field, PlanetModel planetModel, Polygon... polygons)`
  Create a query for matching a polygon.
  `static Query`
  `newShapeQuery(String field, GeoShape shape)`
  Returns a query matching all points inside the provided shape.
  `String`
  `toString()`

  ### Methods inherited from class org.apache.lucene.document.Field

  `binaryValue, fieldType, getCharSequenceValue, invertableType, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, storedValue, stringValue, tokenStream, tokenStreamValue`

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

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

- ## Field Details

  - ### planetModel

    protected final PlanetModel planetModel
    Planet Model for this Geo3DPoint

  - ### TYPE

    public static final FieldType TYPE
    Indexing `FieldType`.

- ## Constructor Details

  - ### Geo3DPoint

    public Geo3DPoint(String name, double lat, double lon)
    Creates a new Geo3DPoint field with the specified latitude, longitude (in degrees), with default WGS84 PlanetModel.
    Throws:
      `IllegalArgumentException` - if the field name is null or latitude or longitude are out of bounds

  - ### Geo3DPoint

    public Geo3DPoint(String name, double x, double y, double z)
    Creates a new Geo3DPoint field with the specified x,y,z, using default WGS84 planet model.
    Throws:
      `IllegalArgumentException` - if the field name is null or latitude or longitude are out of bounds

  - ### Geo3DPoint

    public Geo3DPoint(String name, PlanetModel planetModel, double x, double y, double z)
    Creates a new Geo3DPoint field with the specified x,y,z, and given planet model.
    Throws:
      `IllegalArgumentException` - if the field name is null or latitude or longitude are out of bounds

  - ### Geo3DPoint

    public Geo3DPoint(String name, PlanetModel planetModel, double latitude, double longitude)
    Creates a new Geo3DPoint field with the specified latitude, longitude (in degrees), given a planet model.
    Throws:
      `IllegalArgumentException` - if the field name is null or latitude or longitude are out of bounds

- ## Method Details

  - ### newDistanceQuery

    public static Query newDistanceQuery(String field, PlanetModel planetModel, double latitude, double longitude, double radiusMeters)
    Create a query for matching points within the specified distance of the supplied location.
    Parameters:
      `field` - field name. must not be null. Note that if `PlanetModel.WGS84` is used, the query is approximate and may have up to 0.5% error.
      `latitude` - latitude at the center: must be within standard +/-90 coordinate bounds.
      `longitude` - longitude at the center: must be within standard +/-180 coordinate bounds.
      `radiusMeters` - maximum distance from the center in meters: must be non-negative and finite.
    Returns:
      query matching points within this distance
    Throws:
      `IllegalArgumentException` - if `field` is null, location has invalid coordinates, or radius is invalid.

  - ### newBoxQuery

    public static Query newBoxQuery(String field, PlanetModel planetModel, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude)
    Create a query for matching a box.

    The box may cross over the dateline.

    Parameters:
      `field` - field name. must not be null.
      `minLatitude` - latitude lower bound: must be within standard +/-90 coordinate bounds.
      `maxLatitude` - latitude upper bound: must be within standard +/-90 coordinate bounds.
      `minLongitude` - longitude lower bound: must be within standard +/-180 coordinate bounds.
      `maxLongitude` - longitude upper bound: must be within standard +/-180 coordinate bounds.
    Returns:
      query matching points within this box
    Throws:
      `IllegalArgumentException` - if `field` is null, or the box has invalid coordinates.

  - ### newPolygonQuery

    public static Query newPolygonQuery(String field, PlanetModel planetModel, Polygon... polygons)
    Create a query for matching a polygon. The polygon should have a limited number of edges (less than 100) and be well-defined, with well-separated vertices.

    The supplied `polygons` must be clockwise on the outside level, counterclockwise on the next level in, etc.

    Parameters:
      `field` - field name. must not be null.
      `polygons` - is the list of polygons to use to construct the query; must be at least one.
    Returns:
      query matching points within this polygon

  - ### newLargePolygonQuery

    public static Query newLargePolygonQuery(String field, PlanetModel planetModel, Polygon... polygons)
    Create a query for matching a large polygon. This differs from the related newPolygonQuery in that it does little or no legality checking and is optimized for very large numbers of polygon edges.

    The supplied `polygons` must be clockwise on the outside level, counterclockwise on the next level in, etc.

    Parameters:
      `field` - field name. must not be null.
      `polygons` - is the list of polygons to use to construct the query; must be at least one.
    Returns:
      query matching points within this polygon

  - ### newPathQuery

    public static Query newPathQuery(String field, double[] pathLatitudes, double[] pathLongitudes, double pathWidthMeters, PlanetModel planetModel)
    Create a query for matching a path.
    Parameters:
      `field` - field name. must not be null.
      `pathLatitudes` - latitude values for points of the path: must be within standard +/-90 coordinate bounds.
      `pathLongitudes` - longitude values for points of the path: must be within standard +/-180 coordinate bounds.
      `pathWidthMeters` - width of the path in meters.
    Returns:
      query matching points within this polygon

  - ### encodeDimension

    public static void encodeDimension(double value, byte[] bytes, int offset, PlanetModel planetModel)
    Encode single dimension

  - ### decodeDimension

    public static double decodeDimension(byte[] value, int offset, PlanetModel planetModel)
    Decode single dimension

  - ### newShapeQuery

    public static Query newShapeQuery(String field, GeoShape shape)
    Returns a query matching all points inside the provided shape.
    Parameters:
      `field` - field name. must not be `null`.
      `shape` - Which `GeoShape` to match

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Field`