ponca_module_fitting.mdoc

namespace Ponca
{ MeanNormal* meanNormal = fit.meanNormal();
    // Do whatever you want with a 'MeanNormal' instance
  \endcode
 
  \subsection fitting_newestim Estimator API
 
  \subsubsection fitting_newestimbase Minimal requirements
 
  In order to make an estimator compatible with Ponca Fitting API, new estimator should have the following structure:
 
  \snippet concepts.hpp ComputationalObjectConcept
 
  \note The macro PONCA_FITTING_DECLARE_DEFAULT_TYPES defines the `Base` type (alias for T) as well as `Scalar`, `VectorType` and `NeighborFilter` for
  manipulation of related data. This macro is defined within <Fitting/defines.h>
  \note If the estimator is expected to be the upmost parent of the hierarchy, do not inherit from T and default it to be void.
  \warning The macro PONCA_FITTING_DECLARE_DEFAULT_TYPES opens a public section. 
 
  In order for each computation to work properly, the functions `init`, `addLocalNeighbor` and `finalize` should call their Base version (`Base::init`, `Base::addLocalNeighbor`, `Base::finalize`).
  Presumably, this is among the first thing each of these function does.
    
  \subsubsection fitting_newcapabilities Computational objets capabilities and requirements
 
  Aggregating small computational objects allows to minimize code duplication, but also to easily combine different techniques.
  For instance, GLSDer can be used independently of the fitting technique, e.g. Ponca::OrientedSphereFit or Ponca::UnorientedSphereFit, as long as the fitted \ref PrimitiveBase "Primitive" is an AlgebraicSphere.
 
  In order to detect if the computational objects are correctly combined, Ponca relies on C++20 concepts. Most concepts provided for Basket extensions and tools can be found within the Fitting/concepts.hpp file. 
  For instance, the GLSParam class is defined as:
 
  \snippet gls.h example_requirements_usage
 
  We encourage macros to express requirements, as they ease definitions. For instance: 
  \snippet gls.h example_requirements
 
  This indicates that the class expects another extention to provide an AlgebraicSphere. If not, a compiler error
  will be emitted. For instance, gcc emits:
 
  ```sh
ponca/tests/src/test.cpp:192:9:   required from ‘void callSubTests() [with Scalar = long double; int Dim = 3]’
ponca/tests/src/test.cpp:252:5:   required from here
ponca/Ponca/src/Fitting/Basket/basket.h:53:19: error: template constraint failure for ‘template<class DataPoint, class _NFi
lter, class T>  requires  ProvidesAlgebraicSphere<T> class Ponca::GLSParam’
   53 |             using type = Ext<P, NF, Aggregate>;
      |                   ^~~~
ponca/Ponca/src/Fitting/Basket/basket.h:53:19: note: constraints not satisfied
  ```
 
  The whole output can be quite verbose, but is very precise: it tells you exactly what expression of a requirement is invalid and
  can help you debug the code. 
  Classes do not describe which concept they satisfies, apart perhaps in their documentation.
 
  \note In its current version, the requirement/capability system offer limited protection over the combination of tools providing the same capabilities.
  Indeed, it is possible to build ill-formed combinations where two computations attempt to save their results at the same place, e.g. when using two fitting technique for the same primitive:
  \snippet fit_plane.cpp Conflicting type
  This case is not detected at compile time, but rather dynamically when calling finalize(), which returns `CONFLICT_ERROR_FOUND`.
  Internally, this is implemented by checking if the primitive is already valid (ie. it has been computed already) when finalizing the computation.
  This limitation is expected to be resolved in upcoming releases.
 
  \subsubsection fitting_cast Providing cast operations
 
  As explained earlier, the class hierarchy can not reach every function of every through the provided `Base` type due to overloading. 
  The mecanism Ponca implements is a cast operator. Fortunately, this is quite common and a macro helps to define them. Add the following 
  within a public section of your class:
 
  \code
    PONCA_EXPLICIT_BASKET_CAST_OPERATORS(ClassName, className);
  \endcode
 
  Where the first parameter is the class name and the second is the name of the cast function which is, most of the time, the same as the 
  class name excpet a first lower case letter. Note that this macro requires the template parameter to be named following ponca conventions. 
  A class may provide multiple cast operator. 
 
  In order to respects concepts, a cast operator to a common name is required. This name can be found within the concept declaration (Fitting/concepts.hpp)
 
  \subsubsection fitting_newdiff New primitive differentiation (BasketDiff API)
    
  The API for defining new estimator that differentiate the primitive follows the same principle from classical estimator. The base class is BasketDiff which follows the 
  same CRTP / inheritance principle except that a Basket is required as a first parameter. 
 
  \snippet concepts.hpp ComputationalDerivativesConcept
 
  \note PrimitiveDer is the default entry point to most classes used in BasketDiff
 
  A few addition should be notted however. First, the class is now templated on a flag (an integer) representing the variables according to which we want to differentiate. For now, 
  Ponca defines only two set of variables (&lt;Fitting/enums.h&gt;):
 
  - FitScaleDer: The derivatives of the primitive parameters w.r.t the scale (the neig radius)
  - FitSpaceDer: The derivatives of the primitive parameters w.r.t the position of evaluation
  - FitScaleSpaceDer: Compute derivative for both types. 
 
  The macro `PONCA_FITTING_DECLARE_DEFAULT_DER_TYPES` defines two additionnal types `ScalarArray` and  `VectorArray`. Those types defines storage for derivative result. Note that 
  they are fixed-size array whose size is adapted to the total number of derivatives. Their layout is described below depending on the type of differentiation. 
 
  <table>
      <tr>
          <th>Fitting derivative value</th>
          <th>Number of derivatives</th>
          <th> Scalar Array indices </th>
      </tr>
      <tr>
          <td>FitScaleDer</td>
          <td> 1 </td>
          <td> [0] is the derivative w.r.t scale </td>
      </tr>
      <tr>
          <td> FitSpaceDer </td>
          <td> DataPoint::Dim </td>
          <td> [0:DataPoint::Dim] derivatives w.r.t eval position </td>
      </tr>
      <tr>
          <td> FitScaleSpaceDer </td>
          <td> 1 + DataPoint::Dim </td>
          <td> [0] derivatives w.r.t scale, <br/> [1:DataPoint::Dim+1) derivatives w.r.t eval position </td>
      </tr>
  </table>
 
 
  \section fitting_advanced Advanced usage
 
  \subsection fitting_factory Iterating over common Baskets
 
  In many cases, one may want to compare multiple Baskets or extensions. The classical solution is to write a function that accepts a template type (which would be your Basket) and then call the function manually for each type. For this reason, Ponca provides a Factory that abstracts away the iteration over compute objects for the most common types.
 
  \snippet ponca_factory.cpp FactoryBasicForeach
 
  The Factory module also provides the ability to filter by concept. Most Ponca fitting concepts have a corresponding filter. For a concept named "ProvidesXXX", Ponca creates two filters: "XXXProvider" and "NotXXXProvider", which can be used for filtering.
 
  \snippet ponca_factory.cpp FactoryFilterPersistent
 
  Classical literature methods can also be obtained through the Factory. For a complete list, see the `Ponca::Method` enumeration.
 
  \snippet ponca_factory.cpp FactoryClassicalMethods
 
  \warning Factories may contain different compute objects depending on the given point, filter, or derivative types. For example, Monge Patch fitting is currently only available in 3D; therefore, the Factory will include the corresponding classes only when provided with 3D points.
 
  \subsection fitting_multiprimitive Fitting with multiple primitives
  In most cases, only one primitive is included in the Basket, and it is recommended to use the helper classes provided by Ponca for fitting, e.g. CovariancePlaneFitImpl, OrientedSphereFitImpl.
  However, Ponca also allows to combine multiple primitives, for instance to share intermediate computation results.
  Using this functionality requires to really understand how the different primitives and fitting techniques are working.
  In any case, it is recommended to explicitly define the computational arrangement, e.g.:
  \snippet basket.cpp HybridType
 
  After fitting, this object provides access to both the plane and the sphere, through the respective cast operators #AlgebraicSphere::algebraicSphere() and #Plane::plane().
 
  \section fitting_cuda Cuda and SYCL
  Ponca can be used directly on GPU, thanks to several mechanisms:
   - Eigen capabilities, see <a href="http://eigen.tuxfamily.org/dox-devel/TopicCUDA.html"  target="_blank">Eigen documentation</a> for more details.
   You *need* to use a consistent `Eigen::Index` on both CPU and GPU if you plan to transfer memory between the computing units.
   That's why we recommend to set the following preprocessor variable when compiling your project:
   \code -DEIGEN_DEFAULT_DENSE_INDEX_TYPE=int\endcode
   You might also need to define the `--expt-relaxed-constexpr` preprocessor option for `NVCC`.
   Example of working cmake file (see \ref example_cu_ssc_page):
   \code
   enable_language(CUDA)
   add_executable(ponca_ssgls "ponca_ssgls.cu")
   target_compile_options(ponca_ssgls PRIVATE --expt-relaxed-constexpr)
   \endcode
   - Automatic CPU/GPU compilation qualifiers. We use the macro
  \code
          PONCA_MULTIARCH void function();
  \endcode
  to use the same code for C++ and CUDA. It has no effect when the code is compiled with GCC or Clang, but it will force the compilation for both host and device architectures when compiling with nvcc. A similar macro system is provided for mathematical functions, to switch between STL and CUDA versions.
 
  Check the \ref cu_ssgl_intro_sec "C++/Cuda", the \ref example_python_ssc_page "Python/Cuda" (using PyCuda), \ref example_sycl_basic and \ref example_sycl_kdtree examples for more details and how-to.
 
  <hr>
  <center>[\ref fitting_concepts "Go to concept page"]</center>
  <center>[\ref user_manual_page "Go back to user manual"]</center>
 */
 }