Aim: Implements the Shrouds Regularization algorithm of Nielson et al [78]. More...

#include <DGtal/geometry/surfaces/ShroudsRegularization.h>

Public Types
enum class	Regularization { AREA , SNAKE , SQUARED_CURVATURE }
	The enum class specifying the possible shrouds regularization. More...

typedef TDigitalSurfaceContainer	Container

typedef ShroudsRegularization< Container >	Self

typedef Container::KSpace	KSpace

typedef KSpace::Space	Space

typedef Space::RealVector	RealVector

typedef Space::RealPoint	RealPoint

typedef RealVector::Component	Scalar

typedef IndexedDigitalSurface< Container >	IdxDigitalSurface

typedef IdxDigitalSurface::Vertex	IdxVertex

typedef IdxDigitalSurface::Surfel	IdxSurfel

typedef IdxVertex	Vertex

typedef std::vector< IdxSurfel >	IdxSurfelRange

typedef std::vector< Scalar >	Scalars

typedef std::vector< RealVector >	RealVectors

typedef std::vector< RealPoint >	RealPoints

Public Member Functions
Standard services (construction, initialization)
	ShroudsRegularization ()
	Default constructor. The object is not valid. More...

	ShroudsRegularization (CountedPtr< IdxDigitalSurface > surface)

void	init ()

void	setParams (double eps, double alpha=1.0, double beta=1.0)

std::tuple< double, double, double >	getParams () const

Accessor services
RealPoint	position (const Vertex v, const double t) const

RealPoint	position (const Vertex v) const

RealPoints	positions () const

Dimension	orthDir (const Vertex v) const

std::pair< Vertex, Dimension >	next (const std::pair< Vertex, Dimension > &v_i) const

std::pair< Vertex, Dimension >	prev (const std::pair< Vertex, Dimension > &v_i) const

Geometric services
void	parameterize ()
	Computes the distances between the vertices along slices. More...

Scalar	c1 (const std::pair< Vertex, Dimension > &v_i) const

std::tuple< Scalar, Scalar, Scalar >	c2_all (const std::pair< Vertex, Dimension > &v_i) const

Regularization services
std::pair< double, double >	regularize (const Regularization reg=Regularization::SQUARED_CURVATURE, const double randomization=0.0, const double max_loo=0.0001, const int maxNb=100)

double	energy (const Regularization reg=Regularization::SQUARED_CURVATURE)

double	energySquaredCurvature ()

double	energySnake ()

double	energyArea ()

std::pair< double, double >	oneStepAreaMinimization (const double randomization=0.0)

std::pair< double, double >	oneStepSnakeMinimization (const double alpha=1.0, const double beta=1.0, const double randomization=0.0)

std::pair< double, double >	oneStepSquaredCurvatureMinimization (const double randomization=0.0)

void	enforceBounds ()
	Forces t to stay in ]0,1[. More...

Protected Member Functions
Internal methods
void	precomputeTopology ()

Private Member Functions
	BOOST_CONCEPT_ASSERT ((concepts::CDigitalSurfaceContainer< TDigitalSurfaceContainer >))

Private Attributes
CountedPtr< IdxDigitalSurface >	myPtrIdxSurface
	the indexed digital surface (internal surface representation). More...

const KSpace *	myPtrK
	A const pointer to the cellular space in which lives the digital surface. More...

Scalar	myEpsilon

Scalar	myAlpha
	The alpha parameter for Snake first order regularization (~ area) More...

Scalar	myBeta
	The beta parameter for Snake second order regularization (~ curvature) More...

Vertex	myInvalid
	the index of the invalid vertex. More...

Scalars	myT

RealPoints	myInsV

RealPoints	myOutV

std::vector< Dimension >	myOrthDir
	the direction axis of each dual edge. More...

std::vector< Vertex >	myNext [3]
	for each vertex, its successor on the slice of given axis direction. More...

std::vector< Vertex >	myPrev [3]
	for each vertex, its predessor on the slice of given axis direction. More...

Scalars	myNextD [3]

Scalars	myPrevD [3]

Detailed Description

template<typename TDigitalSurfaceContainer>
class DGtal::ShroudsRegularization< TDigitalSurfaceContainer >

Aim: Implements the Shrouds Regularization algorithm of Nielson et al [78].

Description of template class 'ShroudsRegularization'

Represents a decomposition of a closed digital surface into three stacks of slices, one per dimension. Gives methods to optimize the positions of vertices and smooth the resulting surface, generally according to curvature-related regularizers.

See also: Digital surface regularization using the Shrouds algorithm

Note: This method is limited to closed digital surfaces.

Template Parameters

TDigitalSurfaceContainer any digital surface container (a model concepts::CDigitalSurfaceContainer), for instance a SetOfSurfels.

See also: testShroudsRegularization.cpp

Definition at line 73 of file ShroudsRegularization.h.

Member Typedef Documentation

◆ Container

template<typename TDigitalSurfaceContainer >

typedef TDigitalSurfaceContainer DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::Container

Definition at line 79 of file ShroudsRegularization.h.

◆ IdxDigitalSurface

template<typename TDigitalSurfaceContainer >

typedef IndexedDigitalSurface< Container > DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::IdxDigitalSurface

Definition at line 86 of file ShroudsRegularization.h.

◆ IdxSurfel

template<typename TDigitalSurfaceContainer >

typedef IdxDigitalSurface::Surfel DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::IdxSurfel

Definition at line 88 of file ShroudsRegularization.h.

◆ IdxSurfelRange

template<typename TDigitalSurfaceContainer >

typedef std::vector< IdxSurfel > DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::IdxSurfelRange

Definition at line 90 of file ShroudsRegularization.h.

◆ IdxVertex

template<typename TDigitalSurfaceContainer >

typedef IdxDigitalSurface::Vertex DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::IdxVertex

Definition at line 87 of file ShroudsRegularization.h.

◆ KSpace

template<typename TDigitalSurfaceContainer >

typedef Container::KSpace DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::KSpace

Definition at line 81 of file ShroudsRegularization.h.

◆ RealPoint

template<typename TDigitalSurfaceContainer >

typedef Space::RealPoint DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::RealPoint

Definition at line 84 of file ShroudsRegularization.h.

◆ RealPoints

template<typename TDigitalSurfaceContainer >

typedef std::vector< RealPoint > DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::RealPoints

Definition at line 93 of file ShroudsRegularization.h.

◆ RealVector

template<typename TDigitalSurfaceContainer >

typedef Space::RealVector DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::RealVector

Definition at line 83 of file ShroudsRegularization.h.

◆ RealVectors

template<typename TDigitalSurfaceContainer >

typedef std::vector< RealVector > DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::RealVectors

Definition at line 92 of file ShroudsRegularization.h.

◆ Scalar

template<typename TDigitalSurfaceContainer >

typedef RealVector::Component DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::Scalar

Definition at line 85 of file ShroudsRegularization.h.

◆ Scalars

template<typename TDigitalSurfaceContainer >

typedef std::vector< Scalar > DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::Scalars

Definition at line 91 of file ShroudsRegularization.h.

◆ Self

template<typename TDigitalSurfaceContainer >

typedef ShroudsRegularization< Container > DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::Self

Definition at line 80 of file ShroudsRegularization.h.

◆ Space

template<typename TDigitalSurfaceContainer >

typedef KSpace::Space DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::Space

Definition at line 82 of file ShroudsRegularization.h.

◆ Vertex

template<typename TDigitalSurfaceContainer >

typedef IdxVertex DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::Vertex

Definition at line 89 of file ShroudsRegularization.h.

Member Enumeration Documentation

◆ Regularization

template<typename TDigitalSurfaceContainer >

enum DGtal::ShroudsRegularization::Regularization

strong

The enum class specifying the possible shrouds regularization.

Enumerator
AREA
SNAKE
SQUARED_CURVATURE

Definition at line 96 of file ShroudsRegularization.h.

96 { AREA, SNAKE, SQUARED_CURVATURE };

Constructor & Destructor Documentation

◆ ShroudsRegularization() [1/2]

template<typename TDigitalSurfaceContainer >

DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::ShroudsRegularization ( )

inline

Default constructor. The object is not valid.

Definition at line 104 of file ShroudsRegularization.h.

105 : myPtrIdxSurface( nullptr ), myPtrK( nullptr )

106 {}

DGtal::ShroudsRegularization::myPtrIdxSurface

CountedPtr< IdxDigitalSurface > myPtrIdxSurface

the indexed digital surface (internal surface representation).

Definition: ShroudsRegularization.h:534

DGtal::ShroudsRegularization::myPtrK

const KSpace * myPtrK

A const pointer to the cellular space in which lives the digital surface.

Definition: ShroudsRegularization.h:536

◆ ShroudsRegularization() [2/2]

template<typename TDigitalSurfaceContainer >

DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::ShroudsRegularization ( CountedPtr< IdxDigitalSurface > surface )

inline

Constructor from (closed) surface. Also calls methods precomputeTopology and init.

Parameters

surface a counted pointer on an indexed digital surface.

Note: Complexity is linear in the number of surfels of surface.

Definition at line 113 of file ShroudsRegularization.h.

       : myPtrIdxSurface( surface ),
         myPtrK( &surface->container().space() ),
         myEpsilon( 0.0001 ), myAlpha( 1.0 ), myBeta( 1.0 )
     {
       precomputeTopology();
       init();
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

Member Function Documentation

◆ BOOST_CONCEPT_ASSERT()

template<typename TDigitalSurfaceContainer >

DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::BOOST_CONCEPT_ASSERT ( (concepts::CDigitalSurfaceContainer< TDigitalSurfaceContainer >) )

private

◆ c1()

template<typename TDigitalSurfaceContainer >

Scalar DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::c1 ( const std::pair< Vertex, Dimension > & v_i ) const

inline

Parameters

v_i	a pair (vertex,tangent direction)

Returns: the coefficient for centered first-order finite difference.

Note: We have y'i ~= c1 * (y{i+1} - y_{i-1} )

Definition at line 261 of file ShroudsRegularization.h.

     {
       const Scalar din = myNextD[ v_i.second ][ v_i.first ];
       const Scalar dip = myPrevD[ v_i.second ][ v_i.first ];
       return 1.0 / (din + dip);
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNextD, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrevD.

◆ c2_all()

template<typename TDigitalSurfaceContainer >

std::tuple<Scalar,Scalar,Scalar> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::c2_all ( const std::pair< Vertex, Dimension > & v_i ) const

inline

Parameters

v_i	a pair (vertex,tangent direction)

Returns: the coefficients for centered second-order finite difference.

Note: We have y''i ~= c2<0> * y{i+1} - c2<1> * y_{i} + c2<2> * y_{i-1}

Definition at line 271 of file ShroudsRegularization.h.

     {
       const Scalar din = myNextD[ v_i.second ][ v_i.first ];
       const Scalar dip = myPrevD[ v_i.second ][ v_i.first ];
       return std::make_tuple( 2.0 / ( din * ( din + dip ) ),
                               2.0 / ( din * dip ),
                               2.0 / ( dip * ( din + dip ) ) );
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNextD, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrevD.

◆ energy()

template<typename TDigitalSurfaceContainer >

double DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energy ( const Regularization reg = Regularization::SQUARED_CURVATURE )

inline

Parameters

reg	your choice of regularization in AREA (not nice in 3D), SNAKE (not so bad), SQUARED_CURVATURE (works best)

Returns: the current energy of the shrouds, according to the chosen regularization process.

Definition at line 335 of file ShroudsRegularization.h.

     {
       if ( reg == Regularization::SQUARED_CURVATURE )
         return energySquaredCurvature();
       else if ( reg == Regularization::SNAKE )
         return energySnake();
       else
         return energyArea();
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energyArea(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energySnake(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energySquaredCurvature(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::SNAKE, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::SQUARED_CURVATURE.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::regularize(), and TEST_CASE().

◆ energyArea()

template<typename TDigitalSurfaceContainer >

double DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energyArea ( )

Returns: the current energy associated to the area regularization process.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energy().

◆ energySnake()

template<typename TDigitalSurfaceContainer >

double DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energySnake ( )

Returns: the current energy associated to the snake regularization process.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energy().

◆ energySquaredCurvature()

template<typename TDigitalSurfaceContainer >

double DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energySquaredCurvature ( )

Returns: the current energy associated to the squared curvature regularization process.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::energy().

◆ enforceBounds()

template<typename TDigitalSurfaceContainer >

void DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::enforceBounds ( )

Forces t to stay in ]0,1[.

◆ getParams()

template<typename TDigitalSurfaceContainer >

std::tuple< double, double, double > DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::getParams ( ) const

inline

Retrieves the parameters that affect the output regularized shape.

Returns: a tuple (eps, alpha, beta) where eps is the bounds for varying the positions of vertices in ]0,1[, alpha is the parameter for Snake first order regularization (~ area), beta is the parameter for Snake second order regularization (~ curvature).

Definition at line 167 of file ShroudsRegularization.h.

     {
       return std::make_tuple( myEpsilon, myAlpha, myBeta );
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myAlpha, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myBeta, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myEpsilon.

◆ init()

template<typename TDigitalSurfaceContainer >

void DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init ( )

inline

Prepares the shroud for optimization. Must be called before any call to regularize, oneStepAreaMinimization, oneStepSnakeMinimization, oneStepSquaredCurvatureMinimization.

Note: Complexity is linear in the number of surfels of surface.

Definition at line 128 of file ShroudsRegularization.h.

     {
       const auto embedder = CanonicSCellEmbedder<KSpace>( *myPtrK );
       const auto nbV      = myPtrIdxSurface->nbVertices();
       myT.resize( nbV );
       myInsV.resize( nbV );
       myOutV.resize( nbV );
       for ( Dimension i = 0; i < 3; ++i )
         {
           myPrevD[ i ].resize( nbV );
           myNextD[ i ].resize( nbV );
         }
       for ( Vertex v = 0; v < myT.size(); ++v )
         {
           const auto s = myPtrIdxSurface->surfel( v );
           const auto k = myPtrK->sOrthDir( s );
           myInsV[ v ]  = embedder( myPtrK->sDirectIncident( s, k ) );
           myOutV[ v ]  = embedder( myPtrK->sIndirectIncident( s, k ) );
         }
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myInsV, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNextD, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOutV, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrevD, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPtrIdxSurface, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPtrK, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myT.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::ShroudsRegularization(), and TEST_CASE().

◆ next()

template<typename TDigitalSurfaceContainer >

std::pair<Vertex,Dimension> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::next ( const std::pair< Vertex, Dimension > & v_i ) const

inline

Useful to navigate tangentially along a slice.

Parameters

v_i	a pair (vertex,tangent direction)

Returns: the next vertex and associated tangent direction along the slice.

Definition at line 216 of file ShroudsRegularization.h.

     {
       const Vertex    vn = myNext[ v_i.second ][ v_i.first ];
       const Dimension in = myOrthDir[ vn ] == v_i.second
         ? myOrthDir[ v_i.first ] : v_i.second;
       return std::make_pair( vn, in );
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNext, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOrthDir.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

◆ oneStepAreaMinimization()

template<typename TDigitalSurfaceContainer >

std::pair<double,double> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::oneStepAreaMinimization ( const double randomization = 0.0 )

Smooths the shape according to the minimization of area.

Parameters

randomization if greater than 0.0 add some perturbation to the solution. May be used for quitting a local minima.

Returns: the pair of \( l_\infty \) and \( l_2 \) norms of vertex displacements.

Note: Not very nice.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::regularize().

◆ oneStepSnakeMinimization()

template<typename TDigitalSurfaceContainer >

std::pair<double,double> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::oneStepSnakeMinimization	(	const double	alpha = `1.0`,
		const double	beta = `1.0`,
		const double	randomization = `0.0`
	)

Smooths the shape according to the minimization of elastic + thin plate energy (like snakes).

\[ E^{snk}(C) = \int_C \alpha (x'(s)^2 + y'(s)^2) + \beta (x''(s)^2 + y''(s)^2) ds, \]

for \( C=(x(s),y(s)) \) and boundary constraints.

Parameters

alpha	parameter for first order regularization (~ area)
beta	parameter for second order regularization (~ curvature)
randomization	if greater than 0.0 add some perturbation to the solution. May be used for quitting a local minima.

Returns: the pair of \( l_\infty \) and \( l_2 \) norms of vertex displacements.

Euler-Lagrange equations leads to necessary conditions: for all s, \( x''''(s) = 0 \) and \( y''''(s) = 0 \).

A vertex \( v(s) \) has a position \( X \). Next and previous vertices are denoted by \( Xn, Xnn, Xp, Xpp \). If i the tangent direction and k the orthogonal direction at \( X \), then \( x(s)=X[i], y(s)=X[k] \).

At a vertex \( v(s) \), the position is parameterized by t. Varying t only modifies the vertical position \( X[k] \), i.e. y. So \( y(t) = (1-t)*I[v][k] + t*O[v][k] \) (for \( I[v] \) and \( O[v] \) inside and outside voxel positions).

\( x' ~= ( Xn[i] - Xp[i] ) / (d(X,Xn)+d(X,Xp) \) does not depend on t. \( y' ~= ( Xn[k] - Xp[k] ) / (d(X,Xn)+d(X,Xp) \) does not depend on t. \( x'' ~= ( c_0 * Xn[i] - c_1 * X[i] + c_2 * Xp[i] ) \) does not depend on t.

for \( c_0, c_1, c_2 \) constants depending on \( d(X,Xn) \) and \( d(X,Xp) \). \( y'' ~= ( c_0 * Xn[k] - c_1 * X[k] + c_2 * Xp[k] ) \) solely depend on t.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::regularize().

◆ oneStepSquaredCurvatureMinimization()

template<typename TDigitalSurfaceContainer >

std::pair<double,double> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::oneStepSquaredCurvatureMinimization ( const double randomization = 0.0 )

Smooths the shape according to the minimization of squared curvature.

\[ E^{\kappa^2}(C) = \int_C (x'(s) y''(s) + x''(s) y'(s))^2 / (x'(s)^2 + y'(s)^2)^3 ds, \]

for \( C=(x(s),y(s)) \) and boundary constraints.

Parameters

randomization if greater than 0.0 add some perturbation to the solution. May be used for quitting a local minima.

Returns: the pair of \( l_\infty \) and \( l_2 \) norms of vertex displacements.

Euler-Lagrange equations leads to rather complex necessary conditions. At each position (we omit parameter s for making things more readable):

\[ 24*x'^3*x''^3*y' + x'''*( - 13*x'^4*x''*y' - 14*x'^2*x''*y'^3 - x''*y'^5 ) + y'''*( 8*x'^5*x'' + 4*x'^3*x''*y'^2 - 4*x'*x''*y'^4 ) + x''''*( x'^5*y' + 2*x'^3*y'^3 + x'*y'^5 ) + y''*( 12*x'^4*y'*y''' + 12*x'^2*y'^3*y''' - 24*x'^4*x''^2 + 5*x'^5*x''' + 51*x'^2*x''^2*y'^2 - 2*x'^3*x'''*y'^2 + 3*x''^2*y'^4 - 7*x'*x'''*y'^4 ) + y''^2*( -54*x'^3*x''*y' + 18*x'*x''*y'^3 ) + y''^3*( 3*x'^4 - 21*x'^2*y'^2 ) + y''''*( - x'^6 - 2*x'^4*y'^2 - x'^2*y'^4 ) == 0 \]

A vertex \( v(s) \) has a position \( X \). Next and previous vertices are denoted by \( Xn, Xnn, Xp, Xpp \). If i the tangent direction and k the orthogonal direction at \( X \), then \( x(s)=X[i], y(s)=X[k] \).

At a vertex \( v(s) \), the position is parameterized by t. Varying t only modifies the vertical position \( X[k] \), i.e. y. So \( y(t) = (1-t)*I[v][k] + t*O[v][k] \) (for \( I[v] \) and \( O[v] \) inside and outside voxel positions).

The Euler-Lagrange are factorized as above in order to isolate at best the parameter t of vertex \( v(s) \).

The first four lines do not depend on t (except \( y''' \) but it is neglected and the old value is used).
\( y''^2 \) and \( y''^3 \) are linarized as \( y'' * y''_{old} \) and \( y'' * y''_{old}^2 \)
\( y'''' ~= ( c_0 * Yn - c_1 * y'' + c_2 * Yp ) \)
all \( y'' \) are sumed up, while the rest gives a constant.

\( x' ~= ( Xn[i] - Xp[i] ) / (d(X,Xn)+d(X,Xp) \) does not depend on t. \( y' ~= ( Xn[k] - Xp[k] ) / (d(X,Xn)+d(X,Xp) \) does not depend on t. \( x'' ~= ( c_0 * Xn[i] - c_1 * X[i] + c_2 * Xp[i] ) \) does not depend on t.

for \( c_0, c_1, c_2 \) constants depending on \( d(X,Xn) \) and \( d(X,Xp) \). \( y'' ~= ( c_0 * Xn[k] - c_1 * X[k] + c_2 * Xp[k] ) \) solely depend on t. where \( X[k] = y(t) = (1-t)*I[v][k] + t*O[v][k]. \) And so on.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::regularize().

◆ orthDir()

template<typename TDigitalSurfaceContainer >

Dimension DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::orthDir ( const Vertex v ) const

inline

Useful to find the two tangent directions to a given vertex (i.e. (orthDir(v)+1)%3 and (orthDir(v)+2)%3).

Returns: the orthogonal direction to vertex v.

Definition at line 208 of file ShroudsRegularization.h.

     {
       return myOrthDir[ v ];
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOrthDir.

◆ parameterize()

template<typename TDigitalSurfaceContainer >

void DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize ( )

inline

Computes the distances between the vertices along slices.

Definition at line 243 of file ShroudsRegularization.h.

     {
       Scalar d = 0.0;
       // Vertex n = 0;
       for ( Dimension i = 0; i < 3; ++i )
         for ( Vertex v = 0; v < myT.size(); ++v )
           {
             if ( myNext[ i ][ v ] == myInvalid )  continue; // not a valid slice
             myNextD[ i ][ v ] = ( position( myNext[ i ][ v ] ) - position( v ) ).norm();
             myPrevD[ i ][ v ] = ( position( myPrev[ i ][ v ] ) - position( v ) ).norm();
             d += myNextD[ i ][ v ];
             //      n += 1;
           }
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myInvalid, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNext, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNextD, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrev, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrevD, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myT, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::position().

◆ position() [1/2]

template<typename TDigitalSurfaceContainer >

RealPoint DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::position ( const Vertex v ) const

inline

Parameters

v	any valid vertex.

Returns: its position.

Definition at line 189 of file ShroudsRegularization.h.

     {
       const auto t = myT[ v ];
       return (1-t) * myInsV[ v ] + t * myOutV[ v ];
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myInsV, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOutV, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myT.

◆ position() [2/2]

template<typename TDigitalSurfaceContainer >

RealPoint DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::position	(	const Vertex	v,
		const double	t
	)		const

inline

Parameters

v	any valid vertex.
t	some adjustement parameter

Returns: the position of vertex v for this parameter t.

Definition at line 182 of file ShroudsRegularization.h.

     {
       return (1-t) * myInsV[ v ] + t * myOutV[ v ];
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myInsV, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOutV.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::positions().

◆ positions()

template<typename TDigitalSurfaceContainer >

RealPoints DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::positions ( ) const

inline

Returns: the vector of vertex positions

Definition at line 196 of file ShroudsRegularization.h.

     {
       RealPoints result( myT.size() );
       for ( Vertex v = 0; v < myT.size(); ++v )
         result[ v ] = position( v );
       return result;
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myT, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::position().

Referenced by TEST_CASE().

◆ precomputeTopology()

template<typename TDigitalSurfaceContainer >

void DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology ( )

inlineprotected

This method precomputes the neighbors of each vertex along each crossing curves. Must be called at shroud initialization.

Definition at line 476 of file ShroudsRegularization.h.

     {
       typedef typename Container::Tracker      Tracker;
       typedef DigitalSurface2DSlice< Tracker > Slice;
       myT       = Scalars( myPtrIdxSurface->nbVertices(), 0.5 );
       myInvalid = myT.size();
       myOrthDir.resize( myT.size() );
       for ( Dimension i = 0; i < 3; ++i )
       {
         myNext[ i ] = std::vector<Vertex>( myT.size(), myInvalid );
         myPrev[ i ] = std::vector<Vertex>( myT.size(), myInvalid );
       }
       // for each vertex, extracts its two slices.
       for ( Vertex v = 0; v < myT.size(); ++v )
         {
           auto surf      = myPtrIdxSurface->surfel( v );
           Dimension k    = myPtrK->sOrthDir( surf );
           myOrthDir[ v ] = k;
           for ( Dimension i = 0; i < 3; ++i )
             {
               if ( k == i )   continue; // not a valid slice
               if ( myNext[ i ][ v ] != myInvalid ) continue; // already computed
               Tracker* tracker = myPtrIdxSurface->container().newTracker( surf );
               Slice    slice( tracker, i );
               if ( ! slice.isClosed() ) {
                 trace.error() << "[ShroudsRegularization::precomputeTopology]"
                               << " Shrouds works solely on closed surfaces."
                               << std::endl;
                 return;
               }
               auto start = slice.cstart();
               auto  next = start;
               auto  prev = next++;
               Vertex  vp = v;
               do
                 {
                   auto sp = *prev;
                   auto sn = *next;
                   Dimension in = myPtrK->sOrthDir( sn ) == k ? i : k;
                   Dimension ip = myPtrK->sOrthDir( sp ) == k ? i : k;
                   Vertex vn = myPtrIdxSurface->getVertex( sn );
                   myNext[ ip ][ vp ] = vn;
                   myPrev[ in ][ vn ] = vp;
                   prev = next++;
                   vp   = vn;
                 }
               while ( prev != start );      
               delete tracker;
             }
         }
     }

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::ShroudsRegularization().

◆ prev()

template<typename TDigitalSurfaceContainer >

std::pair<Vertex,Dimension> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::prev ( const std::pair< Vertex, Dimension > & v_i ) const

inline

Useful to navigate tangentially along a slice.

Parameters

v_i	a pair (vertex,tangent direction)

Returns: the previous vertex and associated tangent direction along the slice.

Definition at line 227 of file ShroudsRegularization.h.

     {
       const Vertex    vp = myPrev[ v_i.second ][ v_i.first ];
       const Dimension ip = myOrthDir[ vp ] == v_i.second
         ? myOrthDir[ v_i.first ] : v_i.second;
       return std::make_pair( vp, ip );
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOrthDir, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrev.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

◆ regularize()

template<typename TDigitalSurfaceContainer >

std::pair<double,double> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::regularize	(	const Regularization	reg = `Regularization::SQUARED_CURVATURE`,
		const double	randomization = `0.0`,
		const double	max_loo = `0.0001`,
		const int	maxNb = `100`
	)

inline

Generic method for shrouds regularization.

Parameters

reg	your choice of regularization in AREA (not nice in 3D), SNAKE (not so bad), SQUARED_CURVATURE (works best)
randomization	if greater than 0.0 add some perturbation to the solution. May be used for quitting a local minima.
max_loo	the maximum \( l_\infty \)-norm of one step of regularization before stopping the regularization.
maxNb	the maximum number of optimization steps.

See also: oneStepAreaMinimization; oneStepSnakeMinimization; oneStepSquaredCurvatureMinimization

Definition at line 304 of file ShroudsRegularization.h.

     {
       double loo      = 0.0;
       double  l2      = 0.0;
       int     nb      = 0;
       double   r      = 0.5;
       do {
         std::tie( loo, l2 ) =
           reg == Regularization::SQUARED_CURVATURE
           ? oneStepSquaredCurvatureMinimization( r )
           : reg == Regularization::SNAKE
           ? oneStepSnakeMinimization( myAlpha, myBeta, r )
           : oneStepAreaMinimization( r );
         if ( nb % 50 == 0 )
           trace.info() << "[Shrouds iteration " << nb
                        << " E=" << energy( reg )
                        << "] dx <= " << loo << " l2=" << l2 << std::endl;
         r  *= 0.9;
         nb += 1;
       } while ( loo > max_loo && nb < maxNb );
       return std::make_pair( loo, l2 );
     }

Referenced by TEST_CASE().

◆ setParams()

template<typename TDigitalSurfaceContainer >

void DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::setParams	(	double	eps,
		double	alpha = `1.0`,
		double	beta = `1.0`
	)

inline

Sets some parameters that affect the output regularized shape.

Parameters

eps	the bounds for varying the positions of vertices in ]0,1[
alpha	parameter for Snake first order regularization (~ area)
beta	parameter for Snake second order regularization (~ curvature)

Definition at line 154 of file ShroudsRegularization.h.

     {
       myEpsilon = eps;
       myAlpha   = alpha;
       myBeta    = beta;
     }

References DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myAlpha, DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myBeta, and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myEpsilon.

Field Documentation

◆ myAlpha

template<typename TDigitalSurfaceContainer >

Scalar DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myAlpha

private

The alpha parameter for Snake first order regularization (~ area)

Definition at line 541 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::getParams(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::regularize(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::setParams().

◆ myBeta

template<typename TDigitalSurfaceContainer >

Scalar DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myBeta

private

The beta parameter for Snake second order regularization (~ curvature)

Definition at line 543 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::getParams(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::regularize(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::setParams().

◆ myEpsilon

template<typename TDigitalSurfaceContainer >

Scalar DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myEpsilon

private

The limiting bounds for the displacement of vertices along their unit dual edge: \( \lbrack \epsilon, 1-\epsilon \rbrack \)

Definition at line 539 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::getParams(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::setParams().

◆ myInsV

template<typename TDigitalSurfaceContainer >

RealPoints DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myInsV

private

the vector of dual points lying inside (inside extremity of each dual edge).

Definition at line 552 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::position().

◆ myInvalid

template<typename TDigitalSurfaceContainer >

Vertex DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myInvalid

private

the index of the invalid vertex.

Definition at line 545 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

◆ myNext

template<typename TDigitalSurfaceContainer >

std::vector<Vertex> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNext[3]

private

for each vertex, its successor on the slice of given axis direction.

Definition at line 559 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::next(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

◆ myNextD

template<typename TDigitalSurfaceContainer >

Scalars DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myNextD[3]

private

for each vertex, the estimated distance to its successor on the slice of given axis direction.

Definition at line 564 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::c1(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::c2_all(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize().

◆ myOrthDir

template<typename TDigitalSurfaceContainer >

std::vector<Dimension> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOrthDir

private

the direction axis of each dual edge.

Definition at line 557 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::next(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::orthDir(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::prev().

◆ myOutV

template<typename TDigitalSurfaceContainer >

RealPoints DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myOutV

private

the vector of dual points lying outside (outside extremity of each dual edge).

Definition at line 555 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::position().

◆ myPrev

template<typename TDigitalSurfaceContainer >

std::vector<Vertex> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrev[3]

private

for each vertex, its predessor on the slice of given axis direction.

Definition at line 561 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::prev().

◆ myPrevD

template<typename TDigitalSurfaceContainer >

Scalars DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPrevD[3]

private

for each vertex, the estimated distance to its predessor on the slice of given axis direction.

Definition at line 567 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::c1(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::c2_all(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize().

◆ myPtrIdxSurface

template<typename TDigitalSurfaceContainer >

CountedPtr<IdxDigitalSurface> DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPtrIdxSurface

private

the indexed digital surface (internal surface representation).

Definition at line 534 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

◆ myPtrK

template<typename TDigitalSurfaceContainer >

const KSpace* DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myPtrK

private

A const pointer to the cellular space in which lives the digital surface.

Definition at line 536 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

◆ myT

template<typename TDigitalSurfaceContainer >

Scalars DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::myT

private

the vector of vertex displacements along their dual edge (each value lies in \( \lbrack \epsilon, 1-\epsilon \rbrack \)), which is optimized by the shrouds algorithm.

Definition at line 549 of file ShroudsRegularization.h.

Referenced by DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::init(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::parameterize(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::position(), DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::positions(), and DGtal::ShroudsRegularization< TDigitalSurfaceContainer >::precomputeTopology().

The documentation for this class was generated from the following file:

ShroudsRegularization.h

Public Types

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

template<typename TDigitalSurfaceContainer> class DGtal::ShroudsRegularization< TDigitalSurfaceContainer >

Member Typedef Documentation

◆ Container

◆ IdxDigitalSurface

◆ IdxSurfel

◆ IdxSurfelRange

◆ IdxVertex

◆ KSpace

◆ RealPoint

◆ RealPoints

◆ RealVector

◆ RealVectors

◆ Scalar

◆ Scalars

◆ Self

◆ Space

◆ Vertex

Member Enumeration Documentation

◆ Regularization

Constructor & Destructor Documentation

◆ ShroudsRegularization() [1/2]

◆ ShroudsRegularization() [2/2]

Member Function Documentation

◆ BOOST_CONCEPT_ASSERT()

◆ c1()

◆ c2_all()

◆ energy()

◆ energyArea()

◆ energySnake()

◆ energySquaredCurvature()

◆ enforceBounds()

◆ getParams()

◆ init()

◆ next()

◆ oneStepAreaMinimization()

◆ oneStepSnakeMinimization()

◆ oneStepSquaredCurvatureMinimization()

◆ orthDir()

◆ parameterize()

◆ position() [1/2]

◆ position() [2/2]

◆ positions()

◆ precomputeTopology()

◆ prev()

◆ regularize()

◆ setParams()

Field Documentation

◆ myAlpha

◆ myBeta

◆ myEpsilon

◆ myInsV

◆ myInvalid

◆ myNext

◆ myNextD

◆ myOrthDir

◆ myOutV

◆ myPrev

◆ myPrevD

◆ myPtrIdxSurface

◆ myPtrK

◆ myT

template<typename TDigitalSurfaceContainer>
class DGtal::ShroudsRegularization< TDigitalSurfaceContainer >