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
`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 and 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
`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, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, 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`