SphericalCoordinates.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 __SphericalCoordinates_HH__
#define __SphericalCoordinates_HH__

#include <Geometry/CoordinateTransform3D.hh>
#include <Base/Geometry/HomgPoint3D.hh>


  namespace BIAS {
    /** \brief Transformation between affine and spherical coordinates.
     * \ingroup g_geometry
     *
     * Class is able to transform euclidean coordinates into a spherical 
     * coordinates and vice versa. Moreover a CoordinateTransform3D is applied
     * to the passed coordinates. The CoordinateTransform3D stored internaly
     * can be understood as the pose of the spherical frame.
     * Meaning that passing euclidean coordinates of a point will first 
     * transform this coordinates into the local frame defined by the "pose"
     * and then map them to spherical coordinates.
     *
     * The angle references are chosen classically within the local
     * coordinate frame defined by affineReferenceFrame_: the e_z axis is the 
     *  reference for the angle Theta and the e_x axis the reference for the 
     * angle phi in the e_x and e_y plane. 
     * 
     * Convention: In general valid angle ranges lie within (-M_PI, M_PI]
     * 
     * 
     * \author bartczak 10/2007
     **/
    class SphericalCoordinates {
    public:
      /** Sets the "local" coordinate frame of the spherical coordinates. 
       *  
       *  GlobalToLocal is applied when mapping to spherical coordinates. 
       *  LocalToGlobal is applied when unmapping from spherical coordinates.
       **/
      void SetAffineBase(const CoordinateTransform3D& newAffineBase);
      const CoordinateTransform3D& GetAffineBase() const;
      
      /** Method calculates spherical coordinates, hereby phi will lie in the 
       * range (-M_PI, M_PI] while theta lies in [0, M_PI].
       *
       * \attention If rho drops below 1e-12 all returned values will be zero.
       *
       **/
      void GetSphericalCoordinatesFullPhi(const HomgPoint3D& point, 
                                          double& rho, 
                                          double& phi, double& theta) const;

       /** Calculates the Euclidean ray belonging to the passed angles in the
       * world coordinate frame. Uses the affineReferenceFrame_ information
       * to calculate the ray coordinates in the global frame.
       */
      void GetCartesianRayFromFullPhi(const double& phi, const double& theta,
        HomgPoint3D& ray) const;
      
      
    protected:
      /** Defines the reference frame (see discussion in
       *  CoordinateTransform3D).  GlobalToLocal is applied when
       *  GlobalToLocal is applied when mapping to spherical coordinates. 
       *  LocalToGlobal is applied when unmapping from spherical coordinates.
       **/
      CoordinateTransform3D affineReferenceFrame_;
    };
  }


#endif