CGAL 6.2 - 3D Mesh Generation: CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex > Class Template Reference

CGAL 6.2 - 3D Mesh Generation

Loading...
Searching...
No Matches
List of all members
CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex > Class Template Reference
Reference Manual » Domain Classes

`#include <CGAL/Labeled_mesh_domain_3.h>`

## Definition

template<class BGT, class SubdomainIndex = int, class SurfacePatchIndex = std::pair<SubdomainIndex, SubdomainIndex>>
class CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex >

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`.
  SubdomainIndex | is the type of the indices of the subdomains.
  SurfacePatchIndex | is the type of the indices of the surface patches.

Is model of
  `MeshDomain_3`

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

Examples
  Mesh_3/mesh_3D_gray_image.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_image_initialization.cpp, Mesh_3/mesh_3D_image_with_initial_points.cpp, Mesh_3/mesh_3D_image_with_input_features.cpp, Mesh_3/mesh_3D_weighted_image.cpp, Mesh_3/mesh_3D_weighted_image_with_detection_of_features.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 BGT::Point_3 | Point_3
| The point type of the geometric traits class.
typedef BGT::Sphere_3 | Sphere_3
| The sphere type of the geometric traits class.
typedef BGT::Iso_cuboid_3 | Iso_cuboid_3
| The iso-cuboid type of the geometric traits class.
typedef BGT::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())
| 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 BoundingObject , typename NamedParameters = CGAL::parameters::Default_named_parameters>
static Labeled_mesh_domain_3 | create_implicit_mesh_domain (const Function &function, const BoundingObject &bounding_object, const NamedParameters &np=parameters::default_values())
| Construction from an implicit function.

## Member Typedef Documentation

## ◆ Labeling_function

template<class BGT , class SubdomainIndex = int, class SurfacePatchIndex = std::pair<SubdomainIndex, SubdomainIndex>>

typedef std::function< Subdomain_index(const Point_3 &)> CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex >::Labeling_function

The type of object that stores the function using type-erasure.

A labeling function `f` must return `0` if the point is not 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 the domain.
- `f(p)=a`, `a!=0` means that `p` is inside subdomain `a`.

The function type must be a model of the concept `Callable` with 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`.

## Constructor & Destructor Documentation

## ◆ Labeled_mesh_domain_3()

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

CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex >::Labeled_mesh_domain_3 | ( | const Function & | function,
|  | const Bounding_object & | bounding_object,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |

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

Template Parameters

  Function | a type compatible with `Labeling_function`. The class `CGAL::Implicit_multi_domain_to_labeling_function_wrapper` is a good candidate for this template parameter if there are several components to mesh.
  NamedParameters | a sequence of Named Parameters
  BoundingObject | either a bounding sphere (of type `Sphere_3`), a bounding box (type `Bbox_3` or `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 SubdomainIndex = int, class SurfacePatchIndex = std::pair<SubdomainIndex, SubdomainIndex>>
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

static Labeled_mesh_domain_3 CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex >::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 = less ? Mesh_domain::create_gray_image_mesh_domain(image,
params::image_values_to_subdomain_indices(Is_interior<true>(iso)).
value_outside(iso+1))
: Mesh_domain::create_gray_image_mesh_domain(image,
params::image_values_to_subdomain_indices(Is_interior<false>(iso)).
value_outside(iso+1));
CGAL::Labeled_mesh_domain_3::create_gray_image_mesh_domain
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.

## ◆ create_implicit_mesh_domain()

template<class BGT , class SubdomainIndex = int, class SurfacePatchIndex = std::pair<SubdomainIndex, SubdomainIndex>>
template<typename Function , typename BoundingObject , typename NamedParameters = CGAL::parameters::Default_named_parameters>

static Labeled_mesh_domain_3 CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex >::create_implicit_mesh_domain | ( | const Function & | function,
|  | const BoundingObject & | 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.

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
  BoundingObject | either a bounding sphere (of type `Sphere_3`), a bounding box (type `Bbox_3` or `Iso_cuboid_3`) which is required to circumscribe the surface and to have its center inside the domain.

Parameters

  function | the implicit function
  bounding_object | object bounding 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 SubdomainIndex = int, class SurfacePatchIndex = std::pair<SubdomainIndex, SubdomainIndex>>
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

static auto CGAL::Labeled_mesh_domain_3< BGT, SubdomainIndex, SurfacePatchIndex >::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 postprocessed 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 holds a shared pointer to a 3D image buffer.
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:326

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