org.apache.lucene.document

Class LatLonPoint

java.lang.Object

org.apache.lucene.document.Field

org.apache.lucene.document.LatLonPoint

All Implemented Interfaces:

IndexableField

public class LatLonPoint
extends Field

An indexed location field.

Finding all documents within a range at search time is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for creating common queries:

• newBoxQuery() for matching points within a bounding box.
• newDistanceQuery() for matching points within a specified distance.
• newPolygonQuery() for matching points within an arbitrary polygon.

WARNING: Values are indexed with some loss of precision, incurring up to 1E-7 error from the original double values.

See Also:

PointValues

Nested Class Summary

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

Field.Store

Field Summary

Fields

Modifier and Type	Field and Description
static FieldType	TYPE Type for an indexed LatLonPoint

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

boost, fieldsData, name, tokenStream, type

Constructor Summary

Constructors

Constructor and Description
LatLonPoint(String name, double latitude, double longitude) Creates a new LatLonPoint with the specified latitude and longitude

Method Summary

Modifier and Type	Method and Description
static double	decodeLatitude(byte[] src, int offset) Turns quantized value from byte array back into a double.
static double	decodeLatitude(int encoded) Turns quantized value from encodeLatitude(double) back into a double.
static double	decodeLongitude(byte[] src, int offset) Turns quantized value from byte array back into a double.
static double	decodeLongitude(int encoded) Turns quantized value from encodeLongitude(double) back into a double.
static int	encodeLatitude(double latitude) Quantizes double (64 bit) latitude into 32 bits
static int	encodeLongitude(double longitude) Quantizes double (64 bit) longitude into 32 bits
static Query	newBoxQuery(String field, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude) Create a query for matching a bounding box.
static Query	newDistanceQuery(String field, double latitude, double longitude, double radiusMeters) Create a query for matching points within the specified distance of the supplied location.
static Query	newPolygonQuery(String field, double[] polyLats, double[] polyLons) Create a query for matching a polygon.
void	setLocationValue(double latitude, double longitude) Change the values of this field
String	toString()

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

binaryValue, boost, fieldType, name, numericValue, readerValue, setBoost, 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

TYPE

public static final FieldType TYPE

Type for an indexed LatLonPoint

Each point stores two dimensions with 4 bytes per dimension.

Constructor Detail

LatLonPoint

public LatLonPoint(String name,
                   double latitude,
                   double longitude)

Creates a new LatLonPoint with the specified latitude and longitude

Parameters:

name - field name

latitude - latitude value: must be within standard +/-90 coordinate bounds.

longitude - longitude value: must be within standard +/-180 coordinate bounds.

Throws:

IllegalArgumentException - if the field name is null or latitude or longitude are out of bounds

Method Detail

setLocationValue

public void setLocationValue(double latitude,
                             double longitude)

Change the values of this field

Parameters:

latitude - latitude value: must be within standard +/-90 coordinate bounds.

longitude - longitude value: must be within standard +/-180 coordinate bounds.

Throws:

IllegalArgumentException - if latitude or longitude are out of bounds

toString

public String toString()

Overrides:

toString in class Field

encodeLatitude

public static int encodeLatitude(double latitude)

Quantizes double (64 bit) latitude into 32 bits

Parameters:

latitude - latitude value: must be within standard +/-90 coordinate bounds.

Returns:

encoded value as a 32-bit int

Throws:

IllegalArgumentException - if latitude is out of bounds

encodeLongitude

public static int encodeLongitude(double longitude)

Quantizes double (64 bit) longitude into 32 bits

Parameters:

longitude - longitude value: must be within standard +/-180 coordinate bounds.

Returns:

encoded value as a 32-bit int

Throws:

IllegalArgumentException - if longitude is out of bounds

decodeLatitude

public static double decodeLatitude(int encoded)

Turns quantized value from encodeLatitude(double) back into a double.

Parameters:

encoded - encoded value: 32-bit quantized value.

Returns:

decoded latitude value.

decodeLatitude

public static double decodeLatitude(byte[] src,
                                    int offset)

Turns quantized value from byte array back into a double.

Parameters:

src - byte array containing 4 bytes to decode at offset

offset - offset into src to decode from.

Returns:

decoded latitude value.

decodeLongitude

public static double decodeLongitude(int encoded)

Turns quantized value from encodeLongitude(double) back into a double.

Parameters:

encoded - encoded value: 32-bit quantized value.

Returns:

decoded longitude value.

decodeLongitude

public static double decodeLongitude(byte[] src,
                                     int offset)

Turns quantized value from byte array back into a double.

Parameters:

src - byte array containing 4 bytes to decode at offset

offset - offset into src to decode from.

Returns:

decoded longitude value.

newBoxQuery

public static Query newBoxQuery(String field,
                                double minLatitude,
                                double maxLatitude,
                                double minLongitude,
                                double maxLongitude)

Create a query for matching a bounding box.

The box may cross over the dateline.

Parameters:

field - field name. cannot 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.

newDistanceQuery

public static Query newDistanceQuery(String field,
                                     double latitude,
                                     double longitude,
                                     double radiusMeters)

Create a query for matching points within the specified distance of the supplied location.

Parameters:

field - field name. cannot be null.

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.

newPolygonQuery

public static Query newPolygonQuery(String field,
                                    double[] polyLats,
                                    double[] polyLons)

Create a query for matching a polygon.

The supplied polyLats/polyLons must be clockwise or counter-clockwise.

Parameters:

field - field name. cannot be null.

polyLats - latitude values for points of the polygon: must be within standard +/-90 coordinate bounds.

polyLons - longitude values for points of the polygon: must be within standard +/-180 coordinate bounds.

Returns:

query matching points within this polygon

Throws:

IllegalArgumentException - if field is null, polyLats is null or has invalid coordinates, polyLons is null or has invalid coordinates, if polyLats has a different length than polyLons, if the polygon has less than 4 points, or if polygon is not closed (first and last points should be the same)