ProjectionParametersBase.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_ProjectionParametersBase_hh__
#define __BIAS_ProjectionParametersBase_hh__

#include <bias_config.h>

#include <math.h>

#include <Geometry/Pose.hh>

#include <Base/Common/BIASpragmaStart.hh>

#include <Base/Common/CompareFloatingPoint.hh>
#include <Base/Math/Vector3.hh>
#include <Base/Math/Matrix3x4.hh>
#include <Base/Math/Matrix4x4.hh>
#include <Base/Geometry/HomgPoint2D.hh>
#include <Base/Geometry/Quaternion.hh>
#include <Base/Debug/Exception.hh>
#include <Geometry/PMatrix.hh>
#include <MathAlgo/UnscentedTransform.hh>

#include <Base/Debug/Debug.hh>
#ifdef BIAS_HAVE_XML2
#  include <Base/Common/XMLBase.hh>
#endif

#include <Geometry/RMatrix.hh>


namespace BIAS {

  /** @class PixelIterator
      @brief Can be used to run along the image border.
      @author koeser 09/2007 */
  class PixelIterator {
  public:
    /** If using BorderPixel methods these are the coordinates of the pixel.
        In the image, (0,0) is center of upper left, and (w-1, h-1) is the
        center of lower right pixel.
        If using EdgePosition methods this is (-0.5, -0.5) for the upper left
        image corner and (w-0.5, h-0.5) for the lower right image corner.
    */
    double x,y;
    PixelIterator(): x(-1.0), y(-1.0) {}
    PixelIterator(const double& xx, const double& yy): x(xx), y(yy) {}
  };

  /** @class ProjectionParametersBase
   *  @test tested with TestProjectionParametersBase.cpp
      @brief Camera parameters which define the mapping between rays in the
      camera coordinate system and pixels in the image as well as camera pose.
      @author koeser/evers/streckel
  */
  class BIASGeometry_EXPORT ProjectionParametersBase
    : protected UnscentedTransform
#ifdef BIAS_HAVE_XML2
    , public XMLBase
#endif
  {
  public:
    
    ProjectionParametersBase(const unsigned int width = 0,
                             const unsigned int height = 0);

    virtual ProjectionParametersBase& operator=(
      const ProjectionParametersBase& p)
    {
      Pose_ = p.Pose_;
      width_= p.width_;
      height_= p.height_;
      principalX_= p.principalX_;
      principalY_= p.principalY_;
      aspectratio_= p.aspectratio_;
      QValid_ = p.QValid_;
      CValid_ = p.CValid_;
      identifier_ = p.identifier_;
      videoSourceType_ = p.videoSourceType_;
      return *this;
    }

    virtual ~ProjectionParametersBase();


    /** @brief call this to start a run at the outer boundary of an image.
     *
     *  You get the first boundary position in it, e.g. (0,0) for a perspective
     *  image. Feed this into GetNextBorderPixel to get the next position.
     *  @author koeser 09/2007 */
    virtual void GetFirstBorderPixel(PixelIterator& it);

    /** @brief call this iteratively to run at the outer boundary of an image.
     *
     *  All returned coordinates must have valid local rays in the camera
     *  coordinate system (e.g. in fisheye cams, we run at the fov circle) and
     *  must be in the image. Two subsequent coordinates must not be more
     *  distant than 1 pixel.
     *  @param it must be initialized by GetFirstBorderPixel
     *  @return false if the returned position closes the loop around the image
     *  @author koeser 09/2007 */
    virtual bool GetNextBorderPixel(PixelIterator& it);

    /** @brief call this to start a run at the outer boundary of an image.
     *
     *  You get the first edge position i.e. (-0.5, -0.5) for a perspective
     *  image. Feed this into GetNextBorderPixel to get the next position.
     *  @author bartczak 06/2009 */
    virtual void GetFirstEdgePosition(PixelIterator& it);

    /** @brief call this iteratively to run at the outer edge of an image.
     *
     *  Like the GetNextBorderPixel() method, however runs along the
     *  outer rim of an image, i.e. the coordinate range (-0.5, -0.5) and (W-0.5, H-0.5).
     *  The positions returned are the upper left corner of the pixels.
     *  These are at the same time the upper right corners of the neighboring pixel.
     *
     *  @param it must be initialized by GetFirstBorderPixel
     *  @return false if the returned position closes the loop around the image
     *  @author  bartczak 06/2009 */

    virtual bool GetNextEdgePosition(PixelIterator& it);

    /** Determines the maximal and minimal viewing range in means of
     *  spherical coordinates. The spherical coordinates are calculated
     *  relatively to the passed coordinate frame.
     *  The method is using the class SphericalCoordinates, see also the
     *  documentation there in order to understand the meaning of the
     *  sphericalReferenceFrame.
     *
     * \attention in order to make sense the sphericalReferenceFrame
     *  must have the same origin as the ProjectionParameters.
     *
     * \param sphericalReferenceFrame reference frame for the calculation of
     * spherical coordinates belonging to optical rays, must be defined in the
     * same coordinate frame like the local frame of the ProjectionParameters.
     *
     * \returns minPhi phi angle from (-M_PI, M_PI] with smallest value
     *          within viewing range.
     * \returns maxPhi phi angle from (-M_PI, M_PI] with largest value
     *          within viewing range.
     * \returns centerPhi phi angle from (-M_PI, M_PI] belonging to the
     *          optical ray passing through the image center. This angle
     *          allows to determine which direction the camera was facing
     *          in the sphericalReferenceFrame.
     * \returns minTheta theta angle from [0, M_PI] with smallest value
     *          within viewing range.
     * \returns maxTheta theta angle from [0, M_PI] with largest value
     *          within viewing range.
     *
     * \author bartczak 10/2007
     **/
    virtual int
      GetSphericalViewingRange(const CoordinateTransform3D& sphericalReferenceFrame,
                               double& minPhi, double& maxPhi, double& centerPhi,
                               double& minTheta, double& maxTheta);

    /** Delivers the assumed minimal angular distance between two optical rays
     * belonging to integer image coordinates within the FoV.
     * \author bartczak 10/2007
     **/
    virtual int GetMinimalAngularSamplingStep(double& minAngleStep)
    {
      BIASERR("To be implemented in specialized child class!");
      return -1;
    }

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

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

    /** Checks if 3D point projects into specified image and returns
     *  belonging 2D image point.
     *  @param X assumes homogenized point!
     *  @author bartczak
     */
    virtual bool
      DoesPointProjectIntoImage(const HomgPoint3D& X, HomgPoint2D& x,
                                bool IgnoreDistortion = false) const;
    
    /** Checks if 3D point projects into specified image and returns
     *  belonging 2D image point.
     *  @param localX assumes homogenized point!
     *  @author bartczak
     */
    virtual bool
      DoesPointProjectIntoImageLocal(const Vector3<double>& localX,
                                     HomgPoint2D& x,
                                     bool IgnoreDistortion = false) const
    {
      BIASERR("To be implemented in specialized child class!");
      return false;
    }


    /** @brief calculates the projection of a point in the world coordinate
        system to a pixel in the image plane of the camera
        !warning! the function my return an invalid point (0,0,0) in certain
        cases (3d point) behind camera or 3d point to close to camera center
        @author woelk 05/2006 */
    virtual inline HomgPoint2D Project(const HomgPoint3D &X,
                                       bool IgnoreDistortion = false) const {
      Vector3<double> x;
      GetExternals().Mult(X, x);
      return ProjectLocal(x, IgnoreDistortion);
    }

    /** @brief calculates the projection of a point in the world 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 valid 2d point is
        computed, *particularily* when the 3d point is behind the camera
        or when the resulting 2d point is at infinity.
        returns negative, when 3d point and camera center coincide
        @author woelk 05/2006 */
    virtual inline int Project(const HomgPoint3D &X, HomgPoint2D &p2d,
                               bool IgnoreDistortion = false) const {
      Vector3<double> x;
      GetExternals().Mult(X, x);
      return ProjectLocal(x, p2d, IgnoreDistortion);
    }

    /** @brief calculates the projection of a point in the local camera
        coordinate system  to a pixel in the image plane of the camera

        !warning! function return an invalid 2d point (0,0,0) in certain cases

        In the simplest case perspective pinhole projection x = K * point
        where point is transformed of X using  point = (R^T | -R^T C) X */
    virtual HomgPoint2D
      ProjectLocal(const Vector3<double>& point,
                   bool IgnoreDistortion = false) const = 0;

    /** @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 = 0;

    /**
     * @brief Calculates the view ray, which belongs to the given position
     *        on the image plane, in local coordinates.
     * @param pos position on the image plane
     * @param origin origin of the ray
     * @param direction will be the direction of the ray
     * @param ignoreDistortion optional parameter which specifies
     *                         if potential distortions are ignored
     *                         (is false by default)
     * @author Koeser, Evers, Streckel, Husvogt
     *
     * In case of a perspective projection, the ray goes through the optical
     * center of the projection ((0, 0, 0) in local coordinates) and the
     * given position on the image plane.
     */
    virtual void
          UnProjectLocal(const HomgPoint2D& pos, Vector3<double>& origin,
                         Vector3<double>& direction,
                         bool ignoreDistortion = false) const = 0;

    /*virtual Vector3<double>
      UnProjectLocal(const HomgPoint2D& pos,
                     bool IgnoreDistortion = false) const = 0;*/

    /** @brief map points from image onto unit diameter image plane in 3D.
     */
    virtual HomgPoint3D
      UnProjectToImagePlane(const HomgPoint2D& pos,
                            const double& depth = 1.0,
                            bool IgnoreDistortion = false) const = 0;

    /** @brief unprojects the covariance matrices to K=Identity camera

        This uses the unscented transform to propagate covariance. Use a faster
        or better specialization in derived class if you want.
        @author koeser 06/2006 */
    virtual Matrix3x3<double>
      UnProjectCovLocal(const HomgPoint2D& pos, const Matrix3x3<double>& cov2D,
                        bool IgnoreDistortion = false, bool Normalize = false);

    /**
     * @brief Calculates the view ray, which belongs to the given position
     *        on the image plane, in global coordinates.
     * @param pos position on the image plane
     * @param origin origin of the ray
     * @param direction will be the direction of the ray
     * @param ignoreDistortion optional parameter which specifies
     *                         if potential distortions are ignored
     *                         (is false by default)
     * @author Woelk, Husvogt
     * @date May 2006, March 2012
     *
     * In case of a perspective projection, the ray goes through the optical
     * center of the projection and the given position on the image plane.
     */
    virtual inline void UnProjectToRay(
      const HomgPoint2D& pos, Vector3<double>& origin,
      Vector3<double>& direction, bool ignoreDistortion=false) const
    {
      Vector3<double> point, dir;
      UnProjectLocal(pos, point, dir, ignoreDistortion);
      RMatrix R = GetR();
      R.Mult(dir, direction);
      R.Mult(point, origin);
      origin += GetC();
    }

    /**
     * @brief Calculates the view ray, which belongs to the given position
     *        on the image plane, in global coordinates.
     * @param pos position on the image plane
     * @param direction will be the direction of the ray
     * @param ignoreDistortion optional parameter which specifies
     *                         if potential distortions are ignored
     *                         (is false by default)
     * @author Woelk, Husvogt
     * @date May 2006, March 2012
     *
     * In case of a perspective projection, the ray goes through the optical
     * center of the projection and the given position on the image plane.
     */
    virtual inline void UnProjectToRay(
      const HomgPoint2D& pos, Vector3<double>& direction, bool ignoreDistortion=false) const
    {
      Vector3<double> point, dir;
      UnProjectLocal(pos, point, dir, ignoreDistortion);
      RMatrix R = GetR();
      R.Mult(dir, direction);
    }

    /**
     * @brief Calculates the view ray, which belongs to the given position
     *        on the image plane, using the given projection.
     * @param pos position on the image plane
     * @param origin origin of the ray
     * @param direction will be the direction of the ray
     * @param proj reference to the projection which is used
     * @param ignoreDistortion optional parameter which specifies
     *                         if potential distortions are ignored
     *                         (is false by default)
     * @author Woelk, Husvogt
     * @date May 2006, March 2012
     *
     * In case of a perspective projection, the ray goes through the optical
     * center of the given projection and the given position on the
     * image plane.
     */
    virtual inline void UnProjectToRay(
      const HomgPoint2D& pos, Vector3<double>& origin,
      Vector3<double>& direction, const ProjectionParametersBase &proj,
      bool ignoreDistortion=false) const
    {
        Vector3<double> point, dir;
        proj.UnProjectLocal(pos, point, dir, ignoreDistortion);
        RMatrix R = GetR();
        R.Mult(dir, direction);
        R.Mult(point, origin);
        origin += GetC();
    }

    /** @brief calculates a 3D point in
        the global (not the rig) coordinate system, which
        belongs to the image position pos with distance depth to the
        camera center.
        @return: (0,0,0,0) is returned on failure */
    virtual HomgPoint3D UnProjectToPoint(const HomgPoint2D& pos, double depth,
                                 bool IgnoreDistortion = false) const;

    virtual HomgPoint3D UnProjectToPoint(
      const HomgPoint2D& pos, const double depth,
      const ProjectionParametersBase &proj,
      bool IgnoreDistortion = false) const;

    /** @brief calculates a 3D point in
        the local camera coordinate system, which
        belongs to the image position pos in cam with distance depth to the
        camera center cam.
        @author koeser  */
    virtual Vector3<double>
      UnProjectToPointLocal(const HomgPoint2D& pos, const double& depth,
                            bool IgnoreDistortion = false) const;

    /** Interface defintion for lens distortion function, implemented by
        derived classes */
    virtual bool Distort(BIAS::HomgPoint2D& point2d) const = 0;

    /** Interface defintion for lens undistortion function, implemented by
        derived classes */
    virtual bool Undistort(BIAS::HomgPoint2D& point2d) const = 0;


    /** @brief Get warp (local magnification/shear/...) when going from the
     *  real image to ideal image with focal length = 1.
     *
     *  When an image is undistorted to an ideal perspective camera with
     *  K=id, the region around each pixel must be warped. For perspective
     *  cameras without radial distortion this is the undoing (inverse) of
     *  the upper 2x2 part of the KMatrix (simply a rescale of coordinates).
     *  If radial distortion is present, the local warp depends on the image
     *  position. Same for most other camera models. This matrix is closely
     *  related to the absolute local image resolution.
     *
     *  Instead of going to the w=1 (homogenized) ideal image, we can as well
     *  go to a tangent image. This can be steered by the parameter
     *  homogenized (if false, we use normalized mode).
     *
     *  @author koeser 06/2008
     */
    virtual int GetUnProjectionJacobian(const HomgPoint2D& x,
                                        Matrix2x2<double>& Jac,
                                        const bool homogenized = true) const;

    /**
     * @brief Returns true if the camera represented by this
     *        ProjectionParametersBase is left of the given one.
     *
     * Computes the baseline vector and rotates it so that this cam would
     * have zero rotation. This cam is left of the given one if the x component
     * of the transformed baseline is non-negative.
     *
     * Note that the orientation of the given camere is not considered, only
     * its position.
     *
     * @param ppb
     *        the parameters of the cam to compare this to
     *
     * @author rwulff
     * @date   09/2011
     */
    bool IsLeftOf(const ProjectionParametersBase& ppb) const;

    // ---- Getter methods  -------------------------------------------

    /** @brief Get projection center. */
    virtual BIAS::Vector3<double> GetC() const 
    { 
      if(!CValid_) {
        BIASWARN("Projection is not valid");
        BEXCEPTION("ProjectionParametersBase::GetC(): Extrinsics are invalid.");
      }   
      return Pose_.GetC();
    }

    /** @brief Get orientation as unit quaternion. */
    virtual BIAS::Quaternion<double> GetQ() const
    {
     if(!QValid_ ) {
        BIASWARN("Projection is not valid");    
        BEXCEPTION("ProjectionParametersBase::GetQ(): Extrinsics are invalid.");
      } 
      return Pose_.GetQ();
    }

    /** @brief Return pose as 7 vector (first projection center C, then
        unit quaternion Q representing orientation). */
    virtual BIAS::Vector<double> GetCQ() const
    {
      //if(!QValid_ || !CValid_) BIASWARN("Projection is not valid");
      BIAS::Vector<double> CQ(7);
      const BIAS::Vector3<double> C = Pose_.GetC();
      const BIAS::Quaternion<double> Q = Pose_.GetQ();
      CQ[0] = C[0]; CQ[1] = C[1]; CQ[2] = C[2];
      CQ[3] = Q[0]; CQ[4] = Q[1]; CQ[5] = Q[2]; CQ[6] = Q[3];
      return CQ;
    }

    /** @brief Get orientation as rotation matrix R. */
    virtual BIAS::RMatrix GetR() const;

    /** @brief Return pose covariance as 7x7 matrix with respect to C, Q. */
    virtual BIAS::Matrix<POSE_TYPE> GetCov() const {
      return Pose_.GetCovariance();
    }

    /** @brief Return complete pose object. */
    virtual const BIAS::Pose& GetPose() const
    {
      //if(!QValid_ || !CValid_) {
      //  BIASWARN("Projection is not valid");
      //  //BEXCEPTION("ProjectionParametersBase::GetPose(): "
      //  //           "Extrinsics are invalid.");
      //  //BIASABORT;
      //}
      return Pose_;
    }

    /** @brief Return copy of pose parametrization object. */
    virtual inline BIAS::PoseParametrization GetPoseParametrization() const 
    { 
      //if(!QValid_ || !CValid_) {
      //  BIASWARN("Projection is not valid");
      //  //BEXCEPTION("ProjectionParametersBase::GetPoseParametrization(): "
      //  //           "Extrinsics are invalid.");
      //  //BIASABORT;        
      //}
      return Pose_.GetPoseParameters();
    }

    /** @brief Set pose from pose parametrization. */
    virtual inline void SetPoseParametrization(const BIAS::PoseParametrization& pp)
    { Pose_.Set(pp);  QValid_ = CValid_ = true; }

    /** @brief Return cached 3x4 representation of external matrix [R|C] */
    virtual BIAS::Matrix3x4<double> GetExternals() const 
    { 
      //if(!QValid_ || !CValid_) {
      //  BIASWARN("Projection is not valid");
      //  //BEXCEPTION("ProjectionParametersBase::GetExternals(): "
      //  //           "Extrinsics are invalid.");
      //  //BIASABORT;
      //}
      return Pose_.GetMatrix3x4();
    }

    /** @brief Obtain image dimensions. */
    virtual inline int GetImageSize(unsigned int& Width, unsigned int& Height) const {
      Width  = width_;
      Height = height_;
      return 0;
    }

    /**
     * @brief Returns the image width.
     *
     * @return the image width
     */
    virtual inline
    const unsigned int& GetImageWidth() const
    {
      return width_;
    }

    /**
     * @brief Returns the image height.
     *
     * @return the image height
     */
    virtual inline
    const unsigned int& GetImageHeight() const
    {
      return height_;
    }

    virtual inline std::string GetIdentifier() const {
      return identifier_;
    }

    virtual inline std::string GetVideoSourceType() const {
      return videoSourceType_;
    }

    /** @brief Return aspectratio (i.e. cellsizeX / cellsizeY). */
    virtual inline double GetAspectratio() const {
      return aspectratio_;
    }

    /** @brief Get principal point (in pixels relative to top left corner). */
    virtual inline int GetPrincipal(double& PrincipalX, double& PrincipalY) const {
      PrincipalX = principalX_;
      PrincipalY = principalY_;
      return 0;
    }

    // ---- Setter methods  ------------------------------------------------

    /** @brief Set CCD aspect ratio (i.e. cellsizeX / cellsizeY).
        @author streckel */
    virtual inline void SetAspectratio(const double AspectRatio) {
      aspectratio_ = AspectRatio;
    }

    /** @brief Set principal point (in pixels relative to top left corner).
        @author streckel */
    virtual inline void SetPrincipal(const double x, const double y) {
      principalX_ = x;
      principalY_ = y;
    }

    /** @brief Set image dimensions (in pixels). */
    virtual inline void SetImageSize(const unsigned int w,
                                     const unsigned int h) {
      width_ = w;
      height_ = h;
    }

    /** @brief Set the identification string */
    virtual inline void SetIdentifier(std::string name ){
      identifier_ = name;
    }

    /** @brief Set the camera source type */
    virtual void SetVideoSourceType(const std::string &name);

    /** @brief Adapt internal parameters to resampled image 
        @param ratio 2.0 = downsample by 2, 0.5 = upsample by 2.
                @param offset Offset for principal point (applied before down/upsampling!)
        \attention Delivers only correct results if ratio is chosen
        to rescale image size to integral image dimensions
        in both directions. Image size is rounded!
    */
    virtual void Rescale(double ratio, const double offset = 0.0);

    /**
     * @brief adapt internal parameters to new image size
     * @param width and height are the new images sizes
     *  \attention Delivers only correct results if ratio is chosen
     *   to rescale image size to integral image dimensions in both directions.
     */
    virtual void Rescale(unsigned int width, unsigned int height);

    /** @brief Covariant virtual copy constructor used in #BIAS::Projection. */
    virtual ProjectionParametersBase* Clone() const = 0;

    /** @brief Set orientation from unit quaternion Q. */
    virtual void SetQ(const BIAS::Quaternion<double>& Q)
    { Pose_.SetQ(Q); QValid_ = true; }

    /** @brief Set projection center. */
    virtual void SetC(const BIAS::Vector3<double>& C)
    { Pose_.SetC(C); CValid_ = true; }

    /** @brief Set pose from unit quaternion Q and projection center C. */
    virtual void SetQC(const BIAS::Quaternion<double>& Q,
                       const BIAS::Vector3<double>& C)
    { Pose_.Set(Q,C); QValid_ = CValid_ = true; }

    /** @brief Set pose from pose object. */
    virtual void SetPose(const BIAS::Pose pose)
    { Pose_ = pose; QValid_ = CValid_ = true; }

    /** @brief Set orientation from rotation matrix R. */
    virtual void SetR(const BIAS::RMatrix& R) {
      Quaternion<double> Q;
      R.GetQuaternion(Q);
      Pose_.SetQ(Q);
      QValid_ = true;
    }

    /** @brief Set pose covariance matrix with respect to C, Q. */
    virtual void SetCov(const Matrix<POSE_TYPE>& Cov)
    { Pose_.SetCovariance(Cov); }

    /** @brief Check of current projection center is valid. */
    virtual inline bool CValid() const { return CValid_; }

    /** @brief Check if current orientation is valid. */
    virtual inline bool QValid() const { return QValid_; }

    /** @brief Check if current pose is valid. */
    virtual inline bool PoseValid() const
    { return (CValid_ && QValid_); }

    /** @brief Invalidate currently set pose. */
    virtual inline void InvalidatePose()
    { CValid_ = QValid_ = false; }

    /** @brief Validate currently set pose. */
    virtual void ValidatePose() {
      QValid_= true;
      CValid_ = true;
    }

    /** @brief Returns a fake KMatrix for the camera.

        @attention Stolen from PPSpherical, since this is a general issue.
        THERE MAY BE PROBLEMS FOR OTHER THAN FISHEYE CAMERAS (UNTESTED)
        If this implementation is not correct for your derived projection
        parameters you have to reimplement it in the derived class.

        The FoV of the KMatrix is specified by maxangle (PI*80/180 for 160deg)
        or the max angle, if this is <160deg.
        @param resolution The resolution parameter influences the
        Resolution of the perspective image that is represented by the camera.
        0 - The perspective image has the same size as the this image
        1 - The perspective image has the same resolution as this
        image in the center (highest resolution)
        2 - The perspective image has the same resolution as this
        image near the border (lowest resolution)
        @param imgsize returns the image size
        @param maxangle maximum theta in rad, e.g. (PI*80/180 for 160deg fov)
        @author streckel 05/2006 (moved here by koeser)
    */
    virtual BIAS::KMatrix GetFakeKMatrix(double& imgsize, int resolution = 0,
                                         const double& maxangle = 1.4) const;
    virtual BIAS::KMatrix GetFakeKMatrix(int resolution = 0,
                                         const double& maxangle = 1.4) const;

    /** @brief Returns difference between two projections like |C1-C2|.
        This function can be used to calculate inter-camera distance e.g.
        for ordering purposes.
        @author koeser 03/2006
    */
    virtual double ViewDifference(const ProjectionParametersBase*) const;

#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

    /** Worker function for Unscented Transform.
        @author koeser
    */
    virtual int Transform_(const Vector<double>& src,
                           Vector<double>& dst) const;

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

    /** @brief Looks at given point, similar to gluLookAt
        @param eye Eye coordinate
        @param center 3D point to look at
        @param up Up vector of the camera
        @return true, if everything is fine - false, otherwise
    */
    const inline bool LookAt(const Vector3<double> &eye, const Vector3<double> &center, const Vector3<double> &up){
      return Pose_.LookAt(eye, center, up);
    };

    /** @brief Looks at given point, similar to gluLookAt
        @param center 3D point to look at
        @param up Up vector of the camera
        @return true, if everythings fine - false, otherwise
    */
    const inline bool LookAt(const Vector3<double> &center, const Vector3<double> &up){
      return Pose_.LookAt(GetC(), center, up);
    };

    /** @brief Looks at given point, similar to gluLookAt
        @param eye Eye coordinate
        @param center 3D point to look at
        @param up Up vector of the camera
        @return true, if everything is fine - false, otherwise
    */
    const inline bool LookAtGL(const Vector3<double> &eye, const Vector3<double> &center, const Vector3<double> &up){
      return Pose_.LookAtGL(eye, center, up);
    };

    /** @brief Looks at given point, similar to gluLookAt
        @param center 3D point to look at
        @param up Up vector of the camera
        @return true, if everythings fine - false, otherwise
    */
    const inline bool LookAtGL(const Vector3<double> &center, const Vector3<double> &up){
      return Pose_.LookAtGL(GetC(), center, up);
    };

  protected:

    /// pose
    Pose Pose_;
    /// validity flag for orientation and position
    bool QValid_, CValid_;

    /// width of image in pixels
    unsigned int width_;
    /// height of image in pixels
    unsigned int height_;

    /// principal point in pixel coordinates (one for all zoom settings)
    double principalX_, principalY_;

    /// aspect ratio of the camera CCD
    double aspectratio_;

    /// unscented transform worker variables
    bool ustTransformIntoImage_;
    bool ustIgnoreDistortion_;
    bool ustNormalize_;
    /** Multifunctional identifier. */
    std::string identifier_;
    std::string videoSourceType_;
  };

  inline std::ostream& operator<<(std::ostream &os,
                                  const ProjectionParametersBase& p)
  {
    // os<<"Type: "<<typeid(p).name()<<std::endl;
    os<<"Identifier: "<<p.GetIdentifier()<<std::endl;
    if (p.CValid_)  os <<"C:"<<p.GetC()<<std::endl;
    else os<<"C: invalid"<<std::endl;
    if (p.QValid_)  os <<"Q: "<<p.GetQ()<<std::endl;
    else os<<"Q: invalid"<<std::endl;
    os<<"ImageSize:  "<<p.width_<<" x "<<p.height_<<std::endl;
    os<<"Principal:  "<<p.principalX_<<" x "<<p.principalY_<<std::endl;
    os<<"Aspectratio:"<<p.GetAspectratio()<<std::endl;
    //os<<"Cov:        "<<p.GetCov()<<endl;
    return os;
  }
} // end namespace

#include <Base/Common/BIASpragmaEnd.hh>

#endif