RectificationBase.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 __RectificationBase_hh__
#define __RectificationBase_hh__

#include <Image/Camera.hh>
#include <Base/Image/Image.hh>
#include <Geometry/ProjectionParametersBase.hh>

namespace BIAS {

#define UNDEFINED_DEPTH 0.0

  /** 
   * base class for rectification implementations and wrappers
   * \ingroup Stereo
   * \ingroup g_filter
   * \author bartczak 11/2006
   */
  template <class InputStorageType, class OutputStorageType> 
  class BIASImage_EXPORT RectificationBase {
  public:

    virtual ~RectificationBase();
    RectificationBase();

    /** \name Input data 
     * fundamental setters.*/
    /** @{*/
    /** \returns -1 if rectification class is not supporting the 
     * specified projection type (what includes invalid projections).
     * \returns 1 if argument projection is already set.
     */
    virtual int SetCameraA(BIAS::Camera<InputStorageType>& cam);

    /** \returns -1 if rectification class is not supporting the 
     * specified projection type (what includes invalid projections).
     * \returns 1 if argument projection is already set.
     * Will only use pointer for polymorphism. 
     * Will aquire copy of projection.
     */
    virtual int SetCameraA(const BIAS::Image<InputStorageType>& img,
                           const BIAS::ProjectionParametersBase* proj);

    /** \returns -1 if rectification class is not supporting the 
     * specified projection type (what includes invalid projections).
     * \returns 1 if argument projection is already set.
     */
    virtual int SetCameraB(BIAS::Camera<InputStorageType>& cam);

    /** \returns -1 if rectification class is not supporting the 
     * specified projection type (what includes invalid projections).
     * \returns 1 if argument projection is already set.
     * Will only use pointer for polymorphism. 
     * Will aquire copy of projection.
     */
    virtual int SetCameraB(const BIAS::Image<InputStorageType>& img,
                           const BIAS::ProjectionParametersBase* proj);
    /** @}*/

    /** Fundamental method which contains the rectification implementation.
     * \returns 0 on successfull rectification.     
     */
    virtual int Rectify() = 0;    
    
    /** Uses the passed disparity map for camera A to calculate the 
     *  corresponding depth map.
     * \param DisparityMap disparity map for camera A.
     * \param DepthMap resulting depth map for camera A.
     * \param border image border of depth map that will be ignored
     */
    virtual int Disp2Depth(const Image<float>& DisparityMap, 
                           Image<float>& DepthMap, 
                           unsigned int border) = 0;

    /** \name Getters 
     * Return stored results. If there are.
     */
    //@{    
    void GetRectifiedImageA(Image<OutputStorageType>& rectImg);
    void GetRectifiedImageB(Image<OutputStorageType>& rectImg);
    //@}

    /** \name Utility functions 
     * Methods connected with rectification but are rather unspecific.
     */
    //@{
    /** Method determines two orthonormal bases suitable for rectification. 
     * This bases are parallel to oneanother. The x-basevector is parallel to
     * the line connecting the origins of poseA and poseB. The z-basevector
     * is chosen so that it is in between the z-vectors of original poses.
     * \param failIfForwardMove if true will have an error code(<0) returned
     *          if one of the original z-basevectors is parallel to baseline 
     */
    static int CalculateRectifiedBases(const Pose& poseA,
                                       const Pose& poseB,
                                       Pose& poseResA,
                                       Pose& poseResB,
                                       bool failIfForwardMove = false);
    /** Method calculates an intermediate orientation for rectification 
     *  from all three poses. Does not check for forward movement now!
     *  Fails if two of the cameras are the same!
     */
    static int CalculateMeanOrientation(const Pose& poseLeft,
                                        const Pose& poseCenter,
                                        const Pose& poseRight,
                                        Quaternion<double>& orientation);
    //@}
    
    /** @{ 
     *  Method is called by SetCamera* methods and returns true if arguments
     *  are accepted by rectification implementations. E.g. a rectification
     *  method specialised on perspective images will refuse to handle
     *  spherical parameters. If method returns false the SetCamera* routines 
     *  will also fail.
     */
    /** Method calls two parameteric pure virtual method */
    bool IsInputCameraValid(BIAS::Camera<InputStorageType>& cam);


    /** \name Grabbing/RT Utils 
     * Methods granting direct access to data structures of rectification.
     * \attention Use this with caution, methods were introduced to allow
     *  direct image grabbing into rectification object and efficient
     *  rectification readout when camera parameter do not change!
     * \attention Use of methods belonging to this group does not trigger ANY 
     *  state update!
     * Methods were designed for following scenario:
     * -# Use Set methods to initialize rectification and trigger state update.
     * -# Use pointer aquired by GetImagePointerA()/B() to set original image 
     *  content! It is not possible to set the ProjectionParamters this way!
     * -# Call Rectify(): running this the first time will take some
     *   calculational effort because LUT will be constructed.
     * -# Use pointer aquired GetRectifiedImagePointerA()/B(): to readout 
     *   the result.
     * If camera parameters do not change repeat all but the first dash to 
     * aquire rectified images.
     */
    //@{    
    Camera<InputStorageType>* GetImagePointerA();
    Camera<InputStorageType>* GetImagePointerB();
    const Image<OutputStorageType>* GetRectifiedImagePointerA();
    const Image<OutputStorageType>* GetRectifiedImagePointerB();
    //@}

    virtual bool 
      IsInputCameraValid(const BIAS::Image<InputStorageType>& img,
                         const BIAS::ProjectionParametersBase* proj) = 0;
    /** @} */
  protected:
    
    /** local copy of passed projection parameters*/
    ProjectionParametersBase* ppBA_;
    
    /** local copy of passed image*/
    Camera<InputStorageType> imageA_;

    /** local copy of passed projection parameters*/
    ProjectionParametersBase* ppBB_;

    /** local copy of passed image*/
    Camera<InputStorageType> imageB_;

    /** Results of rectification */
    Image<OutputStorageType> rectImageA_;

    /** Results of rectification */
    Image<OutputStorageType> rectImageB_;

    
  };


}//end of namespace

#endif