Index: trunk/archive/pslib/include/psAstrom.h =================================================================== --- trunk/archive/pslib/include/psAstrom.h (revision 247) +++ trunk/archive/pslib/include/psAstrom.h (revision 251) @@ -1,4 +1,4 @@ -#if !defined(PS_ASTROM_H) -#define PS_ASTROM_H +# if !defined(PS_ASTROM_H) +# define PS_ASTROM_H /** \file psAstrom.h @@ -7,211 +7,220 @@ */ +/** Astrometric solution for an OTA. + * There are five coordinate frames that we need to worry about: + * 1. Cell frame: x,y in pixels (raw coordinates; lower-left pixel center is 0.5,0.5 TBR) + * 2. Chip frame: X,Y in pixels + * 3. FPA frame: P,Q in microns + * 4. Tangent plane: L,M in arcsec (TBR - angles or linear?) from the telescope boresight. + * 5. Sky frame: R,D in degrees (TBR - radians?) + * + * 1 <--> 2: cell.coords : a 2-D linear transformation : rotation, scaling, offset, (skew) + * 2 <--> 3: chip.coords : a 2-D cubic (max) transform : specifies how the chips are mounted on the focal plane. + * 3 <--> 4: fpa.distort : a 2-D quartic (?) transform : specifies the distortions in the optics + * 4 <--> 5: fpa.SLpars : SLALib parameters generated based on the telescope, ra, dec, time, etc from exposure info + */ + +/** Information needed (by SLALIB) to convert Apparent to Observed Position */ +typedef struct { + double latitude; ///< geodetic latitude (radians) + double sinLat, cosLat; ///< sine and cosine of geodetic latitude + double abberationMag; ///< magnitude of diurnal aberration vector + double height; ///< height (HM) + double temperature; ///< ambient temperature (TDK) + double pressure; ///< pressure (PMB) + double humidity; ///< relative humidity (RH) + double wavelength; ///< wavelength (WL) + double lapseRate; ///< lapse rate (TLR) + double refractA, refractB; ///< refraction constants A and B (radians) + double longitudeOffset; ///< longitude + eqn of equinoxes + ``sidereal UT'' (radians) + double siderealTime; ///< local apparent sidereal time (radians) +} psGrommit; + +/** Exposure information from the telescope */ +typedef struct { + // Telescope longitude, latitude and height are stored separately, since they don't change with pointing + double ra, dec; //!< Telescope boresight + double ha; //!< Hour angle + double zd; //!< Zenith distance + double az; //!< Azimuth + double lst; //!< Local Sidereal Time + float mjd; //!< MJD of observation + float rotAngle; //!< Rotator position angle + float temp; //!< Air temperature, for estimating refraction + float pressure; //!< Air pressure, for calculating refraction + float humidity; //!< Relative humidity, for calculating refraction + float exptime; //!< Exposure time + /* Derived quantities */ + float posAngle; //!< Position angle + float parallactic; //!< Parallactic angle + float airmass; //!< Airmass, calculated from zenith distance + float pf; //!< Parallactic factor + char *cameraName; ///< name of camera which provided exposure + char *telescopeName; ///< name of telescope which provided exposure + psGrommit *grommit; //!< Data needed to convert from the sky to the tangent plane +} psExposure; + +/** a Focal plane array: a collection of chips. Not all chips in a camera need to be listed in an instance of + * psFPA. + */ +typedef struct { + int nChips; ///< Number of Cells assigned + int nAlloc; ///< Number of Cells available + psChip *chips; ///< Chips in the Focal Plane Array + psMetaData *md; ///< FPA-level metadata + psDistort *TPtoFP; ///< Transformation term from + psDistort *FPtoTP; ///< Transformation term from + psExposure *exp; ///< information about this exposure + psMatrix *dx, *dy; //!< Focal Plane fixed pattern residual offsets + psPhotSystem colorPlus, colorMinus; ///< Colour reference + float rmsX, rmsY; //!< Dispersion in astrometric solution + float chi2; //!< chi^2 of astrometric solution +} psFPA; + +/** a Chip: a collection of cells. Not all valid cells in a chip need to be listed in an + * instance of psChip. + */ +typedef struct { + int nCells; ///< Number of Cells assigned + psCell *cells; ///< Cells in the Chip + psMetaData *md; ///< Chip-level metadata + + psCoordXform *chipToFPA; ///< Transformations from chip coordinates to FPA coordinates + psCoordXform *FPAtoChip; ///< Transformations from chip coordinates to FPA coordinates + + psFPA *parentFPA; ///< FPA which contains this chip +} psChip; + +/** a Cell: a collection of pixels. + */ +typedef struct { + psObjectTable *objects; ///< objects derived from cell + psImage *image; ///< imaging area of cell + psImage *overscan; ///< bias region (subimage) of cell + psMetaData *md; ///< Cell-level metadata + + psCoordXform *cellToChip; ///< Transformations from cell coordinates to chip coordinates + psCoordXform *cellToFPA; ///< Transformations from cell coordinates to FPA coordinates + + psChip *parentChip; ///< chip which contains this cell +} psCell; + +/*** Functions ***********************************************************************/ + /***********************************************************************************************************/ -/** Exposure information from the telescope */ -typedef struct { - // Telescope longitude, latitude and height are stored separately, since they don't change with pointing - double ra, dec; //!< Telescope boresight - double ha; //!< Hour angle - double zd; //!< Zenith distance - double az; //!< Azimuth - double lst; //!< Local Sidereal Time - float mjd; //!< MJD of observation - float rotAngle; //!< Rotator position angle - float temp; //!< Air temperature, for estimating refraction - float pressure; //!< Air pressure, for calculating refraction - float humidity; //!< Relative humidity, for calculating refraction - float exptime; //!< Exposure time - /* Derived quantities */ - float posAngle; //!< Position angle - float parallactic; //!< Parallactic angle - float airmass; //!< Airmass, calculated from zenith distance - float pf; //!< Parallactic factor -} psExposure; +/* Calculating and applying astrometric solutions */ + +/** returns Cell in Chip which contains the given point */ +int +psCellInChip (psChip *chip, ///< chip description + psCoords *coords ///< coordinate to find + ); + +/** returns the Cell coords for the specified Cell corresponding to the given Chip coords */ +psCoords +psChipCoordsOnCell (psCell *cell, ///< source cell for coordinate + psCoords *coords ///< coordinate of interest + ); + +/** returns the Cell coords for the specified Cell corresponding to the given Chip coords */ +psCoords +psCellCoordsInChip (psChip *chip, ///< + int cell, ///< + psCoords *coords ///< + ); + +/** returns Chip in FPA which contains the given point */ +int +psChipInFPA (psFPA *fpa, ///< + psCoords *coords ///< + ); + +/** returns the Chip coords for the specified Chip corresponding to the given FPA coords */ +psCoords +psFPACoordsOnChip (psChip *chip, ///< + psCoords *coords ///< + ); + +/** returns the Chip coords for the specified Chip corresponding to the given FPA coords */ +psCoords +psChipCoordsInFPA (psFPA *fpa, ///< + int chip, ///< + psCoords *coords ///< + ); + +/** Convert (RA,Dec) to (cell#,x,y) */ +psCoords * +psSkyToFPA(psFPA *fpa, //!< OTA details + psCoords *coords //!< Position on the sky + ); + +/** Convert (cell#,x,y) to (RA,Dec) */ +psCoords * +psFPAToSky(psFPA *fpa, //!< OTA details + psCoords *coords //!< Position on the sky + ); + +/** Convert (RA,Dec) to (cell#,x,y) */ +psCoords * +psSkyToTP(psExposure *exp, //!< OTA details + psCoords *coords //!< Position on the sky + ); + +/** Convert (RA,Dec) to (cell#,x,y) */ +psCoords * +psTPtoSky(psExposure *exp, //!< OTA details + psCoords *coords //!< Position on the sky + ); + +/** Get the airmass for a given position and sidereal time */ +float +psGetAirmass(psCoords *coords, //!< Position on the sky + double siderealTime //!< Sidereal time + ); + +/** Get the parallactic angle for a given position and sidereal time */ +float +psGetParallactic(psCoords *coords, //!< Position on the sky + double siderealTime //!< Sidereal time + ); + +/** Estimate atmospheric refraction, along the parallactic */ +float +psGetRefraction(float colour, //!< Colour of object + psColourRef colourRef, //!< Colour reference + psExposure *exp //!< Telescope pointing information, for airmass, temp and pressure + ); + +/** Fit astrometric solution to list of (chip#,x,y) and (RA,Dec) */ +int +psFitAstrom(psOTADescription *restrict ota, //!< Initial guess for coefficients + const psOTAPosArray *restrict detector, //!< Positions on OTA (chip#,x,y) + const psSkyPosArray *restrict sky, //!< Positions on the sky (RA,Dec) + const psExposure *exp //!< Telescope pointing information, for airmass, parallactic angle + //!< which may help set the astrometric solution + ); + +/*** Constructors / Destructors ******************************************************/ /** Constructor */ psExposure * -psExposureAlloc(double ra, double dec, //!< Telescope boresight - double ha, //!< Hour angle - double zd, //!< Zenith distance - double az, //!< Azimuth - double lst, //!< Local Sidereal Time - float mjd, //!< MJD - float rotAngle, //!< Rotator position angle - float temp, //!< Temperature - float pressure, //!< Pressure - float humidity, //!< Relative humidity - float exptime //!< Exposure time - ); +psExposureAlloc(double ra, double dec, //!< Telescope boresight + double ha, //!< Hour angle + double zd, //!< Zenith distance + double az, //!< Azimuth + double lst, //!< Local Sidereal Time + float mjd, //!< MJD + float rotAngle, //!< Rotator position angle + float temp, //!< Temperature + float pressure, //!< Pressure + float humidity, //!< Relative humidity + float exptime //!< Exposure time + ); /** Destructor */ void psExposureFree(psExposure *restrict myExp //!< Object to destroy - ); - - -/***********************************************************************************************************/ - -/** Cell details: specifies how the cell is mounted on its parent OTA */ -typedef struct { - double x, y; //!< Position of cell in its OTA. Specifies the position of the - //!< (imaginary) pixel (0,0) - double xErr, yErr; //!< Error in position of cell in the OTA. - double rotation; //!< Rotation of cell in its OTA. Specified from +x through +y - int xSize, ySize; //!< Number of pixels in x and y - double scale; //!< Relative pixel scales, if CCD pitch varies over the OTA. Specify - //!< a positive scale for a left-handed coordinate system, negative - //!< for right. If NULL, then every chip has identical scale, and - //!< system is left-handed. -} psCellDescription; - -/** Constructor */ -psCellDescription * -psCellDescriptionAlloc(void); - -/** Destructor */ -void -psCellDescriptionFree(psCellDescription *restrict myCell //!< Cell description to destroy - ); - -/***********************************************************************************************************/ - -/** Array of cell descriptions */ -typedef struct { - psType type; //!< Type of data. THIS STRUCT ELEMENT MUST BE FIRST IN THE STRUCT! - int size; //!< Total number of elements available - int n; //!< Number of elements in use - double *arr; //!< The array data -} psCellDescriptionArray; - -/** Constructor */ -psCellDescriptionArray *psCellDescriptionArrayAlloc(int s, //!< Total number of elements to make available - int n //!< Number of elements that will be used - ); -/** Reallocator */ -psCellDescriptionArray *psCellDescriptionArrayRealloc(psCellDescriptionArray *myArray, //!< Array to - //!< reallocate - int s //!< Total number of elements to make available - ); -/** Destructor */ -void psCellDescriptionArrayFree(psCellDescriptionArray *restrict myArray //!< Array to free - ); - -/***********************************************************************************************************/ - -/** OTA details: specifies how the OTA is mounted on the focal plane */ -typedef struct { - double x, y; //!< Position of OTA on the focal plane. Specifies the position of - //!< the bottom left-hand corner. - double xErr, yErr; //!< Error in the position of the OTA. - double rotation; //!< Rotation of OTA on the focal plane. Specified from +x through +y - psCellDescriptionArray *restrict cells; //!< Cell descriptions - struct psOTAAstrom *astrom; //!< OTA astrometry - psExposure *exp; //!< Exposure data -} psOTADescription; - -/** Constructor */ -psOTADescription * -psOTADescriptionAlloc(void); - -/** Destructor. */ -void -psOTADescriptionFree(psOTADescription *restrict myOTA //!< OTA description to destroy - ); - -/***********************************************************************************************************/ - -/** Astrometric solution for an OTA. - * There are four coordinate frames that we need to worry about: - * 1. Chip frame: chip# plus x,y in pixels - * 2. Focal plane frame: X,Y in microns - * 3. Tangent plane: xi,eta in arcsec from the telescope boresight. - * 4. Sky frame: RA,Dec - * - * 1 <--> 2: OTA description (parent of this struct) specifies how the chips are mounted on the focal plane. - * 2 <--> 3: The astrometric solution corrects for distortions in the optics so we can go from what the - * telescope sees on the focal plane to what it really should be like (i.e. the tangent plane). - * 3 <--> 4: SLALib converts between the tangent plane and the celestial sphere using a set of numbers one - * must calculate for each tangent point. - * - * Coordinate frames 2 and 3 are generally hidden from the user because all they care about is going between - * frames 1 and 4. - */ -typedef struct { - /* Focal plane to and from tangent plane */ - psDPolynomial4D *restrict tpToFPX, *restrict tpToFPY; //!< General astrometric solution for tangent plane - //!< to focal plane - psDPolynomial4D *restrict fpToTPXi, *restrict fpToTPEta; //!< General astrometric solution for focal plane - //!< to tangent plane - psMatrix *pattern; //!< Fixed pattern distortions for focal plane to tangent plane (simply - //!< * -1 for the reverse); MAY NEED TO BE REVISED UPON IMPLEMENTATION - /* Tangent plane to and from the celestial sphere */ - psDoubleArray *restrict tp; //!< Data needed to convert from the sky to the tangent plane and back; - //!< produced by and used by SLALib (a.k.a. "Wallace's Grommit") - psColourRef colorRef; //!< Colour reference - /* Characterisation of the solution */ - float rmsX, rmsY; //!< Dispersion in astrometric solution - float chi2; //!< chi^2 of astrometric solution -} psOTAAstrom; - -/** Constructor */ -psOTAAstrom * -psOTAAstromAlloc(const psExposure *exp //!< Telescope pointing, used to initialise the tp data. - ); - -/** Destructor */ -void -psOTAAstromFree(psOTAAstrom *restrict myAstrom //!< Object to destroy - ); - -/***********************************************************************************************************/ - -/* Calculating and applying astrometric solutions */ - -/** Convert (RA,Dec) to (cell#,x,y) */ -psOTAPos * -psSkyToOTA(const psSkyPos *restrict position, //!< Position on the sky - const psOTADescription *restrict ota //!< OTA details - ); - -/** Convert (cell#,x,y) to (RA,Dec) */ -psSkyPos * -psOTAToSky(const psOTAPos *restrict position, //!< Position on the detector - const psOTADescription *restrict ota //!< OTA details - ); - -/** Fit astrometric solution to list of (chip#,x,y) and (RA,Dec) */ -int -psFitAstrom(psOTADescription *restrict ota, //!< Initial guess for coefficients - const psOTAPosArray *restrict detector, //!< Positions on OTA (chip#,x,y) - const psSkyPosArray *restrict sky, //!< Positions on the sky (RA,Dec) - const psExposure *exp //!< Telescope pointing information, for airmass, parallactic angle - //!< which may help set the astrometric solution - ); - -/***********************************************************************************************************/ - -/* Functions needed for astrometry, and will likely be useful elsewhere */ - -/** Get the airmass for a given position and sidereal time */ -float -psGetAirmass(const psSkyPos *restrict position, //!< Position on the sky - double siderealTime //!< Sidereal time - ); - -/** Get the parallactic angle for a given position and sidereal time */ -float -psGetParallactic(const psSkyPos *restrict position, //!< Position on the sky - double siderealTime //!< Sidereal time - ); - -/** Estimate atmospheric refraction, along the parallactic */ -float -psGetRefraction(float colour, //!< Colour of object - psColourRef colourRef, //!< Colour reference - psExposure *exp //!< Telescope pointing information, for airmass, temp and pressure - ); - -/***********************************************************************************************************/ + ); #endif