org.apache.lucene.spatial3d

Class Geo3DDocValuesField

java.lang.Object

org.apache.lucene.document.Field

org.apache.lucene.spatial3d.Geo3DDocValuesField

All Implemented Interfaces:

IndexableField

public class Geo3DDocValuesField
extends Field

An per-document 3D location field.

Sorting by distance is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for common operations:

• TBD

If you also need query operations, you should add a separate Geo3DPoint instance.

WARNING: Values are indexed with some loss of precision from the original double values (4.190951585769653E-8 for the latitude component and 8.381903171539307E-8 for longitude).

See Also:

Geo3DPoint

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 a Geo3DDocValuesField

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

fieldsData, name, tokenStream, type

Constructor Summary

Constructors

Constructor and Description
Geo3DDocValuesField(String name, double x, double y, double z) Creates a new Geo3DDocValuesField with the specified x, y, and z
Geo3DDocValuesField(String name, GeoPoint point) Creates a new Geo3DDocValuesField with the specified x, y, and z

Method Summary

Modifier and Type	Method and Description
static GeoPoint	decodePoint(long docValue) Decode GeoPoint value from long docvalues value.
static double	decodeXValue(long docValue) Decode X value from long docvalues value.
static double	decodeYValue(long docValue) Decode Y value from long docvalues value.
static double	decodeZValue(long docValue) Decode Z value from long docvalues value.
static long	encodePoint(double x, double y, double z) Encode a point.
static long	encodePoint(GeoPoint point) Encode a point.
static SortField	newDistanceSort(String field, double latitude, double longitude, double maxRadiusMeters) Creates a SortField for sorting by distance within a circle.
static SortField	newOutsideBoxSort(String field, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude) Creates a SortField for sorting by outside distance from a box.
static SortField	newOutsideDistanceSort(String field, double latitude, double longitude, double maxRadiusMeters) Creates a SortField for sorting by outside distance from a circle.
static SortField	newOutsideLargePolygonSort(String field, Polygon... polygons) Creates a SortField for sorting by outside distance from a large polygon.
static SortField	newOutsidePathSort(String field, double[] pathLatitudes, double[] pathLongitudes, double pathWidthMeters) Creates a SortField for sorting by outside distance from a path.
static SortField	newOutsidePolygonSort(String field, Polygon... polygons) Creates a SortField for sorting by outside distance from a polygon.
static SortField	newPathSort(String field, double[] pathLatitudes, double[] pathLongitudes, double pathWidthMeters) Creates a SortField for sorting by distance along a path.
static double	roundDownX(double startValue) Round the provided X value down, by encoding it, decrementing it, and unencoding it.
static double	roundDownY(double startValue) Round the provided Y value down, by encoding it, decrementing it, and unencoding it.
static double	roundDownZ(double startValue) Round the provided Z value down, by encoding it, decrementing it, and unencoding it.
static double	roundUpX(double startValue) Round the provided X value up, by encoding it, incrementing it, and unencoding it.
static double	roundUpY(double startValue) Round the provided Y value up, by encoding it, incrementing it, and unencoding it.
static double	roundUpZ(double startValue) Round the provided Z value up, by encoding it, incrementing it, and unencoding it.
void	setLocationValue(double x, double y, double z) Change the values of this field
void	setLocationValue(GeoPoint point) Change the values of this field
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

TYPE

public static final FieldType TYPE

Type for a Geo3DDocValuesField

Each value stores a 64-bit long where the three values (x, y, and z) are given 21 bits each. Each 21-bit value represents the maximum extent in that dimension for the WGS84 planet model.

Constructor Detail

Geo3DDocValuesField

public Geo3DDocValuesField(String name,
                           GeoPoint point)

Creates a new Geo3DDocValuesField with the specified x, y, and z

Parameters:

name - field name

point - is the point.

Throws:

IllegalArgumentException - if the field name is null or the point is out of bounds

Geo3DDocValuesField

public Geo3DDocValuesField(String name,
                           double x,
                           double y,
                           double z)

Creates a new Geo3DDocValuesField with the specified x, y, and z

Parameters:

name - field name

x - is the x value for the point.

y - is the y value for the point.

z - is the z value for the point.

Throws:

IllegalArgumentException - if the field name is null or x, y, or z are out of bounds

Method Detail

setLocationValue

public void setLocationValue(GeoPoint point)

Change the values of this field

Parameters:

point - is the point.

Throws:

IllegalArgumentException - if the point is out of bounds

setLocationValue

public void setLocationValue(double x,
                             double y,
                             double z)

Change the values of this field

Parameters:

x - is the x value for the point.

y - is the y value for the point.

z - is the z value for the point.

Throws:

IllegalArgumentException - if x, y, or z are out of bounds

encodePoint

public static long encodePoint(GeoPoint point)

Encode a point.

Parameters:

point - is the point

Returns:

the encoded long

encodePoint

public static long encodePoint(double x,
                               double y,
                               double z)

Encode a point.

Parameters:

x - is the x value

y - is the y value

z - is the z value

Returns:

the encoded long

decodePoint

public static GeoPoint decodePoint(long docValue)

Decode GeoPoint value from long docvalues value.

Parameters:

docValue - is the doc values value.

Returns:

the GeoPoint.

decodeXValue

public static double decodeXValue(long docValue)

Decode X value from long docvalues value.

Parameters:

docValue - is the doc values value.

Returns:

the x value.

decodeYValue

public static double decodeYValue(long docValue)

Decode Y value from long docvalues value.

Parameters:

docValue - is the doc values value.

Returns:

the y value.

decodeZValue

public static double decodeZValue(long docValue)

Decode Z value from long docvalues value.

Parameters:

docValue - is the doc values value.

Returns:

the z value.

roundDownX

public static double roundDownX(double startValue)

Round the provided X value down, by encoding it, decrementing it, and unencoding it.

Parameters:

startValue - is the starting value.

Returns:

the rounded value.

roundUpX

public static double roundUpX(double startValue)

Round the provided X value up, by encoding it, incrementing it, and unencoding it.

Parameters:

startValue - is the starting value.

Returns:

the rounded value.

roundDownY

public static double roundDownY(double startValue)

Round the provided Y value down, by encoding it, decrementing it, and unencoding it.

Parameters:

startValue - is the starting value.

Returns:

the rounded value.

roundUpY

public static double roundUpY(double startValue)

Round the provided Y value up, by encoding it, incrementing it, and unencoding it.

Parameters:

startValue - is the starting value.

Returns:

the rounded value.

roundDownZ

public static double roundDownZ(double startValue)

Round the provided Z value down, by encoding it, decrementing it, and unencoding it.

Parameters:

startValue - is the starting value.

Returns:

the rounded value.

roundUpZ

public static double roundUpZ(double startValue)

Round the provided Z value up, by encoding it, incrementing it, and unencoding it.

Parameters:

startValue - is the starting value.

Returns:

the rounded value.

toString

public String toString()

Overrides:

toString in class Field

newDistanceSort

public static SortField newDistanceSort(String field,
                                        double latitude,
                                        double longitude,
                                        double maxRadiusMeters)

Creates a SortField for sorting by distance within a circle.

This sort orders documents by ascending distance from the location. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance from the circle center is used.

Parameters:

field - field name. must not 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.

maxRadiusMeters - is the maximum radius in meters.

Returns:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or circle has invalid coordinates.

newPathSort

public static SortField newPathSort(String field,
                                    double[] pathLatitudes,
                                    double[] pathLongitudes,
                                    double pathWidthMeters)

Creates a SortField for sorting by distance along a path.

This sort orders documents by ascending distance along the described path. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance along the path is used.

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:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or path has invalid coordinates.

newOutsideDistanceSort

public static SortField newOutsideDistanceSort(String field,
                                               double latitude,
                                               double longitude,
                                               double maxRadiusMeters)

Creates a SortField for sorting by outside distance from a circle.

This sort orders documents by ascending outside distance from the circle. Points within the circle have distance 0.0. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance to the circle is used.

Parameters:

field - field name. must not 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.

maxRadiusMeters - is the maximum radius in meters.

Returns:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or location has invalid coordinates.

newOutsideBoxSort

public static SortField newOutsideBoxSort(String field,
                                          double minLatitude,
                                          double maxLatitude,
                                          double minLongitude,
                                          double maxLongitude)

Creates a SortField for sorting by outside distance from a box.

This sort orders documents by ascending outside distance from the box. Points within the box have distance 0.0. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance to the box is used.

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:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or box has invalid coordinates.

newOutsidePolygonSort

public static SortField newOutsidePolygonSort(String field,
                                              Polygon... polygons)

Creates a SortField for sorting by outside distance from a polygon.

This sort orders documents by ascending outside distance from the polygon. Points within the polygon have distance 0.0. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance to the polygon is used.

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:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or polygon has invalid coordinates.

newOutsideLargePolygonSort

public static SortField newOutsideLargePolygonSort(String field,
                                                   Polygon... polygons)

Creates a SortField for sorting by outside distance from a large polygon. This differs from the related newOutsideLargePolygonSort in that it does little or no legality checking and is optimized for very large numbers of polygon edges.

This sort orders documents by ascending outside distance from the polygon. Points within the polygon have distance 0.0. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance to the polygon is used.

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:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or polygon has invalid coordinates.

newOutsidePathSort

public static SortField newOutsidePathSort(String field,
                                           double[] pathLatitudes,
                                           double[] pathLongitudes,
                                           double pathWidthMeters)

Creates a SortField for sorting by outside distance from a path.

This sort orders documents by ascending outside distance from the described path. Points within the path are given the distance of 0.0. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance from the path is used.

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:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or path has invalid coordinates.