CGAL 5.6.3 - 3D Mesh Generation

Loading...
Searching...
No Matches
List of all members
CGAL::Labeled_mesh_domain_3< BGT, Subdomain_index_, Surface_patch_index_ > Class Template Reference
3D Mesh Generation Reference » Domain Classes

`#include <CGAL/Labeled_mesh_domain_3.h>`

## Definition

template<class BGT, class Subdomain_index_ = int, class Surface_patch_index_ = std::pair<Subdomain_index_, Subdomain_index_>>
class CGAL::Labeled_mesh_domain_3< BGT, Subdomain_index_, Surface_patch_index_ >

The class `Labeled_mesh_domain_3` implements indexed domains.

This class is a model of concept `MeshDomain_3`.

Any boundary facet is labeled <a,b>, with a<b, where a and b are the tags of its incident subdomains. Thus, a boundary facet of the domain is labeled <0,b>, where b!=0.

This class includes a labeling function that provides the index of the subdomain in which any query point lies. An intersection between a segment and bounding surfaces is detected when both segment endpoints are associated with different values of subdomain indices. The intersection is then constructed by bisection. The bisection stops when the query segment is shorter than an error bound `e` given by the product of the length of the diagonal of the bounding box (in world coordinates), or the radius of the bounding sphere, and a relative error bound passed as argument to the constructor of `Labeled_mesh_domain_3`.

This class has a constructor taking a labeling function. It has also three static template member functions that act as named constructors:

- `create_gray_image_mesh_domain()`, to create a domain from a 3D gray image,
- `create_labeled_image_mesh_domain()`, to create a domain from a 3D labeled image, and
- `create_implicit_mesh_domain()`, to create a domain from an implicit function.

Template Parameters

  BGT | is a geometric traits class that provides the basic operations to implement intersection tests and intersection computations through a bisection method. This parameter must be instantiated with a model of the concept `BisectionGeometricTraits_3`.

Labeling function

A labeling function `f` must return `0` if the point isn't located in any subdomain. The return type of labeling functions is an integer.

Let `p` be a Point.

- `f(p)=0` means that `p` is outside domain.
- `f(p)=a`, `a!=0` means that `p` is inside subdomain `a`.

`CGAL::Implicit_multi_domain_to_labeling_function_wrapper` is a good candidate for this template parameter if there are several components to mesh.

The function type can be any model of the concept `Callable` compatible with the signature `Subdomain_index(const Point_3&)`: it can be a function, a function object, a lambda expression... that takes a `Point_3` as argument, and returns a type convertible to `Subdomain_index`.

Is Model Of:
  `MeshDomain_3`

See also
  `Implicit_multi_domain_to_labeling_function_wrapper`
  `CGAL::make_mesh_3()`.

Examples
  Mesh_3/mesh_3D_gray_image.cpp, Mesh_3/mesh_3D_gray_image_with_custom_initialization.cpp, Mesh_3/mesh_3D_gray_vtk_image.cpp, Mesh_3/mesh_3D_image.cpp, Mesh_3/mesh_3D_image_variable_size.cpp, Mesh_3/mesh_3D_image_with_custom_initialization.cpp, Mesh_3/mesh_3D_image_with_detection_of_features.cpp, Mesh_3/mesh_3D_image_with_features.cpp, Mesh_3/mesh_3D_image_with_input_features.cpp, Mesh_3/mesh_3D_weighted_image.cpp, Mesh_3/mesh_hybrid_mesh_domain.cpp, Mesh_3/mesh_implicit_domains.cpp, Mesh_3/mesh_implicit_domains_2.cpp, Mesh_3/mesh_implicit_ellipsoid.cpp, Mesh_3/mesh_implicit_sphere.cpp, Mesh_3/mesh_implicit_sphere_variable_size.cpp, Mesh_3/mesh_optimization_example.cpp, Mesh_3/mesh_optimization_lloyd_example.cpp, and Mesh_3/mesh_two_implicit_spheres_with_balls.cpp.

## Types
typedef Subdomain_index_ | Subdomain_index
| The subdomain index of this model of `MeshDomain_3`
typedef std::function< Subdomain_index(const Point_3 &)> | Labeling_function
| The type of object that stores the function using type-erasure.

## Types imported from the geometric traits class
typedef Geom_traits::Point_3 | Point_3
| The point type of the geometric traits class.
typedef Geom_traits::Sphere_3 | Sphere_3
| The sphere type of the geometric traits class.
typedef Geom_traits::Iso_cuboid_3 | Iso_cuboid_3
| The iso-cuboid type of the geometric traits class.
typedef Geom_traits::FT | FT
| The number type (a field type) of the geometric traits class.

## Creation
template<typename Function , typename Bounding_object , typename NamedParameters = CGAL::parameters::Default_named_parameters>
| Labeled_mesh_domain_3 (const Function &function, const Bounding_object &bounding_object, const NamedParameters &np=parameters::default_values(), typename std::enable_if<!is_named_function_parameter< Function > >::type *=nullptr)
| Construction from a function, a bounding object and a relative error bound.

## Creation of domains from 3D images
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>
static Labeled_mesh_domain_3 | create_gray_image_mesh_domain (const CGAL::Image_3 &image_, const NamedParameters &np=parameters::default_values())
| Construction from a 3D gray image.
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>
static auto | create_labeled_image_mesh_domain (const CGAL::Image_3 &image_, const NamedParameters &np=parameters::default_values())
| Construction from a 3D labeled image.

## Creation of domains from implicit functions
template<typename Function , typename Bounding_object , typename NamedParameters = CGAL::parameters::Default_named_parameters>
static Labeled_mesh_domain_3 | create_implicit_mesh_domain (const Function &function, const Bounding_object &bounding_object, const NamedParameters &np=parameters::default_values())
| Construction from an implicit function.

## Constructor & Destructor Documentation

## ◆ Labeled_mesh_domain_3()

template<class BGT , class Subdomain_index_ = int, class Surface_patch_index_ = std::pair<Subdomain_index_, Subdomain_index_>>
template<typename Function , typename Bounding_object , typename NamedParameters = CGAL::parameters::Default_named_parameters>

CGAL::Labeled_mesh_domain_3< BGT, Subdomain_index_, Surface_patch_index_ >::Labeled_mesh_domain_3 | ( | const Function & | function,
|  | const Bounding_object & | bounding_object,
|  | const NamedParameters & | np = `parameters::default_values()`,
|  | typename std::enable_if<!is_named_function_parameter< Function > >::type * | = `nullptr`
| ) |  |

Construction from a function, a bounding object and a relative error bound.

Template Parameters

  Function | a type compatible with `Labeling_function`
  NamedParameters | a sequence of Named Parameters
  Bounding_object | either a bounding sphere (of type `Sphere_3`), a bounding box (type `Bbox_3`), or a bounding `Iso_cuboid_3`

Parameters

  function | the labeling function
  bounding_object | the bounding object bounding the meshable space.
  np | an optional sequence of Named Parameters among the ones listed below:

Optional Named Parameters

  the relative error bound used to compute intersection points between the implicit surface and query segments. The bisection is stopped when the length of the intersected segment is less than the product of `relative_error_bound` by the diameter of the bounding object. Default: FT(1e-3) |

Example
From the example (Mesh_3/mesh_implicit_domains_2.cpp):

namespace params = CGAL::parameters;
Mesh_domain domain(Function_wrapper(v, vps),
K::Sphere_3(CGAL::ORIGIN, CGAL::square(K::FT(5))),
params::relative_error_bound(1e-6));
CGAL::square
NT square(const NT &x)
CGAL::ORIGIN
const CGAL::Origin ORIGIN
CGAL::parameters

## Member Function Documentation

## ◆ create_gray_image_mesh_domain()

template<class BGT , class Subdomain_index_ = int, class Surface_patch_index_ = std::pair<Subdomain_index_, Subdomain_index_>>
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

static Labeled_mesh_domain_3 CGAL::Labeled_mesh_domain_3< BGT, Subdomain_index_, Surface_patch_index_ >::create_gray_image_mesh_domain | ( | const CGAL::Image_3 & | image_,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |
| static

Construction from a 3D gray image.

This static method is a named constructor. It constructs a domain described by a 3D gray image. A 3D gray image is a grid of voxels, where each voxel is associated with a gray level value. Unless otherwise specified by the parameter `image_values_to_subdom_indices`, the domain to be discretized is the union of voxels that lie inside a surface described by an isolevel value, called isovalue. The voxels lying inside the domain have gray level values that are larger than the isovalue.

The value of voxels is interpolated to a gray level value at any query point.

Template Parameters

  NamedParameters | a sequence of Named Parameters

Parameters

  image_ | the input 3D image.
  np | an optional sequence of Named Parameters among the ones listed below:

Optional Named Parameters

  the isovalue, inside `image`, of the surface describing the boundary of the object to be meshed. Default: 0 |
  a function or a function object, compatible with the signature `Subdomain_index(double)`. This function returns the subdomain index corresponding to a pixel value. If this parameter is used, then the parameter `iso_value` is ignored. Default: Null_functor() |
  the value attached to voxels outside of the domain to be meshed. It should be lower than `iso_value`. Default: 0 |
  is the relative error bound, relative to the diameter of the box of the image. Default: FT(1e-3) |

Examples

From the example (Mesh_3/mesh_3D_gray_image.cpp):

Mesh_domain domain =
Mesh_domain::create_gray_image_mesh_domain(image, params::iso_value(2.9f).value_outside(0.f));

From the example (Mesh_3/mesh_3D_gray_vtk_image.cpp):

namespace params = CGAL::parameters;
Mesh_domain domain = Mesh_domain::create_gray_image_mesh_domain
(image,
params::image_values_to_subdomain_indices(Less(iso)).
value_outside(0));

## ◆ create_implicit_mesh_domain()

template<class BGT , class Subdomain_index_ = int, class Surface_patch_index_ = std::pair<Subdomain_index_, Subdomain_index_>>
template<typename Function , typename Bounding_object , typename NamedParameters = CGAL::parameters::Default_named_parameters>

static Labeled_mesh_domain_3 CGAL::Labeled_mesh_domain_3< BGT, Subdomain_index_, Surface_patch_index_ >::create_implicit_mesh_domain | ( | const Function & | function,
|  | const Bounding_object & | bounding_object,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |
| static

Construction from an implicit function.

This static method is a named constructor. It constructs a domain whose bounding surface is described implicitly as the zero level set of a function. The domain to be discretized is assumed to be the domain where the function has negative values.

The method takes as argument a bounding sphere which is required to circumscribe the surface and to have its center inside the domain.

Template Parameters

  Function | a type compatible with the signature `FT(Point_3)`: it takes a point as argument, and returns a scalar value. That object must be model of `CopyConstructible`
  NamedParameters | a sequence of Named Parameters
  Bounding_object | either a bounding sphere (of type `Sphere_3`), a bounding box (type `Bbox_3`), or a bounding `Iso_cuboid_3`

Parameters

  function | the implicit function
  bounding_object | object boundint the meshable domain and its center is inside the domain.
  np | an optional sequence of Named Parameters among the ones listed below:

Optional Named Parameters

  is the relative error bound, relative to the diameter of the box of the image. Default: FT(1e-3) |

Examples

From the example (Mesh_3/mesh_implicit_sphere.cpp):

Mesh_domain domain =
Mesh_domain::create_implicit_mesh_domain( sphere_function,
K::Sphere_3(CGAL::ORIGIN, K::FT(2)));

From the example (Mesh_3/mesh_implicit_sphere_variable_size.cpp):

Mesh_domain domain = Mesh_domain::create_implicit_mesh_domain
(sphere_function, K::Sphere_3(CGAL::ORIGIN, K::FT(2))
);

## ◆ create_labeled_image_mesh_domain()

template<class BGT , class Subdomain_index_ = int, class Surface_patch_index_ = std::pair<Subdomain_index_, Subdomain_index_>>
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

static auto CGAL::Labeled_mesh_domain_3< BGT, Subdomain_index_, Surface_patch_index_ >::create_labeled_image_mesh_domain | ( | const CGAL::Image_3 & | image_,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |
| static

Construction from a 3D labeled image.

This static method is a named constructor. It constructs a domain described by a 3D labeled image. A 3D labeled image is a grid of voxels, where each voxel is associated with an index (a subdomain index) characterizing the subdomain in which the voxel lies. The domain to be discretized is the union of voxels that have non-zero values.

Returns
  either a `Labeled_mesh_domain_3`, or a `Mesh_domain_with_polyline_features_3<Labeled_mesh_domain_3>` depending on whether one or more of the named parameters `features_detector` and `input_features` are provided.

Template Parameters

  NamedParameters | a sequence of Named Parameters

Parameters

  image_ | the input 3D image.
  np | an optional sequence of Named Parameters among the ones listed below:

Optional Named Parameters

  a reference to an input 3D image that provides weights associated to each voxel (the word type is `unsigned char`, and the voxels values are integers between 0 and 255). The weights image can be generated with `CGAL::Mesh_3::generate_label_weights()`. Its dimensions must be the same as the dimensions of `parameters::image`. Default: CGAL::Image_3() Type: CGAL::Image_3& Extra: if `features_detector` is provided, `weights` should be modified accordingly. The available functors described in See Feature Detection implement the necessary modifications. Extra: if `input_features` is provided, `weights` should be modified accordingly to keep consistency of the output `MeshDomainWithFeatures_3` |
  the value attached to voxels outside of the domain to be meshed. It should be lower than `iso_value`. Default: 0 |
  is the relative error bound, relative to the diameter of the box of the image. Default: FT(1e-3) |
  a functor that implements `std::vector<std::vector<Point>> operator()(const Image_3& img) const`, and `std::vector<std::vector<Point>> operator()(const Image_3& img, Image_3& weights) const`, where `Point` matches the mesh domain point type, that both return a range of detected polyline features for feature protection. Only one implementation is used, depending on whether the named parameter `weights` is provided or not. Polyline features are added to the domain for further feature protection. See Feature Detection for available functors. Default: CGAL::Null_functor() Extra: The return type of the function depends on whether this parameter or `input_features` are provided or not. Extra: If `weights` is provided, it must either be adapted to the detected features, or post-processed during feature detection to keep consistency of the output `MeshDomainWithFeatures_3`. Available functors implement the necessary modifications. |
  a `Range` of polyline features, represented as `Range`s of `Point_3`. Polyline features are added to the domain for further feature protection. Input polyline features must be different from the detected features and can intersect only at vertices, if they do. Otherwise, the meshing process may not terminate. Default: `std::vector<std::vector<Point_3>>()` Extra: The return type of the function depends on whether this parameter or `input_features` are provided or not. Extra: It is recommended to pass a const-reference for this parameter, possibly using `std::cref(polylines_range)` to avoid useless copies. Extra: If `weights` is provided, it must be adapted to the input features, to keep consistency of the output `MeshDomainWithFeatures_3` |

Example

From the example (Mesh_3/mesh_3D_image.cpp):

Mesh_domain domain = Mesh_domain::create_labeled_image_mesh_domain(image);

From the example (Mesh_3/mesh_3D_weighted_image.cpp), where the labeled image is used with a precomputed 3D image of weights :

const float sigma = (std::max)(image.vx(), (std::max)(image.vy(), image.vz()));
CGAL::Image_3 img_weights =
CGAL::Mesh_3::generate_label_weights(image, sigma);
Mesh_domain domain
= Mesh_domain::create_labeled_image_mesh_domain(image,
params::weights(img_weights).
relative_error_bound(1e-6));
CGAL::Image_3
The class Image_3 is a C++ wrapper around the InrImage library.
Definition: Image_3.h:11
CGAL::Mesh_3::generate_label_weights
CGAL::Image_3 generate_label_weights(const CGAL::Image_3 &image, const float &sigma)
Free function that generates a CGAL::Image_3 of weights associated to each voxel of image,...
Definition: generate_label_weights.h:315

From the example (Mesh_3/mesh_3D_image_with_detection_of_features.cpp) where the features are detected in `image`:

Mesh_domain domain
= Mesh_domain::create_labeled_image_mesh_domain(image,
params::features_detector = CGAL::Mesh_3::Detect_features_in_image());
CGAL::Mesh_3::Detect_features_in_image
Functor for feature detection in labeled images.
Definition: Detect_features_in_image.h:263

From the example (Mesh_3/mesh_3D_image_with_input_features.cpp) where the features are provided by the user:

Mesh_domain domain = Mesh_domain::create_labeled_image_mesh_domain(image,
params::input_features = std::cref(features_inside));//use std::cref to avoid a copy