RectificationViaProjectionMappingBase.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
 */

#include <Base/Common/BIASpragmaStart.hh>

#ifndef __RectificationViaProjectionMappingBase_hh__
#define __RectificationViaProjectionMappingBase_hh__

#include <Image/RectificationBase.hh>
#include <Image/BackwardMapping.hh>
#include <Image/ProjectionMapping.hh>

namespace BIAS
{

  /** Base class for rectification implementations that make use of
   *  projections to represent rectified state and where the projection-centers
   *  in rectified and original state are the same.
   *  Implementation of child classes only have to supply the rectified params
   *  calculation. Aftwerwards they can make use of the ProjectionMapping
   *  facilities that are implemented in this class to rectify images and
   *  evaluate disparity maps into depth maps. Be warned: ProjectionMapping
   *  is a very expansive implementation, yet takles nonlinearities in
   *  coordinate transformation (i.e. distortions).
   *
   * \ingroup g_filter
   *  \author bartczak 11/2006
   */
  template<class InputStorageType, class OutputStorageType>
    class BIASImage_EXPORT RectificationViaProjectionMappingBase : public RectificationBase<
        InputStorageType, OutputStorageType>
    {
    public:

      virtual
      ~RectificationViaProjectionMappingBase();
      RectificationViaProjectionMappingBase(const std::string& stringID,
          const double& Scale = 1.0);

      /** Scale factor for isotropically scaling the rectified images (and rectified intrinsic parameters).
       * \attention If targetWidth_ is greater zero the scale factor set using this method is ignored, see
       * SetTargetWidth().
       **/
      inline void
      SetScale(const double& scale)
      {
        scale_ = scale;
        rectificationParamsAreValid_ = false;
      }

      virtual int
      SetCameraA(BIAS::Camera<InputStorageType>& cam);
      virtual int
      SetCameraA(const BIAS::Image<InputStorageType>& img,
          const BIAS::ProjectionParametersBase* proj);
      virtual int
      SetCameraB(BIAS::Camera<InputStorageType>& cam);
      virtual int
      SetCameraB(const BIAS::Image<InputStorageType>& img,
          const BIAS::ProjectionParametersBase* proj);

      virtual int
      Rectify();

      virtual int
      Disp2Depth(const Image<float>& DisparityMap, Image<float>& DepthMap,
          unsigned int border);

      // frick
      static int
      Disp2Depth(const Image<float>& DisparityMap, Image<float>& DepthMap,
          const ProjectionParametersBase* origCamPA,
          const ProjectionParametersBase* origCamPB,
          const ProjectionParametersBase* rectCamPA,
          const ProjectionParametersBase* rectCamPB, unsigned int border);

      /** Tries to calculate the rectification parameters and returns clones
       *  of internal members. If just one rectification parameter could not
       *  be determined the returned pointer will be NULL and the return value is
       *  less 0.
       */
      virtual int
      GetClonesOfRectificationParameters(ProjectionParametersBase*& rectPPA,
          ProjectionParametersBase*& rectPPB);

      /** Determines the type of interpolation used when rectifying.
       *  Types are taken from BackwardMapping.hh
       */
      void
      SetInterpolationMethod(InterpolationMethod interpolationType);

      /** fill color for second image (first is black) */
      void
      SetSecondFill(OutputStorageType d)
      {
        secondFill_ = d;
      }

      /** \name Rectification Setup I/O */
      /** @{ */
      /** Method returns the current rectification setup.
       * The Camera class is used as a carrier for the camera parameters
       * stored in the meta data under a single projection.
       * The image data part is containing the BWM-Look-Up-Tables.
       * Each image row contains a single BWM-LUT.
       * The ascii meta data field will contain the StringID of the
       * rectification, which can be quaried using GetStringID().
       **/
      int
      GetRectificationSetup(Camera<float>& rectSetup);

      /** Loads rectification setup from Camera data.
       * \returns -1 if ID stored in the image does not fit the class id.
       * \attention if Set*() is called with parameters not fitting the loaded
       * setup, a reinitalisation of the mapping structures is performed
       * (like in scenarios where the setup was not loaded!).
       **/
      int
      SetRectificationSetup(Camera<float>& rectSetup);

      /** Returns the displacement maps rather then the rectified images,
       *  Suitable for texture look ups for multiple images of same
       *  configuration.
       */
      int
      GetRectifyingDisplacementMaps(Image<float>& displacementA,
          Image<float>& displacementB);

      /** Returns the string id that identifies the rctification classes in
       * this hierarchy. Suitable for factories from information stored in
       * Setup files.
       */
      const std::string&
      GetStringID() const
      {
        return stringID_;
      }
      /** @} */

      /** Set the override angles, which are individually chosen for the
       * internal parameters, if the respective override leads to
       * a smaller fov of the rectified cameras, then the automatically derived
       * fov. The angles are defined in the rectified coordinate frame of the
       * first camera and have the same defintion as the angle coordinates used
       * in ProjectionParametersGreatCircle.
       **/
      void
      SetOverrideAngles(double thetaMinOverride, double thetaMaxOverride,
          double phiMinOverride, double phiMaxOverride);

      /** Similar to SetScale but uses the argument width to determine scale
       * factor.
       * Method sets the value of targetWidth_ which defaults to zero.
       * If targetWidth_ is set greater then zero an isotropic scale factor
       * for the calculated rectified intrinsic parameters is derived so that
       * both rectified images will have this width.
       *
       * \attention If targetWidth_ is greater zero the scale factor set using
       *  SetScale is ignored.
       *
       **/
      void
      SetTargetWidth(unsigned int targetWidth);

      /** Method allows to turn on or off the use of look up tables.
       * Per default use of look up tables is turned on. If it is turned off
       * loading rectification setups will turn it on!
       */
      void
      UseLookUpTables(bool use);

    protected:
      /** \name Rectification Setup I/O */
      /** @{ */
      /** Descriptive identifier of the classes in the hierarchy **/
      std::string stringID_;
      /** @} */

      /** Calculating the projection parameters for specific rectification.
       * Is called by Rectify implementation. Must return 0 upon success, every
       * other code is handled as failure.
       */
      virtual int
      DetermineRectificationParameters_() = 0;

      /** this computes ideal parameters and applies the scale */
      int
      DetermineScaledRectificationParameters_();

      /** Projection parameters of the rectified image A */
      ProjectionParametersBase* rectPPA_;

      /** Projection parameters of the rectified image B */
      ProjectionParametersBase* rectPPB_;

      /// scale computed rectification resolution by this amount
      double scale_;

      /** if this value is greater zero the scale the computed rectification
       * parameters are isotropically scaled by a scale factor so that the image width of
       * both rectified images matches this value. Its value is set using SetTargetWidth().
       **/
      unsigned int targetWidth_;
    protected:
      /** Checks for rectificationParamsAreValid_ if not true will
       *  try to succsessfully process DetermineRectificationParameters_().
       *  If this is the case it will set rectificationParamsAreValid_ to true
       *  and return this value. Otherwise will return false.
       */
      bool
      AreRectificationParametersValid_();

      /** Flag is true when DetermineRectificationParameters_() was succesfull
       * and no setter was called afterwards.
       */
      bool rectificationParamsAreValid_;

      InterpolationMethod interpolationType_;
      OutputStorageType secondFill_;

      /** Classes holding rectification parameters and performing mapping **/
      ProjectionMapping<InputStorageType, OutputStorageType> rectMapperA_;
      ProjectionMapping<InputStorageType, OutputStorageType> rectMapperB_;

      /** Tells whether the lut structure and the result images have been initialized.
       * This flag is set to true by method InitializeMapping_(). It is false after
       * object creation and is set false when rectificationParamsAreValid_ flag changes
       * from false to true, which is the case in AreRectificationParametersValid_().
       **/
      bool mappingInitialized_;

      /** \name Initialization.
       * The general rectification procedure runs as follows:
       *  -# Receive input data: image and cam-params.
       *  -# Determine the rectification parameters, influenced by scale factors.
       *  -# Initialize the two projection mapping objects that perform the
       *     Mapping (InitializeMapping_()).
       *
       *  The rectification setup can be stored and loaded. The full
       *  initialization procedure is not necessary if the BWM-LUTs are loaded.
       *  In this case it suffices to initialize the target images
       *  (InitializeSinkImages_()).
       *  If informations about the mapping process have to be aquired without
       *  rectifciation, it can be of use to initialize the objects performing
       *  the mapping. This can be done using
       *  InitializeProjectionMappingObjects_().
       *
       *  \attention This initializers do not order a rectification parameter
       *  calculation via AreRectificationParametersValid_().
       */
      /** @{ */
      /** Initializes lut structure and the result images.**/
      void
      InitializeMapping_();
      void
      InitializeSinkImages_();
      void
      InitializeProjectionMappingObjects_();
      /** @}*/

      /** Value used to override thetaMin result of automatic fov
       * calculation if thetaMinOverride_ is larger.
       **/
      double thetaMinOverride_;

      /** Value used to override thetaMax result of automatic fov
       * calculation if thetaMaxOverride_ is smaller.
       **/
      double thetaMaxOverride_;

      /** Value used to override phiMin result of automatic fov
       * calculation if phiMinOverride_ is larger.
       **/
      double phiMinOverride_;

      /** Value used to override phiMax result of automatic fov
       * calculation if phiMaxOverride_ is smaller.
       **/
      double phiMaxOverride_;

      /** Toggles the use of lookup tables.
       */
      bool useLookUpTables_;
    };

}

#endif

#include <Base/Common/BIASpragmaEnd.hh>