CGAL::Labeled_mesh_domain_3< BGT > Class Template Reference

#include <CGAL/Labeled_mesh_domain_3.h>

Definition

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_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 int	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 ... A_i>
	Labeled_mesh_domain_3 (const A_i &...)
	Construction from a function, a bounding object and a relative error bound. More...

Creation of domains from implicit functions
template<typename ... A_i>
static Labeled_mesh_domain_3	create_implicit_mesh_domain (A_i &...)
	Construction from an implicit function. More...

Creation of domains from 3D images
template<typename ... A_i>
static Labeled_mesh_domain_3	create_gray_image_mesh_domain (A_i &...)
	Construction from a 3D gray image. More...
template<typename ... A_i>
static Labeled_mesh_domain_3	create_labeled_image_mesh_domain (A_i &...)
	Construction from a 3D labeled image. More...

Deprecated constructors
Those three constructors have been deprecated since CGAL-4.13, and replaced by the constructor using the Boost Parameter Library.
	Labeled_mesh_domain_3 (Labeling_function f, const Sphere_3 &bounding_sphere, const FT &relative_error_bound=FT(1e-3))
	Construction from a labeling function, a bounding Sphere and a relative error bound. More...
	Labeled_mesh_domain_3 (Labeling_function f, const Bbox_3 &bbox, const FT &relative_error_bound=FT(1e-3))
	Construction from a labeling function, a bounding box and a relative error bound. More...
	Labeled_mesh_domain_3 (Labeling_function f, const Iso_cuboid_3 &bbox, const FT &relative_error_bound=FT(1e-3))
	Construction from a function, a bounding Iso_cuboid_3 and a relative error bound. More...

Constructor & Destructor Documentation

Labeled_mesh_domain_3() [1/4]

template<typename BGT >

template<typename ... A_i>

CGAL::Labeled_mesh_domain_3< BGT >::Labeled_mesh_domain_3

(

const A_i &

...

)

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

This constructor uses named parameters (from the Boost Parameter Library). They can be specified in any order.

Named Parameters

• parameters::function (mandatory) the labeling function, compatible with Labeling_function.
• parameters::bounding_object (mandatory) the bounding object is either a bounding sphere (of type Sphere_3), a bounding box (type Bbox_3), or a bounding Iso_cuboid_3. It bounds the meshable space.

• parameters::relative_error_bound (optional) 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. Its default value is FT(1e-3).

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

    namespace param = CGAL::parameters;
    Mesh_domain domain(param::function = Function_wrapper(v, vps),
                       param::bounding_object = K::Sphere_3(CGAL::ORIGIN,
                                                            5.*5.),
                       param::relative_error_bound = 1e-6);

Labeled_mesh_domain_3() [2/4]

template<typename BGT >

CGAL::Labeled_mesh_domain_3< BGT >::Labeled_mesh_domain_3	(	Labeling_function	f,
		const Sphere_3 &	bounding_sphere,
		const FT &	relative_error_bound = FT(1e-3)
	)

Construction from a labeling function, a bounding Sphere and a relative error bound.

Parameters

f	the labeling function.
bounding_sphere	the bounding sphere of the meshable space.
relative_error_bound	is 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 radius of bounding_sphere.

Deprecated:

This constructor is deprecated since CGAL-4.13, and replaced by the constructor using the Boost Parameter Library.

Labeled_mesh_domain_3() [3/4]

template<typename BGT >

CGAL::Labeled_mesh_domain_3< BGT >::Labeled_mesh_domain_3	(	Labeling_function	f,
		const Bbox_3 &	bbox,
		const FT &	relative_error_bound = FT(1e-3)
	)

Construction from a labeling function, a bounding box and a relative error bound.

Parameters

f	the labeling function.
bbox	the bounding box of the meshable space.
relative_error_bound	is 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 diagonal of bounding_box.

Deprecated:

This constructor is deprecated since CGAL-4.13, and replaced by the constructor using the Boost Parameter Library.

Labeled_mesh_domain_3() [4/4]

template<typename BGT >

CGAL::Labeled_mesh_domain_3< BGT >::Labeled_mesh_domain_3	(	Labeling_function	f,
		const Iso_cuboid_3 &	bbox,
		const FT &	relative_error_bound = FT(1e-3)
	)

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

Parameters

f	the function.
bbox	the bounding box of the meshable space.
relative_error_bound	is 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 diagonal of bounding_box.

Deprecated:

This constructor is deprecated since CGAL-4.13, and replaced by the constructor using the Boost Parameter Library.

Member Function Documentation

create_gray_image_mesh_domain()

template<typename BGT >

template<typename ... A_i>

static Labeled_mesh_domain_3 CGAL::Labeled_mesh_domain_3< BGT >::create_gray_image_mesh_domain ( A_i &  ... )

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.

This constructor uses named parameters (from the Boost Parameter Library). They can be specified in any order.

Named Parameters
The parameters are optional unless otherwise specified.

• parameters::image (mandatory) the input 3D image. Must be a CGAL::Image_3 object.

• parameters::iso_value the isovalue, inside image, of the surface describing the boundary of the object to be meshed. Its default value is 0.

• parameters::image_values_to_subdom_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.

• parameter::value_outside the value attached to voxels outside of the domain to be meshed. It should be lower than iso_value. Its default value is 0.

• parameter::relative_error_bound is the relative error bound, relative to the diameter of the box of the image. Its default value is FT(1e-3).

Examples

From the example (Mesh_3/mesh_3D_gray_image.cpp), where the name of the parameters is not specified, as they are given is the same order as the parameters definition:

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

From the example (Mesh_3/mesh_3D_gray_vtk_image.cpp):

  // To avoid verbose function and named parameters call
  using namespace CGAL::parameters;

  Mesh_domain domain = Mesh_domain::create_gray_image_mesh_domain
    (image,
     image_values_to_subdomain_indices = Less(iso),
     value_outside = 0);

create_implicit_mesh_domain()

template<typename BGT >

template<typename ... A_i>

static Labeled_mesh_domain_3 CGAL::Labeled_mesh_domain_3< BGT >::create_implicit_mesh_domain ( A_i &  ... )

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.

This constructor uses named parameters (from the Boost Parameter Library). They can be specified in any order.

Named Parameters

• parameters::function (mandatory) the implicit function, 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.
• parameters::bounding_object (mandatory) the bounding object is either a bounding sphere (of type Sphere_3), a bounding box (type Bbox_3), or a bounding Iso_cuboid_3. It must bounds the surface, and its center must be inside the domain.

Examples

From the example (Mesh_3/mesh_implicit_sphere.cpp), where the name of the parameters is not specified, as they are given is the same order as the parameters definition:

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

From the example (Mesh_3/mesh_implicit_sphere_variable_size.cpp):

  namespace p = CGAL::parameters;
  Mesh_domain domain = Mesh_domain::create_implicit_mesh_domain
    (p::function = &sphere_function,
     p::bounding_object = K::Sphere_3(CGAL::ORIGIN, 2.)
     );

create_labeled_image_mesh_domain()

template<typename BGT >

template<typename ... A_i>

static Labeled_mesh_domain_3 CGAL::Labeled_mesh_domain_3< BGT >::create_labeled_image_mesh_domain ( A_i &  ... )

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.

This constructor uses named parameters (from the Boost Parameter Library). They can be specified in any order.

Named Parameters
The parameters are optional unless otherwise specified.

• parameters::image (mandatory) the input 3D image. Must be a CGAL::Image_3 object.

• parameters::weights 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.

• parameter::value_outside the value attached to voxels outside of the domain to be meshed. Its default value is 0.

• parameter::relative_error_bound is the relative error bound, relative to the diameter of the box of the image. Its default value is FT(1e-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,
                                                    weights = img_weights,
                                                    relative_error_bound = 1e-6);