TextureTransform.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 __TextureTransform__hh__
#define __TextureTransform__hh__

#include <Base/Common/BIASpragmaStart.hh>

#include <Base/Debug/Debug.hh>
#include <Base/Geometry/HomgPoint2D.hh>
#include <Base/Math/Matrix2x2.hh>
#include <Base/Math/Vector.hh>
#include <Geometry/HMatrix.hh>
#include <vector>


namespace BIAS {

  /** @class TextureTransform
   *  @brief class for representing parameterized image warps, such as 
   *         homography, displacement, ...
   *
   *  These classes can be exploited for mapping of images ("stitching") 
   *  or for registration (gradient based estimation of the warp
   *  parameters ("KLT"), see BIAS::ImageAlignment, BIAS::BackwardMapping).
   *
   *  This base class only defines the interface for all derived transforms.
   *  The transformations must form a group, i.e. each concatenation of
   *  transformations of the same class must also be a transformation of that 
   *  class: For instance, two displacements concatenated are expressable as 
   *  one "big" displacement. You must specify how to fuse the parameters
   *  into the parameter for the concatenated transform (e.g. addition).
   *
   *  The transformations must depend on a minimal number of parameters, 
   *  e.g. 6 parameters for the affine transformation. The parameter vector 0
   *  must represent the identity warp. 
   *
   *  You must at least provide the MapBackward and MapForward function. You
   *  can also provide the TextureJacobian functions, which - given
   *  two neighboring pixels in one image - measure their distance in the 
   *  other image (imagine "local magnification"). These functions are needed
   *  for anti-aliased BackwardMapping and they can be approximated numerically
   *  very stable and well (but due to sampling not very fast). 
   *  If you are interested in gradient based image
   *  registration, you should also provide the parameter jacobians, which tell
   *  how the mapping changes, when the parameters change. The approximation
   *  of these Jacobians is heuristic and presumably not very good. See
   *  TextureTransformHomography for an example.
   *
   *  @author koeser 01/2008
   **/
  class BIASImage_EXPORT TextureTransform {
  public:
   
    virtual ~TextureTransform(){};

    /** @brief override the current state with the new parameters, the meaning
     *  of the parameters is defined in the derived class'es SetParameters(). */
    virtual void SetParameters(const Vector<double>& p) = 0;

    /** @brief get the current parameter vector */
    void GetParameters(Vector<double>& p) const { p = P_; }

    /** @brief map a point in image "source" to a point in image "sink" */
    virtual int MapForward(const HomgPoint2D& src, HomgPoint2D& sink) const=0;

    /** @brief map a point in image "source" to a point in image "sink" */
    virtual int MapBackward(const HomgPoint2D& sink, HomgPoint2D& source)
      const = 0;

    /** @brief concatenate *this and an inverse transform with param deltaP 
        and save new parameter vector to *this. Apart from very simple 
        transformations like displacement THIS IS NOT A SIMPLE ADDITION but 
        rather a multiplication-like operation!

        This function is particularly important for inverse compositional image
        alignment (KLT) */
    virtual void ComposeWithInverseDeltaP(const Vector<double>& deltaP) = 0;
    
    /** @brief shape change of the local region when mapping forward */
    virtual int TextureJacobianForward(const HomgPoint2D& src, 
                                       Matrix2x2<double>& Jac) const;

    /** @brief shape change of the local region when mapping backward */
    virtual int TextureJacobianBackward(const HomgPoint2D& sink, 
                                        Matrix2x2<double>& Jac) const; 

    /** @brief return true if the texture jacobian does not depend on the image
        position */
    virtual bool TextureJacobianIsConstant() const = 0;

    /** @brief transformed position change when parameters change */
    virtual int ParameterJacobianForward(Matrix<double>& Jac, 
                                         const HomgPoint2D& src);

    /** @brief transformed position change when parameters change */
    virtual int ParameterJacobianBackward(Matrix<double>& Jac, 
                                          const HomgPoint2D& sink);

    /** @brief compute parameters for inverse operation and obtain the jacobian
        of the inverse parameters with respect to the original parameters for
        error propagation */
    virtual int ParameterInversionJacobian(Matrix<double>& Jac) const {
      BIASERR("not implemented in derived class. Could also be done HERE numerically by calling GetInverseParameters"); BIASABORT;
      return -1;
    }

    /**@brief returns parameter vector which undoes the current warp */
    virtual Vector<double> GetInverseParameters() const {
      BIASERR("not implmented."); BIASABORT;
      return Vector<double>();
    }

    /** @brief return true, if the parameter jacobian does not depend on the 
        image position */
    virtual bool ParameterJacobianIsConstant() const = 0;
    
    /** @brief virtual covariant copy constructor, caller must eventually 
        destroy the created object */
    virtual TextureTransform* Clone() const = 0;

  protected:
    /// current set of parameters, see SetParameters for meaning 
    Vector<double> P_;
  };


} // end namespace BIAS

#endif