Interface ItemDistance

1	/*
2	* Copyright (c) 2016 Martin Davis.
3	*
4	* All rights reserved. This program and the accompanying materials
5	* are made available under the terms of the Eclipse Public License 2.0
6	* and Eclipse Distribution License v. 1.0 which accompanies this distribution.
7	* The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v20.html
8	* and the Eclipse Distribution License is available at
9	*
10	* http://www.eclipse.org/org/documents/edl-v10.php.
11	*/
12
13	package org.locationtech.jts.index.strtree;
14
15
16	/**
17	* A function method which computes the distance
18	* between two {@link ItemBoundable}s in an {@link STRtree}.
19	* Used for Nearest Neighbour searches.
20	* <p>
21	* To make a distance function suitable for
22	* querying a single index tree
23	* via {@link STRtree#nearestNeighbour(ItemDistance)} ,
24	* the function should have a non-zero <i>reflexive distance</i>.
25	* That is, if the two arguments are the same object,
26	* the distance returned should be non-zero.
27	* If it is required that only pairs of <b>distinct</b> items be returned,
28	* the distance function must be <i>anti-reflexive</i>,
29	* and must return {@link Double#MAX_VALUE} for identical arguments.
30	*
31	* @author Martin Davis
32	*
33	*/
34	public interface ItemDistance
35	{
36	/**
37	* Computes the distance between two items.
38	*
39	* @param item1
40	* @param item2
41	* @return the distance between the items
42	*
43	* @throws IllegalArgumentException if the metric is not applicable to the arguments
44	*/
45	double distance(ItemBoundable item1, ItemBoundable item2);
46
47	}
48