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

Misc doc fixes

This commit is contained in:
Mael Rouxel-Labbé 2024-04-04 12:42:50 +02:00
parent 76e07cf9d5
commit ee4c6dc7bf
10 changed files with 58 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
Isosurfacing_3/doc/Isosurfacing_3/Isosurfacing_3.txt
View File

@ -70,23 +70,20 @@ Examples of some configurations for 2D Marching Cubes.
\cgalFigureCaptionEnd
The implementation within \cgal is generic in the sense that it can process any grid-like data structure
that consists of hexahedral cells.
In case of a conforming grid, the Marching Cubes algorithm generates
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
that consists of hexahedral cells. When the hexahedral grid is a conforming grid (meaning that the
intersection of two hexahedral cells is a face, and edge, or a vertex), the Marching Cubes algorithm
generates as output a surface triangle mesh that is almost always combinatorially 2-manifold,
but can also produce cracks in the surface.
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.
Compared to other approaches such as Delaunay refinement, and depending on the parameters,
MC often generates more triangles, and more skinny triangles with small or large angles.
@todo PA: The statement is too strong - I would largely reformulate it as this depends too much on the parameters. I recommend to add instead a figure with different parameters and methods,
depicting the mesh edges in black in addition to the shaded facets.
Compared to other meshing approaches such as Delaunay refinement, Marching Cubes is much faster,
but often tends to generate more triangles for an equivalent desired sizing field. In addition,
the quality of the elements if generally poor, with many needles / caps shaped faces.
Furthermore, MC does not preserve the sharp features present in the isovalue of the input scalar field
Furthermore, Marching Cubes does not preserve the sharp features present in the isovalue of the input scalar field
(see \cgalFigureRef{IsosurfacingMCDC}).
\subsection SubSecTMC Topologically Correct Marching Cubes (TMC)
@ -128,7 +125,7 @@ Comparison between a mesh of a CSG shape generated by Marching Cubes (left) and
In addition to the scalar field, %Dual Contouring requires knowledge of the gradient of said scalar field.
The \cgal implementation uses a point positioning strategy based on Quadric Error Metrics: for
The \cgal implementation uses a point positioning strategy based on *Quadric Error Metrics*: for
a cell, the position of the vertex is computed by minimizing the error to the sum of the quadrics
defined at each edge-isosurface intersection.
Using this strategy, the position can in fact lie outside the cell, which is a desirable property
@ -150,11 +147,10 @@ of the output surface mesh.
| ---- | ---- | ---- | ---- | ---- | ---- |
MC | Triangles | no | no | no | no |
TMC | Triangles | yes | yes | yes | no |
DC | Polygons | no | no | no | yes** |
DC | Polygons | no | no | no | yes (not guaranteed) |
</center>
(* assuming the isosurface does not exit the specified bounding box of the input 3D domain)<br>
(** not guaranteed)
(* assuming the isosurface does not exit the specified bounding box of the input 3D domain)
Note that the output mesh has boundaries when the isosurface intersects the domain boundaries,
regardless of the method (see \cgalFigureRef{IsosurfacingOpen}).
@ -208,35 +204,35 @@ To enable parallelism, \cgal must be linked with the <a href="https://github.com
\subsection SubSecIsosurfacingDomains Domains
A domain is an object that provides functions to access the partition of the 3D volume,
the scalar field, and - optionally - the gradient field at a given position.
the scalar field, and, optionally, the gradient field at a given position.
These requirements are described through two concepts: `IsosurfacingDomain_3` and `IsosurfacingDomainWithGradient_3`.
Two domains, `CGAL::Isosurfacing::Marching_cubes_domain_3` and `CGAL::Isosurfacing::Dual_contouring_domain_3`,
are provided as the respective default class models that fulfill the requirements of the concepts.
Both these domain models are equipped with template parameters enabling the user to customize the domain:
Both these domain models have template parameters enabling the user to customize the domain:
- <b>Partition:</b> this must be a class that describes the partition of the 3D volume into cells.
The most basic example of such class is `CGAL::Isosurfacing::Cartesian_grid_3`, but users
can provide their own partition, provided it meets the requirements described
can pass their own partition, provided it meets the requirements described
by the concept `IsosurfacingPartition_3`.
- <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 `IsosurfacingValueField_3`.
A few classes are provided, such as `CGAL::Isosurfacing::Value_function_3` and
`CGAL::Isosurfacing::Interpolated_discrete_values_3`. Users can pass their own value class,
provided it meets the requirements described by the concept `IsosurfacingValueField_3`.
- <b>GradientField:</b> (`CGAL::Isosurfacing::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
`CGAL::Isosurfacing::Finite_difference_gradient_3` and
`CGAL::Isosurfacing::Interpolated_discrete_gradients_3`.
Users can provide their own gradient class,
provided it meets the requirements described
by the concept `IsosurfacingGradientField_3`.
of the scalar field at the vertices of the partition.
A few classes are provided by default, such as
`CGAL::Isosurfacing::Finite_difference_gradient_3` and
`CGAL::Isosurfacing::Interpolated_discrete_gradients_3`.
Users can pass their own gradient class,
provided it meets the requirements described
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
for `CGAL::Isosurfacing::Dual_contouring_domain_3`. This parameter should
be adjusted depending on how your value field is defined: there is for
example no point doing a dichotomy in DC if the value field is defined
through linear interpolation. Users can provide their own edge intersection
example no point doing a dichotomy in Dual Contouring if the value field is defined
through linear interpolation. Users can pass their own edge intersection
oracle, provided it meets the requirements described by the concept
`IsosurfacingEdgeIntersectionOracle_3`.

23
Isosurfacing_3/doc/Isosurfacing_3/PackageDescription.txt
View File

@ -4,18 +4,28 @@
/// \defgroup IS_Partitions_grp Space Partitioning Data Structures
/// \ingroup PkgIsosurfacing3Ref
///
/// This group encapsulates classes that represent a spatial discretization of space,
/// which will be the scaffolding for the construction of the isosurface.
/// \defgroup IS_Partitions_helpers_grp Space Partitioning Data Structures Helpers
/// \ingroup IS_Partitions_grp
/// \defgroup IS_Fields_helpers_grp Value and Gradient Fields Helpers
/// \ingroup PkgIsosurfacing3Ref
///
/// The following classes and functions are parameters or template parameters of value and gradient fields.
/// \defgroup IS_Fields_grp Value and Gradient Fields
/// \ingroup PkgIsosurfacing3Ref
///
/// The following classes represent the data that defines the isosurface.
/// \defgroup IS_Domains_grp Isosurfacing Domains
/// \ingroup PkgIsosurfacing3Ref
///
/// This group encapsulates the classes that can be used to represent a complete domain (partition
/// and fields), to be used by the isosurfacing methods of this package.
/// \defgroup IS_Domain_helpers_grp Isosurfacing Domain Helpers
/// \ingroup IS_Domains_grp
@ -32,24 +42,21 @@
\cgalPkgPicture{isosurfacing3_ico.png}
\cgalPkgSummaryBegin
\cgalPkgAuthor{Mael Rouxel-Labbé, Julian Stahl, Daniel Zint, and Pierre Alliez}
\cgalPkgDesc{This package implements several isosurfacing algorithms (Marching Cubes,
\cgalPkgDesc{This package implements several grid-based isosurfacing algorithms (Marching Cubes,
its topologically correct variant, and Dual Contouring) that enable generating meshes
from value and gradient fields.}
from value and gradient fields. The methods are generic with respect to the definition
of the grid and the fields, and all methods offer parallel implementations.
The output is a polygon soup (i.e., a container of point coordinates and indexed faces).}
\cgalPkgManuals{Chapter_Isosurfacing3,PkgIsosurfacing3Ref}
\cgalPkgSummaryEnd
\cgalPkgShortInfoBegin
\cgalPkgSince{5.6}
\cgalPkgSince{6.1}
\cgalPkgBib{cgal:sz-mc}
\cgalPkgLicense{\ref licensesGPL "GPL"}
\cgalPkgDemo{Polyhedron demo,polyhedron_3.zip}
\cgalPkgShortInfoEnd
\cgalPkgDescriptionEnd
This package provides algorithms to extract isosurfaces: Marching Cubes, topologically correct Marching Cubes,
and Dual Contouring.
The input is represented as a space partitioning data structure coupled with a 3D scalar field.
The output is a polygon soup (i.e., a container of point coordinates and indexed faces).
\cgalClassifedRefPages
\cgalCRPSection{Concepts}

4
Isosurfacing_3/include/CGAL/Isosurfacing_3/Dual_contouring_domain_3.h
View File

@ -63,7 +63,7 @@ public:
* \param intersection_oracle the oracle for edge-isosurface intersection computation
*
* \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
* As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
* As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
*/
Dual_contouring_domain_3(const Partition& partition,
const ValueField& values,
@ -89,7 +89,7 @@ public:
* \param intersection_oracle the oracle for edge-isosurface intersection computation
*
* \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
* As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
* As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
*/
template <typename Partition,
typename ValueField,

2
Isosurfacing_3/include/CGAL/Isosurfacing_3/Finite_difference_gradient_3.h
View File

@ -53,7 +53,7 @@ public:
/**
* \brief creates a new instance of this gradient class.
*
* \tparam ValueFunction must be a model of `ValueFunction_3`.
* \tparam ValueFunction must be a model of `IsosurfacingValueField_3`.
*
* \param function the function giving the scalar value at each point
* \param delta the distance between samples for calculating the finite differences

4
Isosurfacing_3/include/CGAL/Isosurfacing_3/Interpolated_discrete_gradients_3.h
View File

@ -25,11 +25,11 @@ namespace CGAL {
namespace Isosurfacing {
/**
* \ingroup IS_Domain_helpers_grp
* \ingroup IS_Fields_grp
*
* \cgalModels{IsosurfacingValueField_3}
*
* \brief Class template for a gradient that is calculated using discrete values and trilinear interpolation.
* \brief Class template for a gradient field that is computed using discrete values and interpolation.
*
* \tparam Grid must be `CGAL::Isosurfacing::Cartesian_grid_3<GeomTraits>`, with `GeomTraits` a model of `IsosurfacingTraits_3`
* \tparam InterpolationScheme must be a model of `IsosurfacingInterpolationScheme_3`

2
Isosurfacing_3/include/CGAL/Isosurfacing_3/Interpolated_discrete_values_3.h
View File

@ -26,7 +26,7 @@ namespace CGAL {
namespace Isosurfacing {
/**
* \ingroup IS_Domain_helpers_grp
* \ingroup IS_Fields_grp
*
* \cgalModels{IsosurfacingValueField_3}
*

4
Isosurfacing_3/include/CGAL/Isosurfacing_3/Marching_cubes_domain_3.h
View File

@ -60,7 +60,7 @@ public:
* \param intersection_oracle the oracle for edge-isosurface intersection computation
*
* \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
* As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
* As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
*/
Marching_cubes_domain_3(const Partition& partition,
const ValueField& values,
@ -83,7 +83,7 @@ public:
* \param intersection_oracle the oracle for edge-isosurface intersection computation
*
* \warning the domain class keeps a reference to the `partition`, `values` and `gradients` objects.
* As such, users must ensure that the lifetime of these objects exceeds that of the domain object.
* As such, users must ensure that the lifetimes of these objects exceed that of the domain object.
*/
template <typename Partition,
typename ValueField,

2
Isosurfacing_3/include/CGAL/Isosurfacing_3/Value_function_3.h
View File

@ -23,7 +23,7 @@ namespace CGAL {
namespace Isosurfacing {
/**
* \ingroup IS_Domain_helpers_grp
* \ingroup IS_Fields_grp
*
* \cgalModels{IsosurfacingValueField_3}
*

2
Isosurfacing_3/include/CGAL/Isosurfacing_3/edge_intersection_oracles_3.h
View File

@ -174,6 +174,7 @@ struct Linear_interpolation_edge_intersection
}
};
#ifndef DOXYGEN_RUNNING
/*
* \ingroup IS_Domain_helpers_grp
*
@ -199,6 +200,7 @@ struct Ray_marching_edge_intersection
const typename Domain::Geom_traits::FT isovalue,
typename Domain::Geom_traits::Point_3& p) const;
};
#endif // DOXYGEN_RUNNING
} // namespace Isosurfacing
} // namespace CGAL

6
Isosurfacing_3/include/CGAL/Isosurfacing_3/interpolation_schemes_3.h
View File

@ -195,6 +195,11 @@ public:
}
};
#ifndef DOXYGEN_RUNNING
// [undocumented]
//
// \ingroup IS_Fields_helpers_grp
//
// This can be used for example when we have implicit functions for data (values & gradients),
// but use an interpolated values field as to store data.
template <typename Grid>
@ -227,6 +232,7 @@ public:
return m_gradient_fn(p);
}
};
#endif
} // namespace Isosurfacing
} // namespace CGAL