Add OBB user manual

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},

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
+

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}
+<center>
+<img src="obb_chess.png" style="max-width:70%;"/>
+</center>
+<!-- chess pieces from https://www.myminifactory.com/object/3d-print-chess-game-set-26114 -->
+
 \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 <em>Optimal Bounding Boxes</em>.
+Contrary to AABB, those parallelepipedal boxes are not necessarily axis-aligned,
+but they provide tight approximations.
+
+\cgalFigureAnchor{obb_aabb_vs_obb}
+<center>
+<img src="aabb_vs_obb.jpg" style="max-width:70%;"/>
+</center>
+\cgalFigureCaptionBegin{obb_aabb_vs_obb}
+Left: the axis-aligned bounding box. Right: the optimal bounding box, a much better fit.
+<!-- source and license of the model: https://www.myminifactory.com/object/3d-print-chinese-new-year-dragon-incense-holder-5476 -->
+\cgalFigureCaptionEnd
+
+In 2D, the optimal bounding rectangle of an input can be computed in linear time
+using the technique of <em>rotating calipers</em>, 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, <em>Oriented Bounding Box</em>.
+
+\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 <a href="https://ten-thousand-models.appspot.com/">Thingi10k</a> 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 <a href="https://ten-thousand-models.appspot.com/">Thingi10k</a> 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 */

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