Index: trunk/psLib/src/astro/psCoord.h =================================================================== --- trunk/psLib/src/astro/psCoord.h (revision 1385) +++ trunk/psLib/src/astro/psCoord.h (revision 1393) @@ -10,6 +10,6 @@ * @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,4 +29,11 @@ /// @{ +/** 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,4 +45,11 @@ 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,18 +61,48 @@ 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,4 +114,9 @@ psSphereTransform; +/** Projection type for projection/deprojection + * + * @seealso psProject, psDeproject + * + */ typedef enum { PS_PROJ_TAN, ///< Tangent projection @@ -81,4 +130,9 @@ } psProjectionType; +/** Parameter set for projection/deprojection + * + * @seealso psProject, psDeproject + * + */ typedef struct { @@ -91,58 +145,100 @@ 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 +); /// @}