CGAL 5.3 - 3D Periodic Mesh Generation
CGAL::Periodic_3_function_wrapper< Function, BGT > Class Template Reference

#include <CGAL/Periodic_3_function_wrapper.h>

Definition

The class Periodic_3_function_wrapper is a helper class designed to wrap an (a priori non-periodic) implicit function describing a domain through the relationship [p is inside if f(p)<0] and defined over the canonical cube to a function defined over the whole Euclidean space and periodic, with the same period as the canonical cube.

More precisely, if f is the real function defined either over \( \mathbb R^3\) or over the canonical cube, we construct the periodic real function \( f^{\ast} \) defined over \( \mathbb R^3\) as follows:

  • For any point \((x,y,z)\) in the canonical cube, \( f^{\ast}(x,y,z) = f(x,y,z)\)
  • For any point \((x,y,z)\) outside the canonical cube, there is a unique canonical representative \((x_0,y_0,z_0)\) of \((x,y,z)\) in the canonical cube, i.e., \((x,y,z)=(x_0 + k_x c, y_0 + k_y c, z_0 + k_z c)\) with \((k_x,k_y,k_z)\) in \( \mathbb Z^3\), and \( f^{\ast}(x,y,z) = f(x_0,y_0,z_0) \).

For example, if considering the unit cube as canonical cube, an oracle answering a query such as "what is the value of the implicit function at this point?" at the point (2.5, 2.5, 2.5) will be in fact evaluated at the canonical representative, that is (0.5, 0.5, 0.5). Consequently, it is then not required to provide an input domain that is defined over the whole space or periodic, but only defined over the canonical cube.

periodicity_base.svg
Figure 60.1 Illustration in 2D (cut view) of a domain defined by an implicit function that is transformed into a periodic implicit function. Only the values of the implicit function that are in the canonical cube are used: the values of the implicit function at \( P \) and \( Q \) are obtained by evaluating instead at \( P' \) and \( Q' \), as shown on the right.

In practice, the implicit function provided by the user is likely defined over a larger domain than the canonical cube (in general, it is \( \mathbb R^3\)). Note that – when constructing artificially periodic functions – all the values of the implicit function for points outside this canonical cube are unused since queries are always answered by looking at the canonical representative. Figure 60.2 gives an example of such domain where some information is discarded.

periodicity.svg
Figure 60.2 Illustration in 2D (cut view) of a domain defined by an implicit function artificially made periodic. Any value of the function outside of the canonical cube is ignored.

Note also that when constructing artificially periodic functions, it is the responsability of the user to provide an input function that is compatible with the canonical cube (that is, whose isovalues are periodically continuous and without intersections). Figure 60.3 is an example of a bad choice of input function and canonical cube: there is no continuity of the isovalues at the border of the canonical cube. In such configuration, the mesher might or might not finish and the result is likely to be non-manifold and to contain self-intersections.

periodicity_issue.svg
Figure 60.3 Illustration in 2D (cut view) of a domain defined by an implicit function artificially made periodic. The zero isovalue of the implicit function does not form a continuous curve.

Template Parameters
Functionprovides the definition of the function. This parameter stands for a model of the concept ImplicitFunction described in the surface mesh generation package. The number types Function::FT and BGT::FT are required to match.
BGTis 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.
Examples:
Periodic_3_mesh_3/mesh_implicit_multi_domain.cpp, and Periodic_3_mesh_3/mesh_implicit_shape_with_features.cpp.

Types

typedef BGT::FT FT
 
typedef BGT::Point_3 Point_3
 
typedef BGT::Iso_cuboid_3 Iso_cuboid_3
 

Creation

 Periodic_3_function_wrapper (Function f, const Iso_cuboid_3 &domain)
 Construction from an implicit function and the canonical cube.
 

Operations

FT operator() (const Point_3 &p) const
 Evaluates the function \( f \) passed in input at the canonical representative of \( p \).