From db943b3b6fe328389bb155fd6ee03e1be47e6811 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Mon, 9 Dec 2019 18:54:46 +0100 Subject: [PATCH] Doc changes --- .../Concepts/OptimalBoundingBoxTraits.h | 8 ++++---- .../Optimal_bounding_box/PackageDescription.txt | 2 +- .../Optimal_bounding_box_traits.h | 6 +++--- .../Optimal_bounding_box/internal/evolution.h | 4 ++-- .../internal/nelder_mead_functions.h | 8 ++++---- .../Optimal_bounding_box/internal/population.h | 2 +- .../include/CGAL/optimal_bounding_box.h | 15 +++++++++------ .../test_linear_algebra_functions.cpp | 8 ++++---- .../test_optimization_algorithms.cpp | 6 +++--- 9 files changed, 31 insertions(+), 28 deletions(-) diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/Concepts/OptimalBoundingBoxTraits.h b/Optimal_bounding_box/doc/Optimal_bounding_box/Concepts/OptimalBoundingBoxTraits.h index 8fcb42b3bc2..e41a29d0e4b 100644 --- a/Optimal_bounding_box/doc/Optimal_bounding_box/Concepts/OptimalBoundingBoxTraits.h +++ b/Optimal_bounding_box/doc/Optimal_bounding_box/Concepts/OptimalBoundingBoxTraits.h @@ -18,20 +18,20 @@ class OptimalBoundingBoxTraits { public: /// The field number type; must be a model of the concept `FieldNumberType`. - typedef unspecified_type FT; + typedef unspecified_type FT; /// A 3x3 matrix type; must be a model of the concept `SvdTraits::Matrix` and support /// matrix-matrix and scalar-matrix multiplication, as well as matrix-matrix addition. - typedef unspecified_type Matrix; + typedef unspecified_type Matrix; /// Returns the transpose of a matrix. Matrix transpose(const Matrix& mat) const; /// Returns the determinant of a matrix. - FT determinant(const Matrix& matrix) const; + FT compute_determinant(const Matrix& matrix) const; /// Returns the unary matrix Q obtained in the QR decompoisiton of the matrix `A`. - Matrix qr_factorization(const Matrix& A) const; + Matrix get_Q(const Matrix& A) const; }; } // namespace CGAL diff --git a/Optimal_bounding_box/doc/Optimal_bounding_box/PackageDescription.txt b/Optimal_bounding_box/doc/Optimal_bounding_box/PackageDescription.txt index 156f50dc13e..dfa00bd717d 100644 --- a/Optimal_bounding_box/doc/Optimal_bounding_box/PackageDescription.txt +++ b/Optimal_bounding_box/doc/Optimal_bounding_box/PackageDescription.txt @@ -20,7 +20,7 @@ \cgalPkgSummaryEnd \cgalPkgShortInfoBegin \cgalPkgSince{5.1} -\cgalPkgDependsOn{documented for each function;} +\cgalPkgDependsOn{\ref PkgConvexHull3} \cgalPkgBib{cgal:obb} \cgalPkgLicense{\ref licensesGPL "GPL"} \cgalPkgDemo{Polyhedron demo, polyhedron_3.zip} diff --git a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/Optimal_bounding_box_traits.h b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/Optimal_bounding_box_traits.h index a570cdc2412..9d06fc69ab6 100644 --- a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/Optimal_bounding_box_traits.h +++ b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/Optimal_bounding_box_traits.h @@ -61,17 +61,17 @@ public: } /// Get the determinant of a matrix - FT determinant(const Matrix& matrix) const + FT compute_determinant(const Matrix& matrix) const { return matrix.eigen_object().determinant(); } /// Performs QR decomposition of matrix A to a unitary matrix and an upper triagonal /// and returns the unitary matrix. - Matrix qr_factorization(const Matrix& A) const + Matrix get_Q(const Matrix& A) const { Eigen::HouseholderQR qr(A.eigen_object()); - CGAL_assertion(CGAL::abs(determinant(Matrix(EigenType(qr.householderQ()))) - 1.) < 0.000001); + CGAL_assertion(CGAL::abs(compute_determinant(Matrix(EigenType(qr.householderQ()))) - 1.) < 0.000001); return Matrix(EigenType(qr.householderQ())); } diff --git a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/evolution.h b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/evolution.h index cc1bd28350a..cfd1b4b590e 100644 --- a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/evolution.h +++ b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/evolution.h @@ -129,7 +129,7 @@ public: new_vertex.set(2, 1, lambda * lm(2, 1) + rambda * rm(2, 1)); new_vertex.set(2, 2, lambda * lm(2, 2) + rambda * rm(2, 2)); - offspring[j] = m_traits.qr_factorization(new_vertex); + offspring[j] = m_traits.get_Q(new_vertex); } new_simplices[first_group_size + i] = std::move(offspring); @@ -177,7 +177,7 @@ public: //pop.show_population(); //std::cout << std::endl; const Matrix& R_now = fitness_map.get_best(); - std::cout << "det = " << m_traits.determinant(R_now) << std::endl; + std::cout << "det = " << m_traits.compute_determinant(R_now) << std::endl; #endif new_fit_value = fitness_map.get_best_fitness_value(); diff --git a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/nelder_mead_functions.h b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/nelder_mead_functions.h index 8f080095320..b6966b71940 100644 --- a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/nelder_mead_functions.h +++ b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/nelder_mead_functions.h @@ -61,8 +61,8 @@ Matrix mean(const Matrix& m1, CGAL_assertion(m2.number_of_rows() == 3 && m2.number_of_columns() == 3); const Matrix reduction = 0.5 * m1 + 0.5 * m2; - const Matrix Q = traits.qr_factorization(reduction); - const typename Traits::FT det = traits.determinant(Q); + const Matrix Q = traits.get_Q(reduction); + const typename Traits::FT det = traits.compute_determinant(Q); return (1. / det) * Q; } @@ -74,8 +74,8 @@ const Matrix nm_centroid(const Matrix& S1, const Traits& traits) { const Matrix mean = (1./3.) * (S1 + S2 + S3); - const Matrix Q = traits.qr_factorization(mean); - const typename Traits::FT det = traits.determinant(Q); + const Matrix Q = traits.get_Q(mean); + const typename Traits::FT det = traits.compute_determinant(Q); return (1. / det) * Q; } diff --git a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/population.h b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/population.h index 640b4423a71..1244c289230 100644 --- a/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/population.h +++ b/Optimal_bounding_box/include/CGAL/Optimal_bounding_box/internal/population.h @@ -54,7 +54,7 @@ private: { Simplex simplex; for(std::size_t i=0; i<4; ++i) - simplex[i] = m_traits.qr_factorization(create_vertex(rng)); + simplex[i] = m_traits.get_Q(create_vertex(rng)); return simplex; } diff --git a/Optimal_bounding_box/include/CGAL/optimal_bounding_box.h b/Optimal_bounding_box/include/CGAL/optimal_bounding_box.h index 72243171163..63ceaa998a4 100644 --- a/Optimal_bounding_box/include/CGAL/optimal_bounding_box.h +++ b/Optimal_bounding_box/include/CGAL/optimal_bounding_box.h @@ -160,12 +160,13 @@ void construct_optimal_bounding_box(std::array& obb /// /// constructs a rectangular box that contains all the input points. This bounding box /// is obtained via an optimization process aiming to get a close approximation of the -/// optimal bounding box. +/// optimal bounding box, which is defined as the smallest (in terms of volume) +/// of all the rectangular boxes containing the input points. /// /// \tparam PointRange a model of `Range` with value type `Point` /// \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" /// -/// \param points the input points that the optimal bounding box will contain +/// \param points the input points /// \param obb_points the eight points of the resulting englobing box. /// The order of points is the same as in the function `CGAL::make_hexahedron()` /// \param np an optional sequence of \ref obb_namedparameters "Named Parameters" among the ones listed below: @@ -179,7 +180,7 @@ void construct_optimal_bounding_box(std::array& obb /// \cgalParamBegin{geom_traits} /// a geometric traits class instance, model of the concept `OptimalBoundingBoxTraits`. %Default is /// `CGAL::Optimal_bounding_box::Optimal_bounding_box_traits` where `K` is deduced -/// from the point type, which must be compatible with `CGAL::Kernel_traits`. +/// from the point type, which must then be compatible with `CGAL::Kernel_traits`. /// \cgalParamEnd /// \cgalParamBegin{use_convex_hull} /// a Boolean value to indicate whether the algorithm should first extract the so-called extreme @@ -189,6 +190,8 @@ void construct_optimal_bounding_box(std::array& obb /// \cgalParamEnd /// \cgalNamedParamsEnd /// +/// \pre the value type of `PointRange` is `Point` +/// template @@ -250,14 +253,14 @@ void optimal_bounding_box(const PointRange& points, /// /// constructs a rectangular box that contains the input mesh. This bounding box /// is obtained via an optimization process aiming to get a close approximation of the -/// optimal bounding box. +/// optimal bounding box, which is defined as the smallest (in terms of volume) +/// of all the rectangular boxes containing the input mesh. /// /// \tparam PolygonMesh a model of `FaceListGraph` /// \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" /// /// \param pmesh the input mesh -/// \param obb_mesh the eight points of the resulting englobing box. -/// The order of points is the same as in the function `CGAL::make_hexahedron()` +/// \param obb_mesh the resulting enclosing bounding box (an hexahedron) /// \param np an optional sequence of \ref obb_namedparameters "Named Parameters" among the ones listed below: /// /// \cgalNamedParamsBegin diff --git a/Optimal_bounding_box/test/Optimal_bounding_box/test_linear_algebra_functions.cpp b/Optimal_bounding_box/test/Optimal_bounding_box/test_linear_algebra_functions.cpp index 5ae7753271f..9482f15ff49 100644 --- a/Optimal_bounding_box/test/Optimal_bounding_box/test_linear_algebra_functions.cpp +++ b/Optimal_bounding_box/test/Optimal_bounding_box/test_linear_algebra_functions.cpp @@ -9,7 +9,7 @@ bool assert_doubles(double d1, double d2, double epsilon) return (d1 < d2 + epsilon && d1 > d2 - epsilon) ? true : false; } -void test_qr_factorization() +void test_get_Q() { typedef CGAL::Eigen_dense_matrix Mat; Mat A(3, 3); @@ -23,7 +23,7 @@ void test_qr_factorization() A.set_coef(2, 1, 0.0202949); A.set_coef(2, 2, 0.9240308); - CGAL_assertion_code(Mat Q = CGAL::Eigen_linear_algebra_traits::qr_factorization(A)); + CGAL_assertion_code(Mat Q = CGAL::Eigen_linear_algebra_traits::get_Q(A)); CGAL_assertion_code(double epsilon = 1e-6); CGAL_assertion(assert_doubles(Q(0,0), -0.504895, epsilon)); CGAL_assertion(assert_doubles(Q(0,1), 0.862834, epsilon)); @@ -243,7 +243,7 @@ void test_eigen_matrix_interface() C.set_coef(2, 1, 0.0202949); C.set_coef(2, 2, 0.9240308); - CGAL_assertion_code(Matrix Q = CGAL::Eigen_linear_algebra_traits::qr_factorization(C)); + CGAL_assertion_code(Matrix Q = CGAL::Eigen_linear_algebra_traits::get_Q(C)); CGAL_assertion_code(double epsilon = 1e-5); CGAL_assertion(assert_doubles(Q(0,0), -0.504895, epsilon)); CGAL_assertion(assert_doubles(Q(0,1), 0.862834, epsilon)); @@ -291,7 +291,7 @@ void test_eigen_matrix_interface() int main() { - test_qr_factorization(); + test_get_Q(); test_fitness_function(); test_simplex_operations(); test_centroid(); diff --git a/Optimal_bounding_box/test/Optimal_bounding_box/test_optimization_algorithms.cpp b/Optimal_bounding_box/test/Optimal_bounding_box/test_optimization_algorithms.cpp index fd8eb60b8f0..7284bbc5fe3 100644 --- a/Optimal_bounding_box/test/Optimal_bounding_box/test_optimization_algorithms.cpp +++ b/Optimal_bounding_box/test/Optimal_bounding_box/test_optimization_algorithms.cpp @@ -208,7 +208,7 @@ void test_random_unit_tetra() Matrix R = evolution.get_best(); const double epsilon = 1e-3; - assert(assert_doubles(Linear_algebra_traits::determinant(R), 1, epsilon)); + assert(assert_doubles(Linear_algebra_traits::compute_determinant(R), 1, epsilon)); assert(assert_doubles(R(0,0), -0.25791, epsilon)); assert(assert_doubles(R(0,1), 0.796512, epsilon)); assert(assert_doubles(R(0,2), -0.546855, epsilon)); @@ -249,7 +249,7 @@ void test_reference_tetrahedron(const char* fname) Matrix R = experiment.get_best(); double epsilon = 1e-5; - assert(assert_doubles(Linear_algebra_traits::determinant(R), 1, epsilon)); + assert(assert_doubles(Linear_algebra_traits::compute_determinant(R), 1, epsilon)); #ifdef CGAL_OPTIMAL_BOUNDING_BOX_DEBUG_TEST // postprocessing @@ -282,7 +282,7 @@ void test_long_tetrahedron(const std::string fname) Matrix R = experiment.get_best(); double epsilon = 1e-3; - assert(assert_doubles(Linear_algebra_traits::determinant(R), 1, epsilon)); + assert(assert_doubles(Linear_algebra_traits::compute_determinant(R), 1, epsilon)); assert(assert_doubles(R(0,0), -1, epsilon)); assert(assert_doubles(R(0,1), 0, epsilon)); assert(assert_doubles(R(0,2), 0, epsilon));