org.apache.lucene.spatial3d.geom.DistanceStyle Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of lucene-spatial3d Show documentation
Show all versions of lucene-spatial3d Show documentation
Apache Lucene (module: spatial3d)
/*
* 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.geom;
/**
* Distance computation styles, supporting various ways of computing distance to shapes.
*
* @lucene.experimental
*/
public interface DistanceStyle {
// convenient access to built-in styles:
/** Arc distance calculator */
public static final ArcDistance ARC = ArcDistance.INSTANCE;
/** Linear distance calculator */
public static final LinearDistance LINEAR = LinearDistance.INSTANCE;
/** Linear distance squared calculator */
public static final LinearSquaredDistance LINEAR_SQUARED = LinearSquaredDistance.INSTANCE;
/** Normal distance calculator */
public static final NormalDistance NORMAL = NormalDistance.INSTANCE;
/** Normal distance squared calculator */
public static final NormalSquaredDistance NORMAL_SQUARED = NormalSquaredDistance.INSTANCE;
/**
* Compute the distance from a point to another point.
*
* @param point1 Starting point
* @param point2 Final point
* @return the distance
*/
public default double computeDistance(final GeoPoint point1, final GeoPoint point2) {
return computeDistance(point1, point2.x, point2.y, point2.z);
}
/**
* Compute the distance from a point to another point.
*
* @param point1 Starting point
* @param x2 Final point x
* @param y2 Final point y
* @param z2 Final point z
* @return the distance
*/
public double computeDistance(
final GeoPoint point1, final double x2, final double y2, final double z2);
/**
* Compute the distance from a plane to a point.
*
* @param planetModel The planet model
* @param plane The plane
* @param point The point
* @param bounds are the plane bounds
* @return the distance
*/
public default double computeDistance(
final PlanetModel planetModel,
final Plane plane,
final GeoPoint point,
final Membership... bounds) {
return computeDistance(planetModel, plane, point.x, point.y, point.z, bounds);
}
/**
* Compute the distance from a plane to a point.
*
* @param planetModel The planet model
* @param plane The plane
* @param x The point x
* @param y The point y
* @param z The point z
* @param bounds are the plane bounds
* @return the distance
*/
public double computeDistance(
final PlanetModel planetModel,
final Plane plane,
final double x,
final double y,
final double z,
final Membership... bounds);
/**
* Convert a distance to a form meant for aggregation. This is meant to be used in conjunction
* with aggregateDistances() and fromAggregationForm(). Distances should be converted to
* aggregation form before aggregation is attempted, and they should be converted back from
* aggregation form to yield a final result.
*
* @param distance is an output of computeDistance().
* @return the distance, converted to aggregation form.
*/
public default double toAggregationForm(final double distance) {
return distance;
}
/**
* Aggregate two distances together to produce a "sum". This is usually just an addition
* operation, but in the case of squared distances it is more complex. Distances should be
* converted to aggregation form before aggregation is attempted, and they should be converted
* back from aggregation form to yield a final result.
*
* @param distances are the distances to aggregate.
* @return the combined aggregation form distance.
*/
public default double aggregateDistances(final double... distances) {
double rval = 0.0;
for (final double distance : distances) {
rval += distance;
}
return rval;
}
/**
* Convert an aggregation form distance value back to an actual distance. This is meant to be used
* in conjunction with toAggregationForm() and aggregateDistances(). Distances should be converted
* to aggregation form before aggregation is attempted, and they should be converted back from
* aggregation form to yield a final result.
*
* @param aggregateDistance is the aggregate form of the distance.
* @return the combined distance.
*/
public default double fromAggregationForm(final double aggregateDistance) {
return aggregateDistance;
}
// The following methods are used to go from a distance value back to something
// that can be used to construct a constrained shape.
/**
* Find a GeoPoint, at a specified distance from a starting point, within the specified bounds.
* The GeoPoint must be in the specified plane.
*
* @param planetModel is the planet model.
* @param distanceValue is the distance to set the new point at, measured from point1 and on the
* way to point2.
* @param startPoint is the starting point.
* @param plane is the plane that the point must be in.
* @param bounds are the constraints on where the point can be found.
* @return zero, one, or two points at the proper distance from startPoint.
*/
public GeoPoint[] findDistancePoints(
final PlanetModel planetModel,
final double distanceValue,
final GeoPoint startPoint,
final Plane plane,
final Membership... bounds);
/**
* Given a distance metric, find the minimum arc distance represented by that distance metric.
*
* @param planetModel is the planet model.
* @param distanceValue is the distance metric.
* @return the minimum arc distance that that distance value can represent given the planet model.
*/
public double findMinimumArcDistance(final PlanetModel planetModel, final double distanceValue);
/**
* Given a distance metric, find the maximum arc distance represented by the distance metric.
*
* @param planetModel is the planet model.
* @param distanceValue is the distance metric.
* @return the maximum arc distance that that distance value can represent given the planet model.
*/
public double findMaximumArcDistance(final PlanetModel planetModel, final double distanceValue);
}