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

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