songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update user manual

This commit is contained in:
Mael Rouxel-Labbé 2024-03-01 12:29:18 +01:00
parent 689d69533b
commit 435f42c113
2 changed files with 32 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
Isosurfacing_3/doc/Isosurfacing_3/Doxyfile.in
View File

@ -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

62
Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt
View File

@ -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}
<center>
<img src="open.png" style="max-width:40%;"/>
</center>
\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}
<center>
<img src="open.png" style="max-width:70%;"/>
<img src="MC_TMC.png" style="max-width:70%;"/>
</center>
\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}
<center>
<img src="todo.png" style="max-width:40%;"/>
<img src="MC_DC.png" style="max-width:70%;"/>
</center>
\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.
<center>
| 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** |
</center>
(* 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)<br>
(** 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}
<center>
<img src="cube_mc_dc.png" style="max-width:70%;"/>
<img src="open.png" style="max-width:70%;"/>
</center>
\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
- <b>ValueField:</b> 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`.
- <b>GradientField (`Dual_contouring_domain_3` only):</b> 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`.
- <b>EdgeIntersectionOracle:</b> 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}
<center>
<img src="perf_threads_iwp_mc.svg" style="max-width:70%;"/>
<img src="performance.png" style="max-width:70%;"/>
</center>
\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