Index: /trunk/doc/pslib/psLibSDRS_Astrom.tex
===================================================================
--- /trunk/doc/pslib/psLibSDRS_Astrom.tex	(revision 1512)
+++ /trunk/doc/pslib/psLibSDRS_Astrom.tex	(revision 1512)
@@ -0,0 +1,581 @@
+\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 of the physical device
+    const int xBin, yBin;               ///< Image binning
+    psImage *image;                     ///< imaging area of cell 
+    psDlist *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 coordinates to chip coordinates
+    psPlaneTransform *cellToFPA;        ///< Transformations from cell coordinates to FPA coordinates
+    psPlaneTransform *cellToSky;        ///< Quick and Dirty transformations from cell coordinates to sky
+    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 coordinates to FPA coordinates
+    psPlaneTransform *FPAtoChip;        ///< Transformations from FPA coordinates 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
+    const psGrommit *grommit;           ///< Information for conversion from TP to Sky.
+    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 psTime *time;                 ///< 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 calculating refraction
+    const float exptime;                ///< Exposure time
+    const float wavelength;             ///< Wavelength of observation
+    const psObservatory *observatory;   ///< Observatory data
+    /* 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{Observatory data}
+
+We need a container for the observatory data that doesn't change per
+exposure.
+
+\begin{verbatim}
+typedef struct {
+    const char *name;                   ///< Name of observatory
+    const double latitude;              ///< Latitude of observatory, east positive
+    const double longitude;             ///< Longitude of observatory
+    const double height;                ///< Height of observatory
+    const double tlr;                   ///< Tropospheric Lapse Rate
+} psObservatory;
+\end{verbatim}
+
+\subsubsection{Constructors}
+
+Each of the above structures needs an appropriate constructor and
+destructor.  In what follows, each of the variables has the same
+meaning as in the appropriate structure.
+
+The constructor for \code{psExposure} shall be:
+\begin{verbatim}
+psExposure *psExposureAlloc(double ra, double dec, double ha, double zd, double az, double lst,
+                            const psTime *time, float rotAngle, float temp, float pressure, float humidity,
+                            float exptime, float wavelength, const psObservatory *observatory);
+\end{verbatim}
+
+The constructor for \code{psObservatory} shall be:
+\begin{verbatim}
+psObservatory *psObservatoryAlloc(const char *name, double latitude, double longitude,
+                                  double height, double tlr);
+\end{verbatim}
+
+The constructor for \code{psFPA} shall be:
+\begin{verbatim}
+psFPA *psFPAAlloc(int nAlloc, const psExposure *exp);
+\end{verbatim}
+The constructor shall make an empty \code{psFPA}, with the
+\code{nAlloc} allocated pointers to \code{psChip}s being set to
+\code{NULL}; all other pointers in the structure shall be initialized
+to \code{NULL}, apart from the \code{grommit}, which shall be
+constructed on the basis of the \code{exp}.
+
+The destructor for \code{psFPA} shall destroy the related
+\code{psGrommit}.
+
+The constructor for \code{psChip} shall be:
+\begin{verbatim}
+psChip *psChipAlloc(int nCells, psFPA *parentFPA);
+\end{verbatim}
+The constructor shall make an empty \code{psChip}, with the
+\code{nCells} allocated pointers to \code{psCell}s being set to
+\code{NULL}; all other pointers in the structure shall be initialized
+to \code{NULL}.
+
+The constructor for \code{psCell} shall be:
+\begin{verbatim}
+psCell *psCellAlloc(int nReadouts, struct psChip *parentChip);
+\end{verbatim}
+The constructor shall make an empty \code{psCell}, with the
+\code{nReadouts} allocated pointers to \code{psReadout}s being set to
+\code{NULL}; all other pointers in the structure shall be initialized
+to \code{NULL}.
+
+The constructor for \code{psReadout} shall be:
+\begin{verbatim}
+psReadout *psReadoutAlloc(int x0, int y0, const psImage *image);
+\end{verbatim}
+All pointers in the structure other than the \code{image} shall be
+initialized to \code{NULL}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\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, \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.
+
+
+\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?}.