2 // Java Spatial Index Library
\r
3 // Copyright (C) 2002-2005 Infomatiq Limited.
\r
5 // This library is free software; you can redistribute it and/or
\r
6 // modify it under the terms of the GNU Lesser General Public
\r
7 // License as published by the Free Software Foundation; either
\r
8 // version 2.1 of the License, or (at your option) any later version.
\r
10 // This library is distributed in the hope that it will be useful,
\r
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
\r
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
\r
13 // Lesser General Public License for more details.
\r
15 // You should have received a copy of the GNU Lesser General Public
\r
16 // License along with this library; if not, write to the Free Software
\r
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
\r
19 package com.infomatiq.jsi;
\r
21 import gnu.trove.TIntProcedure;
\r
23 import java.util.Properties;
\r
26 * Defines methods that must be implemented by all
\r
27 * spatial indexes. This includes the RTree and its variants.
\r
29 * @author aled@sourceforge.net
\r
32 public interface SpatialIndex {
\r
35 * Initializes any implementation dependent properties
\r
36 * of the spatial index. For example, RTree implementations
\r
37 * will have a NodeSize property.
\r
39 * @param props The set of properties used to initialize the spatial index.
\r
41 public void init(Properties props);
\r
44 * Adds a new rectangle to the spatial index
\r
46 * @param r The rectangle to add to the spatial index.
\r
47 * @param id The ID of the rectangle to add to the spatial index.
\r
48 * The result of adding more than one rectangle with
\r
49 * the same ID is undefined.
\r
51 public void add(Rectangle r, int id);
\r
54 * Deletes a rectangle from the spatial index
\r
56 * @param r The rectangle to delete from the spatial index
\r
57 * @param id The ID of the rectangle to delete from the spatial
\r
60 * @return true if the rectangle was deleted
\r
61 * false if the rectangle was not found, or the
\r
62 * rectangle was found but with a different ID
\r
64 public boolean delete(Rectangle r, int id);
\r
67 * Finds the nearest rectangles to the passed rectangle and calls
\r
68 * v.execute(id) for each one.
\r
70 * If multiple rectangles are equally near, they will
\r
73 * @param p The point for which this method finds the
\r
74 * nearest neighbours.
\r
76 * @param v The IntProcedure whose execute() method is is called
\r
77 * for each nearest neighbour.
\r
79 * @param furthestDistance The furthest distance away from the rectangle
\r
80 * to search. Rectangles further than this will not be found.
\r
82 * This should be as small as possible to minimise
\r
85 * Use Float.POSITIVE_INFINITY to guarantee that the nearest rectangle is found,
\r
86 * no matter how far away, although this will slow down the algorithm.
\r
88 public void nearest(Point p, TIntProcedure v, float furthestDistance);
\r
91 * Finds the N nearest rectangles to the passed rectangle, and calls
\r
92 * execute(id, distance) on each one, in order of increasing distance.
\r
94 * Note that fewer than N rectangles may be found if fewer entries
\r
95 * exist within the specified furthest distance, or more if rectangles
\r
96 * N and N+1 have equal distances.
\r
98 * @param p The point for which this method finds the
\r
99 * nearest neighbours.
\r
101 * @param v The IntfloatProcedure whose execute() method is is called
\r
102 * for each nearest neighbour.
\r
104 * @param n The desired number of rectangles to find (but note that
\r
105 * fewer or more may be returned)
\r
107 * @param distance The furthest distance away from the rectangle
\r
108 * to search. Rectangles further than this will not be found.
\r
110 * This should be as small as possible to minimise
\r
113 * Use Float.POSITIVE_INFINITY to guarantee that the nearest rectangle is found,
\r
114 * no matter how far away, although this will slow down the algorithm.
\r
116 public void nearestN(Point p, TIntProcedure v, int n, float distance);
\r
119 * Same as nearestN, except the found rectangles are not returned
\r
120 * in sorted order. This will be faster, if sorting is not required
\r
122 public void nearestNUnsorted(Point p, TIntProcedure v, int n, float distance);
\r
125 * Finds all rectangles that intersect the passed rectangle.
\r
127 * @param r The rectangle for which this method finds
\r
128 * intersecting rectangles.
\r
130 * @param ip The IntProcedure whose execute() method is is called
\r
131 * for each intersecting rectangle.
\r
133 public void intersects(Rectangle r, TIntProcedure ip);
\r
136 * Finds all rectangles contained by the passed rectangle.
\r
138 * @param r The rectangle for which this method finds
\r
139 * contained rectangles.
\r
141 * @param ip The procedure whose visit() method is is called
\r
142 * for each contained rectangle.
\r
144 public void contains(Rectangle r, TIntProcedure ip);
\r
147 * Returns the number of entries in the spatial index
\r
153 * Returns the bounds of all the entries in the spatial index,
\r
154 * or null if there are no entries.
\r
156 public Rectangle getBounds();
\r
159 * Returns a string identifying the type of
\r
160 * spatial index, and the version number,
\r
161 * eg "SimpleIndex-0.1"
\r
163 public String getVersion();
\r