More factory methods (#30)

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [Unreleased]
 
 ### Added
+- Added missing factory methods for STR loaded R-Trees and kD-Tree(IndexConfig)
+  [#30](https://github.com/tzaeschke/tinspin-indexes/pull/30)
 - Added factory classes for indexes, e.g. `PointMap.Factory.createKdTree()`.
   [#29](https://github.com/tzaeschke/tinspin-indexes/pull/29)
 

README.md

@@ -39,8 +39,8 @@ Indexes can be created via factories in the interfaces, e.g. `PointMap.Factory.c
 **WARNING** *The `Map` implementations are mostly not strict with respect to unique keys. That means they work fine if keys are unique. However, they may not enforce uniqueness (replace entries when the same key is added twice) and instead always add another entry. That means they may effectively act as multimaps.* At the moment, only PH-Tree bases indexes enforce uniqueness and properly overwrite existing keys.
 
 Note:
- - The `RTree` class can be used for **R*Trees** and **STR-Trees** depending on how it is loaded. Adding entries via `insert(...)` will create a normal R*Tree while adding entries via `load()` creates an STR-Tree. **Note:** currently, `load()` is not available in the interfaces. It requires casting the index to `RTree` (for boxes) or the respective wrapper class (for points).
- - **R*Trees** and **STR-Trees** and can be turned into a `PointMap` or `PointMultimap` via mappers, e.g. `PointMapWrapper.create(RTree.createRStar(dims))`
+ - **STR-Trees** are simply R-Trees that are preloaded using the STR algorithm. THis can be done with
+   the factory methods `....Factory.createAndLoadStrRTree(...)`.
  - `PointArray` and `BoxArray` are simple array based implementations. They scale badly with size, their only use is for verifying correctness of other indexes. 
 
 ## Changelog

src/main/java/org/tinspin/index/BoxMap.java

@@ -21,8 +21,8 @@
 import org.tinspin.index.phtree.PHTreeR;
 import org.tinspin.index.qthypercube.QuadTreeRKD;
 import org.tinspin.index.qtplain.QuadTreeRKD0;
-import org.tinspin.index.rtree.Entry;
 import org.tinspin.index.rtree.RTree;
+import org.tinspin.index.rtree.RTreeEntry;
 
 import java.util.Iterator;
 
@@ -190,7 +190,7 @@ static <T> BoxMap<T> createQuadtreeHC(int dims, int maxNodeCapacity, double[] mi
         }
 
         /**
-         * Create an R*Tree. R*Trees can be "turned into" STR-Trees by using {@link RTree#load(Entry[])}.
+         * Create an R*Tree.
          *
          * @param dims Number of dimensions.
          * @param <T>  Value type
@@ -199,5 +199,19 @@ static <T> BoxMap<T> createQuadtreeHC(int dims, int maxNodeCapacity, double[] mi
         static <T> BoxMap<T> createRStarTree(int dims) {
             return RTree.createRStar(dims);
         }
+
+        /**
+         * Create an STR-loaded R*Tree.
+         *
+         * @param dims    Number of dimensions.
+         * @param entries All entries of the tree. Entries can be created with
+         *                {@link RTreeEntry#createBox(double[], double[], Object)}
+         * @return New STR-loaded R*Tree
+         */
+        static <T> BoxMap<T> createAndLoadStrRTree(int dims, RTreeEntry<T>[] entries) {
+            RTree<T> tree = RTree.createRStar(dims);
+            tree.load(entries);
+            return tree;
+        }
     }
 }

src/main/java/org/tinspin/index/BoxMultimap.java

@@ -20,8 +20,8 @@
 import org.tinspin.index.array.RectArray;
 import org.tinspin.index.qthypercube.QuadTreeRKD;
 import org.tinspin.index.qtplain.QuadTreeRKD0;
-import org.tinspin.index.rtree.Entry;
 import org.tinspin.index.rtree.RTree;
+import org.tinspin.index.rtree.RTreeEntry;
 
 import java.util.Iterator;
 import java.util.function.Predicate;
@@ -211,7 +211,7 @@ static <T> BoxMultimap<T> createQuadtreeHC(int dims, int maxNodeCapacity, double
         }
 
         /**
-         * Create an R*Tree. R*Trees can be "turned into" STR-Trees by using {@link RTree#load(Entry[])}.
+         * Create an R*Tree.
          *
          * @param dims Number of dimensions.
          * @param <T>  Value type
@@ -220,5 +220,19 @@ static <T> BoxMultimap<T> createQuadtreeHC(int dims, int maxNodeCapacity, double
         static <T> BoxMultimap<T> createRStarTree(int dims) {
             return RTree.createRStar(dims);
         }
+
+        /**
+         * Create an STR-loaded R*Tree.
+         *
+         * @param dims    Number of dimensions.
+         * @param entries All entries of the tree. Entries can be created with
+         *                {@link RTreeEntry#createBox(double[], double[], Object)}
+         * @return New STR-loaded R*Tree
+         */
+        static <T> BoxMultimap<T> createAndLoadStrRTree(int dims, RTreeEntry<T>[] entries) {
+            RTree<T> tree = RTree.createRStar(dims);
+            tree.load(entries);
+            return tree;
+        }
     }
 }

src/main/java/org/tinspin/index/PointMap.java

@@ -24,8 +24,8 @@
 import org.tinspin.index.qthypercube.QuadTreeKD;
 import org.tinspin.index.qthypercube2.QuadTreeKD2;
 import org.tinspin.index.qtplain.QuadTreeKD0;
-import org.tinspin.index.rtree.Entry;
 import org.tinspin.index.rtree.RTree;
+import org.tinspin.index.rtree.RTreeEntry;
 import org.tinspin.index.util.PointMapWrapper;
 
 /**
@@ -141,16 +141,27 @@ static <T> PointMap<T> createCoverTree(int dims) {
         }
 
         /**
-         * Create a kD-Tree
+         * Create a kD-Tree.
          *
          * @param dims Number of dimensions.
          * @param <T>  Value type
-         * @return New PH-Tree
+         * @return New kD-Tree
          */
         static <T> PointMap<T> createKdTree(int dims) {
             return KDTree.create(dims);
         }
 
+        /**
+         * Create a kD-Tree.
+         *
+         * @param cfg Index configuration.
+         * @param <T> Value type
+         * @return New kD-Tree
+         */
+        static <T> PointMap<T> createKdTree(IndexConfig cfg) {
+            return KDTree.create(cfg);
+        }
+
         /**
          * Create a PH-Tree.
          *
@@ -244,7 +255,7 @@ static <T> PointMap<T> createQuadtreeHC2(int dims, int maxNodeCapacity, double[]
         }
 
         /**
-         * Create an R*Tree. R*Tree can be "turned into" STR-Trees by using {@link RTree#load(Entry[])}.
+         * Create an R*Tree.
          *
          * @param dims Number of dimensions.
          * @param <T>  Value type
@@ -253,5 +264,19 @@ static <T> PointMap<T> createQuadtreeHC2(int dims, int maxNodeCapacity, double[]
         static <T> PointMap<T> createRStarTree(int dims) {
             return PointMapWrapper.create(RTree.createRStar(dims));
         }
+
+        /**
+         * Create an STR-loaded R*Tree.
+         *
+         * @param dims    Number of dimensions.
+         * @param entries All entries of the tree. Entries can be created with
+         *                {@link RTreeEntry#createPoint(double[], Object)}
+         * @return New STR-loaded R*Tree
+         */
+        static <T> PointMap<T> createAndLoadStrRTree(int dims, RTreeEntry<T>[] entries) {
+            RTree<T> tree = RTree.createRStar(dims);
+            tree.load(entries);
+            return PointMapWrapper.create(tree);
+        }
     }
 }

src/main/java/org/tinspin/index/PointMultimap.java

@@ -23,8 +23,8 @@
 import org.tinspin.index.qthypercube.QuadTreeKD;
 import org.tinspin.index.qthypercube2.QuadTreeKD2;
 import org.tinspin.index.qtplain.QuadTreeKD0;
-import org.tinspin.index.rtree.Entry;
 import org.tinspin.index.rtree.RTree;
+import org.tinspin.index.rtree.RTreeEntry;
 import org.tinspin.index.util.PointMultimapWrapper;
 
 import java.util.Iterator;
@@ -155,16 +155,27 @@ static <T> PointMultimap<T> createArray(int dims, int size) {
         }
 
         /**
-         * Create a kD-Tree
+         * Create a kD-Tree.
          *
          * @param dims Number of dimensions.
          * @param <T>  Value type
-         * @return New PH-Tree
+         * @return New kD-Tree
          */
         static <T> PointMultimap<T> createKdTree(int dims) {
             return KDTree.create(dims);
         }
 
+        /**
+         * Create a kD-Tree.
+         *
+         * @param cfg Index configuration.
+         * @param <T> Value type
+         * @return New kD-Tree
+         */
+        static <T> PointMultimap<T> createKdTree(IndexConfig cfg) {
+            return KDTree.create(cfg);
+        }
+
         /**
          * Create a PH-Tree.
          *
@@ -258,7 +269,7 @@ static <T> PointMultimap<T> createQuadtreeHC2(int dims, int maxNodeCapacity, dou
         }
 
         /**
-         * Create an R*Tree. R*Tree can be "turned into" STR-Trees by using {@link RTree#load(Entry[])}.
+         * Create an R*Tree.
          *
          * @param dims Number of dimensions.
          * @param <T>  Value type
@@ -267,5 +278,19 @@ static <T> PointMultimap<T> createQuadtreeHC2(int dims, int maxNodeCapacity, dou
         static <T> PointMultimap<T> createRStarTree(int dims) {
             return PointMultimapWrapper.create(RTree.createRStar(dims));
         }
+
+        /**
+         * Create an STR-loaded R*Tree.
+         *
+         * @param dims    Number of dimensions.
+         * @param entries All entries of the tree. Entries can be created with
+         *                {@link RTreeEntry#createPoint(double[], Object)}
+         * @return New STR-loaded R*Tree
+         */
+        static <T> PointMultimap<T> createAndLoadStrRTree(int dims, RTreeEntry<T>[] entries) {
+            RTree<T> tree = RTree.createRStar(dims);
+            tree.load(entries);
+            return PointMultimapWrapper.create(tree);
+        }
     }
 }