Changeset 5447 for trunk/psLib/src/astro/psEarthOrientation.h

Timestamp:

Oct 27, 2005, 10:38:19 AM (21 years ago)

Author:

drobbin

Message:

Updated EarthOrientation - Gravity Deflection and tests

File:

• trunk/psLib/src/astro/psEarthOrientation.h (modified) (3 diffs)

trunk/psLib/src/astro/psEarthOrientation.h

@@ -9 +9 @@
 *  @author Robert Daniel DeSonia, MHPCC
 *
-*  @version $Revision: 1.4 $ $Name: not supported by cvs2svn $
-*  @date $Date: 2005-10-26 01:20:15 $
+*  @version $Revision: 1.5 $ $Name: not supported by cvs2svn $
+*  @date $Date: 2005-10-27 20:38:18 $
 *
 *  Copyright 2005 Maui High Performance Computing Center, University of Hawaii
@@ -22 +22 @@
 #include "psSphereOps.h"
 
-/**
- *
- *
- */
+/** Structure for respresenting the Earth's pole at any moment or determine velocity
+ *  at the pole.  This structure carries the polar coordinate information.       */
 typedef struct
 {
-    double x;                          ///<
-    double y;                          ///<
-    double s;                          ///<
+    double x;                          ///< X component of the earth's pole
+    double y;                          ///< Y component of the earth's pole
+    double s;                          ///< s component of the earth's pole
 }
 psEarthPole;
 
-/**
+/** Method for spherical precession used to specify the level of detail used in
+ *  calculation.
  *
+ *  @see psSpherePrecess
  *
  */
 typedef enum {
-    PS_PRECESS_ROUGH,                  ///<
-    PS_PRECESS_COMPLETE,               ///<
-    PS_PRECESS_IAU2000A,               ///<
+    PS_PRECESS_ROUGH,                  ///< roughest, lowest level of detail
+    PS_PRECESS_COMPLETE,               ///< complete level of detail
+    PS_PRECESS_IAU2000A,               ///< highest level of detail
 } psPrecessMethod;
 
-/**
+/** Calculates the actual position of a star, given its apparent position and the
+ *  velocity vector of the observer.
  *
+ *  The actual and apparent positions are represented as psSphere entries, as is the
+ *  direction of motion.  The speed in that direction is given in units of the speed
+ *  of light.  If the value of actual is NULL, a new psSphere is allocated, otherwise
+ *  the point to actual is used for the result.
  *
- *
+ *  @return psSphere*:      the actual position of a star.
  */
 psSphere *psAberration(
-    psSphere *apparent,                ///<
-    const psSphere *actual,            ///<
-    const psSphere *direction,         ///<
-    double speed                       ///<
+    psSphere *actual,                  ///< actual position of star
+    const psSphere *apparent,          ///< apparent position of star
+    const psSphere *direction,         ///< direction of motion of observer
+    double speed                       ///< speed of motion of observer
 );
 
@@ -66 +71 @@
  */
 psSphere *psGravityDeflection(
+    psSphere *actual,                  ///< actual position of star
     psSphere *apparent,                ///< apparent position of star
-    psSphere *actual,                  ///< actual position of star
     psSphere *sun                      ///< position of the sun
 );
 
-/**
+/** Calculate the parallax factor for the given position and time.
  *
- *
+ *  @return double:     the calculated parallax factor.
  */
 double psEOC_ParallaxFactor(
-    const psSphere *coords,            ///<
-    const psTime *time                 ///<
+    const psSphere *coords,            ///< specified position
+    const psTime *time                 ///< specified time
 );
 
-/**
+/** Calculates the components of the rotation between the CEO and GCRS frames, X, Y,
+ *  and s, using the IAU2000A precession & nutation model.
  *
+ *  The input time may be represented in any format other than UT1.  This routine must
+ *  give results identical to the IERS XYS2000A subroutine.
  *
+ *  @return psEarthPole*:       the calculated components of the rotation.
  */
 psEarthPole *psEOC_PrecessionModel(
-    const psTime *time                 ///<
+    const psTime *time                 ///< specified time
 );
 
-/**
+/** Provides interpolated corrections to the X and Y components of the polar
+ *  coordinates from the tables provided by the IERS, just as it does for UT1 and
+ *  polar motion.
  *
- *
+ *  @return psEarthPole*:       interpolated corrections to the precession components.
  */
 psEarthPole *psEOC_PrecessionCorr(
-    const psTime *time,                ///<
-    psTimeBulletin bulletin            ///<
+    const psTime *time,                ///< specified time
+    psTimeBulletin bulletin            ///< IERS tables for polar coordinate components.
 );
 
-/**
+/** Constructs the spherical rotation for transforming from CEO to GCRS coordinates.
  *
+ *  The resulting psSphereRot may be used to determine the rotation from CIP/CEO to
+ *  GCRS.  This function must give results identical to the IERS BPN2000.
  *
+ *  @return psSphereRot*:       spherical rotation for CEO to GCRS transformation.
  */
 psSphereRot *psSphereRot_CEOtoGCRS(
-    const psEarthPole *pole            ///<
+    const psEarthPole *pole            ///< input coordinates to transform
 );
 
-/**
+/** Calculates the rotation of the Earth about the CIP.
  *
- *
+ *  @return psSphereRot*:       sphereical rotation
  */
 psSphereRot *psSphereRot_TEOtoCEO(
-    const psTime *time                 ///<
+    const psTime *time                 ///< specified time
 );
 
-/**
+/** Provides interpolated values of the polar motion components extracted from the
+ *  IERS tables.
  *
- *
+ *  @return psEarthPole*:       interpolated polar motion components.
  */
 psEarthPole *psEOC_GetPolarMotion(
-    const psTime *time,                ///<
-    psTimeBulletin bulletin            ///<
+    const psTime *time,                ///< specified time
+    psTimeBulletin bulletin            ///< IERS tables for polar coordinate components.
 );
 
-/**
+/** Provides tidal corrections to the polar motion components using the Ray model
+ *  of Simon et al.
  *
- *
+ *  @return psEarthPole*:       corrected polar motion components.
  */
 psEarthPole *psEOC_PolarTideCorr(
-    const psTime *time                 ///<
+    const psTime *time                 ///< specified time
 );
 
-/**
+/** Provides the additional corrections due to nutation terms with periods less than
+ *  or equal to two days, as well as the correction to the s-prime component of polar
+ *  motion.
  *
- *
- *
+ *  @return psEarthPole*:       corrected polar motion components.
  */
 psEarthPole *psEOC_NutationCorr(
-    psTime *time                       ///<
+    psTime *time                       ///< specified time
 );
 
-/**
+/** Converts the polar motion corrections to a spherical rotation.
  *
+ *  This function should give identical results to the IERS POM2000 subroutine.
  *
- *
+ *  @return psSphereRot*:       ITRS to TEO sphere rotation.
  */
 psSphereRot *psSphereRot_ITRStoTEO(
-    const psEarthPole *motion          ///<
+    const psEarthPole *motion          ///< corrected polar motion components
 );