Position.hpp

Go to the documentation of this file.

#pragma ident "$Id: Position.hpp 3143 2012-06-19 16:19:50Z snelsen $"



#ifndef GPSTK_POSITION_HPP
#define GPSTK_POSITION_HPP

//============================================================================
//
//  This file is part of GPSTk, the GPS Toolkit.
//
//  The GPSTk 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
//  any later version.
//
//  The GPSTk 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 GPSTk; if not, write to the Free Software Foundation,
//  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA
//  
//  Copyright 2004, The University of Texas at Austin
//
//============================================================================

#include "Exception.hpp"
#include "StringUtils.hpp"
#include "Triple.hpp"
#include "EllipsoidModel.hpp"
#include "ReferenceFrame.hpp"
#include "Xvt.hpp"

namespace gpstk
{

      // forward declarations
   class Position;
   double range(const Position& A, const Position& B) throw(GeometryException);
   
   class Position : public Triple
   {
   public:
      // ----------- Part  1: coordinate systems --------------------------------
      //
      enum CoordinateSystem
      {
         Unknown=0,  
         Geodetic,   
         Geocentric, 
         Cartesian,  
         Spherical   
      };

      std::string getSystemName()
         throw();

      // ----------- Part  2: member functions: tolerance -----------------------
      //
      static const double ONE_MM_TOLERANCE;
      static const double ONE_CM_TOLERANCE;
      static const double ONE_UM_TOLERANCE;
      
      static double POSITION_TOLERANCE;

      static double setPositionTolerance(const double tol)
         { POSITION_TOLERANCE = tol;  return POSITION_TOLERANCE; }

      static double getPositionTolerance()
         { return POSITION_TOLERANCE; }
   
      Position& setTolerance(const double tol)
         throw();

      // ----------- Part  3: member functions: constructors --------------------
      //
      Position()
         throw();

      Position(const double& a,
               const double& b,
               const double& c,
               CoordinateSystem s = Cartesian,
               EllipsoidModel *ell = NULL,
               ReferenceFrame frame = ReferenceFrame::Unknown)
         throw(GeometryException);

      Position(const double ABC[3],
               CoordinateSystem s = Cartesian,
               EllipsoidModel *ell = NULL,
               ReferenceFrame frame = ReferenceFrame::Unknown)
         throw(GeometryException);

      Position(const Triple& ABC,
               CoordinateSystem s = Cartesian,
               EllipsoidModel *ell = NULL,
               ReferenceFrame frame = ReferenceFrame::Unknown)
         throw(GeometryException);

      Position(const Xvt& xvt)
         throw();

      ~Position()
         throw()
         {}

      // ----------- Part  4: member functions: arithmetic ----------------------
      //
      Position& operator-=(const Position& right)
         throw();

      Position& operator+=(const Position& right)
         throw();

      friend Position operator-(const Position& left,
                                      const Position& right)
         throw();

      friend Position operator+(const Position& left,
                                      const Position& right)
         throw();

      friend Position operator*(const double& scale,
                                const Position& right)
         {
            Position tmp(right);
            tmp.theArray *= scale;
            return tmp;
         }

      friend Position operator*(const Position& left,
                                const double& scale)
         {
            return operator*(scale, left);
         }

      friend Position operator*(const int& scale,
                                const Position& right)
         {
            return operator*(double(scale), right);
         }

      friend Position operator*(const Position& left,
                                const int& scale)
         {
            return operator*(double(scale), left);
         }

      // ----------- Part  5: member functions: comparisons ---------------------
      //
      bool operator==(const Position &right) const
         throw();

      bool operator!=(const Position &right) const
         throw();

      // ----------- Part  6: member functions: coordinate transformations ------
      //
      Position transformTo(CoordinateSystem sys)
         throw();
  
      Position asGeodetic()
         throw()
      { transformTo(Geodetic); return *this; }

      Position asGeodetic(EllipsoidModel *ell)
         throw(GeometryException)
      {
         try { setEllipsoidModel(ell); }
         catch(GeometryException& ge) { GPSTK_RETHROW(ge); }
         transformTo(Geodetic);
         return *this;
      }

      Position asECEF()
         throw()
      { transformTo(Cartesian); return *this; }


      // ----------- Part  7: member functions: get -----------------------------
      // 
      // These routines retrieve coordinate values in all coordinate systems.
      //

      const ReferenceFrame& getReferenceFrame() const
         throw();
      
      double X() const
         throw();

      double Y() const
         throw();

      double Z() const
         throw();

      double geodeticLatitude() const
         throw();

      double geocentricLatitude() const
         throw();

      double theta() const
         throw();

      double phi() const
         throw();

      double longitude() const
         throw();

      double radius() const
         throw();

      double height() const
         throw();

      CoordinateSystem getCoordinateSystem() const
         throw() 
      { return system; };

      double getGeodeticLatitude() const
         throw()
      { return geodeticLatitude(); }

      double getGeocentricLatitude() const
         throw()
      { return geocentricLatitude(); }

      double getLongitude() const
         throw()
      { return longitude(); }

      double getAltitude() const
         throw()
      { return height(); }

      double getHeight() const
         throw()
      { return height(); }

      double getX() const
         throw()
      { return X(); }

      double getY() const
         throw()
      { return Y(); }

      double getZ() const
         throw()
      { return Z(); }

      double getTheta() const
         throw()
      { return theta(); }

      double getPhi() const
         throw()
      { return phi(); }

      double getRadius() const
         throw()
      { return radius(); }

      // ----------- Part  8: member functions: set -----------------------------
      //
      void setReferenceFrame(const ReferenceFrame& frame)
         throw();

      void setEllipsoidModel(const EllipsoidModel *ell)
         throw(GeometryException);

      Position& setGeodetic(const double lat,
                            const double lon,
                            const double ht,
                            const EllipsoidModel *ell = NULL)
         throw(GeometryException);

      Position& setGeocentric(const double lat,
                              const double lon,
                              const double rad)
         throw(GeometryException);

      Position& setSpherical(const double theta,
                             const double phi,
                             const double rad)
         throw(GeometryException);

      Position& setECEF(const double X,
                        const double Y,
                        const double Z)
         throw();

      Position& setECEF(const double XYZ[3])
         throw()
      { return setECEF(XYZ[0],XYZ[1],XYZ[2]); }

      Position& setECEF(const Triple& XYZ)
         throw()
      { return setECEF(XYZ[0],XYZ[1],XYZ[2]); }

      // ----------- Part 9: member functions: setToString, printf -------------
      //
      Position& setToString(const std::string& str,
                            const std::string& fmt)
         throw(GeometryException,
               StringUtils::StringException);


         // if you can see this, ignore the \'s below, as they are for
         // the nasty html-ifying of doxygen.  Browsers try to
         // interpret the % and they get all messed up.
      std::string printf(const char *fmt) const
         throw(StringUtils::StringException);

      std::string printf(const std::string& fmt) const
         throw(StringUtils::StringException) 
      { return printf(fmt.c_str()); }

      std::string asString() const
         throw(StringUtils::StringException);

      // ----------- Part 10: functions: fundamental conversions ---------------
      // 
      static void convertSphericalToCartesian(const Triple& tpr,
                                              Triple& xyz)
         throw();

      static void convertCartesianToSpherical(const Triple& xyz,
                                              Triple& tpr)
         throw();


      static void convertCartesianToGeodetic(const Triple& xyz,
                                             Triple& llh,
                                             const double A,
                                             const double eccSq)
         throw();

      static void convertGeodeticToCartesian(const Triple& llh,
                                             Triple& xyz,
                                             const double A,
                                             const double eccSq)
         throw();


      static void convertCartesianToGeocentric(const Triple& xyz,
                                               Triple& llr)
         throw();

      static void convertGeocentricToCartesian(const Triple& llr,
                                               Triple& xyz)
         throw();


      static void convertGeocentricToGeodetic(const Triple& llr,
                                              Triple& geodeticllh,
                                              const double A,
                                              const double eccSq)
         throw();

      static void convertGeodeticToGeocentric(const Triple& geodeticllh,
                                              Triple& llr,
                                              const double A,
                                              const double eccSq)
         throw();

      // ----------- Part 11: operator<< and other useful functions -------------
      //
      friend std::ostream& operator<<(std::ostream& s,
                                      const Position& p);

      friend double range(const Position& A,
                          const Position& B)
         throw(GeometryException);

      static double radiusEarth(const double geolat,
                                const double A,
                                const double eccSq)
         throw();

      double radiusEarth() const
         throw()
      {
         Position p(*this);
         p.transformTo(Position::Geodetic);
         return Position::radiusEarth(p.theArray[0], p.AEarth, p.eccSquared);
      }

      double elevation(const Position& Target) const
         throw(GeometryException);

      double elevationGeodetic(const Position& Target) const
         throw(GeometryException);

      double azimuth(const Position& Target) const
         throw(GeometryException);

      double azimuthGeodetic(const Position& Target) const
         throw(GeometryException);

      Position getIonosphericPiercePoint(const double elev,
                                         const double azim,
                                         const double ionoht) const
         throw();

      double getCurvMeridian() const
         throw();

      double getCurvPrimeVertical() const
         throw();

      // ----------- Part 12: private functions and member data -----------------
      //
   private:

      void initialize(const double a,
                     const double b,
                     const double c,
                     CoordinateSystem s = Cartesian,
                     EllipsoidModel *ell = NULL,
                     ReferenceFrame frame = ReferenceFrame::Unknown)
         throw(GeometryException);

         /* Values of the coordinates, defined for each system as follows;
         *    Cartesian  : X,Y,Z in meters
         *    Geocentric : Latitude(degrees N), Longitude(degrees E),
         *                    Radius (meters)
         *    Geodetic   : Latitude(degrees N), Longitude(degrees E),
         *                    Height above ellipsoid (meters)
         *    Spherical  : theta (degrees) - angle from the z axis
         *                 phi (degrees) - angle in xy plane from x axis toward
         *                                     y axis (same as longitude)
         *                 radius (meters?) - distance from origin
         */
      // use std::valarray<double> theArray;  -- inherit from Triple

      double AEarth;

      double eccSquared;

      CoordinateSystem system;

      double tolerance;
      
      ReferenceFrame refFrame;

   };   // end class Position


}  // namespace gpstk

#endif   // GPSTK_POSITION_HPP

---