ProjectionParametersSpherical.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_ProjectionParametersSpherical_hh__
#define __BIAS_ProjectionParametersSpherical_hh__
#include "bias_config.h"

#include <Base/Common/BIASpragmaStart.hh>
#include <Geometry/ProjectionParametersBase.hh>
#include <Geometry/ProjectionParametersPerspective.hh>
#include <MathAlgo/Interpolator.hh>
#include <Base/ImageUtils/BresenhamCircle.hh>

namespace BIAS {

 /** @class ProjectionParametersSpherical
  *  @ingroup g_geometry
     @brief camera parameters which define the mapping between rays in the
     camera coordinate system and pixels in the image as well as external pose
     @author koeser/evers/streckel
 */
  class BIASGeometry_EXPORT ProjectionParametersSpherical:
    public  ProjectionParametersBase {
  public:

    ProjectionParametersSpherical(const unsigned int width = 0,
                                  const unsigned int height = 0)
      : ProjectionParametersBase(width, height)
    {
      radius_=0;
      MaxCamAngle_=0;
      interpolatorInit_ = false;
    };

    ProjectionParametersSpherical(const double radius,
                                  const double maxAngle,
                                  const unsigned int width,
                                  const unsigned int height)
      : ProjectionParametersBase(width, height)
    {
      radius_=radius;
      MaxCamAngle_=maxAngle;
      interpolatorInit_ = false;
    }

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

    ProjectionParametersSpherical&
    operator=(const ProjectionParametersSpherical & P)
    {
      ProjectionParametersBase::operator=(P);
      radius_ = P.radius_;
      MaxCamAngle_ = P.MaxCamAngle_;
      interpolatorAngle_ = P.interpolatorAngle_;
      interpolatorAngleBack_ = P.interpolatorAngleBack_;
      interpolatorInit_ = P.interpolatorInit_;
      acCoeff_ = P.acCoeff_;
      return *this;
    }

    virtual ~ProjectionParametersSpherical() {}

    /** @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.
     *  Special implmentation here, because we need to run around the FOV
     *  circle. NOT YET IMPLEMENTED, PLEASE DO !
     */
    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. NOT YET IMPLEMENTED, PLEASE DO !
     *  @param it must be initialized by GetFirstBorderPixel
     *  @return false if the returned position closes the loop around the image
     */
    virtual bool GetNextBorderPixel(PixelIterator& it);


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

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

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



    bool DoesPointProjectIntoImageLocal(const BIAS::Vector3<double>& localX,
                                        HomgPoint2D& x,
                                        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 is indicated
        by a return value of (0, 0, 0). 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.*/
    virtual HomgPoint2D ProjectLocal(const Vector3<double>& point,
                                     bool IgnoreDistortion = false) const {
      HomgPoint2D retVal_hom2D;
      ProjectionParametersSpherical::ProjectLocal(point, retVal_hom2D, IgnoreDistortion);
      return retVal_hom2D;
    }

    /** @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 is indicated
        by a return value of zero. 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 spherical image plane with radius 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
        e.g. (0,0,1) means optical axis
    */
    virtual void
    UnProjectLocal(const HomgPoint2D& pos, Vector3<double>& origin,
              Vector3<double>& direction, bool IgnoreDistortion = false) const;

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

    /** @brief Return radius of spherical image in pixels. */
    inline double GetRadius() const {
      return radius_;
    }

    /** @brief Set radius of spherical image in pixels. */
    inline void SetRadius(const double r) {
      radius_ = r;
    }

    /** @brief Get maximal camera angle (in rad), i.e. azimuth angle of rays
               corresponding to the outer rim of the image. */
    inline double GetMaxCamAngle() const {
      return MaxCamAngle_;
    }

    /** @brief Set maximal camera angle (in rad), i.e. azimuth angle of rays
               corresponding to the outer rim of the image.
        @param[in] maxCamAngle New maximal camera angle to set (in rad)
        @attention If undistortion polynomial is set, it will be recalculated
                   with default sampling. Use RecalculateUndistortion instead
                   if you want to reset undistortion and max. camera angle
                   by yourself.
    */
    void SetMaxCamAngle(const double maxCamAngle);

    /** @brief Recalculate undistortion polynomial for new maximal camera angle.
        @param[in] maxCamAngle New maximal camera angle to set (in rad)
        @attention If new max. camera angle is larger than former, the
                   undistortion polynomial is extrapolated linearly beyond the
                   former range which may result in strange behaviour!
    */
    void RecalculateUndistortion(const double maxCamAngle);

    /** @brief Set undistortion polynomial from corresponding undistorted and
               distorted azimuth angles (in rad) and image radius (in pixels).
        @param[in] undistAngles Vector of undistorted azimuth angles (in rad)
        @param[in] distAngles   Vector of corresponding distorted angles
        @param[in] radius       Radius of spherical image to set (in pixels)
    */
    int SetUndistortion(const std::vector<double>& undistAngles,
                        const std::vector<double>& distAngles,
                        const double radius);

    /** @deprecated Use vector interface for #InitAngleCorrFromPoly! */
    inline int InitAngleCorrFromPoly(const double maxCamAngle, const double acCoeff0,
                                     const double acCoeff1, const double acCoeff2,
                                     const double acCoeff3, const double acCoeff4)
    {
      std::vector<double> coefficients;
      coefficients.reserve(5);
      coefficients.push_back(acCoeff0);
      coefficients.push_back(acCoeff1);
      coefficients.push_back(acCoeff2);
      coefficients.push_back(acCoeff3);
      coefficients.push_back(acCoeff4);
      return InitAngleCorrFromPoly(maxCamAngle, coefficients);
    }

    /** @brief Set undistortion polynomial from from polynomial coefficients
               of undistortion (mapping radius to z coordinate) or distortion
               (mapping theta to radius) function.
        @param[in] maxCamAngle Maximal azimuth angle corresponding to the
                               outer rim of the spherical image
        @param[in] coefficients Vector of polynomial coefficients to
                                estimate the undistortion polynomial from
        @param[in] mapsRadiusToZ Specifies if the given polynomial coefficients
                                 describe the undistortion (mapping radius to
                                 z cooordinate), or distortion (mapping theta
                                 to radius).
    */
    int InitAngleCorrFromPoly(const double maxCamAngle,
                              const std::vector<double>& coefficients,
                              const bool mapsRadiusToZ = true);

    /** @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) {
      ProjectionParametersBase::Rescale(ratio, offset);
      radius_ /= ratio;
    }

    virtual void Rescale(unsigned int width, unsigned int height){
      unsigned int oldwidth = width_;
      ProjectionParametersBase::Rescale(width, height);
      radius_ /= ((double)oldwidth/(double)width_);
    }

    virtual double ViewDifference(const ProjectionParametersBase* pPPB) const;

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

        Uses MaxAngle_ to limit maxangle, then calls PPB::GetFakeK.
        The FoV of the KMatrix is specified by maxangle (PI*80/180 for 160deg)
        or the max fisheye 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 fisheye image
        1 - The perspective image has the same resolution as the fisheye
        image in the center (highest resolution)
        2 - The perspective image has the same resolution as the fisheye
        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
    */
    virtual BIAS::KMatrix GetFakeKMatrix(double& imgsize, int resolution=0,
                                         const double& maxangle = 1.4) const;

    /** @brief stupid reimplementation since this class does not inherit
        function from base class (gcc) */
    virtual BIAS::KMatrix GetFakeKMatrix(int resolution=0,
                                         const double& maxangle = 1.4) const {
      return ProjectionParametersBase::GetFakeKMatrix(resolution, maxangle);
    }

    /** Calculates perspective camera with specified viewing angle and
     * optical axis aligned with the optical ray corresponding to viewCenter
     * in spherical camera.
     * @param viewCenter pixel position in spherical image that is the
     * center of the perspective cutout.
     * @param perspHalfViewingAngle half field of view of the cutout in Degree
     * @pp returning cutout parameters
     * \returns false if perspective cut out could not be calculated.
     * @author streckel 08/2006
     */
    bool GetPerspectiveCutOutParameters(const BIAS::HomgPoint2D& viewCenter,
                                        const double perspHalfViewingAngleDEG,
                                        ProjectionParametersPerspective& pp)
      const;

    /** @brief calculates a 3D point in
        a local camera coordinate system specified by camSystem, which
        belongs to the image position pos in cam with distance depth to the
        camera center cam. Overload to habe return value (0,0,0)
        for undefined or out of image radius pixels.
        @author streckel  */
    virtual Vector3<double> UnProjectToPointLocal(const HomgPoint2D& pos,
                                                  const double& depth,
                                                  bool IgnoreDistortion = false) const;


    /** @brief Estimates undistortion polynomial mapping z coordinates to
               radius according to Scaramuzza's Matlab toolbox.

        Scaramuzza's undistortion polynomial is a function z(radius) which
        typically has a local extremum at radius = 0 and therefore can not
        have a linear monomial.
        @author koeser 04/2007
     */
    int EstimateUndistortionPolynomial(std::vector<double>& coefficients,
                                       const unsigned int degree = 4,
                                       bool LinearMonomialIsZero = true);

    /** @brief Estimates distortion polynomial mapping angle theta to radius
               according to Scaramuzza's Matlab toolbox.

        Scaramuzza's distortion polynomial is a function radius(theta) which
        is usually close to linear for fisheye cameras and SHOULD therefore
        have a linear monomial.
        @author koeser 04/2007
    */
    int EstimateDistortionPolynomial(std::vector<double>& coefficients,
                                     const unsigned int degree = 4,
                                     bool LinearMonomialIsZero = false);

    /** @brief Returns polynomial coefficients of angle correction polynomial
               (aka undistortion polynomial) mapping distorted to undistorted
               azimuth angles.
        @param[out] coeffs Returns coefficients of undistortion polynomial
    */
    inline void GetAngleCorrCoefficients(std::vector<double> &coeffs) const {
      coeffs.clear();
      for (unsigned i = 0; i < acCoeff_.size(); i++)
        coeffs.push_back(acCoeff_[i]);
    }

    /** @brief Returns samples for undistorted and distorted angles from
               which the angle correction polynomial (aka undistortion
               polynomial) has been interpolated.
        @param[out] undistAngles Returns knot points of distortion interpolator,
                                 i.e. samples of undistorted azimuth angles
        @param[out] distAngles   Returns control points of distortion interpolator,
                                 i.e. samples of distorted azimuth angles
    */
    inline void GetAngleCorr(std::vector<double>& undistAngles,
                             std::vector<double>& distAngles) const {
      interpolatorAngle_.GetKnotPoints(undistAngles);
      interpolatorAngle_.GetControlPoints(distAngles);
    }

    /** @brief Returns samples for distorted and unddistorted angles from
               which the angleback correction polynomial (aka distortion
               polynomial) has been interpolated.
        @param[out] distAngles Returns knot points of undistortion interpolator,
                                 i.e. samples of distorted azimuth angles
        @param[out] undistAngles   Returns control points of undistortion interpolator,
                                 i.e. samples of undistorted azimuth angles
    */
    inline void GetAngleCorrBack(std::vector<double>& distAngles,
                                 std::vector<double>& undistAngles) const{
      interpolatorAngleBack_.GetKnotPoints(distAngles);
      interpolatorAngleBack_.GetControlPoints(undistAngles);
    }
    
    
#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

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


    // long names to avoid global symbol clashes
    std::vector<double> myvaluesPolynomialWithoutLinearMonomialError;
    std::vector<double> mylocationsPolynomialWithoutLinearMonomialError;

  protected:

    /** \brief helper function for EstimateUndistortionPolynomial */
    int FitPolynomialWithoutLinearMonomial_(const unsigned int degree,
                                            const std::vector<double>& x,
                                            const std::vector<double>& y,
                                            std::vector<double> &coefficients);

    /** @brief Transforms a coordinate pair of image coordinates x, y in the
        uncalibrated spherical image, to a calibrated pair of polar coordinates
        phi, theta.
        @author Birger Streckel */
    void TransfCoordImage2Sphere_ (const HomgPoint2D& Source,
                                 double &theta, double &phi) const;

    /** @brief Transforms a coordinate pair of image coordinates x, y in the
        calibrated spherical image, to a calibrated pair of polar coordinates
        phi, theta.
        @author Birger Streckel */
    void TransfCoordCalibImage2Sphere_ (const HomgPoint2D& Source,
                                      double &theta, double &phi) const;

    /** @brief Transforms a calibrated pair of polar coordinates phi, theta
        to a coordinate pair of image coordinates x, y in the uncalibrated
        spherical image.
        @author Birger Streckel */
    void TransfCoordSphere2Image_ (double theta, double phi,
                                 HomgPoint2D &Source) const;

    /** @brief Transforms a calibrated pair of polar coordinates phi, theta
        to a coordinate pair of image coordinates x, y in the uncalibrated
        spherical image.
        @author Birger Streckel */
    int TransfCoordRotateSphere2Image_ (double theta, double phi,
                                        double viewCenterX,
                                        double viewCenterY,
                                        HomgPoint2D &Source) const;

    /** @brief Transforms a calibrated pair of polar coordinates phi, theta
        to a coordinate pair of image coordinates x, y in an equidistant
        spherical image.
        @author Birger Streckel */
    void TransfCoordSphere2CalibImage_ (double theta, double phi,
                                        HomgPoint2D &Source) const;

    /** @brief theta and phi are periodic in 2*M_PI, if they are out of a
        suitable range, try to find best equivalent angle by adding 2*l*M_PI
        @return 0 on success, <0 indicates that at least one angle is invalid
        @author koeser 10/2004 */
    void EnforceNormalRange_(double& theta, double& phi) const;



    // image radius if image is spherical
    double radius_;

    // Maximum image angle of the fisheye camera
    double MaxCamAngle_;
    // these are the polynom coefficients
    std::vector<double>  acCoeff_;

    // Spline interpolators y(x) for image distortion
    // x : angle in an undistorted image
    // y : distorted angle
    // Example: x = pi, y = 0.8*pi means that the image at angle pi is
    // distorted with factor 0.8
    Interpolator interpolatorAngle_;

    // back transformation
    Interpolator interpolatorAngleBack_;

    // determine if interpolator has been initialized
    bool interpolatorInit_;

    //bresenham-circle for running allong fov area
    BresenhamCircle fovCircle_;
    //projects pixels outside the image onto the image border
    void ProjectOutsidePositions_(int& posX, int& posY);
    

  };

  /////////////// inline code ///////////////////////
  inline std::ostream& operator<<(std::ostream &os,
                                  const ProjectionParametersSpherical& p)
  {
    os<<"ProjectionParametersSpherical:"<<std::endl;
    os<<"Principal: "<<p.principalX_<< " " <<p.principalY_<<std::endl;
    os<<"Radius: "<<p.radius_<<std::endl;
    os<<"MaxCamAngle: "<<p.MaxCamAngle_<<std::endl;
    os<<"Coefficients:"<<std::endl;
    std::vector<double> controlpoints, knotpoints;
    p.interpolatorAngle_.GetControlPoints(controlpoints);
    p.interpolatorAngle_.GetKnotPoints(knotpoints);
    for (unsigned int i=0; i<controlpoints.size(); i++) {
      os<< knotpoints[i]<<" "<< controlpoints[i]<<std::endl;
    }
    return os;
  }

} // end namespace


#include <Base/Common/BIASpragmaEnd.hh>

#endif