Position.hpp

Go to the documentation of this file.

//==============================================================================
//
//  This file is part of GNSSTk, the ARL:UT GNSS Toolkit.
//
//  The GNSSTk 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 3.0 of the License, or
//  any later version.
//
//  The GNSSTk 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 GNSSTk; if not, write to the Free Software Foundation,
//  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA
//
//  This software was developed by Applied Research Laboratories at the
//  University of Texas at Austin.
//  Copyright 2004-2022, The Board of Regents of The University of Texas System
//
//==============================================================================
 
//==============================================================================
//
//  This software was developed by Applied Research Laboratories at the
//  University of Texas at Austin, under contract to an agency or agencies
//  within the U.S. Department of Defense. The U.S. Government retains all
//  rights to use, duplicate, distribute, disclose, or release this software.
//
//  Pursuant to DoD Directive 523024
//
//  DISTRIBUTION STATEMENT A: This software has been approved for public
//                            release, distribution is unlimited.
//
//==============================================================================
 
#ifndef GNSSTK_POSITION_HPP
#define GNSSTK_POSITION_HPP
 
#include "Exception.hpp"
#include "StringUtils.hpp"
#include "Triple.hpp"
#include "EllipsoidModel.hpp"
#include "RefFrame.hpp"
#include "Xvt.hpp"
#include "Angle.hpp"
#include "gnsstk_export.h"
 
namespace gnsstk
{
      // forward declarations
   class Position;
   double range(const Position& A, const Position& B);
 
 
 
   class Position : public Triple
   {
   public:
         // ----------- Part  1: coordinate systems ---------------------------
         //
      enum CoordinateSystem
      {
         Unknown=0,  
         Geodetic,   
         Geocentric, 
         Cartesian,  
         Spherical   
      };
 
      std::string getSystemName()
         noexcept;
 
         // ----------- Part  2: member functions: tolerance ------------------
         //
      GNSSTK_EXPORT static const double ONE_MM_TOLERANCE;
      GNSSTK_EXPORT static const double ONE_CM_TOLERANCE;
      GNSSTK_EXPORT static const double ONE_UM_TOLERANCE;
 
      GNSSTK_EXPORT 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)
         noexcept;
 
         // ----------- Part  3: member functions: constructors ---------------
         //
      Position()
      noexcept;
 
      Position(const double& a,
               const double& b,
               const double& c,
               CoordinateSystem s = Cartesian,
               const EllipsoidModel *ell = nullptr,
               const RefFrame& frame = RefFrame());
 
      Position(const double ABC[3],
               CoordinateSystem s = Cartesian,
               const EllipsoidModel *ell = nullptr,
               const RefFrame& frame = RefFrame());
 
      Position(const Triple& ABC,
               CoordinateSystem s = Cartesian,
               const EllipsoidModel *ell = nullptr,
               const RefFrame& frame = RefFrame());
 
      Position(const Xvt& xvt)
         noexcept;
 
      ~Position()
      noexcept
      {}
 
         // ----------- Part  4: member functions: arithmetic -----------------
         //
      Position& operator-=(const Position& right)
         noexcept;
 
      Position& operator+=(const Position& right)
         noexcept;
 
      friend Position operator-(const Position& left,
                                const Position& right)
         noexcept;
 
      friend Position operator+(const Position& left,
                                const Position& right)
         noexcept;
 
      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
         noexcept;
 
      bool operator!=(const Position &right) const
         noexcept;
 
         // ----------- Part  6: member functions: coordinate transformations -
         //
      Position& transformTo(CoordinateSystem sys)
         noexcept;
 
      Position& asGeodetic()
         noexcept
      { transformTo(Geodetic); return *this; }
 
      Position& asGeodetic(EllipsoidModel *ell)
      {
         try { setEllipsoidModel(ell); }
         catch(GeometryException& ge) { GNSSTK_RETHROW(ge); }
         transformTo(Geodetic);
         return *this;
      }
 
      Position& asECEF()
         noexcept
      { transformTo(Cartesian); return *this; }
 
 
         // ----------- Part  7: member functions: get ------------------------
         //
         // These routines retrieve coordinate values in all
         // coordinate systems.
         //
 
      const RefFrame& getReferenceFrame() const
         noexcept;
 
      double X() const
         noexcept;
 
      double Y() const
         noexcept;
 
      double Z() const
         noexcept;
 
      double geodeticLatitude() const
         noexcept;
 
      double geocentricLatitude() const
         noexcept;
 
      double theta() const
         noexcept;
 
      double phi() const
         noexcept;
 
      double longitude() const
         noexcept;
 
      double radius() const
         noexcept;
 
      double height() const
         noexcept;
 
      CoordinateSystem getCoordinateSystem() const
         noexcept
      { return system; };
 
      double getGeodeticLatitude() const
         noexcept
      { return geodeticLatitude(); }
 
      double getGeocentricLatitude() const
         noexcept
      { return geocentricLatitude(); }
 
      double getLongitude() const
         noexcept
      { return longitude(); }
 
      double getAltitude() const
         noexcept
      { return height(); }
 
      double getHeight() const
         noexcept
      { return height(); }
 
      double getX() const
         noexcept
      { return X(); }
 
      double getY() const
         noexcept
      { return Y(); }
 
      double getZ() const
         noexcept
      { return Z(); }
 
      double getTheta() const
         noexcept
      { return theta(); }
 
      double getPhi() const
         noexcept
      { return phi(); }
 
      double getRadius() const
         noexcept
      { return radius(); }
 
         // ----------- Part  8: member functions: set ------------------------
         //
      void setReferenceFrame(const RefFrame& frame)
         noexcept;
 
      void setEllipsoidModel(const EllipsoidModel *ell);
 
      Position& setGeodetic(const double lat,
                            const double lon,
                            const double ht,
                            const EllipsoidModel *ell = nullptr);
 
      Position& setGeocentric(const double lat,
                              const double lon,
                              const double rad);
 
      Position& setSpherical(const double theta,
                             const double phi,
                             const double rad);
 
      Position& setECEF(const double X,
                        const double Y,
                        const double Z)
         noexcept;
 
      Position& setECEF(const double XYZ[3])
         noexcept
      { return setECEF(XYZ[0],XYZ[1],XYZ[2]); }
 
      Position& setECEF(const Triple& XYZ)
         noexcept
      { return setECEF(XYZ[0],XYZ[1],XYZ[2]); }
 
         // ----------- Part 9: member functions: setToString, printf ---------
         //
      Position& setToString(const std::string& str,
                            const std::string& fmt);
 
 
         // 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;
 
      std::string printf(const std::string& fmt) const
      { return printf(fmt.c_str()); }
 
      std::string asString() const;
 
         // ----------- Part 10: functions: fundamental conversions -----------
         //
      static void convertSphericalToCartesian(const Triple& tpr,
                                              Triple& xyz)
         noexcept;
 
      static void convertCartesianToSpherical(const Triple& xyz,
                                              Triple& tpr)
         noexcept;
 
 
      static void convertCartesianToGeodetic(const Triple& xyz,
                                             Triple& llh,
                                             const double A,
                                             const double eccSq)
         noexcept;
 
      static void convertGeodeticToCartesian(const Triple& llh,
                                             Triple& xyz,
                                             const double A,
                                             const double eccSq)
         noexcept;
 
 
      static void convertCartesianToGeocentric(const Triple& xyz,
                                               Triple& llr)
         noexcept;
 
      static void convertGeocentricToCartesian(const Triple& llr,
                                               Triple& xyz)
         noexcept;
 
 
      static void convertGeocentricToGeodetic(const Triple& llr,
                                              Triple& geodeticllh,
                                              const double A,
                                              const double eccSq)
         noexcept;
 
      static void convertGeodeticToGeocentric(const Triple& geodeticllh,
                                              Triple& llr,
                                              const double A,
                                              const double eccSq)
         noexcept;
 
         // ----------- 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);
 
      static double radiusEarth(const double geolat,
                                const double A,
                                const double eccSq)
         noexcept;
 
      double radiusEarth() const
         noexcept
      {
         Position p(*this);
         p.transformTo(Position::Geodetic);
         return Position::radiusEarth(p.theArray[0], p.AEarth, p.eccSquared);
      }
 
      double elevation(const Position& Target) const;
 
      double elevationGeodetic(const Position& Target) const;
 
      double azimuth(const Position& Target) const;
 
      double azimuthGeodetic(const Position& Target) const;
 
      Position getIonosphericPiercePoint(const double elev,
                                         const double azim,
                                         const double ionoht) const
         noexcept;
 
      double getCurvMeridian() const
         noexcept;
 
      double getCurvPrimeVertical() const
         noexcept;
 
      Angle getZenithAngle(const Position& target, AngleReduced& delta) const;
 
      static Angle getZenithAngle(const Angle& phi1, const Angle& lambda1,
                                  const Angle& phi2, const Angle& lambda2,
                                  double r1, double r2,
                                  AngleReduced& delta);
 
      Position getRayPerigee(const Position& target) const;
 
      Position getRayPosition(double dist, const Position& target) const;
 
      void copyEllipsoidModelFrom(const Position& src)
      {
         AEarth = src.AEarth;
         eccSquared = src.eccSquared;
      }
 
      double getAEarth() const
      { return AEarth; }
 
         // ----------- Part 12: private functions and member data ------------
         //
   private:
 
      void initialize(const double a,
                      const double b,
                      const double c,
                      CoordinateSystem s = Cartesian,
                      const EllipsoidModel *ell = nullptr,
                      const RefFrame& frame = RefFrame());
 
         /* 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;
 
      RefFrame refFrame;
 
   };   // end class Position
 
 
}  // namespace gnsstk
 
#endif   // GNSSTK_POSITION_HPP