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 PlanetModel` | `planetModel` | Planet Model for this Geo3DPoint
    `static FieldType` | `TYPE` | Indexing `FieldType`.

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

      `fieldsData, name, tokenStream, 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

    All Methods Static Methods Instance Methods Concrete Methods
    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 Detail

    - #### planetModel

          protected final PlanetModel planetModel

      Planet Model for this Geo3DPoint

    - #### TYPE

          public static final FieldType TYPE

      Indexing `FieldType`.

  - ### Constructor Detail

    - #### 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 Detail

    - #### 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`