Package ucar.nc2.dt.ugrid.rtree

Class 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:
    Serialized Form

    • Field Detail

      • 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 Detail

      • RTree

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

    • Method Detail

      • 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

      • 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)