From 435f42c113f5265e511f087de83d38f75f9b81a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 1 Mar 2024 12:29:18 +0100 Subject: [PATCH] Update user manual --- Isosurfacing_3/doc/Isosurfacing_3/Doxyfile.in | 7 +-- .../doc/Isosurfacing_3/Isosurfacing_3.txt | 62 +++++++++---------- 2 files changed, 32 insertions(+), 37 deletions(-) diff --git a/Isosurfacing_3/doc/Isosurfacing_3/Doxyfile.in b/Isosurfacing_3/doc/Isosurfacing_3/Doxyfile.in index 6f8ddde9345..a545ae0a900 100644 --- a/Isosurfacing_3/doc/Isosurfacing_3/Doxyfile.in +++ b/Isosurfacing_3/doc/Isosurfacing_3/Doxyfile.in @@ -2,8 +2,7 @@ PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 3D Isosurfacing" -HTML_EXTRA_FILES = ${CGAL_PACKAGE_DOC_DIR}/fig/tractor_offset.gif \ - ${CGAL_PACKAGE_DOC_DIR}/fig/mc_cases.png \ +HTML_EXTRA_FILES = ${CGAL_PACKAGE_DOC_DIR}/fig/mc_cases.png \ ${CGAL_PACKAGE_DOC_DIR}/fig/iwp_dc.png \ - ${CGAL_PACKAGE_DOC_DIR}/fig/cube_mc_dc.png \ - ${CGAL_PACKAGE_DOC_DIR}/fig/perf_threads_iwp_mc.svg + ${CGAL_PACKAGE_DOC_DIR}/fig/MC_DC.png \ + ${CGAL_PACKAGE_DOC_DIR}/fig/performance.png diff --git a/Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt b/Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt index 28d1f825a44..9a8e06b3e27 100644 --- a/Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt +++ b/Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt @@ -74,18 +74,7 @@ In case of a conforming [not defined] grid, the Marching Cubes algorithm generat as output a surface triangle mesh that is 2-manifold in most scenarios. [@todo PA: reformulate, as it is either strict or not - precise in which cases it is not, and say whether you talk about just combinatorially 2-manifold, or truly 2-manifold with 3D embedding taken into account] -If the mesh is 2-manifold and the isosurface does not intersect the domain boundary, -then the output mesh is watertight. Conversely, the output mesh has boundaries when the isosurface -intersects the domain boundaries (see Figure \ref Fig_IsosurfacingMCOpen). - -\cgalFigureAnchor{Fig_IsosurfacingMCOpen} -
- -
-\cgalFigureCaptionBegin{Fig_IsosurfacingMCOpen} -The output MC mesh has boundaries when the isosurface intersects the domain boundary. [todo remake] -\cgalFigureCaptionEnd - +If the mesh is 2-manifold and the isosurface does not intersect the domain boundary, then the output mesh is watertight. As the Marching Cubes algorithm uses linear interpolation of the sampled scalar field along the grid edges, it can miss details or components that are not captured by the sampling of the scalar field. @@ -110,7 +99,7 @@ does not intersect the domain boundaries. [and the input is 2-manifold?] \cgalFigureAnchor{Fig_IsosurfacingMCTMC}
- +
\cgalFigureCaptionBegin{Fig_IsosurfacingMCTMC} MC vs TMC [todo] @@ -125,12 +114,12 @@ of the incident cells. For a uniform hexahedral grid, this results into a quadri On the other hand it generates fewer faces and high quality faces than Marching Cubes, in general. Finally, its main advantage over Marching Cubes is its ability to recover sharp creases and corners. -\cgalFigureAnchor{Fig_IsosurfacingDC} +\cgalFigureAnchor{Fig_IsosurfacingMCDC}
- +
-\cgalFigureCaptionBegin{Fig_IsosurfacingDC} -Isosurface of the a scalar field generated by %Dual Contouring. +\cgalFigureCaptionBegin{Fig_IsosurfacingMCDC} +Comparison between a CSG shape generated by Marching Cubes (left) and %Dual Contouring (right). \cgalFigureCaptionEnd In addition to the scalar field, %Dual Contouring requires knowledge of the gradient of said scalar field. @@ -142,7 +131,7 @@ Using this strategy, the position can in fact lie outside the cell, which is a d to improve the odds of recovering sharp features, but it might also create self-intersections. Users can choose to constrain the placement to lie within the cell. -By default, the Dual Contouring algorithm creates quads, but using edge-isosurface intersections, +By default, %Dual Contouring creates quads, but using edge-isosurface intersections, one can "star" these quads to create four triangles. This is the default behavior in \cgal, and it can be changed in the named parameters. @@ -152,21 +141,28 @@ The following table summarizes the differences between the algorithms in terms o over the input 3D domain, the facets of the output surface mesh, and the properties of the output surface mesh. +
| Algorithm | Facets | 2-Manifold | Watertight* | Topologically correct | Sharpness | | ---- | ---- | ---- | ---- | ---- | ---- | MC | Triangles | no | no | no | no | TMC | Triangles | yes | yes | yes | no | DC | Polygons | no | no | no | yes** | +
-(* assuming the isosurface does not exit the specified bounding box of the input 3D domain) +(* assuming the isosurface does not exit the specified bounding box of the input 3D domain)
(** not guaranteed) -\cgalFigureAnchor{Fig_IsosurfacingMCDC} +Note that the output mesh has boundaries when the isosurface intersects the domain boundaries, +regardless of the method (see Figure \ref Fig_IsosurfacingOpen). + +\cgalFigureAnchor{Fig_IsosurfacingOpen}
- +
-\cgalFigureCaptionBegin{Fig_IsosurfacingMCDC} -Comparison between a cube generated by Marching Cubes (left) and %Dual Contouring (right). +\cgalFigureCaptionBegin{Fig_IsosurfacingOpen} +Ooutput meshes can have boundaries when the isosurface intersects the domain boundary: +outputs of Marching Cubes (left) and %Dual Contouring (right) for an implicit sphere +of radius 1.1 and a domain of size 2x2x2, both centered at the origin. \cgalFigureCaptionEnd \section SecInterface Interface @@ -221,7 +217,7 @@ Both these domain models possess template parameters to allow the user to custom - ValueField: this must be a class that provides the scalar field at the vertices of the partition. A few classes are provided by default, such as `CGAL::Isosurfacing::Value_function_3` and `CGAL::Isosurfacing::Interpolated_discrete_values_3`. Users can provide their own value class, - provided it meets the requirements described by the concept `ValueField_3`. + provided it meets the requirements described by the concept `IsosurfacingValueField_3`. - GradientField (`Dual_contouring_domain_3` only): this must be a class that provides the gradient of the scalar field at the vertices of the partition. A few classes are provided by default, such as @@ -229,7 +225,7 @@ Both these domain models possess template parameters to allow the user to custom `CGAL::Isosurfacing::Interpolated_discrete_gradients_3`. Users can provide their own gradient class, provided it meets the requirements described - by the concept `GradientField_3`. + by the concept `IsosurfacingGradientField_3`. - EdgeIntersectionOracle: this must be a class that provides a function to compute the intersection between an edge and the isosurface. The default is linear interpolation for `CGAL::Isosurfacing::Marching_cubes_domain_3`, and a dichotomy @@ -238,21 +234,21 @@ Both these domain models possess template parameters to allow the user to custom example no point doing a dichotomy in DC if the value field is defined through linear interpolation. Users can provide their own edge intersection oracle, provided it meets the requirements described by the concept - `EdgeIntersectionOracle_3`. + `IsosurfacingEdgeIntersectionOracle_3`. \section SecPerformance Performance -\cgalFigureAnchor{isosurfacing_perf_iwp_mc} +Due to their cell-based nature, the isosurfacing algorithms are well-suited for parallel execution. + +\cgalFigureAnchor{fig_IsosurfacingPerf}
- +
-\cgalFigureCaptionBegin{isosurfacing_perf_iwp_mc} -Scalability of the Marching Cubes algorithm. We plot the algorithm efficiency (number of thousand-cubes per second) against the number of CPU cores. \cgalFigureCaptionEnd \section SecExamples Examples -The first two examples are very basic examples for Marching Cubes and Dual Contouring. +The first two examples are very basic examples for Marching Cubes and %Dual Contouring. Afterwards, the focus is shifted from the method to the type of input data, and examples run both methods on different types of input data. @@ -273,7 +269,7 @@ the free function to create a domain from a Cartesian grid, and its named parame \subsection SubSecImplicitDataExample Implicit Data -The following example shows the usage of Marching Cubes and Dual Contouring algorithms to extract +The following example shows the usage of Marching Cubes and %Dual Contouring algorithms to extract an isosurface. The domain is an implicit domain that describes the unit sphere by the distance to its center (set to the origin) as an implicit field. @@ -290,7 +286,7 @@ In the following example, the input data is sampled at the vertices of a grid, a The following example shows how to load data from an `Image_3`, and generate an isosurface from this voxel data. -\cgalExample{Isosurfacing_3/contouring_image.cpp} +\cgalExample{Isosurfacing_3/contouring_inrimage.cpp} \subsection SubSecOffsetDataExample Offset Mesh