Index: /trunk/psLib/src/astro/psCoord.h =================================================================== --- /trunk/psLib/src/astro/psCoord.h (revision 1495) +++ /trunk/psLib/src/astro/psCoord.h (revision 1496) @@ -11,6 +11,6 @@ * @author George Gusciora, MHPCC * -* @version $Revision: 1.13 $ $Name: not supported by cvs2svn $ -* @date $Date: 2004-08-09 23:40:54 $ +* @version $Revision: 1.14 $ $Name: not supported by cvs2svn $ +* @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -117,5 +117,5 @@ /** Projection type for projection/deprojection * - * @seealso psProject, psDeproject + * @see psProject, psDeproject * */ @@ -133,5 +133,5 @@ /** Parameter set for projection/deprojection * - * @seealso psProject, psDeproject + * @see psProject, psDeproject * */ @@ -148,5 +148,5 @@ /** Mode for Offset calculation between two sky positions * - * @seealso psSphereGetOffset, psSphereSetOffset + * @see psSphereGetOffset, psSphereSetOffset * */ @@ -158,5 +158,5 @@ /** The units of the offset * - * @seealso psSphereGetOffset, psSphereSetOffset + * @see psSphereGetOffset, psSphereSetOffset * */ @@ -170,56 +170,127 @@ /** 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. - ); + * @return psPlane* resulting coordinate based on transform + */ +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 - ); + * @return psPlane* resulting coordinate based on transform + */ +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 - ); + * @return psSphereTransform* newly allocated struct + */ +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); - + * @return psSphere* resulting coordinate based on transform + */ +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 +); + +/** Creates the appropriate transform for converting from ICRS to Ecliptic + * coordinate systems. + * + * @return psSphereTransform* transform for ICRS->Ecliptic coordinate systems + */ +psSphereTransform* psSphereTransformICRStoEcliptic( + psTime time ///< the time for which the resulting transform will be valid +); + +/** Creates the appropriate transform for converting from Ecliptic to ICRS + * coordinate systems. + * + * @return psSphereTransform* transform for Ecliptic->ICRS coordinate systems + */ +psSphereTransform* psSphereTransformEcliptictoICRS( + psTime time ///< the time for which the resulting transform will be valid +); + +/** Creates the appropriate transform for converting from ICRS to Galatic + * coordinate systems. + * + */ psSphereTransform* psSphereTransformICRStoGalatic(void); +/** Creates the appropriate transform for converting from Galatic to ICRS + * coordinate systems. + * + */ 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); +/** Projects a spherical coordinate to a linear coordinate system + * + * @return psPlane* projected coordinate + */ +psPlane* psProject( + const psSphere* coord, ///< coordinate to project + const psProjection* projection ///< parameters of the projection +); + +/** Reverse projection of a linear coordinate to a spherical coordinate system + * + * @return psPlane* projected coordinate + */ +psSphere* psDeproject( + const psPlane* coord, ///< coordinate to project + const psProjection* projection ///< parameters of the projection +); + +/** Determines the offset (RA,Dec) on the sky between two positions. + * + * Both an offset mode and an offset unit may be defined. The mode may be + * either PS_SPHERICAL, in which case the specified offset corresponds to an + * offset in angles, or it may be PS_LINEAR, in which case the offset + * corresponds to a linear offset in a local projection. The offset unit may + * be in one of PS_ARCSEC, PS_ARCMIN, PS_DEGREE, and PS_RADIAN, which + * specifies the units of the offset only. + * + * @return psSphere* the offset between position1 and position2 + */ +psSphere* psSphereGetOffset( + const psSphere* restrict position1, + const psSphere* restrict position2, + psSphereOffsetMode mode, + psSphereOffsetUnit unit +); + +/** Applies the given offset to a coordinate. + * + * Both an offset mode and an offset unit may be defined. The mode may be + * either PS_SPHERICAL, in which case the specified offset corresponds to an + * offset in angles, or it may be PS_LINEAR, in which case the offset + * corresponds to a linear offset in a local projection. The offset unit may + * be in one of PS_ARCSEC, PS_ARCMIN, PS_DEGREE, and PS_RADIAN, which + * specifies the units of the offset only. + * + * @return psSphere* the given position with the given offset applied. + */ +psSphere* psSphereSetOffset( + const psSphere* restrict position, + const psSphere* restrict offset, + psSphereOffsetMode mode, + psSphereOffsetUnit unit +); /// @} Index: /trunk/psLib/src/astro/psTime.h =================================================================== --- /trunk/psLib/src/astro/psTime.h (revision 1495) +++ /trunk/psLib/src/astro/psTime.h (revision 1496) @@ -13,6 +13,6 @@ * @author Ross Harman, MHPCC * - * @version $Revision: 1.10 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-08-09 23:40:54 $ + * @version $Revision: 1.11 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -39,14 +39,13 @@ /** Definition of psTime. * - * The psTime struct is used by psLib to represent time values critical to astronomical calculations. This - * structure represents a time which is equivalent to TAI (International Atomic Time) and is measured in - * both seconds and microseconds. + * The psTime struct is used by psLib to represent time values critical to + * astronomical calculations. This structure represents a time which is + * equivalent to TAI (International Atomic Time) and is measured in both + * seconds and microseconds. */ typedef struct { - - time_t tv_sec; /**< Seconds since epoch, Jan 1, 1970. */ - - suseconds_t tv_usec; /**< Microseconds since last second. */ + time_t tv_sec; ///< Seconds since epoch, Jan 1, 1970. + suseconds_t tv_usec; ///< Microseconds since last second. } psTime; @@ -65,68 +64,66 @@ */ -psTime psTimeGetTime(void - /** No argument. */ - ); +psTime psTimeGetTime(void); /** Convert psTime to ISO time in TAI units. * - * Converts psTime to a null terminated string in the form of: YYYY/MM/DD,HH:MM:SS.SSS. This function assumes - * the input time already is in TAI time and does not add or subtract leapseconds. + * Converts psTime to a null terminated string in the form of: + * YYYY/MM/DD,HH:MM:SS.SSS. This function assumes the input time already is + * in TAI time and does not add or subtract leapseconds. * * @return char*: Pointer null terminated array of chars in ISO time. */ -char *psTimeToISO(psTime time - /** Input time to be converted. */ - ); +char *psTimeToISO( + psTime time ///< Input time to be converted. +); /** Convert psTime to UTC time. * - * Converts psTime to UTC time in double precision floating point notation. The input to this must already be - * int TAI time. The result from this function is not in TAI units, but that of UTC, which does not contain - * leapseconds. + * Converts psTime to UTC time in double precision floating point notation. + * The input to this must already be int TAI time. The result from this + * function is not in TAI units, but that of UTC, which does not contain + * leapseconds. * * @return psTime: UTC time psTime format. */ -psTime psTimeToUTC(psTime time - /** Input time to be converted. */ - ); +psTime psTimeToUTC( + psTime time ///< Input time to be converted. +); /** Convert psTime to modified Julian date time. * - * Converts psTime to modified Julian date (MJD) time. This function assumes the input time already is in TAI - * time and does not add or subtract leapseconds. + * Converts psTime to modified Julian date (MJD) time. This function assumes + * the input time already is in TAI time and does not add or subtract + * leapseconds. * * @return double: Modified Julian Days (MJD) time. */ - -double psTimeToMJD(psTime time - /** Input time to be converted. */ - ); +double psTimeToMJD( + psTime time ///< Input time to be converted. +); /** Convert psTime to Julian date time. * - * Converts psTime to Julian date (JD) time. This function assumes the input time already is in TAI time and - * does not add or subtract leapseconds. + * Converts psTime to Julian date (JD) time. This function assumes the input + * time already is in TAI time and does not add or subtract leapseconds. * * @return double: Julian Date (JD) time. */ - -double psTimeToJD(psTime time - /** Input time to be converted. */ - ); +double psTimeToJD( + psTime time ///< Input time to be converted. +); /** Convert psTime to timeval time. * - * Converts psTime to timeval time. This function assumes the input time already is in TAI time and does not - * add or subtract leapseconds. + * Converts psTime to timeval time. This function assumes the input time + * already is in TAI time and does not add or subtract leapseconds. * * @return timeval: timeval struct time. */ - -struct timeval psTimeToTimeval(psTime time - /** Input time to be converted. */ - ); +struct timeval psTimeToTimeval( + psTime time ///< Input time to be converted. + ); /** Convert psTime to tm time. @@ -137,80 +134,73 @@ * @return tm: tm struct time. */ - -struct tm *psTimeToTM(psTime time - /** Input time to be converted. */ - ); +struct tm *psTimeToTM( + psTime time ///< Input time to be converted. + ); /** Convert ISO to psTime. * - * Converts ISO time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. + * Converts ISO time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. * * @return psTime: time */ - -psTime psISOToTime(char *time - /** Input time to be converted. */ - ); +psTime psISOToTime( + char *time ///< Input time to be converted. +); /** Convert UTC to psTime. * - * Converts UTC time to psTime. This function assumes the input time already is in TAI time and add or - * subtracts the necessary leapseconds. + * Converts UTC time to psTime. This function assumes the input time already + * is in TAI time and add or subtracts the necessary leapseconds. * * @return psTime: time in TAI units. */ - -psTime psUTCToTime(psTime time - /** Input time to be converted. */ - ); +psTime psUTCToTime( + psTime time ///< Input time to be converted. +); /** Convert MJD to psTime. * - * Converts MJD time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psMJDToTime(double time - /** Input time to be converted. */ - ); + * Converts MJD time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psMJDToTime( + double time ///< Input time to be converted. +); /** Convert JD to psTime. * - * Converts JD time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psJDToTime(double time - /** Input time to be converted. */ - ); + * Converts JD time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psJDToTime( + double time ///< Input time to be converted. +); /** Convert timeval to psTime. * - * Converts timeval time to psTime. This function assumes the input time already is in TAI time and does not - * add or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psTimevalToTime(struct timeval *time - /** Input time to be converted. */ - ); + * Converts timeval time to psTime. This function assumes the input time + * already is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psTimevalToTime( + struct timeval *time ///< Input time to be converted. +); /** Convert tm time to psTime. * - * Converts tm time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psTMToTime(struct tm *time - /** Input time to be converted. */ - ); + * Converts tm time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psTMToTime( + struct tm *time ///< Input time to be converted. +); /// @} Index: /trunk/psLib/src/astronomy/psAstrometry.h =================================================================== --- /trunk/psLib/src/astronomy/psAstrometry.h (revision 1495) +++ /trunk/psLib/src/astronomy/psAstrometry.h (revision 1496) @@ -8,6 +8,6 @@ * @author George Gusciora, MHPCC * -* @version $Revision: 1.18 $ $Name: not supported by cvs2svn $ -* @date $Date: 2004-08-11 23:33:44 $ +* @version $Revision: 1.19 $ $Name: not supported by cvs2svn $ +* @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -44,18 +44,18 @@ typedef struct { - const double latitude; ///< geodetic latitude (radians) - const double sinLat; ///< sine of geodetic latitude - const double cosLat; ///< cosine of geodetic latitude - const double abberationMag; ///< magnitude of diurnal aberration vector - const double height; ///< height (HM) - const double temperature; ///< ambient temperature (TDK) - const double pressure; ///< pressure (PMB) - const double humidity; ///< relative humidity (RH) - const double wavelength; ///< wavelength (WL) - const double lapseRate; ///< lapse rate (TLR) - const double refractA; ///< refraction constant A (radians) - const double refractB; ///< refraction constant B (radians) - const double longitudeOffset; ///< longitude + ... (radians) - const double siderealTime; ///< local apparent sidereal time (radians) + const double latitude; ///< geodetic latitude (radians) + const double sinLat; ///< sine of geodetic latitude + const double cosLat; ///< cosine of geodetic latitude + const double abberationMag; ///< magnitude of diurnal aberration vector + const double height; ///< height (HM) + const double temperature; ///< ambient temperature (TDK) + const double pressure; ///< pressure (PMB) + const double humidity; ///< relative humidity (RH) + const double wavelength; ///< wavelength (WL) + const double lapseRate; ///< lapse rate (TLR) + const double refractA; ///< refraction constant A (radians) + const double refractB; ///< refraction constant B (radians) + const double longitudeOffset; ///< longitude + ... (radians) + const double siderealTime; ///< local apparent sidereal time (radians) } psGrommit; @@ -72,12 +72,12 @@ typedef struct { - int nX; ///< Number of elements in x direction - int nY; ///< Number of elements in y direction - double x0; ///< X Position of 0,0 corner on focal plane - double y0; ///< Y Position of 0,0 corner on focal plane - double xScale; ///< Scale of the grid in x direction - double yScale; ///< Scale of the grid in x direction - double **x; ///< The grid of offsets in x - double **y; ///< The grid of offsets in y + int nX; ///< Number of elements in x direction + int nY; ///< Number of elements in y direction + double x0; ///< X Position of 0,0 corner on focal plane + double y0; ///< Y Position of 0,0 corner on focal plane + double xScale; ///< Scale of the grid in x direction + double yScale; ///< Scale of the grid in x direction + double **x; ///< The grid of offsets in x + double **y; ///< The grid of offsets in y } psFixedPattern; @@ -94,12 +94,12 @@ typedef struct { - const unsigned int colBins; ///< Amount of binning in x-dimension - const unsigned int rowBins; ///< Amount of binning in y-dimension - const int col0; ///< Offset from the left of chip. - const int row0; ///< Offset from the bottom of chip. - - psImage* image; ///< imaging area of Readout - psList* objects; ///< objects derived from Readout - psMetadata* metadata; ///< readout-level metadata + const unsigned int colBins; ///< Amount of binning in x-dimension + const unsigned int rowBins; ///< Amount of binning in y-dimension + const int col0; ///< Offset from the left of chip. + const int row0; ///< Offset from the bottom of chip. + + psImage* image; ///< imaging area of Readout + psList* objects; ///< objects derived from Readout + psMetadata* metadata; ///< readout-level metadata } psReadout; @@ -116,13 +116,13 @@ typedef struct psCell { - psArray* readouts; ///< readouts from the cell - psMetadata* metadata; ///< cell-level metadata - - psPlaneTransform* toChip; ///< transformations from cell to chip coordinates - psPlaneTransform* fromChip; ///< transformations from chip to cell coordinates - psPlaneTransform* toFPA; ///< transformations from cell to FPA coordinates - psPlaneTransform* toTP; ///< transformations from cell to tangent plane coordinates - - struct psChip* parent; ///< chip in which contains this cell + psArray* readouts; ///< readouts from the cell + psMetadata* metadata; ///< cell-level metadata + + psPlaneTransform* toChip; ///< transformations from cell to chip coordinates + psPlaneTransform* fromChip; ///< transformations from chip to cell coordinates + psPlaneTransform* toFPA; ///< transformations from cell to FPA coordinates + psPlaneTransform* toTP; ///< transformations from cell to tangent plane coordinates + + struct psChip* parent; ///< chip in which contains this cell } psCell; @@ -138,11 +138,11 @@ typedef struct psChip { - psArray* cells; ///< cells in the chip - psMetadata* metadata; ///< chip-level metadata - - psPlaneTransform* toFPA; ///< transformation from chip to FPA coordinates - psPlaneTransform* fromFPA; ///< transformation from FPA to chip coordinates - - struct psFPA* parent; ///< FPA which contains this chip + psArray* cells; ///< cells in the chip + psMetadata* metadata; ///< chip-level metadata + + psPlaneTransform* toFPA; ///< transformation from chip to FPA coordinates + psPlaneTransform* fromFPA; ///< transformation from FPA to chip coordinates + + struct psFPA* parent; ///< FPA which contains this chip } psChip; Index: /trunk/psLib/src/astronomy/psCoord.h =================================================================== --- /trunk/psLib/src/astronomy/psCoord.h (revision 1495) +++ /trunk/psLib/src/astronomy/psCoord.h (revision 1496) @@ -11,6 +11,6 @@ * @author George Gusciora, MHPCC * -* @version $Revision: 1.13 $ $Name: not supported by cvs2svn $ -* @date $Date: 2004-08-09 23:40:54 $ +* @version $Revision: 1.14 $ $Name: not supported by cvs2svn $ +* @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -117,5 +117,5 @@ /** Projection type for projection/deprojection * - * @seealso psProject, psDeproject + * @see psProject, psDeproject * */ @@ -133,5 +133,5 @@ /** Parameter set for projection/deprojection * - * @seealso psProject, psDeproject + * @see psProject, psDeproject * */ @@ -148,5 +148,5 @@ /** Mode for Offset calculation between two sky positions * - * @seealso psSphereGetOffset, psSphereSetOffset + * @see psSphereGetOffset, psSphereSetOffset * */ @@ -158,5 +158,5 @@ /** The units of the offset * - * @seealso psSphereGetOffset, psSphereSetOffset + * @see psSphereGetOffset, psSphereSetOffset * */ @@ -170,56 +170,127 @@ /** 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. - ); + * @return psPlane* resulting coordinate based on transform + */ +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 - ); + * @return psPlane* resulting coordinate based on transform + */ +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 - ); + * @return psSphereTransform* newly allocated struct + */ +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); - + * @return psSphere* resulting coordinate based on transform + */ +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 +); + +/** Creates the appropriate transform for converting from ICRS to Ecliptic + * coordinate systems. + * + * @return psSphereTransform* transform for ICRS->Ecliptic coordinate systems + */ +psSphereTransform* psSphereTransformICRStoEcliptic( + psTime time ///< the time for which the resulting transform will be valid +); + +/** Creates the appropriate transform for converting from Ecliptic to ICRS + * coordinate systems. + * + * @return psSphereTransform* transform for Ecliptic->ICRS coordinate systems + */ +psSphereTransform* psSphereTransformEcliptictoICRS( + psTime time ///< the time for which the resulting transform will be valid +); + +/** Creates the appropriate transform for converting from ICRS to Galatic + * coordinate systems. + * + */ psSphereTransform* psSphereTransformICRStoGalatic(void); +/** Creates the appropriate transform for converting from Galatic to ICRS + * coordinate systems. + * + */ 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); +/** Projects a spherical coordinate to a linear coordinate system + * + * @return psPlane* projected coordinate + */ +psPlane* psProject( + const psSphere* coord, ///< coordinate to project + const psProjection* projection ///< parameters of the projection +); + +/** Reverse projection of a linear coordinate to a spherical coordinate system + * + * @return psPlane* projected coordinate + */ +psSphere* psDeproject( + const psPlane* coord, ///< coordinate to project + const psProjection* projection ///< parameters of the projection +); + +/** Determines the offset (RA,Dec) on the sky between two positions. + * + * Both an offset mode and an offset unit may be defined. The mode may be + * either PS_SPHERICAL, in which case the specified offset corresponds to an + * offset in angles, or it may be PS_LINEAR, in which case the offset + * corresponds to a linear offset in a local projection. The offset unit may + * be in one of PS_ARCSEC, PS_ARCMIN, PS_DEGREE, and PS_RADIAN, which + * specifies the units of the offset only. + * + * @return psSphere* the offset between position1 and position2 + */ +psSphere* psSphereGetOffset( + const psSphere* restrict position1, + const psSphere* restrict position2, + psSphereOffsetMode mode, + psSphereOffsetUnit unit +); + +/** Applies the given offset to a coordinate. + * + * Both an offset mode and an offset unit may be defined. The mode may be + * either PS_SPHERICAL, in which case the specified offset corresponds to an + * offset in angles, or it may be PS_LINEAR, in which case the offset + * corresponds to a linear offset in a local projection. The offset unit may + * be in one of PS_ARCSEC, PS_ARCMIN, PS_DEGREE, and PS_RADIAN, which + * specifies the units of the offset only. + * + * @return psSphere* the given position with the given offset applied. + */ +psSphere* psSphereSetOffset( + const psSphere* restrict position, + const psSphere* restrict offset, + psSphereOffsetMode mode, + psSphereOffsetUnit unit +); /// @} Index: /trunk/psLib/src/astronomy/psMetadata.h =================================================================== --- /trunk/psLib/src/astronomy/psMetadata.h (revision 1495) +++ /trunk/psLib/src/astronomy/psMetadata.h (revision 1496) @@ -11,6 +11,6 @@ * @author Ross Harman, MHPCC * -* @version $Revision: 1.19 $ $Name: not supported by cvs2svn $ -* @date $Date: 2004-08-09 23:40:54 $ +* @version $Revision: 1.20 $ $Name: not supported by cvs2svn $ +* @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -34,16 +34,16 @@ */ typedef enum { - PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items - PS_META_BOOL, ///< Boolean data. - PS_META_S32, ///< Signed 32-bit integer data. - PS_META_F32, ///< Single-precision float data. - PS_META_F64, ///< Double-precision float data. - PS_META_STR, ///< String data (Stored in as void *). - PS_META_IMG, ///< Image data (Stored in as void *). - PS_META_JPEG, ///< JPEG data (Stored in as void . - PS_META_PNG, ///< PNG data (Stored in as void *). - PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). - PS_META_UNKNOWN, ///< Other data (Stored in as void *). - PS_META_NTYPE ///< Number of types. Must be last. + PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items + PS_META_BOOL, ///< Boolean data. + PS_META_S32, ///< Signed 32-bit integer data. + PS_META_F32, ///< Single-precision float data. + PS_META_F64, ///< Double-precision float data. + PS_META_STR, ///< String data (Stored in as void *). + PS_META_IMG, ///< Image data (Stored in as void *). + PS_META_JPEG, ///< JPEG data (Stored in as void *). + PS_META_PNG, ///< PNG data (Stored in as void *). + PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). + PS_META_UNKNOWN, ///< Other data (Stored in as void *). + PS_META_NTYPE ///< Number of types. Must be last. } psMetadataType; @@ -55,16 +55,16 @@ typedef struct psMetadataItem { - const int id; ///< Unique ID for metadata item. - char *restrict name; ///< Name of metadata item. - psMetadataType type; ///< Type of metadata item. + const int id; ///< Unique ID for metadata item. + char *restrict name; ///< Name of metadata item. + psMetadataType type; ///< Type of metadata item. union { - bool B; - psS32 S32; ///< Signed 32-bit integer data. - psF32 F32; ///< Single-precision float data. - psF64 F64; ///< Double-precision float data. - psPTR V; ///< Pointer to other type of data. - } data; ///< Union for data types. - char *comment; ///< Optional comment ("", not NULL). - psList* restrict items; ///< List of psMetadataItems with same name. + bool B; ///< boolean data + psS32 S32; ///< Signed 32-bit integer data. + psF32 F32; ///< Single-precision float data. + psF64 F64; ///< Double-precision float data. + psPTR V; ///< Pointer to other type of data. + } data; ///< Union for data types. + char *comment; ///< Optional comment ("", not NULL). + psList* restrict items; ///< List of psMetadataItems with same name. } psMetadataItem; @@ -72,12 +72,13 @@ /** Metadata data structure. * - * Struct for holding metadata items. Metadata items are held in two containers. The first employs a - * doubly-linked list to preserve the order of the metadata. The second container employs a hash table which - * allows fast lookup when given a metadata keyword. + * Struct for holding metadata items. Metadata items are held in two + * containers. The first employs a doubly-linked list to preserve the order + * of the metadata. The second container employs a hash table which + * allows fast lookup when given a metadata keyword. */ typedef struct psMetadata { - psList* restrict list; - psHash* restrict table; + psList* restrict list; ///< the metadata in linked-list + psHash* restrict table; ///< the metadata in a hash table } psMetadata; @@ -91,120 +92,135 @@ /** Create a metadata item. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAlloc(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAlloc( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); /** Create a metadata item with va_list. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAllocV(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - va_list list ///< Arguments for name formatting and metadata item - // data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAllocV( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + va_list list ///< Arguments for name formatting and metadata item data. +); /** Create a metadata collection. * - * Returns an empty metadata container with fully allocated internal metadata containers. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataAlloc(void ///< Void. - ); + * Returns an empty metadata container with fully allocated internal metadata + * containers. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataAlloc(void); /** Add existing metadata item to metadata collection. * - * Add a metadata item that has already been created to the metadata collection. + * Add a metadata item that has already been created to the metadata + * collection. + * + * @return bool: True for success, false for failure. + */ +bool psMetadataAddItem( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + psMetadataItem* restrict item ///< Metadata item to be added. +); + +/** Create and add a metadata item to metadata collection. + * + * Creates a new metadata item add to the metadata collection. * * @return bool: True for success, false for failure. */ -bool psMetadataAddItem(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - psMetadataItem* restrict item ///< Metadata item to be added. - ); - -/** Create and add a metadata item to metadata collection. - * - * Creates a new metadata item add to the metadata collection. +bool psMetadataAdd( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); + +/** Remove an item from metadata collection. + * + * Items may be removed from metadata by specifing a key or location. If the + * name is null, the where argument is used instead. If name is not null, + * where is set to PS_LIST_UNKNOWN. If the item is found, it is removed from + * the metadata and true is returned. If the key is not unique, then all + * items corresponding to it are removed. * * @return bool: True for success, false for failure. */ -bool psMetadataAdd(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); - -/** Remove an item from metadata collection. - * - * Items may be removed from metadata by specifing a key or location. If the name is null, the where argument - * is used instead. If name is not null, where is set to PS_LIST_UNKNOWN. If the item is found, it is removed - * from the metadata and true is returned. If the key is not unique, then all items corresponding to it are - * removed. - * - * @return bool: True for success, false for failure. - */ -bool psMetadataRemove(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be removed. - const char *restrict key ///< Name of metadata key. - ); +bool psMetadataRemove( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be removed. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on key name. * - * Items may be found in the metadata by providing a key. If the key is non-unique, the first item is - * returned. If the item is not found, null is returned. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataLookup(psMetadata* restrict md, ///< Metadata collection to insert metadat - // item. - const char *restrict key ///< Name of metadata key. - ); + * Items may be found in the metadata by providing a key. If the key is + * non-unique, the first item is returned. If the item is not found, null is + * returned. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataLookup( + psMetadata* restrict md, ///< Metadata collection to insert metadata item. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on list index. * - * Items may be found in the metadata by their entry position in the list container. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataGet(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where ///< Location to be retrieved. - ); + * Items may be found in the metadata by their entry position in the list + * container. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataGet( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where ///< Location to be retrieved. +); /** Set or reset metadata iterator. * - * Metadata may be iterated by setting or resetting an iterator to a location in the metadata list. + * Metadata may be iterated by setting or resetting an iterator to a location + * in the metadata list. * * @return void: void. */ -bool psMetadataSetIterator(psMetadata* restrict md, ///< Metadata collection to iterate. - int where ///< Location of iterator. - ); +bool psMetadataSetIterator( + psMetadata* restrict md, ///< Metadata collection to iterate. + int where ///< Location of iterator. +); /** Get next metadata item. @@ -214,8 +230,9 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetNext(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetNext( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Get previous metadata item. @@ -225,48 +242,55 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetPrevious(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetPrevious( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Print metadata item to file. * - * Metadata items may be printed to an open file descriptor based on a provided format. The format is a - * sprintf format statement with exactly one % formatting command. If the metadata item type is a numeric - * type, this formatting command must also be numeric, and the type conversion performed to the value to match - * the format type. If the metadata type is a string, the fromatting command must also be for a string. If the - * metadata type is any other data type, printing is not allowed. - * - * @return psMetadataItem* : Pointer metadata item. - */ -void psMetadataItemPrint(FILE * fd, ///< Pointer to file to write metadata item. - const char *format, ///< Format to print metadata item. - const psMetadataItem* restrict metadataItem ///< Metadata item to print. - ); + * Metadata items may be printed to an open file descriptor based on a + * provided format. The format is a sprintf format statement with exactly + * one % formatting command. If the metadata item type is a numeric type, + * this formatting command must also be numeric, and the type conversion + * performed to the value to match the format type. If the metadata type is + * a string, the fromatting command must also be for a string. If the + * metadata type is any other data type, printing is not allowed. + * + * @return psMetadataItem* : Pointer metadata item. + */ +void psMetadataItemPrint( + FILE * fd, ///< Pointer to file to write metadata item. + const char *format, ///< Format to print metadata item. + const psMetadataItem* restrict metadataItem ///< Metadata item to print. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. This file is currently - * unimplemented. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extname, ///< File name extension string. - int extnum, ///< File name extension number. Starts at 1. - char *filename ///< Name of file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. This file is currently unimplemented. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extname, ///< File name extension string. + int extnum, ///< File name extension number. Starts at 1. + char *filename ///< Name of file to read. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataFReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extName, ///< File name extension string. - int extNum, ///< File name extension number. - fitsfile * fd ///< Pointer to file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataFReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extName, ///< File name extension string. + int extNum, ///< File name extension number. + fitsfile * fd ///< Pointer to file to read. +); /// @} Index: /trunk/psLib/src/astronomy/psTime.h =================================================================== --- /trunk/psLib/src/astronomy/psTime.h (revision 1495) +++ /trunk/psLib/src/astronomy/psTime.h (revision 1496) @@ -13,6 +13,6 @@ * @author Ross Harman, MHPCC * - * @version $Revision: 1.10 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-08-09 23:40:54 $ + * @version $Revision: 1.11 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -39,14 +39,13 @@ /** Definition of psTime. * - * The psTime struct is used by psLib to represent time values critical to astronomical calculations. This - * structure represents a time which is equivalent to TAI (International Atomic Time) and is measured in - * both seconds and microseconds. + * The psTime struct is used by psLib to represent time values critical to + * astronomical calculations. This structure represents a time which is + * equivalent to TAI (International Atomic Time) and is measured in both + * seconds and microseconds. */ typedef struct { - - time_t tv_sec; /**< Seconds since epoch, Jan 1, 1970. */ - - suseconds_t tv_usec; /**< Microseconds since last second. */ + time_t tv_sec; ///< Seconds since epoch, Jan 1, 1970. + suseconds_t tv_usec; ///< Microseconds since last second. } psTime; @@ -65,68 +64,66 @@ */ -psTime psTimeGetTime(void - /** No argument. */ - ); +psTime psTimeGetTime(void); /** Convert psTime to ISO time in TAI units. * - * Converts psTime to a null terminated string in the form of: YYYY/MM/DD,HH:MM:SS.SSS. This function assumes - * the input time already is in TAI time and does not add or subtract leapseconds. + * Converts psTime to a null terminated string in the form of: + * YYYY/MM/DD,HH:MM:SS.SSS. This function assumes the input time already is + * in TAI time and does not add or subtract leapseconds. * * @return char*: Pointer null terminated array of chars in ISO time. */ -char *psTimeToISO(psTime time - /** Input time to be converted. */ - ); +char *psTimeToISO( + psTime time ///< Input time to be converted. +); /** Convert psTime to UTC time. * - * Converts psTime to UTC time in double precision floating point notation. The input to this must already be - * int TAI time. The result from this function is not in TAI units, but that of UTC, which does not contain - * leapseconds. + * Converts psTime to UTC time in double precision floating point notation. + * The input to this must already be int TAI time. The result from this + * function is not in TAI units, but that of UTC, which does not contain + * leapseconds. * * @return psTime: UTC time psTime format. */ -psTime psTimeToUTC(psTime time - /** Input time to be converted. */ - ); +psTime psTimeToUTC( + psTime time ///< Input time to be converted. +); /** Convert psTime to modified Julian date time. * - * Converts psTime to modified Julian date (MJD) time. This function assumes the input time already is in TAI - * time and does not add or subtract leapseconds. + * Converts psTime to modified Julian date (MJD) time. This function assumes + * the input time already is in TAI time and does not add or subtract + * leapseconds. * * @return double: Modified Julian Days (MJD) time. */ - -double psTimeToMJD(psTime time - /** Input time to be converted. */ - ); +double psTimeToMJD( + psTime time ///< Input time to be converted. +); /** Convert psTime to Julian date time. * - * Converts psTime to Julian date (JD) time. This function assumes the input time already is in TAI time and - * does not add or subtract leapseconds. + * Converts psTime to Julian date (JD) time. This function assumes the input + * time already is in TAI time and does not add or subtract leapseconds. * * @return double: Julian Date (JD) time. */ - -double psTimeToJD(psTime time - /** Input time to be converted. */ - ); +double psTimeToJD( + psTime time ///< Input time to be converted. +); /** Convert psTime to timeval time. * - * Converts psTime to timeval time. This function assumes the input time already is in TAI time and does not - * add or subtract leapseconds. + * Converts psTime to timeval time. This function assumes the input time + * already is in TAI time and does not add or subtract leapseconds. * * @return timeval: timeval struct time. */ - -struct timeval psTimeToTimeval(psTime time - /** Input time to be converted. */ - ); +struct timeval psTimeToTimeval( + psTime time ///< Input time to be converted. + ); /** Convert psTime to tm time. @@ -137,80 +134,73 @@ * @return tm: tm struct time. */ - -struct tm *psTimeToTM(psTime time - /** Input time to be converted. */ - ); +struct tm *psTimeToTM( + psTime time ///< Input time to be converted. + ); /** Convert ISO to psTime. * - * Converts ISO time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. + * Converts ISO time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. * * @return psTime: time */ - -psTime psISOToTime(char *time - /** Input time to be converted. */ - ); +psTime psISOToTime( + char *time ///< Input time to be converted. +); /** Convert UTC to psTime. * - * Converts UTC time to psTime. This function assumes the input time already is in TAI time and add or - * subtracts the necessary leapseconds. + * Converts UTC time to psTime. This function assumes the input time already + * is in TAI time and add or subtracts the necessary leapseconds. * * @return psTime: time in TAI units. */ - -psTime psUTCToTime(psTime time - /** Input time to be converted. */ - ); +psTime psUTCToTime( + psTime time ///< Input time to be converted. +); /** Convert MJD to psTime. * - * Converts MJD time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psMJDToTime(double time - /** Input time to be converted. */ - ); + * Converts MJD time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psMJDToTime( + double time ///< Input time to be converted. +); /** Convert JD to psTime. * - * Converts JD time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psJDToTime(double time - /** Input time to be converted. */ - ); + * Converts JD time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psJDToTime( + double time ///< Input time to be converted. +); /** Convert timeval to psTime. * - * Converts timeval time to psTime. This function assumes the input time already is in TAI time and does not - * add or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psTimevalToTime(struct timeval *time - /** Input time to be converted. */ - ); + * Converts timeval time to psTime. This function assumes the input time + * already is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psTimevalToTime( + struct timeval *time ///< Input time to be converted. +); /** Convert tm time to psTime. * - * Converts tm time to psTime. This function assumes the input time already is in TAI time and does not add - * or subtract leapseconds. - * - * @return psTime: time. - */ - -psTime psTMToTime(struct tm *time - /** Input time to be converted. */ - ); + * Converts tm time to psTime. This function assumes the input time already + * is in TAI time and does not add or subtract leapseconds. + * + * @return psTime: time. + */ +psTime psTMToTime( + struct tm *time ///< Input time to be converted. +); /// @} Index: /trunk/psLib/src/collections/psMetadata.h =================================================================== --- /trunk/psLib/src/collections/psMetadata.h (revision 1495) +++ /trunk/psLib/src/collections/psMetadata.h (revision 1496) @@ -11,6 +11,6 @@ * @author Ross Harman, MHPCC * -* @version $Revision: 1.19 $ $Name: not supported by cvs2svn $ -* @date $Date: 2004-08-09 23:40:54 $ +* @version $Revision: 1.20 $ $Name: not supported by cvs2svn $ +* @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -34,16 +34,16 @@ */ typedef enum { - PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items - PS_META_BOOL, ///< Boolean data. - PS_META_S32, ///< Signed 32-bit integer data. - PS_META_F32, ///< Single-precision float data. - PS_META_F64, ///< Double-precision float data. - PS_META_STR, ///< String data (Stored in as void *). - PS_META_IMG, ///< Image data (Stored in as void *). - PS_META_JPEG, ///< JPEG data (Stored in as void . - PS_META_PNG, ///< PNG data (Stored in as void *). - PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). - PS_META_UNKNOWN, ///< Other data (Stored in as void *). - PS_META_NTYPE ///< Number of types. Must be last. + PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items + PS_META_BOOL, ///< Boolean data. + PS_META_S32, ///< Signed 32-bit integer data. + PS_META_F32, ///< Single-precision float data. + PS_META_F64, ///< Double-precision float data. + PS_META_STR, ///< String data (Stored in as void *). + PS_META_IMG, ///< Image data (Stored in as void *). + PS_META_JPEG, ///< JPEG data (Stored in as void *). + PS_META_PNG, ///< PNG data (Stored in as void *). + PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). + PS_META_UNKNOWN, ///< Other data (Stored in as void *). + PS_META_NTYPE ///< Number of types. Must be last. } psMetadataType; @@ -55,16 +55,16 @@ typedef struct psMetadataItem { - const int id; ///< Unique ID for metadata item. - char *restrict name; ///< Name of metadata item. - psMetadataType type; ///< Type of metadata item. + const int id; ///< Unique ID for metadata item. + char *restrict name; ///< Name of metadata item. + psMetadataType type; ///< Type of metadata item. union { - bool B; - psS32 S32; ///< Signed 32-bit integer data. - psF32 F32; ///< Single-precision float data. - psF64 F64; ///< Double-precision float data. - psPTR V; ///< Pointer to other type of data. - } data; ///< Union for data types. - char *comment; ///< Optional comment ("", not NULL). - psList* restrict items; ///< List of psMetadataItems with same name. + bool B; ///< boolean data + psS32 S32; ///< Signed 32-bit integer data. + psF32 F32; ///< Single-precision float data. + psF64 F64; ///< Double-precision float data. + psPTR V; ///< Pointer to other type of data. + } data; ///< Union for data types. + char *comment; ///< Optional comment ("", not NULL). + psList* restrict items; ///< List of psMetadataItems with same name. } psMetadataItem; @@ -72,12 +72,13 @@ /** Metadata data structure. * - * Struct for holding metadata items. Metadata items are held in two containers. The first employs a - * doubly-linked list to preserve the order of the metadata. The second container employs a hash table which - * allows fast lookup when given a metadata keyword. + * Struct for holding metadata items. Metadata items are held in two + * containers. The first employs a doubly-linked list to preserve the order + * of the metadata. The second container employs a hash table which + * allows fast lookup when given a metadata keyword. */ typedef struct psMetadata { - psList* restrict list; - psHash* restrict table; + psList* restrict list; ///< the metadata in linked-list + psHash* restrict table; ///< the metadata in a hash table } psMetadata; @@ -91,120 +92,135 @@ /** Create a metadata item. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAlloc(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAlloc( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); /** Create a metadata item with va_list. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAllocV(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - va_list list ///< Arguments for name formatting and metadata item - // data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAllocV( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + va_list list ///< Arguments for name formatting and metadata item data. +); /** Create a metadata collection. * - * Returns an empty metadata container with fully allocated internal metadata containers. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataAlloc(void ///< Void. - ); + * Returns an empty metadata container with fully allocated internal metadata + * containers. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataAlloc(void); /** Add existing metadata item to metadata collection. * - * Add a metadata item that has already been created to the metadata collection. + * Add a metadata item that has already been created to the metadata + * collection. + * + * @return bool: True for success, false for failure. + */ +bool psMetadataAddItem( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + psMetadataItem* restrict item ///< Metadata item to be added. +); + +/** Create and add a metadata item to metadata collection. + * + * Creates a new metadata item add to the metadata collection. * * @return bool: True for success, false for failure. */ -bool psMetadataAddItem(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - psMetadataItem* restrict item ///< Metadata item to be added. - ); - -/** Create and add a metadata item to metadata collection. - * - * Creates a new metadata item add to the metadata collection. +bool psMetadataAdd( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); + +/** Remove an item from metadata collection. + * + * Items may be removed from metadata by specifing a key or location. If the + * name is null, the where argument is used instead. If name is not null, + * where is set to PS_LIST_UNKNOWN. If the item is found, it is removed from + * the metadata and true is returned. If the key is not unique, then all + * items corresponding to it are removed. * * @return bool: True for success, false for failure. */ -bool psMetadataAdd(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); - -/** Remove an item from metadata collection. - * - * Items may be removed from metadata by specifing a key or location. If the name is null, the where argument - * is used instead. If name is not null, where is set to PS_LIST_UNKNOWN. If the item is found, it is removed - * from the metadata and true is returned. If the key is not unique, then all items corresponding to it are - * removed. - * - * @return bool: True for success, false for failure. - */ -bool psMetadataRemove(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be removed. - const char *restrict key ///< Name of metadata key. - ); +bool psMetadataRemove( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be removed. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on key name. * - * Items may be found in the metadata by providing a key. If the key is non-unique, the first item is - * returned. If the item is not found, null is returned. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataLookup(psMetadata* restrict md, ///< Metadata collection to insert metadat - // item. - const char *restrict key ///< Name of metadata key. - ); + * Items may be found in the metadata by providing a key. If the key is + * non-unique, the first item is returned. If the item is not found, null is + * returned. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataLookup( + psMetadata* restrict md, ///< Metadata collection to insert metadata item. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on list index. * - * Items may be found in the metadata by their entry position in the list container. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataGet(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where ///< Location to be retrieved. - ); + * Items may be found in the metadata by their entry position in the list + * container. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataGet( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where ///< Location to be retrieved. +); /** Set or reset metadata iterator. * - * Metadata may be iterated by setting or resetting an iterator to a location in the metadata list. + * Metadata may be iterated by setting or resetting an iterator to a location + * in the metadata list. * * @return void: void. */ -bool psMetadataSetIterator(psMetadata* restrict md, ///< Metadata collection to iterate. - int where ///< Location of iterator. - ); +bool psMetadataSetIterator( + psMetadata* restrict md, ///< Metadata collection to iterate. + int where ///< Location of iterator. +); /** Get next metadata item. @@ -214,8 +230,9 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetNext(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetNext( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Get previous metadata item. @@ -225,48 +242,55 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetPrevious(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetPrevious( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Print metadata item to file. * - * Metadata items may be printed to an open file descriptor based on a provided format. The format is a - * sprintf format statement with exactly one % formatting command. If the metadata item type is a numeric - * type, this formatting command must also be numeric, and the type conversion performed to the value to match - * the format type. If the metadata type is a string, the fromatting command must also be for a string. If the - * metadata type is any other data type, printing is not allowed. - * - * @return psMetadataItem* : Pointer metadata item. - */ -void psMetadataItemPrint(FILE * fd, ///< Pointer to file to write metadata item. - const char *format, ///< Format to print metadata item. - const psMetadataItem* restrict metadataItem ///< Metadata item to print. - ); + * Metadata items may be printed to an open file descriptor based on a + * provided format. The format is a sprintf format statement with exactly + * one % formatting command. If the metadata item type is a numeric type, + * this formatting command must also be numeric, and the type conversion + * performed to the value to match the format type. If the metadata type is + * a string, the fromatting command must also be for a string. If the + * metadata type is any other data type, printing is not allowed. + * + * @return psMetadataItem* : Pointer metadata item. + */ +void psMetadataItemPrint( + FILE * fd, ///< Pointer to file to write metadata item. + const char *format, ///< Format to print metadata item. + const psMetadataItem* restrict metadataItem ///< Metadata item to print. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. This file is currently - * unimplemented. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extname, ///< File name extension string. - int extnum, ///< File name extension number. Starts at 1. - char *filename ///< Name of file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. This file is currently unimplemented. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extname, ///< File name extension string. + int extnum, ///< File name extension number. Starts at 1. + char *filename ///< Name of file to read. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataFReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extName, ///< File name extension string. - int extNum, ///< File name extension number. - fitsfile * fd ///< Pointer to file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataFReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extName, ///< File name extension string. + int extNum, ///< File name extension number. + fitsfile * fd ///< Pointer to file to read. +); /// @} Index: /trunk/psLib/src/types/psMetadata.h =================================================================== --- /trunk/psLib/src/types/psMetadata.h (revision 1495) +++ /trunk/psLib/src/types/psMetadata.h (revision 1496) @@ -11,6 +11,6 @@ * @author Ross Harman, MHPCC * -* @version $Revision: 1.19 $ $Name: not supported by cvs2svn $ -* @date $Date: 2004-08-09 23:40:54 $ +* @version $Revision: 1.20 $ $Name: not supported by cvs2svn $ +* @date $Date: 2004-08-12 01:23:20 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -34,16 +34,16 @@ */ typedef enum { - PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items - PS_META_BOOL, ///< Boolean data. - PS_META_S32, ///< Signed 32-bit integer data. - PS_META_F32, ///< Single-precision float data. - PS_META_F64, ///< Double-precision float data. - PS_META_STR, ///< String data (Stored in as void *). - PS_META_IMG, ///< Image data (Stored in as void *). - PS_META_JPEG, ///< JPEG data (Stored in as void . - PS_META_PNG, ///< PNG data (Stored in as void *). - PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). - PS_META_UNKNOWN, ///< Other data (Stored in as void *). - PS_META_NTYPE ///< Number of types. Must be last. + PS_META_ITEM_SET = 0, ///< Null. Metadata is in psMetadataItem.items + PS_META_BOOL, ///< Boolean data. + PS_META_S32, ///< Signed 32-bit integer data. + PS_META_F32, ///< Single-precision float data. + PS_META_F64, ///< Double-precision float data. + PS_META_STR, ///< String data (Stored in as void *). + PS_META_IMG, ///< Image data (Stored in as void *). + PS_META_JPEG, ///< JPEG data (Stored in as void *). + PS_META_PNG, ///< PNG data (Stored in as void *). + PS_META_ASTROM, ///< Astrometric coefficients (Stored in as void *). + PS_META_UNKNOWN, ///< Other data (Stored in as void *). + PS_META_NTYPE ///< Number of types. Must be last. } psMetadataType; @@ -55,16 +55,16 @@ typedef struct psMetadataItem { - const int id; ///< Unique ID for metadata item. - char *restrict name; ///< Name of metadata item. - psMetadataType type; ///< Type of metadata item. + const int id; ///< Unique ID for metadata item. + char *restrict name; ///< Name of metadata item. + psMetadataType type; ///< Type of metadata item. union { - bool B; - psS32 S32; ///< Signed 32-bit integer data. - psF32 F32; ///< Single-precision float data. - psF64 F64; ///< Double-precision float data. - psPTR V; ///< Pointer to other type of data. - } data; ///< Union for data types. - char *comment; ///< Optional comment ("", not NULL). - psList* restrict items; ///< List of psMetadataItems with same name. + bool B; ///< boolean data + psS32 S32; ///< Signed 32-bit integer data. + psF32 F32; ///< Single-precision float data. + psF64 F64; ///< Double-precision float data. + psPTR V; ///< Pointer to other type of data. + } data; ///< Union for data types. + char *comment; ///< Optional comment ("", not NULL). + psList* restrict items; ///< List of psMetadataItems with same name. } psMetadataItem; @@ -72,12 +72,13 @@ /** Metadata data structure. * - * Struct for holding metadata items. Metadata items are held in two containers. The first employs a - * doubly-linked list to preserve the order of the metadata. The second container employs a hash table which - * allows fast lookup when given a metadata keyword. + * Struct for holding metadata items. Metadata items are held in two + * containers. The first employs a doubly-linked list to preserve the order + * of the metadata. The second container employs a hash table which + * allows fast lookup when given a metadata keyword. */ typedef struct psMetadata { - psList* restrict list; - psHash* restrict table; + psList* restrict list; ///< the metadata in linked-list + psHash* restrict table; ///< the metadata in a hash table } psMetadata; @@ -91,120 +92,135 @@ /** Create a metadata item. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAlloc(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAlloc( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); /** Create a metadata item with va_list. * - * Returns a fill psMetadataItem ready for insertion into the psMetadata struct. The name argument specifies - * the name to use for this item, and may include sprintf formatting codes. The format entry specifies both - * the metadata type and optional flags and is created by bit-wise or of the appropriate type and flag. The - * comment argument is a fixed string used to comment the metadata item. The arguments to the name formatting - * codes and the metadata itself are passed as arguments following the comment string. The data must be - * a pointer for any of the elements stored in data.void. The argument list must be interpreted appropriately - * by the va_list operators in the function. - * specified size and type. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataItemAllocV(const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - va_list list ///< Arguments for name formatting and metadata item - // data. - ); + * Returns a fill psMetadataItem ready for insertion into the psMetadata + * struct. The name argument specifies the name to use for this item, and + * may include sprintf formatting codes. The format entry specifies both + * the metadata type and optional flags and is created by bit-wise or of the + * appropriate type and flag. The comment argument is a fixed string used to + * comment the metadata item. The arguments to the name formatting codes and + * the metadata itself are passed as arguments following the comment string. + * The data must be a pointer for any of the elements stored in data.void. + * The argument list must be interpreted appropriately by the va_list + * operators in the function specified size and type. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataItemAllocV( + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + va_list list ///< Arguments for name formatting and metadata item data. +); /** Create a metadata collection. * - * Returns an empty metadata container with fully allocated internal metadata containers. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataAlloc(void ///< Void. - ); + * Returns an empty metadata container with fully allocated internal metadata + * containers. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataAlloc(void); /** Add existing metadata item to metadata collection. * - * Add a metadata item that has already been created to the metadata collection. + * Add a metadata item that has already been created to the metadata + * collection. + * + * @return bool: True for success, false for failure. + */ +bool psMetadataAddItem( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + psMetadataItem* restrict item ///< Metadata item to be added. +); + +/** Create and add a metadata item to metadata collection. + * + * Creates a new metadata item add to the metadata collection. * * @return bool: True for success, false for failure. */ -bool psMetadataAddItem(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - psMetadataItem* restrict item ///< Metadata item to be added. - ); - -/** Create and add a metadata item to metadata collection. - * - * Creates a new metadata item add to the metadata collection. +bool psMetadataAdd( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be added. + const char *name, ///< Name of metadata item. + psMetadataType type, ///< Type of metadata item. + const char *comment, ///< Comment for metadata item. + ... ///< Arguments for name formatting and metadata item data. +); + +/** Remove an item from metadata collection. + * + * Items may be removed from metadata by specifing a key or location. If the + * name is null, the where argument is used instead. If name is not null, + * where is set to PS_LIST_UNKNOWN. If the item is found, it is removed from + * the metadata and true is returned. If the key is not unique, then all + * items corresponding to it are removed. * * @return bool: True for success, false for failure. */ -bool psMetadataAdd(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be added. - const char *name, ///< Name of metadata item. - psMetadataType type, ///< Type of metadata item. - const char *comment, ///< Comment for metadata item. - ... ///< Arguments for name formatting and metadata item data. - ); - -/** Remove an item from metadata collection. - * - * Items may be removed from metadata by specifing a key or location. If the name is null, the where argument - * is used instead. If name is not null, where is set to PS_LIST_UNKNOWN. If the item is found, it is removed - * from the metadata and true is returned. If the key is not unique, then all items corresponding to it are - * removed. - * - * @return bool: True for success, false for failure. - */ -bool psMetadataRemove(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where, ///< Location to be removed. - const char *restrict key ///< Name of metadata key. - ); +bool psMetadataRemove( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where, ///< Location to be removed. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on key name. * - * Items may be found in the metadata by providing a key. If the key is non-unique, the first item is - * returned. If the item is not found, null is returned. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataLookup(psMetadata* restrict md, ///< Metadata collection to insert metadat - // item. - const char *restrict key ///< Name of metadata key. - ); + * Items may be found in the metadata by providing a key. If the key is + * non-unique, the first item is returned. If the item is not found, null is + * returned. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataLookup( + psMetadata* restrict md, ///< Metadata collection to insert metadata item. + const char *restrict key ///< Name of metadata key. +); /** Find an item in the metadata collection based on list index. * - * Items may be found in the metadata by their entry position in the list container. - * - * @return psMetadataItem* : Pointer metadata item. - */ -psMetadataItem* psMetadataGet(psMetadata* restrict md, ///< Metadata collection to insert metadat item. - int where ///< Location to be retrieved. - ); + * Items may be found in the metadata by their entry position in the list + * container. + * + * @return psMetadataItem* : Pointer metadata item. + */ +psMetadataItem* psMetadataGet( + psMetadata* restrict md, ///< Metadata collection to insert metadat item. + int where ///< Location to be retrieved. +); /** Set or reset metadata iterator. * - * Metadata may be iterated by setting or resetting an iterator to a location in the metadata list. + * Metadata may be iterated by setting or resetting an iterator to a location + * in the metadata list. * * @return void: void. */ -bool psMetadataSetIterator(psMetadata* restrict md, ///< Metadata collection to iterate. - int where ///< Location of iterator. - ); +bool psMetadataSetIterator( + psMetadata* restrict md, ///< Metadata collection to iterate. + int where ///< Location of iterator. +); /** Get next metadata item. @@ -214,8 +230,9 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetNext(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetNext( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Get previous metadata item. @@ -225,48 +242,55 @@ * @return psMetadataItem* : Pointer metadata item. */ -psMetadataItem* psMetadataGetPrevious(psMetadata* restrict md, ///< Metadata collection to iterate. - const char *restrict match, ///< Beginning of key name. - int which ///< Iterator to be used. - ); +psMetadataItem* psMetadataGetPrevious( + psMetadata* restrict md, ///< Metadata collection to iterate. + const char *restrict match, ///< Beginning of key name. + int which ///< Iterator to be used. +); /** Print metadata item to file. * - * Metadata items may be printed to an open file descriptor based on a provided format. The format is a - * sprintf format statement with exactly one % formatting command. If the metadata item type is a numeric - * type, this formatting command must also be numeric, and the type conversion performed to the value to match - * the format type. If the metadata type is a string, the fromatting command must also be for a string. If the - * metadata type is any other data type, printing is not allowed. - * - * @return psMetadataItem* : Pointer metadata item. - */ -void psMetadataItemPrint(FILE * fd, ///< Pointer to file to write metadata item. - const char *format, ///< Format to print metadata item. - const psMetadataItem* restrict metadataItem ///< Metadata item to print. - ); + * Metadata items may be printed to an open file descriptor based on a + * provided format. The format is a sprintf format statement with exactly + * one % formatting command. If the metadata item type is a numeric type, + * this formatting command must also be numeric, and the type conversion + * performed to the value to match the format type. If the metadata type is + * a string, the fromatting command must also be for a string. If the + * metadata type is any other data type, printing is not allowed. + * + * @return psMetadataItem* : Pointer metadata item. + */ +void psMetadataItemPrint( + FILE * fd, ///< Pointer to file to write metadata item. + const char *format, ///< Format to print metadata item. + const psMetadataItem* restrict metadataItem ///< Metadata item to print. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. This file is currently - * unimplemented. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extname, ///< File name extension string. - int extnum, ///< File name extension number. Starts at 1. - char *filename ///< Name of file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. This file is currently unimplemented. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extname, ///< File name extension string. + int extnum, ///< File name extension number. Starts at 1. + char *filename ///< Name of file to read. +); /** Read metadata header. * - * Read a metadata header from file. If the file is not found, an error is reported. - * - * @return psMetadata* : Pointer metadata. - */ -psMetadata* psMetadataFReadHeader(psMetadata* output, ///< Resulting metadata from read. - char *extName, ///< File name extension string. - int extNum, ///< File name extension number. - fitsfile * fd ///< Pointer to file to read. - ); + * Read a metadata header from file. If the file is not found, an error is + * reported. + * + * @return psMetadata* : Pointer metadata. + */ +psMetadata* psMetadataFReadHeader( + psMetadata* output, ///< Resulting metadata from read. + char *extName, ///< File name extension string. + int extNum, ///< File name extension number. + fitsfile * fd ///< Pointer to file to read. +); /// @}