From feb3b766a57eed4660f196f0c0b01c0ae1cf1e7d Mon Sep 17 00:00:00 2001 From: Sven Oesau Date: Thu, 20 Nov 2025 16:49:05 +0100 Subject: [PATCH] doc update bugfix --- .../Convex_decomposition_3.txt | 9 +++++---- .../Convex_decomposition_3/PackageDescription.txt | 2 +- .../doc/Convex_decomposition_3/dependencies | 1 + .../include/CGAL/approximate_convex_decomposition.h | 13 +++++++------ 4 files changed, 14 insertions(+), 11 deletions(-) diff --git a/Convex_decomposition_3/doc/Convex_decomposition_3/Convex_decomposition_3.txt b/Convex_decomposition_3/doc/Convex_decomposition_3/Convex_decomposition_3.txt index d3c6a6506a9..d78c46626a8 100644 --- a/Convex_decomposition_3/doc/Convex_decomposition_3/Convex_decomposition_3.txt +++ b/Convex_decomposition_3/doc/Convex_decomposition_3/Convex_decomposition_3.txt @@ -22,7 +22,7 @@ package offers two methods for decomposing polyhedra. The \ref Convex_decomposition_3Nef "Convex Decomposition of Nef Polyhedra" splits polyhedra into convex pieces with an upper bound on their number. The \ref Convex_decomposition_3ACD_Intro -"Approximate convex decomposition" method offers a fast +"Approximate Convex Decomposition" method offers a fast approximate decomposition of the convex hull into convex volumes. While any number of convex volumes can be generated, these convex volumes are more compact than the convex hull, but still include additional @@ -98,7 +98,7 @@ extended kernels in the convex decomposition is not supported. \cgalFigureCaptionBegin{Acd_topfig} -Approximate convex decomposition of the elephant.off model.\n From left to right: 1. input mesh 2. 5 convex volumes 3. 8 convex volumes 4. 12 convex volumes +Approximate convex decomposition of the elephant.off model.\n From left to right: input mesh, 5, 8, and 12 convex volumes \cgalFigureCaptionEnd The H-VACD method \cgalCite{cgal:mamou2016volumetric}, "Hierarchical volumetrix approximate convex decomposition", computes a set of convex volumes that fit the polyhedron. Contrary to the decomposition of the polyhedron into convex parts, the convex volumes cover the polyhedron, but also include additional volume outside of it. @@ -116,7 +116,7 @@ The algorithm computes a set of convex volumes \f$ C=\{C_i\f$ with \f$ i \in[0.. d(A, B) = |A| - |B| \f} -Where \f$|A|\f$ is the volume of A, P is the input polyhedron and \f$C_i\f$ are convex volumes. The convex volumes \f$C_i\f$ are pairwise disjunct, i.e., \f$|C_i \cap C_j| = 0\f$ if \f$i \neq j\f$. And the union of convex volumes contain the input polyhedron \f$ P \subset \bigcup_{C_i \in C} \f$. +Where \f$|A|\f$ is the volume of A, P is the input polyhedron and \f$C_i\f$ are convex volumes. The convex volumes \f$C_i\f$ are pairwise disjoint, i.e., \f$|C_i \cap C_j| = 0\f$ if \f$i \neq j\f$. And the union of convex volumes contain the input polyhedron \f$ P \subset \bigcup_{C_i \in C} \f$. \cgalFigureAnchor{Acd_pipelinefig}
@@ -127,7 +127,8 @@ Approximate convex decomposition pipeline.\n From left to right: 1. input mesh 2 \cgalFigureCaptionEnd The method employs a top-down splitting phase followed by a bottom-up merging to achieve the target number of convex volumes. The splitting phase aims at decomposing the input mesh into smaller mostly convex parts. Each part of the input mesh is approximated with its convex hull. In a hierarchical manner, each part of the mesh is split into two parts when its convexity is low. The convexity is measured by the volume difference of the part and its convex hull. Splitting a part into two can be done by simply cutting the longest side of the bounding box in half. A better choice is often found by searching the longest side of the bounding box for a concave spot. However, it comes with a higher computational cost. The hierarchical splitting stops when either the convexity is sufficiently high or the maximum depth is reached. -The volume calculation, convex hull computation and the concavity search is accelerated by a voxel grid. The grid is prepared before the splitting phase and is labelled into outside, inside or surface. The convex hulls are calculated from voxel corners. Thus, a mesh with a high resolution is less penalized by its number of vertices. +The volume calculation, convex hull computation and the concavity search is accelerated by a voxel grid. The grid is prepared before the splitting phase and voxel cells overlapping with triangles are labeled as surface. The remaining voxels are labeled as outside or inside by flood fill, in case the input mesh is closed, or by axis-aligned ray shooting, i.e., along x, y and z-axes in positive and negative directions. A voxel is only labeled as inside if at least 3 faces facing away from the voxel have been hit and +no face facing towards the voxel. The convex hulls are calculated from voxel corners. Thus, a mesh with a high resolution is less penalized by its number of vertices. The splitting phase typically results in a number of convex volumes larger than targeted. The second phase employs a bottom-up merging that reduces the number of convex volumes to the targeted number while aiming at maintaining a low volume difference between convex volumes and the input mesh. The greedy merging maintains a priority queue to incrementally merge the pair of convex volumes with the smallest increase of volume difference. The splitting phase is not limited by the chosen `maximum_number_of_convex_volumes`, because a splitting into a larger number of more convex parts with a subsequent merging leads to better results. diff --git a/Convex_decomposition_3/doc/Convex_decomposition_3/PackageDescription.txt b/Convex_decomposition_3/doc/Convex_decomposition_3/PackageDescription.txt index 4db19541a8e..308d8ecbf33 100644 --- a/Convex_decomposition_3/doc/Convex_decomposition_3/PackageDescription.txt +++ b/Convex_decomposition_3/doc/Convex_decomposition_3/PackageDescription.txt @@ -22,7 +22,7 @@ The `CGAL::approximate_convex_decomposition()` instead splits the convex hull of \cgalCRPSection{Functions} - `CGAL::convex_decomposition_3(Nef_polyhedron_3& N)` -- `CGAL::approximate_convex_decomposition()` +- `CGAL::approximate_convex_decomposition(FaceGraph)` */ diff --git a/Convex_decomposition_3/doc/Convex_decomposition_3/dependencies b/Convex_decomposition_3/doc/Convex_decomposition_3/dependencies index 6d540982926..9f1e130e7fe 100644 --- a/Convex_decomposition_3/doc/Convex_decomposition_3/dependencies +++ b/Convex_decomposition_3/doc/Convex_decomposition_3/dependencies @@ -6,3 +6,4 @@ Circulator Stream_support Nef_3 BGL +Polygon_mesh_processing diff --git a/Surface_mesh_decomposition/include/CGAL/approximate_convex_decomposition.h b/Surface_mesh_decomposition/include/CGAL/approximate_convex_decomposition.h index 5b786a69f42..b00b662beba 100644 --- a/Surface_mesh_decomposition/include/CGAL/approximate_convex_decomposition.h +++ b/Surface_mesh_decomposition/include/CGAL/approximate_convex_decomposition.h @@ -1533,11 +1533,10 @@ void merge(std::vector>& candidates, const typ /** * \ingroup PkgConvexDecomposition3Ref * - * \brief approximates the input mesh by a number of convex volumes. The input mesh is voxelized and the voxels intersecting with the mesh are labeled as surface. - * The remaining voxels are labeled as outside or inside by flood fill, in case the input mesh is closed, or by axis-aligned ray shooting, i.e., along x, - * y and z-axis in positive and negative directions. A voxel is only labeled as inside if at least 3 faces facing away from the voxel have been hit and - * no face facing towards the voxel. In a next step, the convex hull of the mesh is hierarchically split until the `volume_error` threshold is satisfied. - * Afterwards, a greedy pair-wise merging combines smaller convex volumes until the given number of convex volumes is met. + * \brief approximates the input mesh by a number of convex volumes. + * The input mesh is voxelized and the voxels intersecting with the mesh are labeled as surface. The remaining voxels are labeled as outside or inside. + * In a next step, the convex hull of the mesh is hierarchically split until the `volume_error` threshold is satisfied or the `maximum_depth` is reached. + * Finally, a greedy pair-wise merging combines smaller convex volumes until `maximum_number_of_convex_volumes` is met. * * \tparam FaceGraph a model of `HalfedgeListGraph`, and `FaceListGraph` * @@ -1607,6 +1606,8 @@ void merge(std::vector>& candidates, const typ * * \return the number of convex hulls. Note that this value may be lower than the `maximum_number_of_convex_volumes`, for example if the specified `volume_error` is quickly met. * + * \pre `tmesh` is a triangle mesh. + * \pre `tmesh` is not self-intersecting. * \sa `CGAL::Polygon_mesh_processing::polygon_soup_to_polygon_mesh()` */ template @@ -1640,7 +1641,7 @@ std::size_t approximate_convex_decomposition(const FaceGraph& tmesh, OutputItera convex_hull_3(boost::make_transform_iterator(vertices(tmesh).begin(), v2p), boost::make_transform_iterator(vertices(tmesh).end(), v2p), ch.points, ch.indices); - *out_hulls = std::make_pair(std::move(ch.points), std::move(ch.indices)); + *out_volumes = std::make_pair(std::move(ch.points), std::move(ch.indices)); return 1; }