Rename Topographic to Topocentric. Add brief comments to all classes.

libsgp4/CoordGeodetic.h

@@ -8,7 +8,9 @@
 #include <iomanip>
 
 /**
- * Stores a geodetic position
+ * @brief Stores a geodetic location (latitude, longitude, altitude).
+ *
+ * Internally the values are stored in radians and kilometres.
  */
 struct CoordGeodetic
 {

libsgp4/CoordTopocentric.cpp

@@ -0,0 +1 @@
+#include "CoordTopocentric.h"

libsgp4/CoordTopocentric.h

@@ -1,5 +1,5 @@
-#ifndef COORDTOPOGRAPHIC_H_
+#ifndef COORDTOPOCENTRIC_H_
-#define COORDTOPOGRAPHIC_H_
+#define COORDTOPOCENTRIC_H_
 
 #include "Util.h"
 
@@ -8,15 +8,19 @@
 #include <iomanip>
 
 /**
- * Stores a topographic position
+ * @brief Stores a topocentric location (azimuth, elevation, range and range
+ * rate).
+ *
+ * Azimuth and elevation are stored in radians. Range in kilometres. Range
+ * rate in kilometres/second.
  */
-struct CoordTopographic
+struct CoordTopocentric
 {
 public:
     /**
      * Default constructor
      */
-    CoordTopographic()
+    CoordTopocentric()
         : azimuth(0.0), 
         elevation(0.0),
         range(0.0),
@@ -26,20 +30,20 @@ public:
 
     /**
      * Constructor
-     * @param[in] arg_azimuth azimuth in radians
+     * @param[in] az azimuth in radians
-     * @param[in] arg_elevation elevation in radians
+     * @param[in] el elevation in radians
-     * @param[in] arg_range range in kilometers
+     * @param[in] rnge range in kilometers
-     * @param[in] arg_range_rate range rate in kilometers per second
+     * @param[in] rnge_rate range rate in kilometers per second
      */
-    CoordTopographic(
+    CoordTopocentric(
-            double arg_azimuth,
+            double az,
-            double arg_elevation,
+            double el,
-            double arg_range,
+            double rnge,
-            double arg_range_rate)
+            double rnge_rate)
-        : azimuth(arg_azimuth),
+        : azimuth(az),
-        elevation(arg_elevation),
+        elevation(el),
-        range(arg_range),
+        range(rnge),
-        range_rate(arg_range_rate)
+        range_rate(rnge_rate)
     {
     }
 
@@ -47,7 +51,7 @@ public:
      * Copy constructor
      * @param[in] topo object to copy from
      */
-    CoordTopographic(const CoordTopographic& topo)
+    CoordTopocentric(const CoordTopocentric& topo)
     {
         azimuth = topo.azimuth;
         elevation = topo.elevation;
@@ -58,7 +62,7 @@ public:
     /**
      * Destructor
      */
-    virtual ~CoordTopographic()
+    virtual ~CoordTopocentric()
     {
     }
 
@@ -66,7 +70,7 @@ public:
      * Assignment operator
      * @param[in] topo object to copy from
      */
-    CoordTopographic& operator=(const CoordTopographic& topo)
+    CoordTopocentric& operator=(const CoordTopocentric& topo)
     {
         if (this != &topo)
         {
@@ -83,7 +87,7 @@ public:
      * @param[in] topo value to check
      * @returns whether the object is equal
      */
-    bool operator==(const CoordTopographic& topo) const
+    bool operator==(const CoordTopocentric& topo) const
     {
         return IsEqual(topo);
     }
@@ -93,7 +97,7 @@ public:
      * @param[in] topo the object to compare with
      * @returns whether the object is not equal
      */    
-    bool operator !=(const CoordTopographic& topo) const
+    bool operator !=(const CoordTopocentric& topo) const
     {
         return !IsEqual(topo);
     }
@@ -123,7 +127,7 @@ public:
     double range_rate;
 
 private:
-    bool IsEqual(const CoordTopographic& topo) const
+    bool IsEqual(const CoordTopocentric& topo) const
     {
         bool equal = false;
         if (azimuth == topo.azimuth &&
@@ -138,7 +142,7 @@ private:
 };
 
 
-inline std::ostream& operator<<(std::ostream& strm, const CoordTopographic& t)
+inline std::ostream& operator<<(std::ostream& strm, const CoordTopocentric& t)
 {
     return strm << t.ToString();
 }

libsgp4/CoordTopographic.cpp

@@ -1 +0,0 @@
-#include "CoordTopographic.h"

libsgp4/DateTime.h

@@ -21,6 +21,9 @@ namespace
     };
 }
 
+/**
+ * @brief Represents an instance in time.
+ */
 class DateTime
 {
 public:

libsgp4/DecayedException.h

@@ -6,6 +6,9 @@
 
 #include <exception>
 
+/**
+ * @brief The exception that the SGP4 class throws when a satellite decays.
+ */
 class DecayedException : public std::exception
 {
 public:

libsgp4/Eci.h

@@ -6,8 +6,7 @@
 #include "DateTime.h"
 
 /**
- * A class store to store an Earth-centered inertial position.
+ * @brief Stores an Earth-centered inertial position for a particular time.
- * This is only valid for the date specified.
  */
 class Eci
 {

libsgp4/Makefile.am

@@ -1,7 +1,7 @@
 lib_LIBRARIES = libsgp4.a
 libsgp4_a_SOURCES = \
 			CoordGeodetic.cpp \
-			CoordTopographic.cpp \
+			CoordTopocentric.cpp \
 			DateTime.cpp \
 			Eci.cpp \
 			Globals.cpp \
@@ -18,7 +18,7 @@ include_HEADERS = CoordGeodetic.h \
 			SatelliteException.h \
 			TleException.h \
 			Vector.h \
-			CoordTopographic.h \
+			CoordTopocentric.h \
 			Globals.h \
 			Observer.h \
 			SGP4.h \

libsgp4/Observer.cpp

@@ -1,11 +1,11 @@
 #include "Observer.h"
 
-#include "CoordTopographic.h"
+#include "CoordTopocentric.h"
 
 /*
  * calculate lookangle between the observer and the passed in Eci object
  */
-CoordTopographic Observer::GetLookAngle(const Eci &eci)
+CoordTopocentric Observer::GetLookAngle(const Eci &eci)
 {
     /*
      * update the observers Eci to match the time of the Eci passed in
@@ -58,7 +58,7 @@ CoordTopographic Observer::GetLookAngle(const Eci &eci)
      * range in km
      * range rate in km/s
      */
-    return CoordTopographic(az,
+    return CoordTopocentric(az,
             el,
             range.w,
             rate);

libsgp4/Observer.h

@@ -5,8 +5,11 @@
 #include "Eci.h"
 
 class DateTime;
-class CoordTopographic;
+class CoordTopocentric;
 
+/**
+ * @brief Stores an observers location in Eci coordinates.
+ */
 class Observer
 {
 public:
@@ -65,7 +68,7 @@ public:
      * @param[in] eci the object to find the look angle to
      * @returns the lookup angle
      */
-    CoordTopographic GetLookAngle(const Eci &eci);
+    CoordTopocentric GetLookAngle(const Eci &eci);
 
 private:
     /**

libsgp4/OrbitalElements.h

@@ -6,6 +6,9 @@
 
 class Tle;
 
+/**
+ * @brief The extracted orbital elements used by the SGP4 propagator.
+ */
 class OrbitalElements
 {
 public:
@@ -112,7 +115,6 @@ public:
     }
 
 private:
-
     double mean_anomoly_;
     double ascending_node_;
     double argument_perigee_;

libsgp4/SGP4.h

@@ -13,6 +13,9 @@
  * This documents the SGP4 tracking library.
  */
 
+/**
+ * @brief The simplified perturbations model 4 propagater.
+ */
 class SGP4
 {
 public:
@@ -30,6 +33,84 @@ public:
     Eci FindPosition(double tsince) const;
     Eci FindPosition(const DateTime& date) const;
 
+private:
+    void Initialise();
+    Eci FindPositionSDP4(const double tsince) const;
+    Eci FindPositionSGP4(double tsince) const;
+    Eci CalculateFinalPositionVelocity(
+            const double tsince,
+            const double e,
+            const double a,
+            const double omega,
+            const double xl,
+            const double xnode,
+            const double xincl,
+            const double xlcof,
+            const double aycof,
+            const double x3thm1,
+            const double x1mth2,
+            const double x7thm1,
+            const double cosio,
+            const double sinio) const;
+    void DeepSpaceInitialise(
+            const double eosq,
+            const double sinio,
+            const double cosio,
+            const double betao,
+            const double theta2,
+            const double betao2,
+            const double xmdot,
+            const double omgdot,
+            const double xnodot);
+    void DeepSpaceCalculateLunarSolarTerms(
+            const double tsince,
+            double& pe,
+            double& pinc,
+            double& pl,
+            double& pgh,
+            double& ph) const;
+    void DeepSpacePeriodics(
+            const double tsince,
+            double& em,
+            double& xinc,
+            double& omgasm,
+            double& xnodes,
+            double& xll) const;
+    void DeepSpaceSecular(
+            const double tsince,
+            double& xll,
+            double& omgasm,
+            double& xnodes,
+            double& em,
+            double& xinc,
+            double& xn) const;
+    void DeepSpaceCalcDotTerms(struct IntegratorValues& values) const;
+    void DeepSpaceIntegrator(
+            const double delt,
+            const double step2,
+            const struct IntegratorValues& values) const;
+    void Reset();
+
+    /*
+     * flags
+     */
+    bool use_simple_model_;
+    bool use_deep_space_;
+
+    /*
+     * the constants used
+     */
+    struct CommonConstants common_consts_;
+    struct NearSpaceConstants nearspace_consts_;
+    struct DeepSpaceConstants deepspace_consts_;
+    struct IntegratorConstants integrator_consts_;
+    mutable struct IntegratorParams integrator_params_;
+
+    /*
+     * the orbit data
+     */
+    OrbitalElements elements_;
+
     struct CommonConstants
     {
         double cosio;
@@ -169,84 +250,6 @@ public:
          */
         struct IntegratorValues values_t;
     };
-
-private:
-    void Initialise();
-    Eci FindPositionSDP4(const double tsince) const;
-    Eci FindPositionSGP4(double tsince) const;
-    Eci CalculateFinalPositionVelocity(
-            const double tsince,
-            const double e,
-            const double a,
-            const double omega,
-            const double xl,
-            const double xnode,
-            const double xincl,
-            const double xlcof,
-            const double aycof,
-            const double x3thm1,
-            const double x1mth2,
-            const double x7thm1,
-            const double cosio,
-            const double sinio) const;
-    void DeepSpaceInitialise(
-            const double eosq,
-            const double sinio,
-            const double cosio,
-            const double betao,
-            const double theta2,
-            const double betao2,
-            const double xmdot,
-            const double omgdot,
-            const double xnodot);
-    void DeepSpaceCalculateLunarSolarTerms(
-            const double tsince,
-            double& pe,
-            double& pinc,
-            double& pl,
-            double& pgh,
-            double& ph) const;
-    void DeepSpacePeriodics(
-            const double tsince,
-            double& em,
-            double& xinc,
-            double& omgasm,
-            double& xnodes,
-            double& xll) const;
-    void DeepSpaceSecular(
-            const double tsince,
-            double& xll,
-            double& omgasm,
-            double& xnodes,
-            double& em,
-            double& xinc,
-            double& xn) const;
-    void DeepSpaceCalcDotTerms(struct IntegratorValues& values) const;
-    void DeepSpaceIntegrator(
-            const double delt,
-            const double step2,
-            const struct IntegratorValues& values) const;
-    void Reset();
-
-    /*
-     * flags
-     */
-    bool use_simple_model_;
-    bool use_deep_space_;
-
-    /*
-     * the constants used
-     */
-    struct CommonConstants common_consts_;
-    struct NearSpaceConstants nearspace_consts_;
-    struct DeepSpaceConstants deepspace_consts_;
-    struct IntegratorConstants integrator_consts_;
-    mutable struct IntegratorParams integrator_params_;
-
-    /*
-     * the orbit data
-     */
-    OrbitalElements elements_;
 };
 
 #endif

libsgp4/SatelliteException.h

@@ -3,6 +3,9 @@
 
 #include <exception>
 
+/**
+ * @brief The exception that the SGP4 class throws upon an error.
+ */
 class SatelliteException : public std::exception
 {
 public:

libsgp4/SolarPosition.h

@@ -4,6 +4,9 @@
 #include "DateTime.h"
 #include "Eci.h"
 
+/**
+ * @brief Find the position of the sun
+ */
 class SolarPosition
 {
 public:

libsgp4/TimeSpan.h

@@ -23,6 +23,13 @@ namespace
     static const long long GregorianStart = 49916304000000000LL;
 }
 
+/**
+ * @brief Represents a time interval.
+ *
+ * Represents a time interval (duration/elapsed) that is measured as a positive
+ * or negative number of days, hours, minutes, seconds, and fractions
+ * of a second.
+ */
 class TimeSpan
 {
 public:

libsgp4/Tle.h

@@ -6,8 +6,9 @@
 #include "TleException.h"
 
 /**
- * Tle class
+ * @brief Processes a two-line element set used to convey OrbitalElements.
- * @details Loads and validates a tle.
+ *
+ * Used to extract the various raw fields from a two-line element set.
  */
 class Tle
 {

libsgp4/TleException.h

@@ -3,6 +3,11 @@
 
 #include <exception>
 
+/**
+ * @brief The exception that the Tle class throws on an error.
+ *
+ * The exception that the Tle decoder will throw on an error.
+ */
 class TleException : public std::exception
 {
 public:

libsgp4/Vector.h

@@ -6,6 +6,11 @@
 #include <sstream>
 #include <iomanip>
 
+/**
+ * @brief Generic vector
+ *
+ * Stores x, y, z, w
+ */
 struct Vector
 {
 public:

passpredict/passpredict.cpp

@@ -1,7 +1,7 @@
 #include <Observer.h>
 #include <SGP4.h>
 #include <Util.h>
-#include <CoordTopographic.h>
+#include <CoordTopocentric.h>
 #include <CoordGeodetic.h>
 
 #include <cmath>
@@ -15,95 +15,6 @@ struct PassDetails
     double max_elevation;
 };
 
-#if 0
-double FindMaxElevation(
-        const CoordGeodetic& user_geo,
-        SGP4& sgp4,
-        const DateTime& aos,
-        const DateTime& los)
-{
-    Observer obs(user_geo);
-
-    double max_elevation = 0.0;
-
-    /*
-     * time step in seconds
-     */
-    double time_step = 180.0;
-    /*
-     * still searching for max elevation
-     */
-    bool searching = true;
-    /*
-     * fine tune the max elevation value
-     */
-    bool fine_tune = false;
-
-    DateTime current_time(aos);
-    while (current_time < los && searching)
-    {
-        /*
-         * find position
-         */
-        Eci eci = sgp4.FindPosition(current_time);
-        CoordTopographic topo = obs.GetLookAngle(eci);
-
-        /*
-         * keep updating max elevation
-         */
-        if (topo.elevation > max_elevation)
-        {
-            max_elevation = topo.elevation;
-        }
-        else if (!fine_tune)
-        {
-            /*
-             * passed max elevation
-             * max elevation happened in the last 6 minutes
-             * go back and fine tune max elevation value
-             */
-            current_time = current_time.AddSeconds(-2.0 * time_step);
-            /*
-             * dont go back before aos
-             */
-            if (current_time < aos)
-                current_time = aos;
-
-            /*
-             * 1 second increment
-             */
-            time_step = 1.0;
-            fine_tune = true;
-
-            /*
-             * reset elevation
-             */
-            max_elevation = -99.9;
-
-        }
-        else
-        {
-            /*
-             * found max elevation
-             */
-
-            searching = false;
-        }
-
-        if (searching)
-        {
-            current_time = current_time.AddSeconds(time_step);
-            if (current_time > los)
-            {
-                current_time = los;
-            }
-        }
-    }
-
-    return max_elevation;
-}
-#endif
-
 double FindMaxElevation(
         const CoordGeodetic& user_geo,
         SGP4& sgp4,
@@ -134,7 +45,7 @@ double FindMaxElevation(
              * find position
              */
             Eci eci = sgp4.FindPosition(current_time);
-            CoordTopographic topo = obs.GetLookAngle(eci);
+            CoordTopocentric topo = obs.GetLookAngle(eci);
 
             if (topo.elevation > max_elevation)
             {
@@ -210,7 +121,7 @@ DateTime FindCrossingPoint(
          * calculate satellite position
          */
         Eci eci = sgp4.FindPosition(middle_time);
-        CoordTopographic topo = obs.GetLookAngle(eci);
+        CoordTopocentric topo = obs.GetLookAngle(eci);
 
         if (topo.elevation > 0.0)
         {
@@ -264,7 +175,7 @@ DateTime FindCrossingPoint(
     while (running && cnt++ < 6)
     {
         Eci eci = sgp4.FindPosition(middle_time);
-        CoordTopographic topo = obs.GetLookAngle(eci);
+        CoordTopocentric topo = obs.GetLookAngle(eci);
         if (topo.elevation > 0)
         {
             middle_time = middle_time.AddSeconds(finding_aos ? -1 : 1);
@@ -305,7 +216,7 @@ std::list<struct PassDetails> GeneratePassList(
          * calculate satellite position
          */
         Eci eci = sgp4.FindPosition(current_time);
-        CoordTopographic topo = obs.GetLookAngle(eci);
+        CoordTopocentric topo = obs.GetLookAngle(eci);
 
         if (!found_aos && topo.elevation > 0.0)
         {

runtest/runtest.cpp

@@ -2,7 +2,7 @@
 #include <SGP4.h>
 #include <Observer.h>
 #include <CoordGeodetic.h>
-#include <CoordTopographic.h>
+#include <CoordTopocentric.h>
 
 #include <list>
 #include <string>

sattrack/sattrack.cpp

@@ -1,4 +1,4 @@
-#include <CoordTopographic.h>
+#include <CoordTopocentric.h>
 #include <CoordGeodetic.h>
 #include <Observer.h>
 #include <SGP4.h>
@@ -28,7 +28,7 @@ int main()
         /*
          * get look angle for observer to satellite
          */
-        CoordTopographic topo = obs.GetLookAngle(eci);
+        CoordTopocentric topo = obs.GetLookAngle(eci);
         /*
          * convert satellite position to geodetic coordinates
          */