Package ucar.nc2.dt.ugrid.rtree

Class RTree

java.lang.Object
ucar.nc2.dt.ugrid.rtree.RTree
All Implemented Interfaces:
Serializable, SpatialIndex
public class RTree extends Object implements SpatialIndex, Serializable

This is a lightweight RTree implementation, specifically designed for the following features (in order of importance):

  • Fast intersection query performance. To achieve this, the RTree uses only main memory to store entries. Obviously this will only improve performance if there is enough physical memory to avoid paging.
  • Low memory requirements.
  • Fast add performance.

The main reason for the high speed of this RTree implementation is the avoidance of the creation of unnecessary objects, mainly achieved by using primitive collections from the COLT library.

NOTE: Node.findEntry() is not implemented and recalculateMBR() is not implemented. These are used in node deletion, therefore nodes cannot be deleted at this time. 06-05-09
See Also:

  • Field Details

    • addTime

      public static long addTime

    • splitTime

      public static long splitTime

    • pickSeedsTime

      public static long pickSeedsTime

    • pickNextTime

      public static long pickNextTime

    • chooseTime

      public static long chooseTime

    • adjustTime

      public static long adjustTime

  • Constructor Details

    • RTree

      public RTree()
      Constructor. Use init() method to initialize parameters of the RTree.

    • RTree

      public RTree(Properties props)

  • Method Details

    • init

      public void init(Properties props)

      Initialize implementation dependent properties of the RTree. Currently implemented properties are:

      • MaxNodeEntries
        • This specifies the maximum number of entries in a node. The default value is 10, which is used if the property is not specified, or is less than 2.
      • MinNodeEntries
        • This specifies the minimum number of entries in a node. The default value is half of the MaxNodeEntries value (rounded down), which is used if the property is not specified or is less than 1.

      see com.asascience.data.rtree.SpatialIndex#init(Properties)
      Specified by:
      init in interface SpatialIndex
      Parameters:
      props - The set of properties used to initialize the spatial index.

    • add

      public void add(LatLonPolygon2D r, int id)
      see com.asascience.data.rtree.SpatialIndex#add(Rectangle2D, int)
      Specified by:
      add in interface SpatialIndex
      Parameters:
      r - The polygon to add to the spatial index.
      id - The ID of the polygon to add to the spatial index. The result of adding more than one polygon with the same ID is undefined.

    • delete

      public boolean delete(LatLonPolygon2D r, int id)
      Description copied from interface: SpatialIndex
      Deletes a polygon from the spatial index
      Specified by:
      delete in interface SpatialIndex
      Parameters:
      r - The polygon to delete from the spatial index
      id - The ID of the polygon to delete from the spatial index
      Returns:
      true if the polygon was deleted, false if the polygon was not found, or the polygon was found but with a different ID

    • nearest

      public int nearest(Point2D p, double searchRadius)

    • nearest

      public int nearest(LatLonPoint2D p, double searchRadius)
      Convenience method for nearestNeighbor search where the IntProcedure is handled internally. Uses the passed search radius.
      Parameters:
      p - the query point.
      searchRadius - the searchRadius to use in the units of the loaded polygons
      Returns:
      the index of the nearest neighbor to the input point. returns -1 if no points are found within the searchRadius.

    • nearest

      public int nearest(Point2D p)

    • nearest

      public int nearest(LatLonPoint2D p)
      Convenience method for nearestNeighbor search where the IntProcedure is handled internally. Uses the default search radius of 0.5 units.
      Parameters:
      p - the query point.
      Returns:
      the index of the nearest neighbor to the input point. returns -1 if no points are found within the search radius.

    • nearest

      public void nearest(LatLonPoint2D p, IntProcedure v, double searchRadius)
      Finds the entry (polygon) which is closest to the given point, and invokes apply() on the given IntProcedure for that entry. Any entries found with a distance greater than 0.5 will not be returned. Also, if two or more entries are equidistant from the given point, apply() will only be invoked for the point closest by centroid.
      Parameters:
      p - The point for which this method finds the nearest neighbors
      v - The IntProcedure whose execute() method is is called for each nearest neighbor.
      searchRadius - The furthest distance away from a polygon to search. Polygons further than this will not be found. This should be as small as possible to minimize the search time. Use Double.POSITIVE_INFINITY to guarantee that the nearest polygon is found, no matter how far away, although this will slow down the algorithm.

    • nearest

      public void nearest(LatLonPoint2D p, IntProcedure v)
      Finds the entry (polygon) which is closest to the given point, and invokes apply() on the given IntProcedure for that entry. Any entries found with a distance greater than 0.5 will not be returned. Also, if two or more entries are equidistant from the given point, apply() will only be invoked for the point closest by centroid.
      Parameters:
      p - The point for which this method finds the nearest neighbors
      v - The IntProcedure whose execute() method is is called for each nearest neighbor.

    • intersects

      public cern.colt.list.IntArrayList intersects(LatLonPolygon2D r)
      Convenience method for intersects search where the IntProcedure is handled internally. Returns only those cells that are completely contained within the r polygon.
      Parameters:
      r - the bounding polygon to search within
      Returns:
      a list of indexes partially or completely contained within the bounding polygon

    • intersects

      public void intersects(LatLonPolygon2D r, IntProcedure v)
      Description copied from interface: SpatialIndex
      Finds all polygons that intersect the passed polygon.
      Specified by:
      intersects in interface SpatialIndex
      Parameters:
      r - The polygon for which this method finds intersecting polygons.
      v - The IntProcedure whose execute() method is is called for each intersecting polygon.

    • contains

      public cern.colt.list.IntArrayList contains(LatLonPolygon2D r)
      Convenience method for contains search where the IntProcedure is handled internally. Returns only those cells that are completely contained within the r polygon.
      Parameters:
      r - the bounding polygon to search within
      Returns:
      a list of indexes completely contained within the bounding polygon

    • contains

      public void contains(LatLonPolygon2D r, IntProcedure v)
      see com.asascience.data.rtree.SpatialIndex#contains(LatLonRectangle2D, IntProcedure)
      Specified by:
      contains in interface SpatialIndex
      Parameters:
      r - The polygon for which this method finds contained polygons.
      v - The visitor whose visit() method is is called for each contained polygon.

    • size

      public int size()
      see com.asascience.data.rtree.SpatialIndex#size()
      Specified by:
      size in interface SpatialIndex

    • getBounds

      public LatLonRectangle2D getBounds()
      see com.asascience.data.rtree.SpatialIndex#getBounds()
      Specified by:
      getBounds in interface SpatialIndex

    • getVersion

      public String getVersion()
      see com.asascience.data.rtree.SpatialIndex#getVersion()
      Specified by:
      getVersion in interface SpatialIndex

    • getTreeHeight

      public int getTreeHeight()
      Get the tree height (a.k.a. # of levels)
      Returns:
      the height of the tree

    • getNode

      public Node getNode(int index)
      Get a node object, given the ID of the node.

    • getNodeCount

      public int getNodeCount()
      Returns:
      Get the number of nodes in this RTree. This is not the total number of entries. Entry total is obtained via size()

    • getHighestUsedNodeId

      public int getHighestUsedNodeId()
      Get the highest used node's ID. This may not be the same number as size(), since node deletion does not reorient the remaining nodes.

    • getRootNodeId

      public int getRootNodeId()
      Get the root node's ID

    • nearestNeighbors

      public void nearestNeighbors(LatLonPoint2D p, IntProcedure v, double searchRadius)
      Finds the entries which are within the circular search area given by the point p and the radius searchRadius.Next invoke apply() on the given IntProcedure for each entry found.
      Specified by:
      nearestNeighbors in interface SpatialIndex
      Parameters:
      p - The point for which this method finds the nearest neighbors
      v - The IntProcedure whose execute() method is is called for each nearest neighbor.
      searchRadius - The distance from p to look for entries

    • getRectMin

      public static double[] getRectMin(LatLonRectangle2D rect)
      Builds a 2 length double array containing the minimum x and y values from the given rectangle. The 0 index of this array contains the minimum x value, and the 1 index contains the minimum y value.
      Parameters:
      rect - a LatLonRectangle2D object
      Returns:
      a 2 length double array, containing x and y coordinates.

    • getRectMax

      public static double[] getRectMax(LatLonRectangle2D rect)
      Builds a 2 length double array containing the maximum x and y values from the given rectangle. The 0 index of this array contains the max x value, and the 1 index contains the max y value.
      Parameters:
      rect - a LatLonRectangle2D object
      Returns:
      a 2 length double array, containing x and y coordinates.

    • getEnlargementArea

      public static double getEnlargementArea(LatLonRectangle2D src, LatLonRectangle2D addition)
      Produces a union of the two rectangles, and determines how much src would have to be enlarged to encompass this union. The original source rectangles will remain unchanged.

      If src fully contains addition this will always return 0, since src would not have to be enlarged.
      Parameters:
      src - a source rectangle
      addition - the rectangle which will be added to the source
      Returns:
      the area which src1 would have to be enlarged to, in order to encompass the union of itself and another rectangle ( src2)

    • getEnlargementArea

      public static double getEnlargementArea(double[] src, double[] addition)
      Produces a union of the two rectangles, and determines how much src would have to be enlarged to encompass this union. The original source rectangles will remain unchanged.

      If src fully contains addition this will always return 0, since src would not have to be enlarged.
      Parameters:
      src - a source rectangle
      addition - the rectangle which will be added to the source
      Returns:
      the area which src1 would have to be enlarged to, in order to encompass the union of itself and another rectangle ( src2)

    • toString

      public String toString()
      Constructs a string representation of this RTree as a tab-indented node list. If this RTree contains many entries this string may be rather long.
      Overrides:
      toString in class Object

    • getNodeMap

      public static StringBuilder getNodeMap(RTree rtree, int nodeId)
      Recursively builds a string representation of the given rtree starting at nodeId. Starting at node id rtree.getRootNodeId() is recommended.
      Parameters:
      rtree - the rtree to traverse
      nodeId - the starting node for the tree building
      Returns:
      a string representation of the given rtree

    • writeFullNodeMap

      public static void writeFullNodeMap(BufferedWriter writer, RTree rtree, int nodeId)