diff --git a/Documentation/doc/biblio/cgal_manual.bib b/Documentation/doc/biblio/cgal_manual.bib index 2dd8fc98bca..fb2a87a0dd7 100644 --- a/Documentation/doc/biblio/cgal_manual.bib +++ b/Documentation/doc/biblio/cgal_manual.bib @@ -363,6 +363,17 @@ Boissonnat} ,pages = {350--355} } +@article{cgal:cgm-fobbo-11, + title={Fast Oriented Bounding Box Optimization on the Rotation Group $\SO(3, \mathrm{R})$}, + author={Chang, Chia-Tche and Gorissen, Bastien and Melchior, Samuel}, + journal={ACM Transactions on Graphics (TOG)}, + volume={30}, + number={5}, + pages={1--16}, + year={2011}, + publisher={ACM New York, NY, USA} +} + @article{cgal:cdeft-slive-00, author = {Cheng, Siu-Wing and Dey, Tamal K. and Edelsbrunner, Herbert and Facello, Michael A. and Teng, Shang-Hua}, title = {Sliver exudation}, @@ -1721,6 +1732,17 @@ ABSTRACT = {We present the first complete, exact and efficient C++ implementatio ,update = "97.04 kettner" } +@article{cgal:nm-smfm-65, + title={A Simplex Method for Function Minimization}, + author={Nelder, John A and Mead, Roger}, + journal={The computer journal}, + volume={7}, + number={4}, + pages={308--313}, + year={1965}, + publisher={Oxford University Press} +} + @book{ cgal:ns-gsn-07 ,author = {G. Narasimhan and M. Smid} ,title = {Geometric Spanner Networks} @@ -1863,6 +1885,17 @@ ABSTRACT = {We present the first complete, exact and efficient C++ implementatio ,pages = {743--750} } +@article{cgal:or-fmeb-85, + title={Finding Minimal Enclosing Boxes}, + author={O'Rourke, Joseph}, + journal={International journal of computer \& information sciences}, + volume={14}, + number={3}, + pages={183--199}, + year={1985}, + publisher={Springer} +} + @article{ cgal:r-lomom-94 ,author = {James Rumbaugh} ,title = {The Life of an Object Model: How the Object-Model @@ -2175,6 +2208,14 @@ location = {Salt Lake City, Utah, USA} , x-international-audience = {yes} } +@inproceedings{cgal:t-sgprc-83, + title={Solving geometric problems with the rotating calipers}, + author={Toussaint, Godfried T}, + booktitle={Proc. IEEE Melecon}, + volume={83}, + pages={A10}, + year={1983} +} @proceedings{ cgal:v-ea-09, editor = {Jan Vahrenhold}, diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/Doxyfile.in b/Optimal_bounding_box/doc/Optimal_bounding_box/Doxyfile.in index d90bd9a87c0..057f5441d8d 100644 --- a/Optimal_bounding_box/doc/Optimal_bounding_box/Doxyfile.in +++ b/Optimal_bounding_box/doc/Optimal_bounding_box/Doxyfile.in @@ -24,3 +24,6 @@ EXPAND_AS_DEFINED = CGAL_BGL_NP_TEMPLATE_PARAMETERS \ EXCLUDE = ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Optimal_bounding_box/internal EXCLUDE_SYMBOLS += experimental +HTML_EXTRA_FILES = ${CGAL_PACKAGE_DOC_DIR}/fig/aabb_vs_obb.jpg \ + ${CGAL_PACKAGE_DOC_DIR}/fig/obb_chess.png + diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/Optimal_bounding_box.txt b/Optimal_bounding_box/doc/Optimal_bounding_box/Optimal_bounding_box.txt index 4c151095116..5e987a4b9ab 100644 --- a/Optimal_bounding_box/doc/Optimal_bounding_box/Optimal_bounding_box.txt +++ b/Optimal_bounding_box/doc/Optimal_bounding_box/Optimal_bounding_box.txt @@ -3,13 +3,175 @@ namespace CGAL { /*! \mainpage User Manual \anchor Chapter_Building_Optimal_Bounding_Box - \cgalAutoToc + +\cgalFigureAnchor{OBBBanner} +
+ +
+ + \authors Konstantinos Katrioplas, Mael Rouxel-Labbé -\section sectionOBBIntro Introduction +\section OBBIntro Introduction -\section sectionOrientedBoundingBox Oriented Bounding Box +Encompassing a model within a volume is a common approach to accelerate +a number of applications such as collision detection or visibility testing: +the proxy volume provides a rapid way to test a configuration or filter results, +with the real model only being used when required. +Typical coarser volumes that can be used to approximate a more complex +model are simplified meshes (for example using the package \ref PkgSurfaceMeshSimplification), +convex hulls, or simple parallelepipedal boxes. Within this last +category, the axis-aligned bounding box (AABB) has obvious advantages: +it is extremely simple to compute and one may build a hierarchical +structure of successively tighter volumes to further speed-up intersection and distance computations. +One such example of structure is the \cgal AABB tree (\ref PkgAABBTree). +The disadvantage is also clear: the box is usually poorly fitting most models. +A good compromise between the good approximation offered by convex hulls or simplified meshes +and the speed offered by boxes are Optimal Bounding Boxes. +Contrary to AABB, those parallelepipedal boxes are not necessarily axis-aligned, +but they provide tight approximations. + +\cgalFigureAnchor{obb_aabb_vs_obb} +
+ +
+\cgalFigureCaptionBegin{obb_aabb_vs_obb} +Left: the axis-aligned bounding box. Right: the optimal bounding box, a much better fit. + +\cgalFigureCaptionEnd + +In 2D, the optimal bounding rectangle of an input can be computed in linear time +using the technique of rotating calipers, first introduced +by Toussaint \cgalCite{cgal:t-sgprc-83}. An algorithm to compute the optimal oriented +bounding box in 3D was proposed by O’Rourke \cgalCite{cgal:or-fmeb-85}, but its cubic complexity (in the number +of points) makes it unusable in practice. The implementation proposed +in this package is based on the paper of Chang et al.\cgalCite{cgal:cgm-fobbo-11}, +who introduced an algorithm to compute a close approximation of the optimal +bounding box. As this is but an approximation of the optimal bounding box, +we call the resulting parallelepiped, Oriented Bounding Box. + +\section OBBOrientedBoundingBox Oriented Bounding Box + +The algorithm introduced by Chang et al. formulates the computation +of the optimal bounding box as an unconstrained optimization problem +on the 3D matrix rotation group. The function to optimize is defined +as the volume of the box. Because this function is non-differentiable, +and in particular near local optima, traditional optimization methods +might encounter convergence issues. +Consequently, Chang et al.'s algorithm employs a combination +of a derivative-free optimization methods, the Nelder-Mead +simplex method \cgalCite{cgal:nm-smfm-65}, and a metaheuristics method based on +biological evolution principles to maintain and evolve a population of tentative +rotation matrices. The purpose of this evolution is to oppose +a global approach to the local Nelder-Mead optimization, +enabling the algorithm to explore the search space as much as possible, +and to find not only a local minimum, but a global optimum. + +\subsection OBBOptimality Missing the Optimality + +The metaheuristic based on biological evolution principles used by Chang et al. +in theory enables the algorithm to explore the complete search space, +given enough time. In practice, a practical algorithm does not have +infinite time at its disposal. In addition, there is no simple way +to check if the current-best solution is optimal. Thus, a practical +implementation of the algorithm cannot offer the same guarantees +that the theoretical algorithm offers. However, we observe in practice +that most of the time the algorithm constructs a close approximation of +the optimal bounding box. + +\subsection OBBConvexHull Convex Hull Computation as Preprocessing + +As the bounding box only depends on the convex hull of the object, +computing its convex hull as a preprocessing step is a good way to reduce +the number of points in subsequent computations. The computational trade-off +is developed in more details in Section \ref OBBComplexityPerformance. + +\section OBBImplementation Design and Implementation + +The computation of the oriented bounding box can be performed by calling the free function +`CGAL::oriented_bounding_box()`. The input can be a range of points, or a mesh, with a variety +of \ref obb_namedparameters "Named Parameters" enabling using further custom inputs. + +The result of the algorithm can be retrieved as: +- the best affine transformation \f${\mathcal R}_b\f$ that the algorithm has found; +- an array of eight points, representing the best oriented bounding box (\f${\mathcal B}_b\f$) +that the algorithm has constructed, which is related to \f$ {\mathcal R}_b\f$ as it is +the inverse transformation of the axis-aligned bounding box of the transformed point set. +The order of the points in the array is the same as in the function +\link PkgBGLHelperFct `CGAL::make_hexahedron()` \endlink, +which can be used to construct a mesh from these points. +- a model of `MutableFaceGraph`, the parallelepiped box mesh. + +The requirements on geometric objects and operations on these objects are described in the traits +class concept `OrientedBoundingBoxTraits_3`. A model of this concept is provided: +`CGAL::Oriented_bounding_box_traits_3`. + +Convex hull computation is performed using the package \ref PkgConvexHull3, and is enabled by default. + +\section OBBComplexityPerformance Complexity and Performance + +A major drawback of the exact algorithm of O’Rourke is its cubic complexity +and consequent large runtimes. In this section, we investigate the speed-up gained +by preprocessing the input data with a convex hull computation, and show that +the oriented bounding box algorithm exhibits linear complexity. + +Models from the Thingi10k data set are used +with speeds being averaged over 100 runs for each model. The machine used is a laptop running Fedora 30 +64-bits, with two 6-core Intel(R) i9-8950HK CPU clocked at 2.90GHz, and with 32GB of RAM. + +\subsection OBBConvexHullComplexity Cost and Gain of Convex Hull Computations + +Computing the convex hull as a preliminary step provides a significant speed advantage, +and never worsens the result in our tests. + +\cgalFigureBegin{ch_speed_up, ch_speedup.png} +Speed-up obtained by computing the oriented bounding box of the convex hull of the data. +It is always beneficial to construct and use the convex hull. +\cgalFigureEnd + +\subsection OBBOrientedBoundingBoxComplexity Performance of the Oriented Bounding Box Algorithm + +We analyze in this section the computation time of the algorithm based on the number of vertices +on the convex hull. + +\cgalFigureBegin{obb_timings, obb_time.jpg} +Running times for the oriented bounding box construction of the convex hull of models +of the Thingi10k data set. +\cgalFigureEnd + +\section OBBexamples Examples + +\subsection OBBBasicExample Basic Example + +\cgalExample{Optimal_bounding_box/obb_example.cpp} + +The following example illustrates a basic usage of the algorithm: an input mesh is read, +its oriented bounding box is computed using an array as output, and a mesh is constructed +from the eight points. + +\subsection OBBExampleNP Using Named Parameters + +The following example illustrates how to use \ref obb_namedparameters "Named Parameters" +to efficiently compute the oriented bounding box of a mesh whose vertices' positions are +modified on the fly. + +\cgalExample{Optimal_bounding_box/obb_with_point_maps_example.cpp} + +\subsection OBBRotatedTree Rotated AABB Tree + +The following example uses the affine transformation, which is the affine transformation such +that the axis-aligned bounding box of the transformed vertices of the mesh has minimum volume), +returned by the algorithm to build a custom vertex point property map. An AABB tree of the (on the fly) +rotated faces of the mesh is then constructed. + +\cgalExample{Optimal_bounding_box/rotated_aabb_tree_example.cpp} + +\section OBBHistory Implementation History + +A prototype was created by Konstantinos Katrioplas in 2018. +Mael Rouxel-Labbé worked to speed up and robustify the implementation, +and to submit the first version of this package. */ } /* namespace CGAL */ diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/dependencies b/Optimal_bounding_box/doc/Optimal_bounding_box/dependencies index 1c28ee0c9b6..2ad60eeb4e0 100644 --- a/Optimal_bounding_box/doc/Optimal_bounding_box/dependencies +++ b/Optimal_bounding_box/doc/Optimal_bounding_box/dependencies @@ -10,4 +10,6 @@ Solver_interface Surface_mesh AABB_tree Property_map +Surface_mesh_simplification +Convex_hull_3 diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/fig/aabb_vs_obb.jpg b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/aabb_vs_obb.jpg new file mode 100644 index 00000000000..62c5754e230 Binary files /dev/null and b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/aabb_vs_obb.jpg differ diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/fig/ch_speedup.png b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/ch_speedup.png new file mode 100644 index 00000000000..f2fd0d39ab3 Binary files /dev/null and b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/ch_speedup.png differ diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/fig/obb_chess.png b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/obb_chess.png new file mode 100644 index 00000000000..1037c985ed9 Binary files /dev/null and b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/obb_chess.png differ diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/fig/obb_time.png b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/obb_time.png new file mode 100644 index 00000000000..cc430509aa3 Binary files /dev/null and b/Optimal_bounding_box/doc/Optimal_bounding_box/fig/obb_time.png differ