src/com/infomatiq/jsi/SpatialIndex.java

   1 //   SpatialIndex.java
   2 //   Java Spatial Index Library
   3 //   Copyright (C) 2002 Infomatiq Limited
   4 //
   5 //  This library is free software; you can redistribute it and/or
   6 //  modify it under the terms of the GNU Lesser General Public
   7 //  License as published by the Free Software Foundation; either
   8 //  version 2.1 of the License, or (at your option) any later version.
   9 //
  10 //  This library is distributed in the hope that it will be useful,
  11 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 //  Lesser General Public License for more details.
  14 //
  15 //  You should have received a copy of the GNU Lesser General Public
  16 //  License along with this library; if not, write to the Free Software
  17 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18
  19 package com.infomatiq.jsi;
  20
  21 import java.util.Properties;
  22
  23 /**
  24  * Defines methods that must be implemented by all
  25  * spatial indexes. This includes the RTree and its variants.
  26  *
  27  * @author  aled.morris@infomatiq.co.uk
  28  * @version 1.0b2
  29  */
  30 public interface SpatialIndex {
  31
  32   /**
  33    * Initializes any implementation dependent properties
  34    * of the spatial index. For example, RTree implementations
  35    * will have a NodeSize property.
  36    *
  37    * @param props The set of properties used to initialize the spatial index.
  38    */
  39   public void init(Properties props);
  40
  41   /**
  42    * Adds a new rectangle to the spatial index
  43    *
  44    * @param r  The rectangle to add to the spatial index.
  45    * @param id The ID of the rectangle to add to the spatial index.
  46    *           The result of adding more than one rectangle with
  47    *           the same ID is undefined.
  48    */
  49   public void add(Rectangle r, int id);
  50
  51   /**
  52    * Deletes a rectangle from the spatial index
  53    *
  54    * @param r  The rectangle to delete from the spatial index
  55    * @param id The ID of the rectangle to delete from the spatial
  56    *           index
  57    *
  58    * @return true  if the rectangle was deleted
  59    *         false if the rectangle was not found, or the
  60    *               rectangle was found but with a different ID
  61    */
  62   public boolean delete(Rectangle r, int id);
  63
  64   /**
  65    * Finds all rectangles that are nearest to the passed rectangle, and calls
  66    * execute() on the passed IntProcedure for each one.
  67    *
  68    * @param p The point for which this method finds the
  69    * nearest neighbours.
  70    *
  71    * @param ip The IntProcedure whose execute() method is is called
  72    * for each nearest neighbour.
  73    *
  74    * @param distance The furthest distance away from the rectangle
  75    * to search. Rectangles further than this will not be found.
  76    *
  77    * This should be as small as possible to minimise
  78    * the search time.
  79    *
  80    * Use Float.POSITIVE_INFINITY to guarantee that the nearest rectangle is found,
  81    * no matter how far away, although this will slow down the algorithm.
  82    */
  83   public void nearest(Point p, IntProcedure v, float distance);
  84
  85   /**
  86    * Finds all rectangles that intersect the passed rectangle.
  87    *
  88    * @param  r The rectangle for which this method finds
  89    *           intersecting rectangles.
  90    *
  91    * @param ip The IntProcedure whose execute() method is is called
  92    *           for each intersecting rectangle.
  93    */
  94   public void intersects(Rectangle r, IntProcedure ip);
  95
  96   /**
  97    * Finds all rectangles contained by the passed rectangle.
  98    *
  99    * @param r The rectangle for which this method finds
 100    *           contained rectangles.
 101    *
 102    * @param v The visitor whose visit() method is is called
 103    *           for each contained rectangle.
 104    */
 105   public void contains(Rectangle r, IntProcedure ip);
 106
 107   /**
 108    * Returns the number of entries in the spatial index
 109    */
 110   public int size();
 111
 112
 113   /**
 114    * Returns the bounds of all the entries in the spatial index,
 115    * or null if there are no entries.
 116    */
 117   public Rectangle getBounds();
 118
 119   /**
 120    * Returns a string identifying the type of
 121    * spatial index, and the version number,
 122    * eg "SimpleIndex-0.1"
 123    */
 124   public String getVersion();
 125
 126 }