Fitting module: Concepts

[Go back to Fitting user manual] [Go back to concept manual] [Go back to user manual]

---

Ponca Fitting Module is structured around the following concepts:

• WeightKernelConcept: defines how neighbor samples should be weighted
• ComputationalObjectConcept and ComputationalDerivativesConcept: define API of the computational objects used in Basket and BasketDiff respectively.

API of Computational Objects

Computations will always follow the same pattern:

// Definition
typedef Basket<MyPointStructure,MyWeightingFunction,MyFittingProcedure...> Fit;
 
// Initialization
MyWeightingFunction w ( some_parameters );  //< Init weight function
Fit fit;                                    //< Create a fit object
fit.init(  );                               //< Initialize the internal state
fit.setWeightFunc( {referencePosition, w} );  //< Set the weighting function (reference position and w can be shared accross multiple fits)
 
// Computations
foreach neighbors of referencePosition      //< Traverse neighborhood
  fit.addNeighbor(neighbor);                //< Intermediate computation for each neighbor
fit.finalize();                             //< Final computations
 
// Usage
if(fit.isStable())
{
    // use the fit ...
}

Note that in the above example, the type Fit can be either a Basket or a BasketDiff, without affecting the rest of the code.

Objects used in Basket

Objects used in Basket should respect the following API:

        template < class DataPoint, class _WFunctor, typename T = void  >
        class ComputationalObjectConcept
        {
        protected:
            enum {
                Check = PROVIDES_CAPABILITY_1 && PROVIDES_CAPABILITY_2 //< List of required capabilities
                PROVIDES_CAPABILITY,                                   //< List of provided capabilities
            };
 
        public:
            using Scalar     = typename DataPoint::Scalar;     //< Inherited scalar type
            using VectorType = typename DataPoint::VectorType; //< Inherited vector type
            using WFunctor   = _WFunctor;                      //< Weight Function
 
        public:
            /**************************************************************************/
            /* Initialization                                                         */
            /**************************************************************************/
            // Init the WeightFunc, without changing the other internal states.
            // \warning Must be called be for any computation
            PONCA_MULTIARCH inline void setWeightFunc (const WFunctor& _w);
 
            // Reset the internal states.
            // \warning Must be called be for any computation
            PONCA_MULTIARCH inline void init();
 
            /**************************************************************************/
            /* Computations                                                           */
            /**************************************************************************/
            // Add a neighbor to perform the fit
            // \return false if param nei is not a valid neighbour (weight = 0)
            PONCA_MULTIARCH inline bool addLocalNeighbor(Scalar, const VectorType &, const DataPoint &);
            // Finalize the fitting procedure.
            // \return State of fitting
            // \warning Must be called be for any use of the fitting output
            PONCA_MULTIARCH inline FIT_RESULT finalize();
        }; //class ComputationalObjectConcept

Objects used in BasketDiff

Objects used in BasketDiff should respect the following API:

        template < class DataPoint, class _WFunctor, int Type, typename T>
        class ComputationalDerivativesConcept
        {
        protected:
            enum {
                Check = PROVIDES_CAPABILITY_1 && PROVIDES_CAPABILITY_2 //< List of required capabilities
                PROVIDES_CAPABILITY,                                   //< List of provided capabilities
            };
 
        public:
            using Scalar     = typename DataPoint::Scalar;     //< Inherited scalar type
            using VectorType = typename DataPoint::VectorType; //< Inherited vector type
            using WFunctor   = _WFunctor;                      //< Weight Function
            // Static array of scalars with a size adapted to the differentiation type
            using VectorArray = typename Base::VectorArray;
            // Static array of scalars with a size adapted to the differentiation type
            using ScalarArray = typename Base::ScalarArray;
 
        public:
            /**************************************************************************/
            /* Initialization                                                         */
            /**************************************************************************/
            // Init the WeightFunc, without changing the other internal states.
            // \warning Must be called be for any computation
            PONCA_MULTIARCH inline void setWeightFunc (const WFunctor& _w);
 
            // Set the evaluation position and reset the internal states.
            // \warning Must be called be for any computation
            PONCA_MULTIARCH inline void init();
 
            /**************************************************************************/
            /* Computations                                                           */
            /**************************************************************************/
            // Add a neighbor to perform the fit
            // \return false if param nei is not a valid neighbour (weight = 0)
            PONCA_MULTIARCH inline bool addLocalNeighbor(Scalar w,
                                                         const VectorType &localQ,
                                                         const DataPoint &attributes,
                                                         ScalarArray &dw);
            // Finalize the fitting procedure.
            // \return State of fitting
            // \warning Must be called be for any use of the fitting output
            PONCA_MULTIARCH inline FIT_RESULT finalize();
        }; //class ComputationalDerivativesConcept

Note

PrimitiveDer defines the default entry point to most classes used in BasketDiff.

Capabilities of the Fitting tools

As described in Computational objets, basket and CRTP, The tool classes provides different kinds of compute capabilities. To describe what a class provides, we uses flags that allows us to check for compatibility at compile time.

Here is an in depth description of all the labels of the Fitting tools :

Label	Provided by	Required by	Outputs
PROVIDES_MEAN_POSITION Mean of the input points vectors	MeanPosition	MeanPositionDer MeanPlaneFitImpl OrientedSphereFitImpl CovarianceFitBase UnorientedSphereFitImpl	barycenter() barycenterDistance() barycenterLocal()
PROVIDES_MEAN_POSITION_DERIVATIVE Provides derivative of the mean position	MeanPositionDer	CovarianceFitDer OrientedSphereDerImpl UnorientedSphereDerImpl	barycenterDerivatives()
PROVIDES_MEAN_NORMAL Mean of the normal vectors	MeanNormal	MeanPlaneFitImpl OrientedSphereFitImpl	meanNormalVector()
PROVIDES_MEAN_NORMAL_DERIVATIVE Provides derivative of the mean normal	MeanNormalDer	-	dMeanNormal()
PROVIDES_PRIMITIVE_BASE Provides base API for primitives	PrimitiveBase	PrimitiveDer AlgebraicSphere	getWeightSum() setNeighborFilter() getNeighborFilter() getCurrentState() getNumNeighbors() isReady() isStable()
PROVIDES_PRIMITIVE_DERIVATIVE Provides base API for primitive derivatives	PrimitiveDer	GLSDer CovarianceFitDer MeanPositionDer MeanNormalDer MlsSphereFitDer OrientedSphereDerImpl UnorientedSphereDerImpl	isScaleDer() isSpaceDer() derDimension()
PROVIDES_GLS_PARAMETRIZATION Growing Least Squares reparametrization of the OrientedSphereFit	GLSParam	GLSDer	tau() eta() kappa() tau_normalized() eta_normalized() kappa_normalized() fitness() compareTo()
PROVIDES_GLS_DERIVATIVE Differentiation of GLSParam	GLSDer	-	dtau() deta() dkappa() dtau_normalized() deta_normalized() dkappa_normalized()
PROVIDES_GLS_GEOM_VAR Provides Geometric Variation as a weighted sum of the GLS scale-invariant partial derivatives	GLSDer	-	geomVar()
PROVIDES_ALGEBRAIC_SPHERE	AlgebraicSphere	OrientedSphereFitImpl OrientedSphereDerImpl SphereFitImpl UnorientedSphereFitImpl UnorientedSphereDerImpl	potential() project() primitiveGradient() isPlane() isValid() isApprox() changeBasis() prattNorm() prattNorm2() applyPrattNorm() radius() center() isNormalized()
PROVIDES_ALGEBRAIC_SPHERE_DERIVATIVE Provides derivatives for algebraic sphere	OrientedSphereDerImpl UnorientedSphereDerImpl	GLSDer MlsSphereFitDer	dPotential()
PROVIDES_COVARIANCE_PLANE_DERIVATIVE Provides derivatives for hyper-planes	CovariancePlaneDerImpl	-	dPotential()
PROVIDES_NORMAL_DERIVATIVE Provides the derivatives of the primitive normal	CovariancePlaneDerImpl MlsSphereFitDer OrientedSphereDerImpl UnorientedSphereDerImpl	NormalDerivativesCurvatureEstimator	dNormal()
PROVIDES_POSITION_COVARIANCE Provides the covariance matrix	CovarianceFitBase	CovarianceFitDer CovarianceLineFitImpl CovariancePlaneFitImpl	solver()
PROVIDES_POSITION_COVARIANCE_DERIVATIVE	CovarianceFitDer	CovariancePlaneDerImpl	-
PROVIDES_PLANE	Plane	CovariancePlaneFitImpl CovariancePlaneDerImpl ProjectedNormalCovarianceCurvatureEstimator MeanPlaneFitImpl MongePatch	setPlane() potential() project() primitiveGradient()
PROVIDES_TANGENT_PLANE_BASIS Turns a point in ambient 3D space to the tangent plane.	CovariancePlaneFitImpl	MongePatch	worldToTangentPlane() tangentPlaneToWorld()

Concepts related to weighting functions

Weighting functions are critical components of the library. They are represented by DistWeightFunc, which is defined from the euclidean distance field centered at the evaluation position (see DistWeightFunc::init()). Given a distance to this evaluation position, the weight is computed (see DistWeightFunc::w()) by applying a 1d weighting function defined as follows:

        // \brief Concept of a 1D weighting function and its derivatives.
        template <typename _Scalar>
        class WeightKernelConcept{
        public:
            typedef _Scalar Scalar;
 
            // \brief Apply the weighting kernel to the scalar value f(x)
            PONCA_MULTIARCH inline Scalar f  (const Scalar& x) const {}
            // \brief Apply the first derivative of the weighting kernel to the scalar value f'(x)
            PONCA_MULTIARCH inline Scalar df (const Scalar& x) const {}
            // \brief Apply the second derivative of the weighting kernel to the scalar value f''(x)
            PONCA_MULTIARCH inline Scalar ddf(const Scalar& x) const {}
        };// class WeightKernelConcept

DistWeightFunc also provides computation of the first and second order derivatives of the weight, both in scale (DistWeightFunc::scaledw(), DistWeightFunc::scaled2w()) and space (DistWeightFunc::spacedw(), DistWeightFunc::spaced2w()), and their cross derivatives (DistWeightFunc::scaleSpaced2w()). Theses methods check if the weight kernels provides the appropriate derivatives

---

[Go back to Fitting user manual] [Go back to concept manual] [Go back to user manual]