Merge branch 'faster_split_box_creation'

Author: attcs

README.md

@@ -12,7 +12,7 @@ What is Morton-Z space-filling curve? https://en.wikipedia.org/wiki/Z-order_curv
 * Adaptable to any existing geometric system
 * Adaptable to the original container of geometrical entities
 * Arbitrary number of dimensions for other scientific usages
-* Support of `std::execution` policies (so it is parallelizable)
+* Parallelization is available (via `std::execution` policies)
 * Edit functions to Insert/Update/Erase entities
 * Wide range of search functions
   * Range search
@@ -35,7 +35,8 @@ What is Morton-Z space-filling curve? https://en.wikipedia.org/wiki/Z-order_curv
 
 ## Usage
 * Use `AdaptorBasicsConcept` or `AdaptorConcept` to adapt the actual geometric system. It is not a necessary step, basic point/vector and bounding box objects are available.
-* Use the static member function `Create()` for a container (`std::unordered_map` or any `std::span` compatible) of Points or Bounding boxes to build the tree. It supports `std::execution` policies (e.g.: `std::execution::parallel_unsequenced_policy`) which can be effectively used to parallelize the creation process. (Template argument of the `Create()` functions)
+* Decide to let the geometry management for octree or not. `Container` types could manage the geometries life-cycle, meanwhile the `non-container` types are just update the relevant metadata about the changes.
+* Use `PAR_EXEC` tag as first parameter of constructor for parallel execution
 * Use `PickSearch()` / `RangeSearch()` member functions to collect the wanted id-s
 * Use `PlaneSearch()` / `PlaneIntersection()` / `PlanePositiveSegmentation()` member functions for hyperplane related searches
 * Use `FrustumCulling()` to get entities in the multi-plane-bounded space/frustum
@@ -55,9 +56,9 @@ What is Morton-Z space-filling curve? https://en.wikipedia.org/wiki/Z-order_curv
 * Naming
   * Container types have "C" postfix (e.g.: core `OctreeBox`'s container is `OctreeBoxC`).
   * `Map` named aliases are declared for `std::unordered_map` geometry containers (e.g.: `QuadtreeBoxMap`, `OctreeBoxMap`, `OctreeBoxMapC`). Non-`Map` named aliases uses `std::span`, which is compatible with `std::vector`, `std::array` or any contigous container.
-  * `s` means adjustable `SPLIT_DEPTH_INCREASEMENT` for box-types.
+  * `s` means adjustable `DO_SPLIT_PARENT_ENTITIES` for box-types.
 * If `int` is preferred for indexing instead of `std::size_t`, declare `#define ORTHOTREE_INDEX_T__INT`.
-* Bounding box-based solution stores item id in the parent node if it is not fit into any child node. Using `SPLIT_DEPTH_INCREASEMENT` template parameter, these boxes can be splitted then placed on the deeper level of the tree. The `SPLIT_DEPTH_INCREASEMENT` default is 2 and this split method is applied by default.
+* Bounding box-based solution stores item id in the parent node if it is not fit into any child node. Using `DO_SPLIT_PARENT_ENTITIES` template parameter, these boxes can be splitted and placed on the first child level of the node. The `DO_SPLIT_PARENT_ENTITIES` default is `true`, it is applied by default.
 * Edit functions are available but not recommended to fully build the tree with them.
 * If less element is collected in a node than the max element then the child node won't be created.
 * The underlying container is a hash-table (`std::unordered_map`) under 16D, which only stores the id-s and the bounding box of the child nodes.
@@ -67,8 +68,8 @@ What is Morton-Z space-filling curve? https://en.wikipedia.org/wiki/Z-order_curv
 ## Recommendations
 * If the geometrical entities are already available, build the tree using the Constructor or Create, rather than entity-wise Insertions. This can result in a significant performance gain.
 * For tree building, `InsertWithRebalancing()` offers much better performance than Insert() with leaf-node settings.
-* If the box tree is used only for collision detection, set `SPLIT_DEPTH_INCREASEMENT = 0` (`OctreeBox` uses 2 by default). Both creation and collision detection will be significantly faster.
-* For `Pick`/`Range`/`Ray`/`Plane` related search, the default `SPLIT_DEPTH_INCREASEMENT = 2` is recommended.
+* If the box tree is used only for collision detection, set `DO_SPLIT_PARENT_ENTITIES = false` (`OctreeBox` uses `true` by default). Both creation and collision detection will be significantly faster.
+* For `Pick`/`Range`/`Ray`/`Plane` related search, the default `DO_SPLIT_PARENT_ENTITIES = true` is recommended.
 * If the overall modeling space size changes dynamically, this tool cannot be applied directly. However, you can combine it with sparse grid-based spatial partitioning, where each cell contains an `Orthotree`.
 * After calling `Init()`, the max depth cannot be changed, and the tree cannot be deepened further.
 * See the **BENCHMARKS** page for performance-related graphs.
@@ -139,17 +140,17 @@ The following defines can be used before the header file include:
   using QuadtreePointC = TreePointContainerND<2, BaseGeometryType>;
 
   // Quadtree for bounding boxes
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using QuadtreeBoxCs = TreeBoxContainerND<2, SPLIT_DEPTH_INCREASEMENT, BaseGeometryType>;
-  using QuadtreeBoxC = TreeBoxContainerND<2, 2, BaseGeometryType>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using QuadtreeBoxCs = TreeBoxContainerND<2, DO_SPLIT_PARENT_ENTITIES, BaseGeometryType>;
+  using QuadtreeBoxC = TreeBoxContainerND<2, true, BaseGeometryType>;
 
   // Octree for points
   using OctreePointC = TreePointContainerND<3, BaseGeometryType>;
 
   // Octree for bounding boxes
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using OctreeBoxCs = TreeBoxContainerND<3, 2, BaseGeometryType>;
-  using OctreeBoxC = TreeBoxContainerND<3, 2, BaseGeometryType>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using OctreeBoxCs = TreeBoxContainerND<3, DO_SPLIT_PARENT_ENTITIES, BaseGeometryType>;
+  using OctreeBoxC = TreeBoxContainerND<3, true, BaseGeometryType>;
 ```
 
 ## Basic examples
@@ -216,11 +217,11 @@ Usage of Container types
         /* and more... */
       };
 
-      auto octreeUsingCtor = OctreeBoxC(boxes
+      auto octreeUsingCtor = OctreeBoxC(PAR_EXEC
+        , boxes
         , 3
         , std::nullopt
         , OctreeBox::DEFAULT_MAX_ELEMENT
-        , true // Set std::execution::parallel_unsequenced_policy
       );
 
       auto octreeUsingCreate = OctreeBoxC::Create<true>(boxes, 3);
@@ -378,7 +379,7 @@ using QuadtreeBoxCustom = OrthoTree::OrthoTreeBoundingBox<
   MyRay2D, 
   MyPlane2D, 
   float, 
-  2, 
+  true, 
   AdaptorCustom>;
 ```
 

adaptor.boost.h

@@ -202,15 +202,15 @@ namespace OrthoTree
       BoostAdaptorGeneral<DIMENSION_NO, TGeometry>,
       TContainer>;
 
-    template<dim_t DIMENSION_NO, uint32_t SPLIT_DEPTH_INCREASEMENT, typename TGeometry, typename TContainer = std::span<boost::geometry::model::boxNd_t<DIMENSION_NO, TGeometry> const>>
+    template<dim_t DIMENSION_NO, bool DO_SPLIT_PARENT_ENTITIES, typename TGeometry, typename TContainer = std::span<boost::geometry::model::boxNd_t<DIMENSION_NO, TGeometry> const>>
     using BoostOrthoTreeBoundingBox = OrthoTreeBoundingBox<
       DIMENSION_NO,
       boost::geometry::model::pointNd_t<DIMENSION_NO, TGeometry>,
       boost::geometry::model::boxNd_t<DIMENSION_NO, TGeometry>,
       boost::geometry::model::rayNd_t<DIMENSION_NO, TGeometry>,
       boost::geometry::model::planeNd_t<DIMENSION_NO, TGeometry>,
       TGeometry,
-      SPLIT_DEPTH_INCREASEMENT,
+      DO_SPLIT_PARENT_ENTITIES,
       BoostAdaptorGeneral<DIMENSION_NO, TGeometry>,
       TContainer>;
   } // namespace BoostAdaptor
@@ -225,8 +225,8 @@ namespace boost::geometry
   template<int DIMENSION_NO, typename TGeometry = double, typename TContainer = std::span<model::pointNd_t<DIMENSION_NO, TGeometry> const>>
   using orthotree_point_t = BoostOrthoTreePoint<DIMENSION_NO, TGeometry, TContainer>;
 
-  template<int DIMENSION_NO, uint32_t SPLIT_DEPTH_INCREASEMENT = 2, typename TGeometry = double, typename TContainer = std::span<model::boxNd_t<DIMENSION_NO, TGeometry> const>>
-  using orthotree_box_t = BoostOrthoTreeBoundingBox<DIMENSION_NO, SPLIT_DEPTH_INCREASEMENT, TGeometry, TContainer>;
+  template<int DIMENSION_NO, bool DO_SPLIT_PARENT_ENTITIES = true, typename TGeometry = double, typename TContainer = std::span<model::boxNd_t<DIMENSION_NO, TGeometry> const>>
+  using orthotree_box_t = BoostOrthoTreeBoundingBox<DIMENSION_NO, DO_SPLIT_PARENT_ENTITIES, TGeometry, TContainer>;
 
 
   using quadtree_point_d = BoostOrthoTreePoint<2, double>;
@@ -240,18 +240,18 @@ namespace boost::geometry
   using octree_point = octree_point_d;
 
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using quadtree_box_ds = BoostOrthoTreeBoundingBox<2, SPLIT_DEPTH_INCREASEMENT, double>;
-  using quadtree_box_d = BoostOrthoTreeBoundingBox<2, 2, double>;
-  using quadtree_box_f = BoostOrthoTreeBoundingBox<2, 2, float>;
-  using quadtree_box_i = BoostOrthoTreeBoundingBox<2, 2, int>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using quadtree_box_ds = BoostOrthoTreeBoundingBox<2, DO_SPLIT_PARENT_ENTITIES, double>;
+  using quadtree_box_d = BoostOrthoTreeBoundingBox<2, true, double>;
+  using quadtree_box_f = BoostOrthoTreeBoundingBox<2, true, float>;
+  using quadtree_box_i = BoostOrthoTreeBoundingBox<2, true, int>;
   using quadtree_box = quadtree_box_d;
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using octree_box_ds = BoostOrthoTreeBoundingBox<3, SPLIT_DEPTH_INCREASEMENT, double>;
-  using octree_box_d = BoostOrthoTreeBoundingBox<3, 2, double>;
-  using octree_box_f = BoostOrthoTreeBoundingBox<3, 2, float>;
-  using octree_box_i = BoostOrthoTreeBoundingBox<3, 2, int>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using octree_box_ds = BoostOrthoTreeBoundingBox<3, DO_SPLIT_PARENT_ENTITIES, double>;
+  using octree_box_d = BoostOrthoTreeBoundingBox<3, true, double>;
+  using octree_box_f = BoostOrthoTreeBoundingBox<3, true, float>;
+  using octree_box_i = BoostOrthoTreeBoundingBox<3, true, int>;
   using octree_box = octree_box_d;
 
   // Container types
@@ -270,21 +270,21 @@ namespace boost::geometry
   using octree_point_c = octree_point_c_d;
 
 
-  template<int DIMENSION_NO, uint32_t SPLIT_DEPTH_INCREASEMENT = 2, typename TGeometry = double>
-  using orthotree_box_c_t = OrthoTree::OrthoTreeContainerBox<orthotree_box_t<DIMENSION_NO, SPLIT_DEPTH_INCREASEMENT, TGeometry>>;
+  template<int DIMENSION_NO, bool DO_SPLIT_PARENT_ENTITIES = true, typename TGeometry = double>
+  using orthotree_box_c_t = OrthoTree::OrthoTreeContainerBox<orthotree_box_t<DIMENSION_NO, DO_SPLIT_PARENT_ENTITIES, TGeometry>>;
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using quadtree_box_c_ds = orthotree_box_c_t<2, SPLIT_DEPTH_INCREASEMENT, double>;
-  using quadtree_box_c_d = orthotree_box_c_t<2, 2, double>;
-  using quadtree_box_c_f = orthotree_box_c_t<2, 2, float>;
-  using quadtree_box_c_i = orthotree_box_c_t<2, 2, int>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using quadtree_box_c_ds = orthotree_box_c_t<2, DO_SPLIT_PARENT_ENTITIES, double>;
+  using quadtree_box_c_d = orthotree_box_c_t<2, true, double>;
+  using quadtree_box_c_f = orthotree_box_c_t<2, true, float>;
+  using quadtree_box_c_i = orthotree_box_c_t<2, true, int>;
   using quadtree_box_c = quadtree_box_c_d;
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using octree_box_c_ds = orthotree_box_c_t<3, SPLIT_DEPTH_INCREASEMENT, double>;
-  using octree_box_c_d = orthotree_box_c_t<3, 2, double>;
-  using octree_box_c_f = orthotree_box_c_t<3, 2, float>;
-  using octree_box_c_i = orthotree_box_c_t<3, 2, int>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using octree_box_c_ds = orthotree_box_c_t<3, DO_SPLIT_PARENT_ENTITIES, double>;
+  using octree_box_c_d = orthotree_box_c_t<3, true, double>;
+  using octree_box_c_f = orthotree_box_c_t<3, true, float>;
+  using octree_box_c_i = orthotree_box_c_t<3, true, int>;
   using octree_box_c = octree_box_c_d;
 
 
@@ -304,18 +304,18 @@ namespace boost::geometry
   using octree_point_map = octree_point_map_d;
 
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using quadtree_box_map_ds = BoostOrthoTreeBoundingBox<2, SPLIT_DEPTH_INCREASEMENT, double, map_container<model::boxNd_t<2, double>>>;
-  using quadtree_box_map_d = BoostOrthoTreeBoundingBox<2, 2, double, map_container<model::boxNd_t<2, double>>>;
-  using quadtree_box_map_f = BoostOrthoTreeBoundingBox<2, 2, float, map_container<model::boxNd_t<2, float>>>;
-  using quadtree_box_map_i = BoostOrthoTreeBoundingBox<2, 2, int, map_container<model::boxNd_t<2, int>>>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using quadtree_box_map_ds = BoostOrthoTreeBoundingBox<2, DO_SPLIT_PARENT_ENTITIES, double, map_container<model::boxNd_t<2, double>>>;
+  using quadtree_box_map_d = BoostOrthoTreeBoundingBox<2, true, double, map_container<model::boxNd_t<2, double>>>;
+  using quadtree_box_map_f = BoostOrthoTreeBoundingBox<2, true, float, map_container<model::boxNd_t<2, float>>>;
+  using quadtree_box_map_i = BoostOrthoTreeBoundingBox<2, true, int, map_container<model::boxNd_t<2, int>>>;
   using quadtree_box_map = quadtree_box_map_d;
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using octree_box_map_ds = BoostOrthoTreeBoundingBox<3, SPLIT_DEPTH_INCREASEMENT, double, map_container<model::boxNd_t<3, double>>>;
-  using octree_box_map_d = BoostOrthoTreeBoundingBox<3, 2, double, map_container<model::boxNd_t<3, double>>>;
-  using octree_box_map_f = BoostOrthoTreeBoundingBox<3, 2, float, map_container<model::boxNd_t<3, float>>>;
-  using octree_box_map_i = BoostOrthoTreeBoundingBox<3, 2, int, map_container<model::boxNd_t<3, int>>>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using octree_box_map_ds = BoostOrthoTreeBoundingBox<3, DO_SPLIT_PARENT_ENTITIES, double, map_container<model::boxNd_t<3, double>>>;
+  using octree_box_map_d = BoostOrthoTreeBoundingBox<3, true, double, map_container<model::boxNd_t<3, double>>>;
+  using octree_box_map_f = BoostOrthoTreeBoundingBox<3, true, float, map_container<model::boxNd_t<3, float>>>;
+  using octree_box_map_i = BoostOrthoTreeBoundingBox<3, true, int, map_container<model::boxNd_t<3, int>>>;
   using octree_box_map = octree_box_map_d;
 
   // Container types
@@ -335,22 +335,22 @@ namespace boost::geometry
   using octree_point_map_c = octree_point_map_c_d;
 
 
-  template<int DIMENSION_NO, uint32_t SPLIT_DEPTH_INCREASEMENT = 2, typename TGeometry = double>
+  template<int DIMENSION_NO, bool DO_SPLIT_PARENT_ENTITIES = true, typename TGeometry = double>
   using orthotree_box_map_c_t =
-    OrthoTree::OrthoTreeContainerBox<orthotree_box_t<DIMENSION_NO, SPLIT_DEPTH_INCREASEMENT, TGeometry, map_container<model::boxNd_t<DIMENSION_NO, TGeometry>>>>;
+    OrthoTree::OrthoTreeContainerBox<orthotree_box_t<DIMENSION_NO, DO_SPLIT_PARENT_ENTITIES, TGeometry, map_container<model::boxNd_t<DIMENSION_NO, TGeometry>>>>;
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using quadtree_box_map_c_ds = orthotree_box_map_c_t<2, SPLIT_DEPTH_INCREASEMENT, double>;
-  using quadtree_box_map_c_d = orthotree_box_map_c_t<2, 2, double>;
-  using quadtree_box_map_c_f = orthotree_box_map_c_t<2, 2, float>;
-  using quadtree_box_map_c_i = orthotree_box_map_c_t<2, 2, int>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using quadtree_box_map_c_ds = orthotree_box_map_c_t<2, DO_SPLIT_PARENT_ENTITIES, double>;
+  using quadtree_box_map_c_d = orthotree_box_map_c_t<2, true, double>;
+  using quadtree_box_map_c_f = orthotree_box_map_c_t<2, true, float>;
+  using quadtree_box_map_c_i = orthotree_box_map_c_t<2, true, int>;
   using quadtree_box_map_c = quadtree_box_map_c_d;
 
-  template<uint32_t SPLIT_DEPTH_INCREASEMENT = 2>
-  using octree_box_map_c_ds = orthotree_box_map_c_t<3, SPLIT_DEPTH_INCREASEMENT, double>;
-  using octree_box_map_c_d = orthotree_box_map_c_t<3, 2, double>;
-  using octree_box_map_c_f = orthotree_box_map_c_t<3, 2, float>;
-  using octree_box_map_c_i = orthotree_box_map_c_t<3, 2, int>;
+  template<bool DO_SPLIT_PARENT_ENTITIES = true>
+  using octree_box_map_c_ds = orthotree_box_map_c_t<3, DO_SPLIT_PARENT_ENTITIES, double>;
+  using octree_box_map_c_d = orthotree_box_map_c_t<3, true, double>;
+  using octree_box_map_c_f = orthotree_box_map_c_t<3, true, float>;
+  using octree_box_map_c_i = orthotree_box_map_c_t<3, true, int>;
   using octree_box_map_c = octree_box_map_c_d;
 
 } // namespace boost::geometry