Aim: Implements Digital Surface Regularization as described in [31]. More...
#include <DGtal/geometry/surfaces/DigitalSurfaceRegularization.h>
Public Types | |
typedef TDigitalSurface | DigSurface |
DigitalSurface type. | |
typedef TDigitalSurface::DigitalSurfaceContainer | DigitalSurfaceContainer |
Digital Surface Container type. | |
typedef Shortcuts< Z3i::KSpace > | SH3 |
We rely on the Shortcuts 3D types. | |
typedef ShortcutsGeometry< Z3i::KSpace > | SHG3 |
We rely on the ShortcutsGeometry 3D types. | |
typedef std::vector< Z3i::RealPoint > | Positions |
Pointels position container. | |
typedef std::vector< Z3i::RealVector > | Normals |
Pointels position container. | |
Public Member Functions | |
BOOST_CONCEPT_ASSERT ((concepts::CDigitalSurfaceContainer< DigitalSurfaceContainer >)) | |
DigitalSurfaceRegularization (CountedPtr< DigSurface > aDigSurf) | |
~DigitalSurfaceRegularization ()=default | |
DigitalSurfaceRegularization (const DigitalSurfaceRegularization &other)=delete | |
DigitalSurfaceRegularization (DigitalSurfaceRegularization &&other)=delete | |
DigitalSurfaceRegularization & | operator= (const DigitalSurfaceRegularization &other)=delete |
DigitalSurfaceRegularization & | operator= (DigitalSurfaceRegularization &&other)=delete |
void | attachNormalVectors (const std::function< SHG3::RealVector(SH3::SCell &)> &normalFunc) |
void | attachConvolvedTrivialNormalVectors (const Parameters someParams=SH3::defaultParameters()|SHG3::defaultParameters()) |
void | init (const double alpha=0.001, const double beta=1.0, const double gamma=0.05) |
Initialize the parameters of the energy function. | |
void | init (ConstAlias< std::vector< double > > alphas, ConstAlias< std::vector< double > > betas, ConstAlias< std::vector< double > > gammas) |
Initialize the parameters of the energy function. | |
double | computeGradient () |
double | computeGradientLocalWeights () |
template<typename AdvectionFunction > | |
double | regularize (const unsigned int nbIters, const double dt, const double epsilon, const AdvectionFunction &advectionFunc) |
Main regularization loop. | |
double | regularize (const unsigned int nbIters=200, const double dt=1.0, const double epsilon=0.0001) |
Main regularization loop. | |
SHG3::RealPoint | getRegularizedPosition (const SH3::Cell &aPointel) |
const Positions & | getRegularizedPositions () const |
const Positions & | getOriginalPositions () const |
const SH3::Cell2Index & | getCellIndex () const |
const Normals & | getNormalVectors () const |
const SH3::Surfel2Index & | getSurfelIndex () const |
void | reset () |
void | selfDisplay (std::ostream &out) const |
bool | isValid () const |
void | enableVerbose () |
void | disasbleVerbose () |
Static Public Member Functions | |
static void | clampedAdvection (SHG3::RealPoint &p, const SHG3::RealPoint &orig, const SHG3::RealVector &v) |
Private Member Functions | |
void | cacheInit () |
Private Attributes | |
double | myAlpha |
Data attachment term coefficient. | |
double | myBeta |
Alignment term coefficient. | |
double | myGamma |
Fairness term coefficient. | |
const std::vector< double > * | myAlphas |
Data attachment term local coefficients. | |
const std::vector< double > * | myBetas |
Alignment attachment term local coefficients. | |
const std::vector< double > * | myGammas |
Fairness attachment term local coefficients. | |
bool | myConstantCoeffs |
Flag if the gradient has constant weights for the init method and gradient. | |
bool | myInit |
Flag if the object has been set up properly. | |
bool | myVerbose |
Flag for verbose messages. | |
CountedPtr< DigSurface > | myDigitalSurface |
Input DigitalSurface to regularize. | |
Positions | myOriginalPositions |
Copy of the input pointels positions. | |
Positions | myRegularizedPositions |
Regularized vertices. | |
Normals | myNormals |
Normals. | |
Positions | myGradient |
Gradient of the energy w.r.t. vertex positons. | |
Positions | myGradientAlign |
Internal members to store precomputed topological informations. | |
SH3::KSpace | myK |
Instance of the KSpace. | |
SH3::SurfelRange | mySurfels |
Indexed surface elements. | |
SH3::Surfel2Index | mySurfelIndex |
Surfel Index. | |
SH3::Cell2Index | myPointelIndex |
Indices for pointels. | |
std::vector< SH3::Idx > | myAlignPointelsIdx |
Indices of adjacent pointels for the Alignement energy term. | |
std::vector< SH3::Cell > | myAlignPointels |
Adjacent pointels for the Alignement energy term. | |
std::vector< unsigned char > | myNumberAdjEdgesToPointel |
Number of adjacent edges to pointels. | |
std::vector< SH3::Idx > | myFairnessPointelsIdx |
Indices of cells foor the Fairness term. | |
std::vector< unsigned char > | myNbAdjacent |
Number of adjacent faces to given vertex. | |
SH3::PolygonalSurface::FaceRange | myFaces |
All faces of the dual digital surfacce. | |
Aim: Implements Digital Surface Regularization as described in [31].
Description of template class 'DigitalSurfaceRegularization'
Given a digital surface and a normal vector field attached to the surfels, this class performs a regularization of the digital surface vertices to obtain a piecewise smooth surface such that each quad of the output surface is as perpendicular as possible to the given input normal vector field.
If P denotes the vertices of the input digital surface, F the set of (quadrilateral) faces and n_f an estimated normal vector on the face f, we want the quad surface vertex positions P^* that minimizes the following energy function:
\mathcal{E}(P) := \alpha \sum_{i=1}^{n} \|p_i - \hat{p}_i\|^2 + \beta \sum_{f\in F} \sum_{{e_j} \in \partial{f} } ( e_j \cdot n_{f} )^2 + \gamma \sum_{i=1}^{n} \|\hat{p}_i - \hat{b}_i\|^2\,.
where "\cdot" is the standard \mathbb{R}^3 scalar product, e_j\in \partial{f} is an edge of the face f (and is equal to some p_k - p_l) and \hat{b}_i is the barycenter of the vertices adjacent to \hat{p}_i.
To minimize this energy, instead of solving the associated sparse linear system as described in [31], we perform a gradient descent strategy which allows us a finer control over the vertices displacement (see advection methods).
TDigitalSurface | a Digital Surface type (see DigitalSurface). |
Definition at line 88 of file DigitalSurfaceRegularization.h.
TDigitalSurface::DigitalSurfaceContainer DGtal::DigitalSurfaceRegularization< TDigitalSurface >::DigitalSurfaceContainer |
Digital Surface Container type.
Definition at line 96 of file DigitalSurfaceRegularization.h.
TDigitalSurface DGtal::DigitalSurfaceRegularization< TDigitalSurface >::DigSurface |
DigitalSurface type.
Definition at line 94 of file DigitalSurfaceRegularization.h.
std::vector<Z3i::RealVector> DGtal::DigitalSurfaceRegularization< TDigitalSurface >::Normals |
Pointels position container.
Definition at line 109 of file DigitalSurfaceRegularization.h.
std::vector<Z3i::RealPoint> DGtal::DigitalSurfaceRegularization< TDigitalSurface >::Positions |
Pointels position container.
Definition at line 106 of file DigitalSurfaceRegularization.h.
Shortcuts<Z3i::KSpace> DGtal::DigitalSurfaceRegularization< TDigitalSurface >::SH3 |
We rely on the Shortcuts 3D types.
Definition at line 100 of file DigitalSurfaceRegularization.h.
ShortcutsGeometry<Z3i::KSpace> DGtal::DigitalSurfaceRegularization< TDigitalSurface >::SHG3 |
We rely on the ShortcutsGeometry 3D types.
Definition at line 103 of file DigitalSurfaceRegularization.h.
|
inline |
Default constructor.
Definition at line 114 of file DigitalSurfaceRegularization.h.
References DGtal::Shortcuts< TKSpace >::getKSpace(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myDigitalSurface, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myK.
|
default |
Destructor.
|
delete |
Copy constructor.
other | the object to clone. |
|
delete |
Move constructor.
other | the object to move. |
void DGtal::DigitalSurfaceRegularization< TDigitalSurface >::attachConvolvedTrivialNormalVectors | ( | const Parameters | someParams = SH3::defaultParameters()|SHG3::defaultParameters() | ) |
Attach convolved trivial normal vectors to the digital surface (cf ShortCutsGeometry::getCTrivialNormalVectors).
An important parameter is the radius used to estimate the normal vectors (t-ring, default=3.0).
someParams | the parameters (t-ring, default=3.0 used in the local convolution). |
Referenced by main(), and TEST_CASE().
void DGtal::DigitalSurfaceRegularization< TDigitalSurface >::attachNormalVectors | ( | const std::function< SHG3::RealVector(SH3::SCell &)> & | normalFunc | ) |
Attach normal vectors from a generic function that associates a normal vector to each surfel.
normalFunc | a function (or a lambda, or a functor) that maps surfels (SH3::SCell) to normal vectors (SH3::RealVector). |
Referenced by TEST_CASE().
DGtal::DigitalSurfaceRegularization< TDigitalSurface >::BOOST_CONCEPT_ASSERT | ( | (concepts::CDigitalSurfaceContainer< DigitalSurfaceContainer >) | ) |
|
private |
Internal init method to set up topological caches.
|
inlinestatic |
Static method to be used in regularize() that clamps to regularized point p when shifted by v in the unit cube centered at orig.
[in,out] | p | the point to advect. |
[in] | orig | the associated point in the original surface. |
[in] | v | the advection vector. |
Definition at line 292 of file DigitalSurfaceRegularization.h.
double DGtal::DigitalSurfaceRegularization< TDigitalSurface >::computeGradient | ( | ) |
Compute the energy gradient vector and return the energy value.
Referenced by TEST_CASE().
double DGtal::DigitalSurfaceRegularization< TDigitalSurface >::computeGradientLocalWeights | ( | ) |
Compute the energy gradient vector and return the energy value.
This method assumes that you have local alpha, beta and gamma weights.
|
inline |
Disable verbose messages.
Definition at line 404 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myVerbose.
|
inline |
Enable verbose messages.
Definition at line 399 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myVerbose.
|
inline |
Definition at line 343 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myInit, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myPointelIndex.
Referenced by TEST_CASE().
|
inline |
Definition at line 353 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myInit, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myNormals.
Referenced by TEST_CASE().
|
inline |
Definition at line 333 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myInit, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myOriginalPositions.
Referenced by TEST_CASE().
|
inline |
[in] | aPointel | the digital surface pointel. |
Definition at line 311 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myInit, DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myK, DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myPointelIndex, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myRegularizedPositions.
Referenced by TEST_CASE().
|
inline |
Definition at line 323 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myInit, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myRegularizedPositions.
Referenced by main(), and TEST_CASE().
|
inline |
Definition at line 364 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myInit, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::mySurfelIndex.
Referenced by TEST_CASE().
void DGtal::DigitalSurfaceRegularization< TDigitalSurface >::init | ( | const double | alpha = 0.001, |
const double | beta = 1.0, | ||
const double | gamma = 0.05 ) |
Initialize the parameters of the energy function.
This init() method attaches the same weights to all vertices.
[in] | alpha | the data attachment term coeff. (default=0.001) |
[in] | beta | the alignemnt term coeff. (default=1.0) |
[in] | gamma | the fairness term coeef. (default=0.05) |
Referenced by main(), and TEST_CASE().
void DGtal::DigitalSurfaceRegularization< TDigitalSurface >::init | ( | ConstAlias< std::vector< double > > | alphas, |
ConstAlias< std::vector< double > > | betas, | ||
ConstAlias< std::vector< double > > | gammas ) |
Initialize the parameters of the energy function.
This init() method considers local weights per vertex (all verctors must have the same size: the number of pointels of the original surface).
[in] | alphas | the data attachment term coeff. |
[in] | betas | the alignemnt term coeff. |
[in] | gammas | the fairness term coeef. |
bool DGtal::DigitalSurfaceRegularization< TDigitalSurface >::isValid | ( | ) | const |
Checks the validity/consistency of the object.
Referenced by TEST_CASE().
|
delete |
Copy assignment operator.
other | the object to copy. |
|
delete |
Move assignment operator.
other | the object to move. |
double DGtal::DigitalSurfaceRegularization< TDigitalSurface >::regularize | ( | const unsigned int | nbIters, |
const double | dt, | ||
const double | epsilon, | ||
const AdvectionFunction & | advectionFunc ) |
Main regularization loop.
This method performs the main minimization loop of the energy using a gradient descent scheme (with automatic update of the learning step). The iterative process stops either when the number of steps reaches nbIters, or when the l_\infty norm of the energy gradient is below epsilon.
The last parameter is a function that describes how regularized points are advected during the gradient descent. By default, points are shifted by a fraction of the energy gradient vector (and the default function is thus p \leftarrow p + v with v = -dt \nabla E_p). See
The energy at the final step is returned.
[in] | nbIters | maxium number of steps |
[in] | dt | initial learning rate |
[in] | epsilon | minimum l_infity norm of the gradient vector |
[in] | advectionFunc | advection function/functor/lambda to move a regularized point &a p associated with the original point o w.r.t to a displacement vector v (default = p+v) |
AdvectionFunction | type of advection function, functor or lambda (RealPoint, RealPoint, RealVector)->RealPoint. |
Referenced by main(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::regularize(), and TEST_CASE().
|
inline |
Main regularization loop.
This method performs the main minimization loop of the energy using a gradient descent scheme (with automatic update of the learning step). The iterative process stops either when the number of steps reaches nbIters, or when the l_\infty norm of the energy gradient is below epsilon.
This methods uses the default advection function p = p + v.
The energy at the final step is returned.
[in] | nbIters | maxium number of steps (default=200) |
[in] | dt | initial learning rate (default = 1.0) |
[in] | epsilon | minimum l_infity norm of the gradient vector (default = 0.0001) |
Definition at line 273 of file DigitalSurfaceRegularization.h.
References dt, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::regularize().
|
inline |
Reset the regularized vertices positions to the original one.
Definition at line 374 of file DigitalSurfaceRegularization.h.
References DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myInit, DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myOriginalPositions, and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::myRegularizedPositions.
Referenced by TEST_CASE().
void DGtal::DigitalSurfaceRegularization< TDigitalSurface >::selfDisplay | ( | std::ostream & | out | ) | const |
Writes/Displays the object on an output stream.
out | the output stream where the object is written. |
|
private |
Adjacent pointels for the Alignement energy term.
Definition at line 479 of file DigitalSurfaceRegularization.h.
|
private |
Indices of adjacent pointels for the Alignement energy term.
Definition at line 477 of file DigitalSurfaceRegularization.h.
|
private |
Data attachment term coefficient.
Definition at line 419 of file DigitalSurfaceRegularization.h.
|
private |
Data attachment term local coefficients.
Definition at line 426 of file DigitalSurfaceRegularization.h.
|
private |
Alignment term coefficient.
Definition at line 421 of file DigitalSurfaceRegularization.h.
|
private |
Alignment attachment term local coefficients.
Definition at line 428 of file DigitalSurfaceRegularization.h.
|
private |
Flag if the gradient has constant weights for the init method and gradient.
Definition at line 433 of file DigitalSurfaceRegularization.h.
|
private |
Input DigitalSurface to regularize.
Definition at line 442 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::DigitalSurfaceRegularization().
|
private |
All faces of the dual digital surfacce.
Definition at line 487 of file DigitalSurfaceRegularization.h.
|
private |
Indices of cells foor the Fairness term.
Definition at line 483 of file DigitalSurfaceRegularization.h.
|
private |
Fairness term coefficient.
Definition at line 423 of file DigitalSurfaceRegularization.h.
|
private |
Fairness attachment term local coefficients.
Definition at line 430 of file DigitalSurfaceRegularization.h.
|
private |
Gradient of the energy w.r.t. vertex positons.
Definition at line 454 of file DigitalSurfaceRegularization.h.
|
private |
Internal members to store precomputed topological informations.
Gradient of the quad alignement w.r.t. vertex positons
Definition at line 462 of file DigitalSurfaceRegularization.h.
|
private |
Flag if the object has been set up properly.
Definition at line 436 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getCellIndex(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getNormalVectors(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getOriginalPositions(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getRegularizedPosition(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getRegularizedPositions(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getSurfelIndex(), and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::reset().
|
private |
Instance of the KSpace.
Definition at line 465 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::DigitalSurfaceRegularization(), and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getRegularizedPosition().
|
private |
Number of adjacent faces to given vertex.
Definition at line 485 of file DigitalSurfaceRegularization.h.
|
private |
Normals.
Definition at line 451 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getNormalVectors().
|
private |
Number of adjacent edges to pointels.
Definition at line 481 of file DigitalSurfaceRegularization.h.
|
private |
Copy of the input pointels positions.
Definition at line 445 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getOriginalPositions(), and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::reset().
|
private |
Indices for pointels.
Definition at line 474 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getCellIndex(), and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getRegularizedPosition().
|
private |
Regularized vertices.
Definition at line 448 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getRegularizedPosition(), DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getRegularizedPositions(), and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::reset().
|
private |
Surfel Index.
Definition at line 471 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::getSurfelIndex().
|
private |
Indexed surface elements.
Definition at line 468 of file DigitalSurfaceRegularization.h.
|
private |
Flag for verbose messages.
Definition at line 439 of file DigitalSurfaceRegularization.h.
Referenced by DGtal::DigitalSurfaceRegularization< TDigitalSurface >::disasbleVerbose(), and DGtal::DigitalSurfaceRegularization< TDigitalSurface >::enableVerbose().