Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 1512) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 1513) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.65 2004-08-10 23:08:40 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.66 2004-08-12 04:19:18 price Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -3652,519 +3652,6 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Astronomical Images} - -\subsubsection{Overview} - -Above, we have defined a basic container for a single 2D collection of -pixels (\code{psImage}), along with basic operations to manipulate the -image pixels. For astronomical applications, this data structure is -insufficient for two reasons. First, it does provide sufficient -additional metadata to describe the data in detail. Second, astronomy -applications frequent involve multiple, related images. For -PanSTARRS, and for general astronomical applications, we require a -richer collection of data structures which describe a very general -image concept. We have defined several layers in the hierarchy which -are necessary to describe the image data which will be produced by the -PanSTARRS Gigapixel cameras as well as other standard astronomical -images. - -A simple 2D image is a basic data unit for much of astronomical -imaging. If we consider various optical and IR array cameras, a -single readout of the detector produces a collection of pixels -measurements. We define our lowest-level astronomical image -structure, \code{psReadout}, to contain the pixels produced by a -single readout of the detector, along with metadata needed to define -that readout: the origin and binning of the image relative to the -original detector pixels explicitly in the structure, and pointers to -the general metadata and derived objects, if any. - -A single detector may produce more than one read which is associated. -For example, infrared detectors frequently produce an image -immediately after the detector is reset followed by an image after the -basic exposure is complete. Both readouts correspond to the same -pixels, though the binning or rastering may be different between the -two readouts. Another example is the video sequence produced by the -PanSTARRS Gigapix camera guide cells, each of which represents a -series of many images from a subraster of pixels in the detector -readout portion. The second level of our image container hierarchy, -\code{psCell}, consists of a collection of readouts from a single -detector. - -In the PanSTARRS Gigapix camera, the basic readout region is a -fraction of the full imaging area of a single CCD chip. The chip is -divided into 64 cells, any fraction of which may have been readout -for a given exposure. In other cameras, such as Megacam at CFHT, the -individual CCDs have multiple amplifiers addressing contiguous -portions of the detector. In such cameras, each amplifier produces a -separate collection of pixels. In the third level of our image -container hierarchy, the data structure \code{psChip} represents a -collection of different cells. - -The top level of our image container hierarchy is a complete focal -plane array (\code{psFPA}). This structure represents the collection -of chips in the camera, all of which are read out in a given -exposure. - -For example, take a mosaic camera consisting of eight $2k\times 4k$ -CCDs, each of which is read out through two amplifiers. Then there -would be sixteen cells in total, each of which is presumably $2k\times -2k$. There would be eight chips, each consisting of two cells, and -the focal plane consists of these eight chips. - -As another example, consider an observation by PS1. The focal plane -would consist of 60 chips, each of which consist of 64 cells (or less; -a few cells may be dead). Some cells (those containing guide stars -for the orthogonal transfer) will contain multiple readouts. - -These data structures represent containers with which to carry around -the collection of related image data. There is no requirement on the -functions or the structures that each instance of one of these data -structures represent the physical hardware. For example, it is not -necessary that an instance of \code{psFPA} always carry the data for -all 60 (or 64) Gigapixel camera OTAs. The usage of these structures -is such that all astronomical operations which apply to a CCD image -should be performed on an instance of \code{psFPA}. If a particular -circumstance only requires a single 2D image, then that is represented -by an instance of \code{psFPA} with one \code{psChip}, which in turn -has one \code{psCell}, which in turn has one \code{psReadout}. - -These container levels also include in their definition the information -needed to transform the coordinates in one of the levels to the -coordinate system relevant at the higher levels. - -\subsubsection{A Readout} - -A readout is the result of a single read of a cell (or a portion -thereof). It contains a pointer to the pixel data, and additional -pointers to the objects found in the readout, and the readout -metadata. It also contains the offset from the lower-left corner of -the chip, in the case that the CCD was windowed. - -\begin{verbatim} -typedef struct { - const int x0, y0; ///< Offset from the lower-left corner - const int nx, ny; ///< Image binning - psImage *image; ///< imaging area of cell - psList *objects; ///< objects derived from cell - psMetadata *md; ///< Readout-level metadata -} psReadout; -\end{verbatim} - -\subsubsection{A Cell} - -A cell consists of one or more readouts (usually only one except in the -case that the cell has been used for fast guiding). It also contains -a pointer to the cell metadata, and a pointer to its parent chip. On -the astrometry side, it also contains coordinate transforms from the -cell to the chip and, as a convenience, from the cell to the focal -plane. It is expected that these transforms will consist of two -first-order 2D polynomials, simply specifying a translation, rotation -and magnification; hence they are easily inverted, and there is no -need to add reverse transformations. We also add an additional -transformation, which is intended to provide a ``quick and dirty'' -transform from the cell coordinates to the sky; this transformation -not guaranteed to be as precise as the ``standard'' transformation of -Cell $\rightarrow$ Chip $\rightarrow$ Focal Plane $\rightarrow$ -Tangent Plane $\rightarrow$ Sky, but will be faster. - -\begin{verbatim} -typedef struct { - int nReadouts; ///< number of readouts in this cell - struct psReadout *readouts; ///< Readouts from the cell - psMetadata *md; ///< Cell-level metadata - psPlaneTransform *cellToChip; ///< Transformations from cell to chip coords - psPlaneTransform *cellToFPA; ///< Transformations from cell to FPA coords - psPlaneTransform *cellToSky; ///< Direct from cell to sky coords - struct psChip *parentChip; ///< chip which contains this cell -} psCell; -\end{verbatim} - -\subsubsection{A Chip} - -A chip consists of one or more cells (according to the number of -amplifiers on the CCD). It contains a pointer to the chip metadata, -and a pointer to the parent focal plane. For astrometry, it contains -a coordinate transform from the chip to the focal plane. It is -expected that this transforms will consist of two second-order 2D -polynomials; hence we think that it is prudent to include a reverse -transformation which will be derived from numerically inverting the -forward transformation. - -\begin{verbatim} -typedef struct { - int nCells; ///< Number of Cells assigned - struct psCell *cells; ///< Cells in the Chip - psMetadata *md; ///< Chip-level metadata - psPlaneTransform *chipToFPA; ///< Transformations from chip to FPA coords - psPlaneTransform *FPAtoChip; ///< Transformations from FPA to chip - struct psFPA *parentFPA; ///< FPA which contains this chip -} psChip; -\end{verbatim} - -\subsubsection{A Focal Plane} - -A focal plane consists of one or more chips (according to the number -of pieces of contiguous silicon). It contains pointers to the focal -plane metadata and the exposure information. For astrometry, it -contains a transformation from the focal plane to the tangent plane -and the fixed pattern residuals. It is expected that the -transformation will consist of two 4D polynomials (i.e.\ a function of -two coordinates in position, the magnitude of the object, and the -color of the object) in order to correct for optical distortions and -the effects of the atmosphere; hence we think that it is prudent to -include a reverse transformation which will be derived from -numerically inverting the forward transformation. Since colors are -involved in the transformation, it is necessary to specify the color -the transformation is defined for. We also include some values to -characterize the quality of the transformation: the root mean square -deviation for the x and y transformation fits, and the $\chi^2$ for -the transformation fit. - -\begin{verbatim} -typedef struct { - int nChips; ///< Number of Cells assigned - int nAlloc; ///< Number of Cells available - struct psChip *chips; ///< Chips in the Focal Plane Array - psMetadata *md; ///< FPA-level metadata - psPlaneDistort *TPtoFP; ///< Transformation term from - psPlaneDistort *FPtoTP; ///< Transformation term from - psFixedPattern *pattern; ///< Fixed pattern residual offsets - const psExposure *exp; ///< information about this exposure - psPhotSystem colorPlus, colorMinus; ///< Colour reference - float rmsX, rmsY; ///< Dispersion in astrometric solution - float chi2; ///< chi^2 of astrometric solution -} psFPA; -\end{verbatim} - -\subsubsection{Exposure information} - -We need several quantities from the telescope in order to make a -first guess at the astrometric solution. From these quantities, -further quantities can be derived and stored for later use. - -\begin{verbatim} -typedef struct { - const double ra, dec; ///< Telescope boresight - const double ha; ///< Hour angle - const double zd; ///< Zenith distance - const double az; ///< Azimuth - const double lst; ///< Local Sidereal Time - const float mjd; ///< MJD of observation - const float rotAngle; ///< Rotator position angle - const float temp; ///< Air temperature, for estimating refraction - const float pressure; ///< Air pressure, for calculating refraction - const float humidity; ///< Relative humidity, for refraction - const float exptime; ///< Exposure time - /* Derived quantities */ - const float posAngle; ///< Position angle - const float parallactic; ///< Parallactic angle - const float airmass; ///< Airmass, calculated from zenith distance - const float pf; ///< Parallactic factor - const char *cameraName; ///< name of camera which provided exposure - const char *telescopeName; ///< name of telescope which provided exposure -} psExposure; -\end{verbatim} - -\subsubsection{Constructors and Destructors} - -Each of the above structures needs an appropriate constructor and -destructor. Other than \code{psExposure}, which contains significant -non-pointer types, the constructors should not take any arguments, and -the destructors should only take the structure to be destroyed. -The constructor for \code{psExposure} is specified below. - -\begin{verbatim} -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 -\end{verbatim} - -\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. - -\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: SLALib transformation using a -transform pre-computed 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{SLALib information} - -SLALib requires several elements to perform the transformations -between the tangent plane and the sky. Pre-computing these quantities -for each exposure means that subsequent transformations are faster. -For historical reasons, this structure is known colloquially as -``Wallace's 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: -\begin{verbatim} -psGrommit *psGrommitAlloc(const psExposure *exp); -void p_psGrommitFree(psGrommit *grommit); -\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} - -\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 (psCell *out, const psPlane *coord, const psFPA *fpa); -psChip *psChipInFPA (psChip *out, const psPlane *coord, const psFPA *fpa); -psCell *psCellInChip(psCell *out, 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); -\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); -\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, const psFPA *fpa); -\end{verbatim} -which converts coordinates \code{in} on the specified focal plane -\code{fpa} to tangent plane coordinates, applying the appropriate -distortion terms. - -\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); -\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, 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. - -\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.cellToSky}. 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, const psFPA *fpa); -\end{verbatim} -which converts the tangent plane coordinates \code{in} to focal plane coordinates. - -\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, 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. - -\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.cellToSky}. -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, double siderealTime, float height); -\end{verbatim} -which returns the airmass for a given position and sidereal time. - -\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?}. +%%% Astronomical Images and Astrometry +\include{psLibSDRS_Astrom} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%