CGAL 5.6 - Triangulated Surface Mesh Deformation
|
#include <CGAL/Surface_mesh_deformation.h>
Class providing the functionalities for deforming a triangulated surface mesh.
TM | a model of HalfedgeGraph |
VIM | a model of ReadablePropertyMap with Surface_mesh_deformation::vertex_descriptor as key and unsigned int as value type. The default is boost::property_map<TM, boost::vertex_index_t>::type . |
HIM | a model of ReadablePropertyMap with Surface_mesh_deformation::halfedge_descriptor as key and unsigned int as value type. The default is boost::property_map<TM, boost::halfedge_index_t>::type . |
TAG | tag for selecting the deformation algorithm |
WC | a model of SurfaceMeshDeformationWeights, with WC::Triangle_mesh being TM . If TAG is ORIGINAL_ARAP , the weights must be positive to guarantee a correct energy minimization. The default is the cotangent weighting scheme. In case TAG is ORIGINAL_ARAP , negative weights are clamped to zero. |
ST | a model of SparseLinearAlgebraWithFactorTraits_d. If Eigen 3.2 (or greater) is available and CGAL_EIGEN3_ENABLED is defined, then an overload of Eigen_solver_traits is provided as default parameter. Eigen::SparseLU<
Eigen::COLAMDOrdering<int> > >
Eigen::SparseMatrix< T > EigenType |
CR | a model of DeformationClosestRotationTraits_3. If Eigen 3.1 (or greater) is available and CGAL_EIGEN3_ENABLED is defined, Deformation_Eigen_polar_closest_rotation_traits_3 is provided as default parameter. |
VPM | a model of ReadWritePropertyMap with Surface_mesh_deformation::vertex_descriptor as key and a point as value type. The point type must be a model of RawPoint_3 . The default is boost::property_map<TM, CGAL::vertex_point_t>::type . |
Types | |
typedef TM | Triangle_mesh |
Triangle mesh type. | |
typedef VIM | Vertex_index_map |
vertex index map type | |
typedef HIM | Hedge_index_map |
halfedge index map type | |
typedef ST | Sparse_linear_solver |
sparse linear solver type | |
typedef CR | Closest_rotation_traits |
closest rotation traits type | |
typedef VPM | Vertex_point_map |
vertex point map type | |
typedef WC | Weight_calculator |
weight calculator functor type | |
typedef boost::graph_traits< Triangle_mesh >::vertex_descriptor | vertex_descriptor |
The type for vertex descriptor. | |
typedef boost::graph_traits< Triangle_mesh >::halfedge_descriptor | halfedge_descriptor |
The type for halfedge descriptor. | |
typedef boost::property_traits< Vertex_point_map >::value_type | Point |
The 3D point type, model of RawPoint_3 | |
typedef std::vector< vertex_descriptor > | Roi_vertex_range |
A constant iterator range over the vertices of the region-of-interest. | |
Construction | |
Surface_mesh_deformation (Triangle_mesh &triangle_mesh, Vertex_index_map vertex_index_map=unspecified_internal_vertex_index_map, Hedge_index_map hedge_index_map=unspecified_internal_halfedge_index_map, Vertex_point_map vertex_point_map=get(boost::vertex_point, triangle_mesh), Weight_calculator weight_calculator=Weight_calculator(triangle_mesh, vertex_point_map)) | |
The constructor of a deformation object. | |
Preprocessing | |
void | clear_roi_vertices () |
Erases all the vertices from the region-of-interest (control vertices included). | |
void | clear_control_vertices () |
Erases all the vertices from the set of control vertices. | |
bool | insert_control_vertex (vertex_descriptor vd) |
Inserts a vertex in the set of control vertices. | |
template<class InputIterator > | |
void | insert_control_vertices (InputIterator begin, InputIterator end) |
Inserts a range of vertices in the set of control vertices. | |
bool | erase_control_vertex (vertex_descriptor vd) |
Erases a vertex from the set of control vertices. | |
template<class InputIterator > | |
void | insert_roi_vertices (InputIterator begin, InputIterator end) |
Inserts a range of vertices in the region-of-interest. | |
bool | insert_roi_vertex (vertex_descriptor vd) |
Inserts a vertex in the region-of-interest. | |
bool | erase_roi_vertex (vertex_descriptor vd) |
Erases a vertex from the region-of-interest and the set of control vertices. | |
bool | preprocess () |
Preprocessing function that need to be called each time the region-of-interest or the set of control vertices are changed before calling deform() . | |
Deformation | |
void | set_target_position (vertex_descriptor vd, const Point &target_position) |
Sets the target position of a control vertex. | |
template<class Vect > | |
void | translate (vertex_descriptor vd, const Vect &t) |
Updates the target position of vd by applying a translation of vector t . | |
template<class InputIterator , class Vect > | |
void | translate (InputIterator begin, InputIterator end, const Vect &t) |
Equivalent to calling the overload taking only one control vertex, for each vertex in the range [begin,end[ . | |
template<typename Quaternion , typename Vect > | |
void | rotate (vertex_descriptor vd, const Vect &to_rotation_center, const Quaternion &quat) |
Updates the target position of vd by applying to its last target position a rotation defined by the quaternion quat , the center of the rotation being the origin translated by to_rotation_center . | |
template<typename InputIterator , typename Vect , typename Quaternion > | |
void | rotate (InputIterator begin, InputIterator end, const Vect &to_rotation_center, const Quaternion &quat) |
Equivalent to calling the overload taking only one control vertex, for each vertex in the range [begin,end[ . | |
const Point & | target_position (vertex_descriptor vd) |
Returns the target position of a control vertex. | |
void | deform () |
Deforms the region-of-interest according to the deformation algorithm, using the target positions of each control vertex set by using rotate() , translate() , or set_target_position() . | |
void | deform (unsigned int iterations, double tolerance) |
Same as deform() but the number of iterations and the tolerance are one-time parameters. | |
void | reset () |
Resets the points associated to the vertices of the region-of-interest at their initial positions at time of the functor construction or after the last call to overwrite_initial_geometry() . | |
void | overwrite_initial_geometry () |
Sets the initial positions of the vertices from the region-of-interest to the current positions. | |
Utilities | |
unsigned int | iterations () |
Gets the default number of iterations (5) or the value passed to the function set_iterations() | |
double | tolerance () |
Gets the default tolerance parameter (1e-4) or the value passed to the function set_tolerance() | |
void | set_iterations (unsigned int iterations) |
Sets the maximum number of iterations ran by deform() | |
void | set_tolerance (double tolerance) |
Sets the tolerance of the convergence used in deform() . | |
const Roi_vertex_range & | roi_vertices () const |
Returns the range of vertices in the region-of-interest. | |
bool | is_roi_vertex (vertex_descriptor vd) const |
Tests whether a vertex is inside the region-of-interest. | |
bool | is_control_vertex (vertex_descriptor vd) const |
Tests whether a vertex is a control vertex. | |
const Triangle_mesh & | triangle_mesh () const |
Provides access to the triangle mesh being deformed. | |
void | set_sre_arap_alpha (double a) |
Sets the alpha coefficient that determines the weight of the bending term (rotation smoothness) for the SRE-ARAP deformation technique. | |
typedef std::vector<vertex_descriptor> CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::Roi_vertex_range |
A constant iterator range over the vertices of the region-of-interest.
It is a model of ConstRange
with vertex_descriptor
as iterator value type.
CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::Surface_mesh_deformation | ( | Triangle_mesh & | triangle_mesh, |
Vertex_index_map | vertex_index_map = unspecified_internal_vertex_index_map , |
||
Hedge_index_map | hedge_index_map = unspecified_internal_halfedge_index_map , |
||
Vertex_point_map | vertex_point_map = get(boost::vertex_point, triangle_mesh) , |
||
Weight_calculator | weight_calculator = Weight_calculator(triangle_mesh, vertex_point_map) |
||
) |
The constructor of a deformation object.
triangle_mesh
consists of only triangular facets triangle_mesh | triangulated surface mesh to deform |
vertex_index_map | a property map which associates a unique id to each vertex, between 0 to num_vertices(triangle_mesh)-1 . |
hedge_index_map | property map which associates a unique id to each halfedge, between 0 to 2*num_edges(triangle_mesh)-1 . |
vertex_point_map | property map which associates a point to each vertex of the triangle mesh. |
weight_calculator | function object or pointer for weight calculation |
void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::deform | ( | ) |
Deforms the region-of-interest according to the deformation algorithm, using the target positions of each control vertex set by using rotate()
, translate()
, or set_target_position()
.
The points associated to each vertex of the input triangle mesh that are inside the region-of-interest are updated.
preprocess()
returns false
. void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::deform | ( | unsigned int | iterations, |
double | tolerance | ||
) |
Same as deform()
but the number of iterations and the tolerance are one-time parameters.
iterations | number of iterations for optimization procedure |
tolerance | tolerance of convergence (see explanations set_tolerance(double tolerance)) |
bool CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::erase_control_vertex | ( | vertex_descriptor | vd | ) |
Erases a vertex from the set of control vertices.
vd | the vertex to be erased |
true
if vd
was a control vertex. bool CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::erase_roi_vertex | ( | vertex_descriptor | vd | ) |
Erases a vertex from the region-of-interest and the set of control vertices.
preprocess()
, any vertex that is no longer in the region-of-interest will be assigned to its original position (that is the position of the vertex at the time of construction or after the last call to overwrite_initial_geometry()
). vd | the vertex to be erased |
true
vd
was a vertex from the region-of-interest. bool CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::insert_control_vertex | ( | vertex_descriptor | vd | ) |
Inserts a vertex in the set of control vertices.
The vertex is also inserted in the region-of-interest if it is not already in it.
vd | the vertex to be inserted |
true
if vd
is not already a control vertex. void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::insert_control_vertices | ( | InputIterator | begin, |
InputIterator | end | ||
) |
Inserts a range of vertices in the set of control vertices.
The vertices are also inserted in the region-of-interest if they are not already in it.
InputIterator | input iterator type with vertex_descriptor as value type |
begin | first iterator of the range of vertices |
end | past-the-end iterator of the range of vertices |
bool CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::insert_roi_vertex | ( | vertex_descriptor | vd | ) |
Inserts a vertex in the region-of-interest.
vd | the vertex to be inserted |
true
if vd
is not already in the region-of-interest. void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::insert_roi_vertices | ( | InputIterator | begin, |
InputIterator | end | ||
) |
Inserts a range of vertices in the region-of-interest.
InputIterator | input iterator with vertex_descriptor as value type |
begin | first iterator of the range of vertices |
end | past-the-end iterator of the range of vertices |
bool CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::is_control_vertex | ( | vertex_descriptor | vd | ) | const |
Tests whether a vertex is a control vertex.
vd | the query vertex |
true
if vd
has been inserted to (and not erased from) the set of control vertices. bool CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::is_roi_vertex | ( | vertex_descriptor | vd | ) | const |
Tests whether a vertex is inside the region-of-interest.
vd | the query vertex |
true
if vd
has been inserted to (and not erased from) the region-of-interest. void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::overwrite_initial_geometry | ( | ) |
Sets the initial positions of the vertices from the region-of-interest to the current positions.
Calling this function has the same effect as creating a new deformation object with the current deformed triangle mesh, keeping the region-of-interest and the set of control vertices.
preprocess()
, it will be called prior to the overwrite.This function might have a non-negligible effect on the result. The Laplacian matrix of the free vertices and the optimal rotations are computed using the original positions of the points associated to the vertices. Thus, if a deformed version of the surface mesh is used as reference, the surface mesh properties the algorithm tries to preserve are those of an altered version (which are already degraded).
bool CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::preprocess | ( | ) |
Preprocessing function that need to be called each time the region-of-interest or the set of control vertices are changed before calling deform()
.
If not already done, deform()
first calls this function.
Collects the vertices not in the region-of-interest that are adjacent to a vertex from the region-of-interest (these vertices are internally considered as fixed control vertices). Then assembles and factorizes the Laplacian matrix used in the function deform()
.
true
if successful. A common reason for failure is that the system is rank deficient, which happens for example when all the vertices are in the region-of-interest and no control vertices are set, or if the weighting scheme used features too many zero and breaks the connectivity information. void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::reset | ( | ) |
Resets the points associated to the vertices of the region-of-interest at their initial positions at time of the functor construction or after the last call to overwrite_initial_geometry()
.
preprocess()
, it will be called prior to the reset. void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::rotate | ( | InputIterator | begin, |
InputIterator | end, | ||
const Vect & | to_rotation_center, | ||
const Quaternion & | quat | ||
) |
Equivalent to calling the overload taking only one control vertex, for each vertex in the range [begin,end[
.
InputIterator | input iterator type with vertex_descriptor as value type |
Quaternion | is a quaternion class with Vect operator*(Quaternion, Vect) returning the product of a quaternion with a vector |
Vect | is a 3D vector class, with Vect(double x,double y, double z) being a constructor from its Cartesian coordinates and double Vect::operator[](int i) with i=0,1 or 2 returning its Cartesian coordinates. |
begin | first iterator of the range of vertices |
end | past-the-end iterator of the range of vertices |
to_rotation_center | the vector to translate the origin to the center of the rotation |
quat | quaternion of the rotation |
quad
represents a rotation void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::rotate | ( | vertex_descriptor | vd, |
const Vect & | to_rotation_center, | ||
const Quaternion & | quat | ||
) |
Updates the target position of vd
by applying to its last target position a rotation defined by the quaternion quat
, the center of the rotation being the origin translated by to_rotation_center
.
Quaternion | is a quaternion class with Vect operator*(Quaternion, Vect) returning the product of a quaternion with a vector |
Vect | is a 3D vector class, with Vect(double x,double y, double z) being a constructor from its Cartesian coordinates and double Vect::operator[](int i) with i=0,1 or 2 returning its Cartesian coordinates. |
vd | a control vertex |
to_rotation_center | the vector to translate the origin to the center of the rotation |
quat | quaternion of the rotation |
is_control_vertex(vd)
quad
represents a rotation void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::set_sre_arap_alpha | ( | double | a | ) |
Sets the alpha coefficient that determines the weight of the bending term (rotation smoothness) for the SRE-ARAP deformation technique.
The range of values can be from 0 to infinity. When alpha=0, the method reverts to ARAP. When alpha is increased, neighboring rotations become similar to each other, where alpha=infinity results in a global rigid transformation of the ROI. The value of alpha depends on the surface area and shape. Since alpha is not too sensitive, it can be tweaked in most cases by multiplying it by powers of 10. The default value for alpha is 0.02.
void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::set_target_position | ( | vertex_descriptor | vd, |
const Point & | target_position | ||
) |
Sets the target position of a control vertex.
vd | the control vertex the target position is set |
target_position | the new target position |
void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::set_tolerance | ( | double | tolerance | ) |
Sets the tolerance of the convergence used in deform()
.
If tolerance==0
, no energy based termination criteria is used (preventing to do the energy computation at each iteration step)
tolerance >
\(|\mathrm{energy}(m_i) - \mathrm{energy}(m_{i-1})| / \mathrm{energy}(m_i)\) will be used as a termination criterium.
const Point & CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::target_position | ( | vertex_descriptor | vd | ) |
Returns the target position of a control vertex.
vd | a control vertex |
is_control_vertex(vd)
void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::translate | ( | InputIterator | begin, |
InputIterator | end, | ||
const Vect & | t | ||
) |
Equivalent to calling the overload taking only one control vertex, for each vertex in the range [begin,end[
.
InputIterator | input iterator type with vertex_descriptor as value type |
Vect | is a 3D vector class, with Vect(double x,double y, double z) being a constructor from its Cartesian coordinates and double Vect::operator[](int i) with i=0,1 or 2 returning its Cartesian coordinates. |
begin | first iterator of the range of vertices |
end | past-the-end iterator of the range of vertices |
t | translation vector |
void CGAL::Surface_mesh_deformation< TM, VIM, HIM, TAG, WC, ST, CR, VPM >::translate | ( | vertex_descriptor | vd, |
const Vect & | t | ||
) |
Updates the target position of vd
by applying a translation of vector t
.
Vect | is a 3D vector class, with Vect(double x,double y, double z) being a constructor from its Cartesian coordinates and double Vect::operator[](int i) with i=0,1 or 2 returning its Cartesian coordinates. |
vd | a control vertex |
t | translation vector |
is_control_vertex(vd)