CGAL::Labeled_mesh_domain_3< BGT, Subdomain_index_, Surface_patch_index_ > Class Template Reference

#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

relative_error_bound 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));

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

iso_value the isovalue, inside image, of the surface describing the boundary of the object to be meshed. Default: 0
image_values_to_subdomain_indices 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()
value_outside the value attached to voxels outside of the domain to be meshed. It should be lower than iso_value. Default: 0
relative_error_bound 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

relative_error_bound 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

weights 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
value_outside the value attached to voxels outside of the domain to be meshed. It should be lower than iso_value. Default: 0
relative_error_bound is the relative error bound, relative to the diameter of the box of the image. Default: FT(1e-3)
features_detector 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.
input_features a Range of polyline features, represented as Ranges 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));

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());

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