Index: trunk/doc/pslib/psLibSDRS_Astrom.tex =================================================================== --- trunk/doc/pslib/psLibSDRS_Astrom.tex (revision 3181) +++ trunk/doc/pslib/psLibSDRS_Astrom.tex (revision 3564) @@ -270,5 +270,5 @@ \code{TRUE} if they are all correctly assigned, otherwise \code{FALSE}. -\subsubsection{Coordinate Transformations} +\subsubsection{Detector Coordinate Transformations} \begin{figure} @@ -322,12 +322,271 @@ \end{verbatim} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -% add psExposure to metadata? -% add grommit to metadata? -% add photsystem data to metadata? -% add statistics to metadata? - -\subsubsection{Observatory data} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Astrometry} + +Astrometry is a basic functionality required for the IPP that will be +used repeatedly, both for low-precision (roughly where is my favorite +object?) and high-precision (what is the proper motion of this star?). +As such, it must be flexible, yet robust. + +\subsubsection{Coordinate frames} +\label{sec:coordinateFrames} + +There are five coordinate frames that we need to worry about for the +purposes of astrometry: +\begin{itemize} +\item Cell: $(x,y)$ in pixels --- raw coordinates; +\item Chip: $(X,Y)$ in pixels --- the location on the silicon; +\item Focal Plane: $(p,q)$ in microns --- the location on the focal plane; +\item Tangent Plane: $(l,m)$ in arcsec from the telescope boresight; and +\item Sky: (RA,Dec) --- ICRS. +\end{itemize} + +The following steps are required to convert from the cell coordinates to +the sky: +\begin{itemize} +\item Cell $\longleftrightarrow$ Chip: two 2D polynomials, $(X,Y) = f(x,y)$; +\item Chip $\longleftrightarrow$ FP: two 2D polynomials, $(p,q) = g(X,Y)$; +\item FP $\longleftrightarrow$ TP: two 4D polynomials, $(l,m) = +h(p,q,m,c)$, where $m$ and $c$ are the magnitude and color of the +object, respectively; and +\item TP $\longleftrightarrow$ Sky: transformation to the sky using +pre-computed coefficients for each pointing. +\end{itemize} + +Note that the transformation between the Focal Plane and the Tangent +Plane is a four-dimensional polynomial, in order to account for any +possible dependencies in the astrometry on the stellar magnitude and +color; the former serves as a check for charge transfer +inefficiencies, while the latter will correct chromatic refraction, +both through the atmosphere and the corrector lenses. + +We require structures to contain each of the above transformations as +well as the pixel data. + +\subsubsection{Position Finding} + +We require functions to return the structure containing given +coordinates. For example, we want the chip that corresponds to the +focal plane coordinates $(p,q) = (-1.234,+5.678)$. These routines +handle the one-to-many problem --- i.e., for one given focal plane +coordinate, there are many chips that this coordinate may be +correspond to; these functions will select the correct one. +% +\begin{verbatim} +psCell *psCellInFPA (const psPlane *coord, const psFPA *fpa); +psChip *psChipInFPA (const psPlane *coord, const psFPA *fpa); +psCell *psCellInChip(const psPlane *coord, const psChip *chip); +\end{verbatim} + +\subsubsection{Conversion Functions} + +We require functions to convert between the various coordinate frames +(Section~\ref{sec:coordinateFrames}). The hierarchy of the coordinate +frames and the transformations between each are shown in +Figure~\ref{fig:coco}. The functions that employ the transformations +are shown in Figure~\ref{fig:cocoFunc}. In addition to +transformations between each adjoining coordinate frame in the +hierarchy, we also require higher-level functions to convert between +the Cell and Sky coordinate frames; these will simply perform the +intermediate steps. + +\begin{figure} +\psfig{file=coordinateFrames,height=7in,angle=-90} +\caption{The coordinate systems in the \PS{} IPP, and the relation +between each by transformations contained in the appropriate +structures.} +\label{fig:coco} +\end{figure} + +\begin{figure} +\psfig{file=coordinateConv,height=7in,angle=-90} +\caption{Conversion between coordinate systems by PSLib.} +\label{fig:cocoFunc} +\end{figure} + +We specify the following functions to convert between coordinates in +one type of frame to another type of frame. The first group consist +of unambiguous transformations: from the coordinates in a low-level +frame to the coordinates in the containing higher-level frame, of +which only one exists. In all of these functions, the output +coordinate structure may be \code{NULL} or may be supplied by the +calling function. In the former case, the structure must be +allocated; in the latter case, the supplied structure must be used. + +\begin{verbatim} +psPlane *psCoordCellToChip (psPlane *out, const psPlane *in, const psCell *cell); +% astrometry comes from cell (no need for parent) +\end{verbatim} +which converts coordindates \code{in} on the specified \code{cell} to +the coordinates on the parent chip. + +\begin{verbatim} +psPlane *psCoordChipToFPA (psPlane *out, const psPlane *in, const psChip *chip); +% astrometry comes from chip (no need for parent) +\end{verbatim} +which converts the coordinates \code{in} on the specified \code{chip} +to the coordinates on the parent FPA. + +\begin{verbatim} +psPlane *psCoordFPAToTP(psPlane *out, const psPlane *in, float color, float mag, const psFPA *fpa); +% astrometry comes from FPA (no need for parent) +\end{verbatim} +which converts coordinates \code{in} on the specified focal plane +\code{fpa} to tangent plane coordinates, applying the appropriate +distortion terms. The \code{color} and magnitude (\code{mag}) of the +source is necessary in order to perform the distortion between the +focal plane and the tangent plane. + +\begin{verbatim} +psSphere *psCoordTPToSky(psSphere *out, const psPlane *in, const psGrommit *grommit); +\end{verbatim} +which converts the tangent plane coordinates \code{in} to (RA,Dec) on +the sky, based on the environmental information specified by +\code{grommit}. + +% astrometry comes from cell +\begin{verbatim} +psPlane *psCoordCellToFPA(psPlane *out, const psPlane *in, const psCell *cell); +\end{verbatim} +which performs the single-step conversion between Cell coordinates +\code{in} and FPA coordinates. + +% astrometry comes from cell,chip,fpa (PARENT IS NEEDED HERE) +\begin{verbatim} +psSphere *psCoordCellToSky(psSphere *out, const psPlane *in, float color, float mag, const psCell *cell); +\end{verbatim} +which converts coordinates on the specified cell to (RA,Dec). This +transformation must be performed using the intermediate stage +transformations of Cell to Chip, Chip to FPA, FPA to Tangent Plane, +Tangent Plane to Sky. The information needed for each of these +transformations is available in the \code{.parent} elements of +\code{psCell} and \code{psChip}, and the \code{psFPA.exposure} +element. The \code{color} and magnitude (\code{mag}) of the source is +necessary in order to perform the distortion between the focal plane +and the tangent plane. + +% astrometry comes from cell (no need for parent) +\begin{verbatim} +psSphere *psCoordCellToSkyQuick(psSphere *out, const psPlane *in, const psCell *cell); +\end{verbatim} +which uses the 'quick-and-dirty' transformation to convert coordinates +on the specified cell to (RA,Dec). This transformation should use the +locally linear transformation specified by the element +\code{psCell.toTP}. Although the accuracy of this transformation +is lower than the complete transformation above, the calculation is +substantially faster as it only involves linear transformations. + +The following functions convert from high-level frames to the +coordinates of contained lower-level frames. + +\begin{verbatim} +psPlane *psCoordSkyToTP(psPlane *out, const psSphere *in, const psGrommit *grommit); +\end{verbatim} +which converts (RA,Dec) coordinates \code{in} to tangent plane coords +based on the enviromental information supplied by \code{grommit}. + +\begin{verbatim} +psPlane *psCoordTPToFPA(psPlane *out, const psPlane *in, float color, float mag, const psFPA *fpa); +\end{verbatim} +which converts the tangent plane coordinates \code{in} to focal plane +coordinates. The \code{color} and magnitude (\code{mag}) of the +source is necessary in order to perform the distortion between the +focal plane and the tangent plane. + +\begin{verbatim} +psPlane *psCoordFPAToChip (psPlane *out, const psPlane *in, const psChip *chip); +\end{verbatim} +which converts the specified FPA coordinates \code{in} to the +coordinates on the given Chip. The specified chip need not contain +the input coordinate. To find the chip which contains a particular +coordinate, the function \code{psChipInFPA}, defined above, should be +used. + +\begin{verbatim} +psPlane *psCoordChipToCell (psPlane *out, const psPlane *in, const psCell *cell); +\end{verbatim} +which converts the specified Chip coordinate \code{in} to the +coordinate on the given Cell. The specified Cell need not contain the +input coordinate. To find the cell which contains a particular +coordinate, the function \code{psCellInChip}, defined above, should be +used. + +\begin{verbatim} +psPlane *psCoordSkyToCell(psPlane *out, const psSphere *in, float color, float mag, psCell *cell); +\end{verbatim} +which directly converts (RA,Dec) \code{in} to coordinates on the +specified cell. The specified cell need not contain the input +coordinates. The \code{color} and magnitude (\code{mag}) of the +source is necessary in order to perform the distortion between the +focal plane and the tangent plane. + +\begin{verbatim} +psPlane *psCoordSkyToCellQuick(psPlane *out, const psSphere *in, psCell *cell); +\end{verbatim} +which directly converts (RA,Dec) \code{in} to coordinates on the +specified cell. The specified cell need not contain the input +coordinates. This transformation should use the locally linear +transformation specified by the element \code{psCell.toTP}. +Although the accuracy of this transformation is lower than the +complete transformation above, the calculation is substantially faster +as it only involves linear transformations. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Astrometry and World Coordinate System} + +The FITS World Coordinate System (WCS) headers are commonly employed +with astronomical images in order to relate pixels to celestial (or +otherwise) coordinates. Since it is a FITS standard, we must be able +to read and write from WCS into our internal format. For the time +being, we will consider only celestial WCS (i.e., no spectral +wavelength calibrations, etc). Because WCS does not support the +multiple layers that we have built for \PS{}, we will use a simple +internal representation: a transformation, which handles any +distortions (i.e., goes directly from the coordinate frame of the +image to the tangent plane); and the projection. + +\begin{verbatim} +bool psAstrometryReadWCS(psPlaneTransform **transform, // Output transformation + psProjection **projection, // Output projection + psMetadata *header // Input FITS header + ); +bool psAstrometryWriteWCS(psMetadata *header, // Output FITS header + psPlaneTransform *transform, // Input transformation + psProjection *projection, // Input projection + double color, // Mean color to use + double magnitude, // Mean magnitude to use + ); +bool psAstrometrySimplify(psPlaneTransform **transform, // Output transformation + psProjection **projection, // Output projection + psCell *cell // Cell for which to generate transform and projection + ); +\end{verbatim} + +\code{pmReadAstrometry} shall parse the specified FITS \code{header}, +returning new instances of the \code{transform} and \code{projection} +that represent the WCS. The function shall return \code{true} if it +was able to successfully generate the outputs; otherwise it shall +return \code{false}. + +\code{pmWriteAstrometry} shall add WCS keywords to the supplied FITS +\code{header} that implement the given \code{transform} and +\code{projection}. The function shall return \code{true} if it was +able to successfully generate the output; otherwise it shall return +\code{false}. + +\code{pmSimplifyAstrometry} shall take a \code{cell} and simplify the +internal astrometric representation (\code{cell->toFPA} or equivalent, +\code{cell->parent->parent->toTangentPlane} and +\code{cell->parent->parent->grommit}) to a single \code{transform} and +\code{projection}. This allows the subsequent use of +\code{pmWriteAstrometry} in the case that we have only the +multi-layered \PS{} internal astrometric representation. The function +shall return \code{true} if it was able to successfully generate the +output; otherwise it shall return \code{false}. + +\subsection{Observatory data} We need a container for the observatory data that doesn't change per @@ -350,5 +609,5 @@ \end{verbatim} -\subsubsection{Exposure information} +\subsection{Exposure information} We need several quantities from the telescope in order to make a @@ -388,369 +647,2 @@ \end{verbatim} -\subsubsection{Environmental Information} - -A-priori astrometric transformations between the tangent plane and the -sky require several pieces of information describing the current -environmental conditions. These quantities are consistent from image -to image, and may vary only slowly with time. Pre-computing these -quantities for exposures means that subsequent transformations are -faster. The structure below carries the environment data of interest. -For historical reasons, this structure is known colloquially as ``the -Grommit''. - -\begin{verbatim} -typedef struct { - const double latitude; ///< geodetic latitude (radians) - const double sinLat, cosLat; ///< sine and 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, refractB; ///< refraction constants A and B (radians) - const double longitudeOffset; ///< longitude + ... (radians) - const double siderealTime; ///< local apparent sidereal time (radians) -} psGrommit; -\end{verbatim} - -The \code{psGrommit} is calculated from telescope information for the -particular exposure, \code{exp}: -\begin{verbatim} -psGrommit *psGrommitAlloc(const psExposure *exp); -\end{verbatim} - -\subsubsection{Fixed Pattern} - -The fixed pattern is a correction to the general astrometric solution -formed by summing the residuals from many observations. The intent is -to correct for higher-order distortions in the camera system on a -coarse grid (larger than individual pixels, but smaller than a single -cell). Hence, in addition to the offsets, we need to specify the size -and scale of the grid in $x$ and $y$, as well as the origin of the -grid. - -\begin{verbatim} -typedef struct { - int nX, nY; ///< Number of elements in x and y - double x0, y0; ///< Position of 0,0 corner on focal plane - double xScale, yScale; ///< Scale of the grid - double **x, **y; ///< The grid of offsets in x and y -} psFixedPattern; -\end{verbatim} - -The constructor for \code{psFixedPattern} shall be: -\begin{verbatim} -psFixedPattern *psFixedPatternAlloc(double x0, double y0, - double xScale, double yScale, - const psImage *x, const psImage *y); -\end{verbatim} -Here, \code{x0}, \code{y0}, \code{xScale} and \code{yScale} have the -same meaning as in the \code{psFixedPattern} structure. Note that the -values of the fixed pattern offsets are specified as images, the -values from which need to be copied into the \code{double **x} and -\code{double **y} of \code{psFixedPattern}, and that the number of -elements may be derived from the size of the images. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\subsection{Astrometry} - -Astrometry is a basic functionality required for the IPP that will be -used repeatedly, both for low-precision (roughly where is my favorite -object?) and high-precision (what is the proper motion of this star?). -As such, it must be flexible, yet robust. Accordingly, we will wrap -the StarLink Astronomy Libraries (SLALib), which has already been -developed. \tbd{SLAlib functions will be replaced in the next -release}. - -\subsubsection{Coordinate frames} -\label{sec:coordinateFrames} - -There are five coordinate frames that we need to worry about for the -purposes of astrometry: -\begin{itemize} -\item Cell: $(x,y)$ in pixels --- raw coordinates; -\item Chip: $(X,Y)$ in pixels --- the location on the silicon; -\item Focal Plane: $(p,q)$ in microns --- the location on the focal plane; -\item Tangent Plane: $(l,m)$ in arcsec from the telescope boresight; and -\item Sky: (RA,Dec) --- ICRS. -\end{itemize} - -The following steps are required to convert from the cell coordinates to -the sky: -\begin{itemize} -\item Cell $\longleftrightarrow$ Chip: two 2D polynomials, $(X,Y) = f(x,y)$; -\item Chip $\longleftrightarrow$ FP: two 2D polynomials, $(p,q) = g(X,Y)$; -\item FP $\longleftrightarrow$ TP: two 4D polynomials, $(l,m) = -h(p,q,m,c)$, where $m$ and $c$ are the magnitude and color of the -object, respectively; and -\item TP $\longleftrightarrow$ Sky: transformation to the sky using -pre-computed coefficients for each pointing. -\end{itemize} - -Note that the transformation between the Focal Plane and the Tangent -Plane is a four-dimensional polynomial, in order to account for any -possible dependencies in the astrometry on the stellar magnitude and -color; the former serves as a check for charge transfer -inefficiencies, while the latter will correct chromatic refraction, -both through the atmosphere and the corrector lenses. - -We require structures to contain each of the above transformations as -well as the pixel data. - -\subsubsection{Position Finding} - -We require functions to return the structure containing given -coordinates. For example, we want the chip that corresponds to the -focal plane coordinates $(p,q) = (-1.234,+5.678)$. These routines -handle the one-to-many problem --- i.e., for one given focal plane -coordinate, there are many chips that this coordinate may be -correspond to; these functions will select the correct one. -% -\begin{verbatim} -psCell *psCellInFPA (const psPlane *coord, const psFPA *fpa); -psChip *psChipInFPA (const psPlane *coord, const psFPA *fpa); -psCell *psCellInChip(const psPlane *coord, const psChip *chip); -\end{verbatim} - -\subsubsection{Conversion Functions} - -We require functions to convert between the various coordinate frames -(Section~\ref{sec:coordinateFrames}). The hierarchy of the coordinate -frames and the transformations between each are shown in -Figure~\ref{fig:coco}. The functions that employ the transformations -are shown in Figure~\ref{fig:cocoFunc}. In addition to -transformations between each adjoining coordinate frame in the -hierarchy, we also require higher-level functions to convert between -the Cell and Sky coordinate frames; these will simply perform the -intermediate steps. - -\begin{figure} -\psfig{file=coordinateFrames,height=7in,angle=-90} -\caption{The coordinate systems in the \PS{} IPP, and the relation -between each by transformations contained in the appropriate -structures.} -\label{fig:coco} -\end{figure} - -\begin{figure} -\psfig{file=coordinateConv,height=7in,angle=-90} -\caption{Conversion between coordinate systems by PSLib.} -\label{fig:cocoFunc} -\end{figure} - -We specify the following functions to convert between coordinates in -one type of frame to another type of frame. The first group consist -of unambiguous transformations: from the coordinates in a low-level -frame to the coordinates in the containing higher-level frame, of -which only one exists. In all of these functions, the output -coordinate structure may be \code{NULL} or may be supplied by the -calling function. In the former case, the structure must be -allocated; in the latter case, the supplied structure must be used. - -\begin{verbatim} -psPlane *psCoordCellToChip (psPlane *out, const psPlane *in, const psCell *cell); -% astrometry comes from cell (no need for parent) -\end{verbatim} -which converts coordindates \code{in} on the specified \code{cell} to -the coordinates on the parent chip. - -\begin{verbatim} -psPlane *psCoordChipToFPA (psPlane *out, const psPlane *in, const psChip *chip); -% astrometry comes from chip (no need for parent) -\end{verbatim} -which converts the coordinates \code{in} on the specified \code{chip} -to the coordinates on the parent FPA. - -\begin{verbatim} -psPlane *psCoordFPAToTP(psPlane *out, const psPlane *in, float color, float mag, const psFPA *fpa); -% astrometry comes from FPA (no need for parent) -\end{verbatim} -which converts coordinates \code{in} on the specified focal plane -\code{fpa} to tangent plane coordinates, applying the appropriate -distortion terms. The \code{color} and magnitude (\code{mag}) of the -source is necessary in order to perform the distortion between the -focal plane and the tangent plane. - -\begin{verbatim} -psSphere *psCoordTPToSky(psSphere *out, const psPlane *in, const psGrommit *grommit); -\end{verbatim} -which converts the tangent plane coordinates \code{in} to (RA,Dec) on -the sky, based on the environmental information specified by -\code{grommit}. - -\begin{verbatim} -psPlane *psCoordCellToFPA(psPlane *out, const psPlane *in, const psCell *cell); -% astrometry comes from cell -\end{verbatim} -which performs the single-step conversion between Cell coordinates -\code{in} and FPA coordinates. - -\begin{verbatim} -psSphere *psCoordCellToSky(psSphere *out, const psPlane *in, float color, float mag, const psCell *cell); -% astrometry comes from cell,chip,fpa (PARENT IS NEEDED HERE) -\end{verbatim} -which converts coordinates on the specified cell to (RA,Dec). This -transformation must be performed using the intermediate stage -transformations of Cell to Chip, Chip to FPA, FPA to Tangent Plane, -Tangent Plane to Sky. The information needed for each of these -transformations is available in the \code{.parent} elements of -\code{psCell} and \code{psChip}, and the \code{psFPA.exposure} -element. The \code{color} and magnitude (\code{mag}) of the source is -necessary in order to perform the distortion between the focal plane -and the tangent plane. - -\begin{verbatim} -psSphere *psCoordCellToSkyQuick(psSphere *out, const psPlane *in, const psCell *cell); -% astrometry comes from cell (no need for parent) -\end{verbatim} -which uses the 'quick-and-dirty' transformation to convert coordinates -on the specified cell to (RA,Dec). This transformation should use the -locally linear transformation specified by the element -\code{psCell.toTP}. Although the accuracy of this transformation -is lower than the complete transformation above, the calculation is -substantially faster as it only involves linear transformations. - -The following functions convert from high-level frames to the -coordinates of contained lower-level frames. - -\begin{verbatim} -psPlane *psCoordSkyToTP(psPlane *out, const psSphere *in, const psGrommit *grommit); -\end{verbatim} -which converts (RA,Dec) coordinates \code{in} to tangent plane coords -based on the enviromental information supplied by \code{grommit}. - -\begin{verbatim} -psPlane *psCoordTPToFPA(psPlane *out, const psPlane *in, float color, float mag, const psFPA *fpa); -\end{verbatim} -which converts the tangent plane coordinates \code{in} to focal plane -coordinates. The \code{color} and magnitude (\code{mag}) of the -source is necessary in order to perform the distortion between the -focal plane and the tangent plane. - -\begin{verbatim} -psPlane *psCoordFPAToChip (psPlane *out, const psPlane *in, const psChip *chip); -\end{verbatim} -which converts the specified FPA coordinates \code{in} to the -coordinates on the given Chip. The specified chip need not contain -the input coordinate. To find the chip which contains a particular -coordinate, the function \code{psChipInFPA}, defined above, should be -used. - -\begin{verbatim} -psPlane *psCoordChipToCell (psPlane *out, const psPlane *in, const psCell *cell); -\end{verbatim} -which converts the specified Chip coordinate \code{in} to the -coordinate on the given Cell. The specified Cell need not contain the -input coordinate. To find the cell which contains a particular -coordinate, the function \code{psCellInChip}, defined above, should be -used. - -\begin{verbatim} -psPlane *psCoordSkyToCell(psPlane *out, const psSphere *in, float color, float mag, psCell *cell); -\end{verbatim} -which directly converts (RA,Dec) \code{in} to coordinates on the -specified cell. The specified cell need not contain the input -coordinates. The \code{color} and magnitude (\code{mag}) of the -source is necessary in order to perform the distortion between the -focal plane and the tangent plane. - -\begin{verbatim} -psPlane *psCoordSkyToCellQuick(psPlane *out, const psSphere *in, psCell *cell); -\end{verbatim} -which directly converts (RA,Dec) \code{in} to coordinates on the -specified cell. The specified cell need not contain the input -coordinates. This transformation should use the locally linear -transformation specified by the element \code{psCell.toTP}. -Although the accuracy of this transformation is lower than the -complete transformation above, the calculation is substantially faster -as it only involves linear transformations. - -\subsubsection{Additional functions} - -We require additional functions to perform general functions which -will be useful for astrometry. Given coordinates on the sky, we -need to get the airmass, the parallactic angle, and an estimate of -the atmospheric refraction. - -\begin{verbatim} -float psGetAirmass(const psSphere *coord, psTime *lst, float height); -\end{verbatim} -which returns the airmass for a given position and local sidereal time -(\code{lst}). - -\begin{verbatim} -float psGetParallactic(const psSphere *coord, double siderealTime); -\end{verbatim} -which returns the parallactic angle for a given position and sidereal time. - -\begin{verbatim} -float psGetRefraction(float colour, ///< Colour of object - psPhotSystem colorPlus, ///< Colour reference - psPhotSystem colorMinus, ///< Colour reference - const psExposure *exp); ///< Telescope pointing information -\end{verbatim} -which provides an estimate of the atmospheric refraction, along the parallactic angle. - -\begin{verbatim} -double psGetParallaxFactor(const psExposure *exp) -\end{verbatim} -Calculate the parallax factor for the given exposure. \tbd{Why do we need this?}. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\subsection{Astrometry and World Coordinate System} - -The FITS World Coordinate System (WCS) headers are commonly employed -with astronomical images in order to relate pixels to celestial (or -otherwise) coordinates. Since it is a FITS standard, we must be able -to read and write from WCS into our internal format. For the time -being, we will consider only celestial WCS (i.e., no spectral -wavelength calibrations, etc). Because WCS does not support the -multiple layers that we have built for \PS{}, we will use a simple -internal representation: a transformation, which handles any -distortions (i.e., goes directly from the coordinate frame of the -image to the tangent plane); and the projection. - -\begin{verbatim} -bool psAstrometryReadWCS(psPlaneTransform **transform, // Output transformation - psProjection **projection, // Output projection - psMetadata *header // Input FITS header - ); -bool psAstrometryWriteWCS(psMetadata *header, // Output FITS header - psPlaneTransform *transform, // Input transformation - psProjection *projection, // Input projection - double color, // Mean color to use - double magnitude, // Mean magnitude to use - ); -bool psAstrometrySimplify(psPlaneTransform **transform, // Output transformation - psProjection **projection, // Output projection - psCell *cell // Cell for which to generate transform and projection - ); -\end{verbatim} - -\code{pmReadAstrometry} shall parse the specified FITS \code{header}, -returning new instances of the \code{transform} and \code{projection} -that represent the WCS. The function shall return \code{true} if it -was able to successfully generate the outputs; otherwise it shall -return \code{false}. - -\code{pmWriteAstrometry} shall add WCS keywords to the supplied FITS -\code{header} that implement the given \code{transform} and -\code{projection}. The function shall return \code{true} if it was -able to successfully generate the output; otherwise it shall return -\code{false}. - -\code{pmSimplifyAstrometry} shall take a \code{cell} and simplify the -internal astrometric representation (\code{cell->toFPA} or equivalent, -\code{cell->parent->parent->toTangentPlane} and -\code{cell->parent->parent->grommit}) to a single \code{transform} and -\code{projection}. This allows the subsequent use of -\code{pmWriteAstrometry} in the case that we have only the -multi-layered \PS{} internal astrometric representation. The function -shall return \code{true} if it was able to successfully generate the -output; otherwise it shall return \code{false}. -