ContourBSplineData.hh

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
  Multimediale Systeme der Informationsverarbeitung
  Institut fuer Informatik
  Christian-Albrechts-Universitaet Kiel


BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef __BIAS_CONTOURBSPLINEDATA_HH_
#define __BIAS_CONTOURBSPLINEDATA_HH_


#include <list>
#include <vector>

#include <Base/Debug/Debug.hh>
#include <Base/Math/Polynom.hh>
#include <Base/Math/Matrix.hh>
#include <Base/Math/Vector.hh>

#include "ContourBSplineType.hh"

#define D_CONTOURBSPLINEMATH_DEBUG      1<<0
#define D_CONTOURBSPLINEMATH_REGISTER   1<<1 
#define D_CONTOURBSPLINEMATH_SPAN       1<<2
#define D_CONTOURBSPLINEMATH_PLACEMENT  1<<3

namespace BIAS{
  /**
     @class ContourBSplineData
     @brief data object which holds all infomations of a B-Spline curve
            (ContourBSpline); its shared by B-Spline curves with same basis.
    
    Objects of this class save informations of a B-Spline curve 
    (ContourBSpline). If two or more ContourBSpline objects are initialised
    with the same order, type and multiplicity vector, then they share the
    same ContourBSplineData object.
    (Attention: shape-space and regularisation matrices are handled by 
    class ContourBSplineShapeMatrix.)
    
    A ContourBSplineData object is created/registered transparently by a 
    call of a ContourBSpline objects Init(...) or Load(...) function. 
    These functions call Register(...) of this class. The Register(...)
    function looks if it allready has the right data object. If yes, it 
    registers the ContourBSpline object by incrementing the reference counter
    of the data object and returns the pointer to the data object. If not,
    it uses the input parameter to create a new data object.
    Details of creation process are documented in book "Active Contours",
    mainly in appendix A.
    
    If a ContourBSpline objects gets destroyed it calls the Unregister 
    function of ContourBSplineData object. The reference counter gets 
    decremented and the data object destroyed if the reference counter is 
    zero.
    @ingroup g_feature      
  */
  class ContourBSplineData : public BIAS::Debug{
    friend class ContourBSpline;
    friend class ContourBSplineShapeMatrix;
    public:
      //! @brief empty standard constructor
      ContourBSplineData(){};
      
      //! @brief destructor
      ~ContourBSplineData(){
        Unregister();
      };

      /**
       * @brief decrements reference counter to this data object and deletes 
       *        it if there is no reference to it
       *
       * This function is transparently called by the destructor of a
       * ContourBSpline object. 
       */
      inline void Unregister();

      /**
       * @brief registers a ContourBSpline object and returns pointer to its
       *        data object
       * @param[in] order order of B-Spline curve
       * @param[in] bType type of B-Spline curve (Open or Closed)
       * @param[in] mPnts vector of multiplicities (holds information in which
       *                  control points edges are modelled
       * 
       * This function is transparently called by the Init(...) function of
       * a ContourBSpline object.
       * 
       * Looks up if there is already a data object that fits to the calling
       * ContourBSpline object. If yes, it returns the pointer to this
       * ContourBSplineData object and inkrements the reference counter of the
       * data object. If not, a new ContourBSplineData object gets created. 
       * 
       * Generation includes class variables:
       * order (copy)
       * bType (copy)
       * mPnts (copy)
       * numBasePolynoms (equal to number of control points (length of mPnts))
       * dependent on type of BSplineCurve (handled by specific helper 
       *                                    functions):
       * splineMetricMatrix_ //see "Active Contours" chapter 3
       * splineMetricMatrixParametric_
       * areaCoefficientMatrix_ //confer to "Active Contours" chapter 3
       *                        //not used for further computation at moment
       * 
       */
      static ContourBSplineData* Register(const unsigned int order, 
                                          const ContourBSplineType::Type bType,
                                       const std::vector<unsigned int>& mPnts);

      /**
       * @brief registers a clustered ContourBSpline object and returns pointer 
       *        to its data object
       * @param[in] bSplinesData vector of data objects from B-Spline curves 
       *                         which get clustered into one data object
       * 
       * This function is transparently called by the Cluster(...) function of
       * class ContourBSpline.
       *
       * Data object is build on basis of given B-Spline curves data objects.
       * 
       * There is no lookup if a data object already exist. When you cluster
       * some B-Spline curves and want a copy of the clustered curve, use
       * operator=.
       *
       */
      static ContourBSplineData* Register(
                         const std::vector<ContourBSplineData*>& bSplinesData);

      //using this for loading a clustered bspline                                 
      /**
       * @brief registers a clustered ContourBSpline object and returns pointer
       *        to its data object
       * @param[in] order order of clustered B-Spline curve
       * @param[in] bType Type of curve (Cluster)
       * @param[in] mPnts multiplicity vector of curve (determines in which
       *            control points edges are modelled)
       * @param[in] numBasePolynoms number of basepolynomes of the curve
       *                            (equal to number of control points)
       * @param[in] numSpans number of spans of curve
       * @param[in] numSpansVec vector seperates numSpans of seperate curves in
       *                        cluster
       * @param[in] placedSpanMatrices vector of all placed span-matrices of
       *                               curve (see "Active Contours" appendix A)
       *
       * This funcion is called transparently by Load(...) function of class
       * ContourBSpline. 
       * 
       * There is no lookup if a data object already exist. When you cluster
       * some B-Spline curves and want a copy of the clustered curve, use
       * operator=.
       *  
       */
      static ContourBSplineData* Register(const unsigned int order, 
                  const ContourBSplineType::Type bType, 
                  const std::vector<unsigned int>& mPnts,
                  const unsigned int numBasePolynoms,
                  const unsigned int numSpans,
                  const std::vector<unsigned int>& numSpansVec,
                  const std::vector<BIAS::Matrix<double> >&placedSpanMatrices);

    public:
      /**
       * @brief looks up if a ContourBSplineData object with the initial given
       *        parameter exist and returns pointer to it or NULL
       * @param[in] order order of B-Spline curve
       * @param[in] bType type of B-Spline curve (Open or Closed)
       * @param[in] mPnts multiplicity vector of curve (determines in which
       *                  control points edges are modelled
       * 
       */
      static ContourBSplineData* LookUpData_(const unsigned int order,
                                       const ContourBSplineType::Type bType,
                                       const std::vector<unsigned int>& mPnts);

      /**
       * @brief inits class variables for a closed B-Spline curve
       * 
       * computes:
       * numSpans_ //number of spans of curve
       * placedSpanMatrices //placed span matrices - see "Active Contours"
       *                    //appendix A, p.292
       * splineMetricMatrix_ //see "Active Contours" chapter 3
       * splineMetricMatrixParametric_
       * areaCoefficientMatrix_ //confer to "Active Contours" chapter 3
       *                        //not used for further computation at moment
       * 
       */
      void RegisterPeriodicBSpline_();
      
      /**
       * @brief inits class variables for an open B-Spline curve
       * 
       * computes:
       * numSpans_ //number of spans of curve
       * placedSpanMatrices //placed span matrices - see "Active Contours"
       *                    //appendix A, p.292
       * splineMetricMatrix_ //see "Active Contours" chapter 3
       * splineMetricMatrixParametric_
       * areaCoefficientMatrix_ //confer to "Active Contours" chapter 3
       *                        //not used for further computation at moment
       * 
       */
      void RegisterAperiodicBSpline_();
      
      /**
       * @brief recursivly computes one base polynom for a span matrix
       * 
       * @param[in] span index of span which includes base polynom
       * @param[in] knotIndex index of first knot of base polynom
       * @param[in] order order of B-Spline curve
       * @param[in] breakpoints vector of knot values
       * 
       * Confer to "Active Contours" appendix A p.291 for details.
       * 
       */
      BIAS::Polynom ComputeBasePolynomRecursive_(const unsigned int span,
                                          const unsigned int knotIndex, 
                                          const unsigned int order,
                                          const std::vector<int>& breakpoints);
      
      /**
       * @brief computes the span matrix of a B-Spline curves span
       * @param[in] span index of span whose matrix should be computed
       * @param[in] placeOff offset used in periodic case for index of first
       *                     knot of a span
       * @param[in] kMult vector of multiplicities of knots
       * @param[in] k vector of knots values (plain)
       * 
       * Confer to "Active Contours" appendix A p.291 for details.
       * 
       */
      void ComputeSpan_(const unsigned int span, 
                       const int placeOff, 
                       const std::vector<unsigned int>& kMult, 
                       const std::vector<int>& k);
      
      /**
       * @brief computes the metric matrix (scriptB) of the B-Spline curve
       * 
       * Confer to "Active Contours" chapter 3, p.50f; appendix A, p.293 for 
       * details.
       * 
       */
      void ComputeSplineMetricMatrix_();
      
      /**
       * @brief computes the metrix matrix (I^2 x scriptB) of the B-Spline 
       *        curve
       * 
       * Confer to "Active Contours" chapter 3, p.59; appendix A, p.293 for 
       * details.
       *  
       */
      void ComputeSplineMetricMatrixParametric_();
      
      /**
       * @brief computes the area coefficient matrix of the B-Spline curve
       * 
       * Confer to "Active Contours" chapter 3, p.65; appendix A, p.293 for
       * details.
       * 
       */
      void ComputeAreaCoefficientMatrix_();

      
      //class variables
      

      //! list of all pointers to ContourBSplineData objects
      static std::list<ContourBSplineData*> pntr_; 

      //! reference counter - for handling unregister
      unsigned int reference_;

      //! order of B-Spline curve
      unsigned int order_;

      //! type of B-Spline curve (Open,Closed,Cluster)
      ContourBSplineType::Type bType_;

      /**
       *  vector of multiplicities - determines in which control points 
       *  edges are modelled
       */
      std::vector<unsigned int>  mPnts_;

      /**
       * number of spans for sub B-Spline curves of the B-Spline curve
       * length >1 when curve is clustered
       */
      std::vector<unsigned int> numSpansVec_;

      //! number of base polynoms of curve - equal to number of control points
      unsigned int numBasePolynoms_;
      
      //! number of spans of curve
      unsigned int numSpans_;

      //! span matrices of curve (multiplied with placement matrices - p.292)
      std::vector<BIAS::Matrix<double>  > placedSpanMatrices_;
      
      //! metric matrix - confer to "Active Contours", chapter 3, p.50f
      BIAS::Matrix<double> splineMetricMatrix_;
 
      //! metric matrix - confer to "Active Contours", chapter 3, p.59
      BIAS::Matrix<double> splineMetricMatrixParametric_;
 
      /**
       * area coefficient matrix - confer to "Active Contours", 
       * chapter 3, p.65
       * 
       * (currently not farther used in fitting process)
       */
      BIAS::Matrix<double> areaCoefficientMatrix_;
  };//class
  
      inline void ContourBSplineData::Unregister(){
        reference_--;
        if(reference_==0){
          pntr_.remove(this);
          delete this;
        }      
      }  
  
}//namespace BIAS
#endif