ContourBSplineShapeMatrix.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_CONTOURBSPLINESHAPEMATRIX_HH_
#define __BIAS_CONTOURBSPLINESHAPEMATRIX_HH_

#include <list>

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

#include "ContourBSplineData.hh"

namespace BIAS{
  
  /** 
      @class ContourBSplineShapeMatrix
     @brief data object which holds a shape matrix or regularisation matrix
            for a b-spline curve; could be shared by some ContourBSpline 
            objects
    
    Objects of this class represents eithe a shape-matrix (invariant as well)
    or a regularisation matrix. These matrices are only needed if a 
    fitting of a B-Spline curve is used. If you use copys of a BSplineContour
    object they share this ContourBSplineMatrix object to save memory.
    
    A ContourBSplineShapeMatrix object is generated transparently
    by using Set[Sub]ShapeSpace...(...) or ComputeRegularisationMatrix() of
    the ContourBSpline object. These methods call Set[Sub]ShapeSpace...(...)
    or ComputeRegularisationMatrix(...) of this class. The pointer to this
    object gets returned.
    
    Copys of a B-Spline curve share this object, the pointer to this 
    object gets copied and the reference counter increased.
    
    If a ContourBSpline objects gets destroyed it calls the Unregister()
    method of its ContourBSplineShapeMatrix objects. This decreases the
    reference counter and destroys these objects, if the reference counter is
    zero.
    @ingroup g_feature     

   */
  class ContourBSplineShapeMatrix : public BIAS::Matrix<double>{
    friend class ContourBSpline;
    public:
      
      /**
       * @brief standard constructor
       */
      ContourBSplineShapeMatrix(){};
      
      /**
       * @brief destructor
       * 
       * Calls Unregister() method to decrease reference counter and destroy
       * object if its reference counter is zero.
       * 
       */
      ~ContourBSplineShapeMatrix(){
        Unregister();
      };
      
      /**
       * @brief a BSplineContour object uses this method to unregister itself
       *        from using this object
       * 
       * Decreases reference counter and destroys object if reference counter
       * is zero.
       * 
       */
      inline void Unregister();
       
      /**
       * @brief generates a new shape-matrix (invariant as well) as 
       *        ContourBSplineShapeMatrix object and returns a pointer to it
       * @param[in] matrix shape-matrix
       * 
       */
      static ContourBSplineShapeMatrix* SetShapeSpaceMatrix(
                                           const BIAS::Matrix<double>& matrix);

      /**
       * @brief generates a new shape-matrix (invariant as well) as 
       *        ContourBSplineShapeMatrix object and returns a pointer to it                                             
       * 
       * @param[in] numBasePolynoms number of base polynoms of curve - equal
       *            to number of control points of the curve
       * 
       * Uses parameter "numBasePolynoms" to generate a identity matrix of
       * size 2*"numBasePolynoms".
       * 
       */
      static ContourBSplineShapeMatrix* SetShapeSpaceIdentity(
                                           const unsigned int numBasePolynoms);

      /**
       * @brief generates a new shape-matrix (invariant as well) as 
       *        ContourBSplineShapeMatrix object and returns a pointer to it                                             
       * 
       * @param[in] numBasePolynoms number of base polynoms of curve - equal
       *            to number of control points of the curve
       * @param[in] Q vector of control points
       * 
       * Builds a shape-matrix (invariant as well) of euclidian similarities.
       * Size of matrix is 2*numBasePolynoms x 4.
       * 
       * Confer to "Active Contours" chapter 4.
       */
      static ContourBSplineShapeMatrix* SetShapeSpaceEuclidian(
                                            const unsigned int numBasePolynoms,
                                            const BIAS::Vector<double>& Q);

      /**
       * @brief generates a new shape-matrix (invariant as well) as 
       *        ContourBSplineShapeMatrix object and returns a pointer to it                                             
       * 
       * @param[in] numBasePolynoms number of base polynoms of curve - equal
       *            to number of control points of the curve
       * @param[in] Q vector of control points
       * 
       * Builds a shape-matrix (invariant as well) of plana affine 
       * transformations. Size of matrix is 2*numBasePolynoms x 6.
       * 
       * Confer to "Active Contours" chapter 4.
       */
      static ContourBSplineShapeMatrix* SetShapeSpacePlanarAffin(
                                            const unsigned int numBasePolynoms,
                                            const BIAS::Vector<double>& Q);

      /**
       * @brief generates a new invariant shape-matrix as 
       *        ContourBSplineShapeMatrix object and returns a pointer to it                                             
       * 
       * @param[in] shapeSpace shape-matrix (not invariant!)
       * 
       * Builds a invariant shape-matrix which is zero. Has same size like
       * the parameter shape-matrix.
       * 
       */
      static ContourBSplineShapeMatrix* SetSubShapeSpaceZero(
                                        ContourBSplineShapeMatrix* shapeSpace);

      /**
       * @brief generates a new regularisation matrix as 
       *        ContourBSplineShapeMatrix object and returns pointer to it
       * 
       * @param[in] data data object of a B-Spline curve
       * @param[in] shapeSpace shape-matrix
       * @param[in] subShapeSpace invariant shape-matrix
       * 
       * Computes the regularisation matrix needed for fitting a B-Spline 
       * curve.
       */
      static ContourBSplineShapeMatrix* ComputeRegularisationMatrix(
                                     ContourBSplineData* data,
                                     ContourBSplineShapeMatrix* shapeSpace,
                                     ContourBSplineShapeMatrix* subShapeSpace);

   
      //! list of all pointers to ContourBSplineShapeMatrix objects
      static std::list<ContourBSplineShapeMatrix*> pntr_;
      
      //! reference counter - for handling unregister      
      unsigned int reference_; //reference counter
      
  };//class
  
  inline void ContourBSplineShapeMatrix::Unregister(){
    reference_--;
    if(reference_==0){
    pntr_.remove(this);
    delete this;
    }
  }
  
}//namespace BIAS
#endif