Changeset 1393 for trunk/psLib/src/astronomy/psCoord.h

Timestamp:

Aug 5, 2004, 9:38:52 AM (22 years ago)

Author:

desonia

Message:

Misc. doxygen polishings.

File:

• trunk/psLib/src/astronomy/psCoord.h (modified) (7 diffs)

trunk/psLib/src/astronomy/psCoord.h

@@ -10 +10 @@
 *  @author George Gusciora, MHPCC
 *
-*  @version $Revision: 1.8 $ $Name: not supported by cvs2svn $
-*  @date $Date: 2004-08-04 23:37:39 $
+*  @version $Revision: 1.9 $ $Name: not supported by cvs2svn $
+*  @date $Date: 2004-08-05 19:38:51 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
@@ -29 +29 @@
 /// @{
 
+/** Euclidiean Coordinate System.
+ *
+ *  Both detector and sky positions will be used extensively in the IPP. One
+ *  coordinate system to be used is linear coordinates which conform to 
+ *  Euclidean geometry. 
+ *
+ */
 typedef struct
 {
@@ -38 +45 @@
 psPlane;
 
+/** Angular Coordinate System
+ *
+ *  Both detector and sky positions will be used extensively in the IPP. One 
+ *  coordinate system to be used is angular coordinates for which additional 
+ *  care must often be taken in comparison to a euclidiean coordinate system.
+ *
+ */
 typedef struct
 {
@@ -47 +61 @@
 psSphere;
 
-typedef struct
-{
-    psDPolynomial2D *x;
-    psDPolynomial2D *y;
+/** 2D Polynomial Transform
+ *
+ *  A transform between coordinate systems that consists simply of two 2D 
+ *  polynomials to transform both components - the output coordinates depend 
+ *  only on the input coordinates and no other quantities of objects at those
+ *  coordinates. 
+ *
+ */
+typedef struct
+{
+    psDPolynomial2D *x;                ///< 2D polynomial transform of X coordinates
+    psDPolynomial2D *y;                ///< 2D polynomial transform of Y coordinates
 }
 psPlaneTransform;
 
-typedef struct
-{
-    psDPolynomial4D *x;
-    psDPolynomial4D *y;
+/** 4D Polynomial Transform
+ *
+ *  A transform between coordinate systems that consists of two 4D polynomials
+ *  in which the output coordinates are also specified to be a function of the 
+ *  magnitude and color of the object with the given coordinates. This type of 
+ *  coordinate transformation is necessary to represent the (color-dependent) 
+ *  optical distortions caused by the atmosphere and camera optics, and the 
+ *  possibly effects of charge transfer inefficiency.
+ *
+ *  The lowest two terms are the x and y axis of the target system.  The higher
+ *  two terms may represent magnitude and color terms.
+ */
+typedef struct
+{
+    psDPolynomial4D *x;                ///< 4D polynomial transform of X coordinates
+    psDPolynomial4D *y;                ///< 4D polynomial transform of Y coordinates
 }
 psPlaneDistort;
 
+/** Spherical Transform Definition
+ *
+ *  We need to be able to convert between ICRS, Galactic and Ecliptic 
+ *  coordinates, and potentially between arbitrary spherical coordinate 
+ *  systems. All of these basic spherical transformations represent rotations 
+ *  of the spherical coordinate reference. We specify a general 
+ *  transformation function which takes a structure, psSphereTransform, 
+ *  defining the transformation between two spherical coordinate systems 
+ *
+ */
 typedef struct
 {
@@ -70 +114 @@
 psSphereTransform;
 
+/** Projection type for projection/deprojection
+ * 
+ *  @seealso psProject, psDeproject
+ *
+ */
 typedef enum {
     PS_PROJ_TAN,        ///< Tangent projection
@@ -81 +130 @@
 } psProjectionType;
 
+/** Parameter set for projection/deprojection
+ * 
+ *  @seealso psProject, psDeproject
+ *
+ */
 typedef struct
 {
@@ -91 +145 @@
 psProjection;
 
+/** Mode for Offset calculation between two sky positions
+ *
+ *  @seealso  psSphereGetOffset, psSphereSetOffset
+ *
+ */
 typedef enum {
-    PS_SPHERICAL,
-    PS_LINEAR
+    PS_SPHERICAL,                      ///< offset corresponds to an angular offset
+    PS_LINEAR                          ///< offset corresponds to a linear offset
 } psSphereOffsetMode;
 
+/** The units of the offset
+ *
+ *  @seealso  psSphereGetOffset, psSphereSetOffset
+ *
+ */
 typedef enum {
-    PS_ARCSEC,
-    PS_ARCMIN,
-    PS_DEGREE,
-    PS_RADIAN
+    PS_ARCSEC,                         ///< Arcseconds
+    PS_ARCMIN,                         ///< Arcminutes
+    PS_DEGREE,                         ///< Degrees
+    PS_RADIAN                          ///< Radians
 } psSphereOffsetUnit;
 
-psPlane *psPlaneTransformApply( psPlane *out,
-                                const psPlaneTransform *transform,
-                                const psPlane *coords );
-
-psPlane *psPlaneDistortApply( psPlane *out,
-                              const psPlaneDistort *transform,
-                              const psPlane *coords,
-                              float term3,
-                              float term4 );
-
-
-// New function prototype.
-psSphereTransform *psSphereTransformAlloc( double NPlat,
-        double Xo,
-        double xo );
-
-void p_psSphereTransformFree( psSphereTransform *trans );
-
-psSphere *psSphereTransformApply( psSphere *out,
-                                  const psSphereTransform *transform,
-                                  const psSphere *coord );
-
-psSphereTransform *psSphereTransformICRStoEcliptic( psTime time );
-psSphereTransform *psSphereTransformEcliptictoICRS( psTime time );
+/** Applies the psPlaneTransform transform to a specified coordinate
+ *
+ */
+psPlane *psPlaneTransformApply(
+    psPlane *out,                      ///< a psPlane to recycle.  If NULL, a new one is generated.
+    const psPlaneTransform *transform, ///< the transform to apply
+    const psPlane *coords              ///< the coordinate to apply the transform above.
+);
+
+/** Applies the psPlaneDistort transform to a specified coordinate
+ *
+ */
+psPlane *psPlaneDistortApply(
+    psPlane *out,                      ///< a psPlane to recycle.  If NULL, a new one is generated.
+    const psPlaneDistort *transform,   ///< the transform to apply
+    const psPlane *coords,             ///< the coordinate to apply the transform above.
+    float term3,                       ///< third term -- maybe magnitude
+    float term4                        ///< forth term -- maybe color
+);
+
+/** Allocator for psSphereTransform
+ *
+ */
+psSphereTransform *psSphereTransformAlloc(
+    double NPlat,                      ///< north pole latitude
+    double Xo,                         ///< First PT of Ares lon
+    double xo                          ///< First PT of Ares equiv lon
+);
+
+
+/** Applies the psSphereTransform transform for a specified coordinate
+ *
+ */
+psSphere *psSphereTransformApply(
+    psSphere *out,                     ///< a psSphere to recycle.  If NULL, a new one is generated.
+    const psSphereTransform *transform,///< the transform to apply
+    const psSphere *coord              ///< the coordinate to apply the transform above.x
+);
+
+psSphereTransform *psSphereTransformICRStoEcliptic(
+    psTime time
+);
+
+psSphereTransform *psSphereTransformEcliptictoICRS(
+    psTime time
+);
+
 psSphereTransform *psSphereTransformICRStoGalatic( void );
+
 psSphereTransform *psSphereTransformGalatictoICRS( void );
 
-psPlane *psProject( const psSphere *coord,
-                    const psProjection *projection );
-
-psSphere *psDeproject( const psPlane *coord,
-                       const psProjection *projection );
-
-psSphere *psSphereGetOffset( const psSphere *restrict position1,
-                             const psSphere *restrict position2,
-                             psSphereOffsetMode mode,
-                             psSphereOffsetUnit unit );
-
-psSphere *psSphereSetOffset( const psSphere *restrict position,
-                             const psSphere *restrict offset,
-                             psSphereOffsetMode mode,
-                             psSphereOffsetUnit unit );
+psPlane *psProject(
+    const psSphere *coord,
+    const psProjection *projection
+);
+
+psSphere *psDeproject(
+    const psPlane *coord,
+    const psProjection *projection
+);
+
+psSphere *psSphereGetOffset(
+    const psSphere *restrict position1,
+    const psSphere *restrict position2,
+    psSphereOffsetMode mode,
+    psSphereOffsetUnit unit
+);
+
+psSphere *psSphereSetOffset(
+    const psSphere *restrict position,
+    const psSphere *restrict offset,
+    psSphereOffsetMode mode,
+    psSphereOffsetUnit unit
+);
 
 /// @}