org.apache.lucene.spatial3d.Geo3DDocValuesField Maven / Gradle / Ivy
Show all versions of lucene-spatial3d Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.lucene.spatial3d;
import org.apache.lucene.document.Field;
import org.apache.lucene.document.FieldType;
import org.apache.lucene.geo.Polygon;
import org.apache.lucene.index.DocValuesType;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.search.FieldDoc;
import org.apache.lucene.search.SortField;
import org.apache.lucene.spatial3d.geom.GeoDistanceShape;
import org.apache.lucene.spatial3d.geom.GeoOutsideDistance;
import org.apache.lucene.spatial3d.geom.GeoPoint;
import org.apache.lucene.spatial3d.geom.PlanetModel;
/**
* 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 {@link Geo3DPoint} instance.
*
*
WARNING: Values are indexed with some loss of precision from the original {@code
* double} values (4.190951585769653E-8 for the latitude component and 8.381903171539307E-8 for
* longitude).
*
* @see Geo3DPoint
*/
public class Geo3DDocValuesField extends Field {
private final PlanetModel planetModel;
/**
* 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 defined planet model.
*/
public static final FieldType TYPE = new FieldType();
static {
TYPE.setDocValuesType(DocValuesType.SORTED_NUMERIC);
TYPE.freeze();
}
/**
* Creates a new Geo3DDocValuesField with the specified x, y, and z
*
* @param name field name
* @param point is the point.
* @throws IllegalArgumentException if the field name is null or the point is out of bounds
*/
public Geo3DDocValuesField(
final String name, final GeoPoint point, final PlanetModel planetModel) {
this(name, TYPE, planetModel);
setLocationValue(point);
}
/**
* Creates a new Geo3DDocValuesField with the specified x, y, and z
*
* @param name field name
* @param x is the x value for the point.
* @param y is the y value for the point.
* @param 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
*/
public Geo3DDocValuesField(
final String name,
final double x,
final double y,
final double z,
final PlanetModel planetModel) {
this(name, TYPE, planetModel);
setLocationValue(x, y, z);
}
private Geo3DDocValuesField(
final String name, final FieldType type, final PlanetModel planetModel) {
super(name, TYPE);
this.planetModel = planetModel;
}
/**
* Change the values of this field
*
* @param point is the point.
* @throws IllegalArgumentException if the point is out of bounds
*/
public void setLocationValue(final GeoPoint point) {
fieldsData = Long.valueOf(planetModel.getDocValueEncoder().encodePoint(point));
}
/**
* Change the values of this field
*
* @param x is the x value for the point.
* @param y is the y value for the point.
* @param z is the z value for the point.
* @throws IllegalArgumentException if x, y, or z are out of bounds
*/
public void setLocationValue(final double x, final double y, final double z) {
fieldsData = Long.valueOf(planetModel.getDocValueEncoder().encodePoint(x, y, z));
}
/** helper: checks a fieldinfo and throws exception if its definitely not a Geo3DDocValuesField */
static void checkCompatible(FieldInfo fieldInfo) {
// dv properties could be "unset", if you e.g. used only StoredField with this same name in the
// segment.
if (fieldInfo.getDocValuesType() != DocValuesType.NONE
&& fieldInfo.getDocValuesType() != TYPE.docValuesType()) {
throw new IllegalArgumentException(
"field=\""
+ fieldInfo.name
+ "\" was indexed with docValuesType="
+ fieldInfo.getDocValuesType()
+ " but this type has docValuesType="
+ TYPE.docValuesType()
+ ", is the field really a Geo3DDocValuesField?");
}
}
@Override
public String toString() {
StringBuilder result = new StringBuilder();
result.append(getClass().getSimpleName());
result.append(" <");
result.append(name);
result.append(':');
long currentValue = (Long) fieldsData;
result.append(planetModel.getDocValueEncoder().decodeXValue(currentValue));
result.append(',');
result.append(planetModel.getDocValueEncoder().decodeYValue(currentValue));
result.append(',');
result.append(planetModel.getDocValueEncoder().decodeZValue(currentValue));
result.append('>');
return result.toString();
}
/**
* Creates a SortField for sorting by distance within a circle.
*
*
This sort orders documents by ascending distance from the location. The value returned in
* {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param latitude latitude at the center: must be within standard +/-90 coordinate bounds.
* @param longitude longitude at the center: must be within standard +/-180 coordinate bounds.
* @param maxRadiusMeters is the maximum radius in meters.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or circle has invalid coordinates.
*/
public static SortField newDistanceSort(
final String field,
final double latitude,
final double longitude,
final double maxRadiusMeters,
final PlanetModel planetModel) {
final GeoDistanceShape shape =
Geo3DUtil.fromDistance(planetModel, latitude, longitude, maxRadiusMeters);
return new Geo3DPointSortField(field, planetModel, shape);
}
/**
* 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 {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param pathLatitudes latitude values for points of the path: must be within standard +/-90
* coordinate bounds.
* @param pathLongitudes longitude values for points of the path: must be within standard +/-180
* coordinate bounds.
* @param pathWidthMeters width of the path in meters.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or path has invalid coordinates.
*/
public static SortField newPathSort(
final String field,
final double[] pathLatitudes,
final double[] pathLongitudes,
final double pathWidthMeters,
final PlanetModel planetModel) {
final GeoDistanceShape shape =
Geo3DUtil.fromPath(planetModel, pathLatitudes, pathLongitudes, pathWidthMeters);
return new Geo3DPointSortField(field, planetModel, shape);
}
// Outside distances
/**
* 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 {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param latitude latitude at the center: must be within standard +/-90 coordinate bounds.
* @param longitude longitude at the center: must be within standard +/-180 coordinate bounds.
* @param maxRadiusMeters is the maximum radius in meters.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or location has invalid coordinates.
*/
public static SortField newOutsideDistanceSort(
final String field,
final double latitude,
final double longitude,
final double maxRadiusMeters,
final PlanetModel planetModel) {
final GeoOutsideDistance shape =
Geo3DUtil.fromDistance(planetModel, latitude, longitude, maxRadiusMeters);
return new Geo3DPointOutsideSortField(field, planetModel, shape);
}
/**
* 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 {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param minLatitude latitude lower bound: must be within standard +/-90 coordinate bounds.
* @param maxLatitude latitude upper bound: must be within standard +/-90 coordinate bounds.
* @param minLongitude longitude lower bound: must be within standard +/-180 coordinate bounds.
* @param maxLongitude longitude upper bound: must be within standard +/-180 coordinate bounds.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or box has invalid coordinates.
*/
public static SortField newOutsideBoxSort(
final String field,
final double minLatitude,
final double maxLatitude,
final double minLongitude,
final double maxLongitude,
final PlanetModel planetModel) {
final GeoOutsideDistance shape =
Geo3DUtil.fromBox(planetModel, minLatitude, maxLatitude, minLongitude, maxLongitude);
return new Geo3DPointOutsideSortField(field, planetModel, shape);
}
/**
* 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 {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param polygons is the list of polygons to use to construct the query; must be at least one.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or polygon has invalid coordinates.
*/
public static SortField newOutsidePolygonSort(
final String field, final PlanetModel planetModel, final Polygon... polygons) {
final GeoOutsideDistance shape = Geo3DUtil.fromPolygon(planetModel, polygons);
return new Geo3DPointOutsideSortField(field, planetModel, shape);
}
/**
* 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 {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param polygons is the list of polygons to use to construct the query; must be at least one.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or polygon has invalid coordinates.
*/
public static SortField newOutsideLargePolygonSort(
final String field, final PlanetModel planetModel, final Polygon... polygons) {
final GeoOutsideDistance shape = Geo3DUtil.fromLargePolygon(planetModel, polygons);
return new Geo3DPointOutsideSortField(field, planetModel, shape);
}
/**
* 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 {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param pathLatitudes latitude values for points of the path: must be within standard +/-90
* coordinate bounds.
* @param pathLongitudes longitude values for points of the path: must be within standard +/-180
* coordinate bounds.
* @param pathWidthMeters width of the path in meters.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or path has invalid coordinates.
*/
public static SortField newOutsidePathSort(
final String field,
final double[] pathLatitudes,
final double[] pathLongitudes,
final double pathWidthMeters,
final PlanetModel planetModel) {
final GeoOutsideDistance shape =
Geo3DUtil.fromPath(planetModel, pathLatitudes, pathLongitudes, pathWidthMeters);
return new Geo3DPointOutsideSortField(field, planetModel, shape);
}
}