ProjectionParametersGreatCircles.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_ProjectionParametersGreatCircles_hh__
#define __BIAS_ProjectionParametersGreatCircles_hh__
#include "bias_config.h"

#include <Base/Common/BIASpragmaStart.hh>
#include <Geometry/ProjectionParametersBase.hh>
#include <Base/Geometry/KMatrix.hh>
#include <Geometry/PMatrix.hh>
#include <Base/Common/CompareFloatingPoint.hh>
#include <iostream>

namespace BIAS {

  /** \class ProjectionParametersGreatCircles
   *  \ingroup g_geometry
   *  \brief spherical camera that samples along big circles containig the H
   *  vector. Sampling is done along spherical coordinates e.g.
   *  along phi and theta.
   *  Theta is mapped to the x-component and phi is mapped to the
   *  y-component of the corresponding image.
   *
   *  Projection was originaly desigened for the purpose of
   *  image rectification.
   *
   *  \author bartczak
   */
  class BIASGeometry_EXPORT ProjectionParametersGreatCircles
    : public  ProjectionParametersBase {
  public:

    ProjectionParametersGreatCircles(const unsigned int width = 0,
                                     const unsigned int height = 0)
      : ProjectionParametersBase(width, height), focallengthTheta_(1.0)
    {
      // set default internals
      SetInternals(-M_PI, M_PI, 0, M_PI, width, height);
    }

    ProjectionParametersGreatCircles(const ProjectionParametersGreatCircles& P)
    {
      *this = P;
    };

    ProjectionParametersGreatCircles&
    operator=(const ProjectionParametersGreatCircles& P);

    virtual ~ProjectionParametersGreatCircles(){};

    virtual const bool DoIntrinsicsDiffer(const ProjectionParametersBase* p)
      const;


    bool DoesPointProjectIntoImageLocal(const Vector3<double>& localX,
                                        HomgPoint2D& x,
                                        bool IgnoreDistortion = false) const;



    /** Determines angle intervalls for the camera from viewing cone.
     * The viewing cone is defined through the optical ray passing through the
     * given worlPoint functioning as cone axis. The halfAngleRange defines
     * the opening angle of the cone. The calculated parameters are chosen
     * so that the whole viewing cone projects into the image. Yet no minimal
     * solution is sought!! The resulting ranges lie within
     *  [thetaMin, thetaMax] in [0, M_PI] and
     *  [phiMin, phiMax] in [-M_PI, M_PI]!
     *
     * \author bartczak 08/2007
     **/
    bool GetAngleInterval(const HomgPoint3D& worldPoint,
                          const double halfAngleRange,
                          double& thetaMin, double& thetaMax,
                          double& phiMin, double& phiMax) const;


    virtual bool Distort(BIAS::HomgPoint2D& point2d) const;

    virtual bool Undistort(BIAS::HomgPoint2D& point2d) const;


    /** Sets viewing volume of camera using GetAngleInterval().
     * width_ and height_ are kept!
     */
    bool SetAngleInterval(const HomgPoint3D& worldPoint,
                          const double& halfAngleRange);

    /** @brief calculates the projection of a point
        in the camera coordinate system
        to a pixel in the image plane of the camera
        with lens distortion
        In the simplest case perspective pinhole projection x = K * y
        where y is the projection of X using  y = (R^T | -R^T C) X
    */
    virtual HomgPoint2D ProjectLocal(const Vector3<double>& point,
                                     bool IgnoreDistortion = false) const;

    /** @brief calculates the projection of a point in the local camera
        coordinate system to a pixel in the image plane of the camera. The
        only case when this function may not compute the 2d point is when the
        camera center and the 3d point coincide. This case must be indicated
        by a negative return value. In all other cases, a 2d point must be
        computed, *particularily* when the 3d point is behind the camera
        or when the resulting 2d point is at infinity.

        In the simplest case perspective pinhole projection x = K * point
        where point is transformed of X using  point = (R^T | -R^T C) X
        @author woelk 08/2008 (c) www.vision-n.de */
    virtual int ProjectLocal(const Vector3<double>& point, HomgPoint2D &p2d,
                             bool IgnoreDistortion = false) const;

    /** @brief map points from image onto unit diameter image plane in 3D.
     * Chosen is the image plane with distance of one from the image center.
     */
    HomgPoint3D UnProjectToImagePlane(const HomgPoint2D& pos,
                                      const double& depth = 1.0,
                                      bool IgnoreDistortion = false) const;


    /** @brief calculates the viewing ray from the camera center (in the
        camera coordinate system) which belongs to the image position pos
        with lens distortion
        e.g. (0,0,1) means optical axis
    */
    virtual void UnProjectLocal(const HomgPoint2D& pos, Vector3<double>& pointOnRay,
                                Vector3<double>& direction, bool ignoreDistortion = false)const;


    /** @brief covariant virtual copy constructor for use in Projection */
    virtual ProjectionParametersGreatCircles* Clone() const {
      return new ProjectionParametersGreatCircles(*this);
    }

    /** \attention off set is being ignored - just for interface purposes
     *
     */
    virtual void Rescale(double ratio, const double offset = 0.0);

    virtual void Rescale(unsigned int width, unsigned int height);

#ifdef BIAS_HAVE_XML2
    /** @brief specialization of XML block name function */
    virtual int XMLGetClassName(std::string& TopLevelTag,
                                double& Version) const;

    /** @brief specialization of XML write function */
    virtual int XMLOut(const xmlNodePtr Node, XMLIO& XMLObject) const;

    /** @brief specialization of XML read function */
    virtual int XMLIn(const xmlNodePtr Node, XMLIO& XMLObject);
#endif

    /** Calculate spherical angles from local 3D point.
     * \param euc coordinates in the local camera coordinate frame.
     * \returns phi angle around the H axis, zero lies at direction of A
     *       and value range is  [-pi, pi].
     * \returns theta angle within plane containing H relative to \b -H,
     *      value range is [0,pi]
     *
     * \returns true if a direction could be calculated, else false.
     * \author bartczak 08/2007
     **/
    static bool LocalEuclideanCamCoordinates2SphericalAngles(
      const BIAS::Vector3<double>& euc, double& phi, double& theta);

    /// deprecated version
    static bool LocalEuclidianCamCoordinates2SphericalAngles(
      const BIAS::Vector3<double>& euc, double& phi, double& theta) {
      return LocalEuclideanCamCoordinates2SphericalAngles(euc, phi, theta);
    };


    /** Calculate euclidean ray direction in local camera frame from
     *  angles
     * \returns ray ray direction in the local camera coordinate frame.
     * \param phi angle around the H axis, zero lies at direction of A
     *       and value range is  [-pi, pi].
     * \params theta angle within plane containing H relative to \b -H,
     *      value range is [0,pi]
     *
     * \returns true if given angles allow for unique ray reconstruction.
     * \author bartczak 08/2007
     **/
    static bool SphericalAngles2LocalEuclideanRay(
      const double phi, const double theta, BIAS::Vector3<double>& ray);

    /// deprecated version
     static bool SphericalAngles2LocalEuclidianRay(
       const double phi, const double theta, BIAS::Vector3<double>& ray) {
       return SphericalAngles2LocalEuclideanRay(phi, theta, ray);
     };

    /** Calculates image coordinates from local angle vectors.
     * See LocalEuclideanCamCoordinates2SphericalAngles().
     * \author bartczak 08/2007
     **/
    void Angle2Image(double phi, double theta,
                     BIAS::HomgPoint2D& imgPoint) const;

    /** Calculates local angle vectors from image coordinate.
     * See LocalEuclideanCamCoordinates2SphericalAngles().
     * \author bartczak 08/2007
     **/
    void Image2Angle(const BIAS::HomgPoint2D& imgPoint,
                     double& phi, double& theta) const;

    /** Calculates and sets internal camera parameters.
     *
     * Valid ranges for the parameters are
     * [minPhi, maxPhi] in [-M_PI, M_PI] and
     * [minTheta, maxTheta] in [0,M_PI].
     *
     * The behaviour of the camera outside this ranges is undefined.
     *
     * Of course all modulo M_PI ranges are valid but it is a nasty thing
     * to work with. Learn how this camera works, before assuming that it is
     * easy to handle arbitrary ranges for this parameters.
     *
     * \author bartczak 08/2007
     **/
    void SetInternals(const double minPhi, const double maxPhi,
                      const double minTheta, const double maxTheta,
                      const unsigned int imgWidth, const unsigned int imgHeight);

    double GetFocallengthTheta();

    friend std::ostream&
      operator<<(std::ostream &os, const ProjectionParametersGreatCircles& p);


  protected:
    /** scale from angles to image*/
    double focallengthTheta_;


  };

  inline std::ostream& operator<<(std::ostream &os,
                                  const ProjectionParametersGreatCircles& p)
  {     
    os << "ProjectionParametersGreatCircles:" << std::endl;       
    os<<"pixel2AngleScale: theta = "<<p.focallengthTheta_;
    os <<", phi = "<<p.aspectratio_*p.focallengthTheta_<<std::endl;
    return os;
  }



} // end namespace


#include <Base/Common/BIASpragmaEnd.hh>

#endif