IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Jul 14, 2005, 2:54:03 PM (21 years ago)
Author:
Paul Price
Message:

Major changes to configuration, focal plane hierarchy.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/modules/CameraImages.tex

    r4176 r4555  
    1 \section{Astronomical Images}
     1\section{Focal Plane}
     2\label{sec:focalplane}
    23
    34\subsection{Overview}
    45
    5 Above, we have defined a basic container for a single 2D collection of
    6 pixels (\code{psImage}), along with basic operations to manipulate the
    7 image pixels.  For astronomical applications, this data structure is
    8 insufficient for two reasons.  First, it does provide sufficient
    9 additional metadata to describe the data in detail.  Second, astronomy
    10 applications frequent involve multiple, related images.  For
    11 Pan-STARRS, and for general astronomical applications, we require a
    12 richer collection of data structures which describe a very general
    13 image concept.  We have defined several layers in the hierarchy which
    14 are necessary to describe the image data which will be produced by the
    15 Pan-STARRS Gigapixel cameras as well as other standard astronomical
    16 images. 
    17 
    18 A simple 2D image is a basic data unit for much of astronomical
    19 imaging.  If we consider various optical and IR array cameras, a
    20 single readout of the detector produces a collection of pixels
    21 measurements which is well represented as a single 2D image.  We
    22 define our lowest-level astronomical image structure,
    23 \code{psReadout}, to contain the pixels produced by a single readout
    24 of the detector, along with metadata needed to define that readout:
    25 the origin and binning of the image relative to the original detector
    26 pixels explicitly in the structure, and pointers to the general
    27 metadata and derived objects, if any.
     6In PSLib, we have defined a basic container for a single 2D collection
     7of pixels (\code{psImage}), along with basic operations to manipulate
     8the image pixels.  For astronomical applications, this data structure
     9is insufficient for two reasons.  First, it does not provide
     10sufficient additional metadata to describe the data in detail.
     11Second, astronomy applications frequently involve multiple, related
     12images.  For Pan-STARRS, and for general astronomical applications, we
     13require a richer collection of data structures which describe a very
     14general image concept.  We have defined several layers in the
     15hierarchy which are necessary to describe the image data which will be
     16produced by the Pan-STARRS GigaPixel Cameras as well as other standard
     17astronomical images.
     18
     19A simple 2D image is the basic data unit for much of astronomical
     20imaging: if we consider various optical and IR array cameras, a single
     21readout of the detector produces a collection of pixel measurements
     22which is well represented as a single 2D image.  We define our
     23lowest-level astronomical image structure, \code{pmReadout}, to
     24contain the pixels produced by a single readout of the detector, along
     25with metadata needed to define that readout: the origin and binning of
     26the image relative to the original detector pixels explicitly in the
     27structure, and pointers to the general metadata and derived objects,
     28if any.
    2829
    2930A single detector may be read multiple times in sequence.  For
    … …  
    3334though the binning or rastering may be different between the two
    3435readouts.  Another example is the video sequence produced by the
    35 Pan-STARRS Gigapix camera guide cells, each of which represents a
     36Pan-STARRS GigaPixel Camera guide cells, each of which represents a
    3637series of many images from a subraster of pixels in the detector
    3738readout portion.  The second level of our image container hierarchy,
    38 \code{psCell}, consists of a collection of readouts from a single
     39\code{pmCell}, consists of a collection of readouts from a single
    3940detector.
    4041
    41 In the Pan-STARRS Gigapix camera, the basic readout region is a
     42In the Pan-STARRS GigaPixel camera, the basic readout region is a
    4243fraction of the full imaging area of a single CCD chip.  The chip is
    43 divided into 64 cells, any fraction of which may have been readout
    44 for a given exposure.  In other cameras, such as Megacam at CFHT, the
     44divided into 64 cells, any fraction of which may have been readout for
     45a given exposure.  In other cameras, such as Megacam at CFHT, the
    4546individual CCDs have multiple amplifiers addressing contiguous
    4647portions of the detector.  In such cameras, each amplifier produces a
    4748separate collection of pixels.  In the third level of our image
    48 container hierarchy, the data structure \code{psChip} represents a
    49 collection of different cells.   
     49container hierarchy, the data structure \code{pmChip} represents a
     50collection of different cells.
    5051
    5152The top level of our image container hierarchy is a complete focal
    52 plane array (\code{psFPA}).  This structure represents the collection
     53plane array (\code{pmFPA}).  This structure represents the collection
    5354of chips in the camera, all of which are read out in a given
    5455exposure. 
    … …  
    5657For example, take a mosaic camera consisting of eight $2k\times 4k$
    5758CCDs, each of which is read out through two amplifiers.  Then there
    58 would be sixteen cells in total, each of which is presumably $2k\times
    59 2k$.  There would be eight chips, each consisting of two cells, and
     59would be sixteen cells in total, each of which is presumably $1k\times
     604k$.  There would be eight chips, each consisting of two cells, and
    6061the focal plane consists of these eight chips.
    6162
    … …  
    6970functions or the structures that each instance of one of these data
    7071structures represent the physical hardware.  For example, it is not
    71 necessary that an instance of \code{psFPA} always carry the data for
    72 all 60 (or 64) Gigapixel camera OTAs.  The usage of these structures
    73 is such that all astronomical operations which apply to a CCD image
    74 should be performed on an instance of \code{psFPA}.  If a particular
     72necessary that an instance of \code{pmFPA} always carry the data for
     73all 60 GigaPixel Camera OTAs.  The usage of these structures is such
     74that all astronomical operations which apply to a CCD image should be
     75performed on an instance of \code{pmFPA}.  If a particular
    7576circumstance only requires a single 2D image, then that is represented
    76 by an instance of \code{psFPA} with one \code{psChip}, which in turn
    77 has one \code{psCell}, which in turn has one \code{psReadout}. 
     77by an instance of \code{pmFPA} with one \code{pmChip}, which in turn
     78has one \code{pmCell}, which in turn has one \code{pmReadout}.
    7879
    7980The data structures defined below provide two additional features
    8081beyond the hierarchy of relationships.  First, each level of the
    81 hierarchy includes a generic \code{psMetadata} pointer to provide
    82 whatever metadata would be appropriate for that level.  The functions
    83 within PSLib do not specify the contents of those metadata containers.
    84 One example of their usage is provided in the documentation for the
    85 Pan-STARRS IPP collection of data processing modules. 
     82hierarchy includes hooks for carrying metadata to provide the PS
     83concepts and analysis metadata that would be appropriate for that
     84level.  The functions within PSLib do not specify the contents of
     85those metadata containers.
    8686
    8787While the \code{psMetadata} pointers provide a mechanism to carry
    … …  
    9191information are provided.  In the first case, basic offsets (and in
    9292the case of the readouts, binning and flips) are defined to specify
    93 the location of a given \code{psCell} with respect to its containing
    94 \code{psChip} in the assumption that the pixels in the entire focal
     93the location of a given \code{pmCell} with respect to its containing
     94\code{pmChip} in the assumption that the pixels in the entire focal
    9595plane array are laid out on a uniform grid.  This is a crude
    9696approximation, and cannot be assumed for careful astrometric analysis,
    … …  
    9999transformations between one frame and the next are also provided.
    100100
    101 \tbd{in the future, it may be worthwhile to migrate all of these
     101\tbd{In the future, it may be worthwhile to migrate all of these
    102102additional pieces to the psMetadata since there is no pressing need to
    103103have them visible in the data structures}
    … …  
    108108
    109109A readout is the result of a single read of a cell (or a portion
    110 thereof).  It contains a pointer to the pixel data, and additional
    111 pointers to the objects found in the readout, and the readout
    112 metadata.  It also contains the offset from the lower-left corner of
    113 the chip, in the case that the CCD was windowed.
     110thereof).  It contains the offset from the lower-left corner of
     111the chip, in the case that the CCD was windowed, as well as the
     112binning factors and parity (if the binning value is negative, then
     113the parity is reversed).  It also contains the pixel data, metadata
     114containers for the concepts and analysis, and a link to the parent.
    114115
    115116\begin{verbatim}
    116117typedef struct {
    117     const int col0;                    ///< Offset from the left of cell.
    118     const int row0;                    ///< Offset from the bottom of cell.
    119     const int colParity;               ///< Readout Direction X
    120     const int rowParity;               ///< Readout Direction Y
    121     const unsigned int colBins;        ///< Amount of binning in x-dimension
    122     const unsigned int rowBins;        ///< Amount of binning in y-dimension
    123     psImage* image;                    ///< imaging area of Readout
    124     psMetadata* metadata;              ///< readout-level metadata
    125 } psReadout;
     118    // Position on the cell
     119    int col0;                          // Offset from the left of cell.
     120    int row0;                          // Offset from the bottom of cell.
     121    int colBins;                       // Amount of binning in x-dimension and parity (from sign)
     122    int rowBins;                       // Amount of binning in y-dimension and parity (from sign)
     123    // Information
     124    psImage *image;                    // Imaging area of readout
     125    psMetadata *analysis;              // Readout-level analysis metadata
     126    psMetadata *concepts;              // Cache for PS concepts
     127    pmCell *parent;                    // Parent cell
     128} pmReadout;
    126129\end{verbatim}   
    127130
    128 The constructor for \code{psReadout} shall be:
    129 \begin{verbatim}
    130 psReadout *psReadoutAlloc();
    131 \end{verbatim}
    132 All pointers in the structure shall be initialized to \code{NULL}.
     131The constructor for \code{pmReadout} shall be:
     132\begin{verbatim}
     133pmReadout *pmReadoutAlloc(pmCell *cell);
     134\end{verbatim}
     135The constructor shall make an empty \code{pmReadout}.  If the parent
     136\code{cell} is not \code{NULL}, the \code{parent} link is made and the
     137readout shall be placed in the parent's array of \code{readouts}.  The
     138metadata containers shall be allocated.  All other pointers in the
     139structure shall be initialized to \code{NULL}.
    133140
    134141\subsubsection{A Cell}
    135142
    136 A cell consists of one or more readouts (usually only one except in the
    137 case that the cell has been used for fast guiding).  It also contains
    138 a pointer to the cell metadata, and a pointer to its parent chip.  On
    139 the astrometry side, it also contains coordinate transforms from the
    140 cell to the chip and, as a convenience, from the cell to the focal
    141 plane.  It is expected that these transforms will consist of two
    142 first-order 2D polynomials, simply specifying a translation, rotation
    143 and magnification; hence they are easily inverted, and there is no
    144 need to add reverse transformations.  We also add an additional
    145 transformation, which is intended to provide a ``quick and dirty''
    146 transform from the cell coordinates to the sky; this transformation
    147 not guaranteed to be as precise as the ``standard'' transformation of
    148 Cell $\rightarrow$ Chip $\rightarrow$ Focal Plane $\rightarrow$
    149 Tangent Plane $\rightarrow$ Sky, but will be faster.
     143A cell consists of one or more readouts (usually only one except in
     144the case that the cell has been used for fast guiding, or similar
     145situations).  It have values which specifies the position of the cell
     146on the chip for rough positioning, along with more precise coordinate
     147transforms from the cell to the chip and, as a convenience, from the
     148cell directly to the focal plane.  It is expected that these
     149transforms will consist of two first-order 2D polynomials, simply
     150specifying a translation, rotation and magnification; hence they are
     151easily inverted, and there is no need to add reverse transformations.
     152We also add an additional transformation, which is intended to provide
     153a ``quick and dirty'' transform from the cell coordinates to the sky;
     154this transformation not guaranteed to be as precise as the
     155``standard'' transformation of Cell $\rightarrow$ Chip $\rightarrow$
     156Focal Plane $\rightarrow$ Tangent Plane $\rightarrow$ Sky, but will be
     157faster.  The cell also contains metadata containers for the concepts
     158and analysis, a link to the parent, and pointers to the various FITS
     159data, if that corresponds to this level.
    150160
    151161\begin{verbatim}
    152162typedef struct {
    153     const int col0;                    ///< Offset from the left of chip.
    154     const int row0;                    ///< Offset from the bottom of chip.
    155     psArray* readouts;                 ///< readouts from the cell
    156     psMetadata* metadata;              ///< cell-level metadata
    157     psPlaneTransform* toChip;          ///< transformations from cell to chip coordinates
    158     psPlaneTransform* toFPA;           ///< transformations from cell to FPA coordinates
    159     psPlaneTransform* toSky;           ///< transformations from cell to sky coordinates
    160     psChip *parent;
    161 } psCell;
    162 \end{verbatim}
    163 
    164 The constructor for \code{psCell} shall be:
    165 \begin{verbatim}
    166 psCell *psCellAlloc(int nReadouts, struct psChip *parentChip);
    167 \end{verbatim}
    168 The constructor shall make an empty \code{psCell}, with the
    169 \code{nReadouts} allocated pointers to \code{psReadout}s being set to
    170  \code{NULL}.  If \code{nreadouts} is zero or less, then 1 readout
    171 shall be allocated.  In either case, the value of
    172 \code{psCell.readouts.n} should be initially set to 0.  If the
    173 \code{parentChip} is not NULL, this link is made, otherwise it is set
    174 to \code{NULL}. All other pointers in the structure shall be
    175 initialized to \code{NULL}.
     163    // Offset specifying position on chip
     164    int col0;                          // Offset from the left of chip.
     165    int row0;                          // Offset from the bottom of chip.
     166    // Astrometric transformations
     167    psPlaneTransform* toChip;          // Transformations from cell to chip coordinates
     168    psPlaneTransform* toFPA;           // Transformations from cell to FPA coordinates
     169    psPlaneTransform* toSky;           // Transformations from cell to sky coordinates
     170    // Information
     171    psMetadata *concepts;              // Cache for PS concepts
     172    psMetadata *analysis;              // Cell-level analysis metadata
     173    psArray *readouts;                 // The readouts (referred to by number)
     174    pmChip *parent;                    // Parent chip
     175    // FITS data
     176    const char *extname;               // Extension name, if it corresponds to this level
     177    psArray *pixels;                   // The pixel data, if it corresponds to this level
     178    psMetadata *header;                // The FITS header, if it corresponds to this level
     179} pmCell;
     180\end{verbatim}
     181
     182The constructor for \code{pmCell} shall be:
     183\begin{verbatim}
     184pmCell *pmCellAlloc(pmChip *chip);
     185\end{verbatim}
     186The constructor shall make an empty \code{pmCell}.  If the parent
     187\code{chip} is not \code{NULL}, the \code{parent} link is made and the
     188cell shall be placed in the parent's array of \code{cells}.  The
     189\code{readouts} array shall be allocated with a zero size, and the
     190metadata containers constructed.  All other pointers in the structure
     191shall be initialized to \code{NULL}.
    176192
    177193\subsubsection{A Chip}
    178194
    179195A chip consists of one or more cells (according to the number of
    180 amplifiers on the CCD).  It contains a pointer to the chip metadata,
    181 and a pointer to the parent focal plane.  For astrometry, it contains
    182 a coordinate transform from the chip to the focal plane.  It is
    183 expected that this transforms will consist of two second-order 2D
    184 polynomials; hence we think that it is prudent to include a reverse
    185 transformation which will be derived from numerically inverting the
    186 forward transformation.
     196amplifiers on the device).  The chip contains metadata containers for
     197the concepts and analysis, a link to the parent, and pointers to the
     198various FITS data, if that corresponds to this level.  For astrometry,
     199in addition to the rough positioning information, it contains a
     200coordinate transform from the chip to the focal plane.  It is expected
     201that this transform will consist of two second-order 2D polynomials;
     202hence we think that it is prudent to include a reverse transformation
     203which will be derived from numerically inverting the forward
     204transformation.
    187205
    188206\begin{verbatim}
    189207typedef struct {
    190     const int col0;                    ///< Offset from the left of FPA.
    191     const int row0;                    ///< Offset from the bottom of FPA.
    192     psArray* cells;                    ///< cells in the chip
    193     psMetadata* metadata;              ///< chip-level metadata
    194     psPlaneTransform* toFPA;           ///< transformation from chip to FPA coordinates
    195     psPlaneTransform* fromFPA;         ///< transformation from FPA to chip coordinates
    196     psFPA *parent;
    197 } psChip;
    198 \end{verbatim}
    199 
    200 The constructor for \code{psChip} shall be:
    201 \begin{verbatim}
    202 psChip *psChipAlloc(int nCells, psFPA *parentFPA);
    203 \end{verbatim}
    204 The constructor shall make an empty \code{psChip}, with the
    205  \code{nCells} allocated pointers to \code{psCell}s being set to
    206  \code{NULL}.  If \code{nCells} is zero or less, then 1 cell shall be
    207  allocated.  In either case, the value of \code{psChip.cells.n} should
    208  be initially set to 0.  If the \code{parentFPA} is not NULL, this
    209  link is made, otherwise it is set to \code{NULL}. All other pointers
    210  in the structure shall be initialized to \code{NULL}.
     208    // Offset specifying position on focal plane
     209    int col0;                          // Offset from the left of FPA.
     210    int row0;                          // Offset from the bottom of FPA.
     211    // Astrometric transformations
     212    psPlaneTransform* toFPA;           // Transformation from chip to FPA coordinates
     213    psPlaneTransform* fromFPA;         // Transformation from FPA to chip coordinates
     214    // Information
     215    psMetadata *concepts;              // Cache for PS concepts
     216    psMetadata *analysis;              // Chip-level analysis metadata
     217    psArray *cells;                    // The cells (referred to by name)
     218    pmFPA *parent;                     // Parent FPA
     219    // FITS data
     220    const char *extname;               // Extension name, if it corresponds to this level
     221    psArray *pixels;                   // The pixel data, if it corresponds to this level
     222    psMetadata *header;                // The FITS header, if it corresponds to this level
     223} pmChip;
     224\end{verbatim}
     225
     226The constructor for \code{pmChip} shall be:
     227\begin{verbatim}
     228pmChip *pmChipAlloc(pmFPA *fpa);
     229\end{verbatim}
     230The constructor shall make an empty \code{pmChip}.  If the parent
     231\code{fpa} is not NULL, the \code{parent} link is made and the chip
     232shall be placed in the parent's array of \code{chips}.  The
     233\code{cells} array shall be allocated with a zero size, and the
     234metadata containers constructed. All other pointers in the structure
     235shall be initialized to \code{NULL}.
    211236
    212237\subsubsection{A Focal Plane}
    213238
    214239A focal plane consists of one or more chips (according to the number
    215 of pieces of contiguous silicon).  It contains pointers to the focal
    216 plane metadata and the exposure information.  For astrometry, it
    217 contains a transformation from the focal plane to the tangent plane
     240of pieces of contiguous silicon).  It contains metadata containers for
     241the concepts and analysis, a link to the parent, and pointers to the
     242various FITS data, if that corresponds to this level.  For astrometry,
     243it contains a transformation from the focal plane to the tangent plane
    218244and the fixed pattern residuals.  It is expected that the
    219245transformation will consist of two 4D polynomials (i.e.\ a function of
    … …  
    222248the effects of the atmosphere; hence we think that it is prudent to
    223249include a reverse transformation which will be derived from
    224 numerically inverting the forward transformation.  Since colors are
    225 involved in the transformation, it is necessary to specify the color
    226 the transformation is defined for.  We also include some values to
    227 characterize the quality of the transformation: the root mean square
    228 deviation for the x and y transformation fits, and the $\chi^2$ for
    229 the transformation fit.
     250numerically inverting the forward transformation.
    230251
    231252\begin{verbatim}
    232253typedef struct {
    233     psArray* chips;                    ///< chips in the focal plane array
    234     psMetadata* metadata;              ///< focal-plane's metadata
    235     psPlaneDistort* fromTangentPlane;  ///< transformation from tangent plane to focal plane
    236     psPlaneDistort* toTangentPlane;    ///< transformation from focal plane to tangent plane
    237     psFixedPattern* pattern;           ///< fixed pattern residual offsets
    238     const struct psExposure* exposure; ///< information about this exposure
    239     const psGrommit* grommit;          ///< grommit allows conversion from tangent plane to sky
    240     psPhotSystem* colorPlus;           ///< Color reference
    241     psPhotSystem* colorMinus;          ///< Color reference
    242     float rmsX;                        ///< RMS for x transformation fits
    243     float rmsY;                        ///< RMS for y transformation fits
    244     float chi2;                        ///< chi^2 of astrometric solution
    245 } psFPA;
    246 \end{verbatim}
    247 
    248 The constructor for \code{psFPA} shall be:
    249 \begin{verbatim}
    250 psFPA *psFPAAlloc(int nChips, const psExposure *exp);
    251 \end{verbatim}
    252 The constructor shall make an empty \code{psFPA}, with the
    253 \code{nChips} allocated pointers to \code{psChip}s being set to
    254 \code{NULL}.  If \code{nChips} is zero or less, then 1 chip shall be
    255  allocated.  In either case, the value of \code{psFPA.chips.n} should
    256  be initially set to 0.  If the value of \code{exp} is not
    257  \code{NULL}, this value shall be assigned an used to set the value of
    258  \code{grommit}.  Otherwise both shall be set to \code{NULL}.  All
    259  other pointers in the structure shall be initialized to \code{NULL}.
    260 
    261 Two utility functions are defined to manage the collection of
    262 backward-pointing links:
    263 \begin{verbatim}
    264 bool psFPASetLinks (psFPA *fpa);
    265 bool psFPATestLinks (psFPA *fpa);
    266 \end{verbatim}
    267 The first of these functions constructs the \code{parent} pointers for
    268 all entries in a \code{psFPA} structure.  The second structure checks
    269 the validity of the links in an \code{psFPA} structure and returns
    270 \code{TRUE} if they are all correctly assigned, otherwise \code{FALSE}.
     254    // Astrometric transformations
     255    psPlaneDistort* fromTangentPlane;  // Transformation from tangent plane to focal plane
     256    psPlaneDistort* toTangentPlane;    // Transformation from focal plane to tangent plane
     257    psProjection *projection;          // Projection from tangent plane to sky
     258    // Information
     259    psMetadata *concepts;              // Cache for PS concepts
     260    psMetadata *analysis;              // FPA-level analysis metadata
     261    const psMetadata *camera;          // Camera configuration
     262    psDB *db;                          // Database handle
     263    psArray *chips;                    // The chips
     264    // FITS data
     265    const char *extname;               // Extension name, if it corresponds to this level
     266    psArray *pixels;                   // The pixel data, if it corresponds to this level
     267    psMetadata *header;                // The FITS header, if it corresponds to this level
     268} pmFPA;
     269\end{verbatim}
     270
     271The constructor for \code{pmFPA} shall be:
     272\begin{verbatim}
     273pmFPA *pmFPAAlloc(const psMetadata *camera, psDB *db);
     274\end{verbatim}
     275The constructor shall make an empty \code{pmFPA}.  The \code{chips}
     276array shall be allocated with a zero size, the \code{camera} and
     277\code{db} pointers set to the values provided, and the \code{concepts}
     278metadata constructed. All other pointers in the structure shall be
     279initialized to \code{NULL}.
     280
     281
     282The inclusion of hierarchical links pointing both down (via the
     283arrays) and up (via the \code{parent}) could make for difficulties.
     284For this reason, we specify a utility function to manage the
     285collection of upward-pointing links:
     286\begin{verbatim}
     287bool pmFPACheckParents(pmFPA *fpa);
     288\end{verbatim}
     289This function checks the validity of the \code{parent} links in the
     290FPA hierarchy.  If a \code{parent} link is not set (or not set
     291correctly), it is corrected, and the function shall return
     292\code{false}.  If all the \code{parent} pointers were correct, the
     293function shall return \code{true}.
    271294
    272295\subsection{Detector Coordinate Transformations}
    … …  
    303326the containing hierarchy is defined for each data level.  For example,
    304327the origin of the coordinates for a single chip are located in the
    305 camera grid at \code{psChip.cell0,row0}.  The \code{psReadout} data
     328camera grid at \code{pmChip.cell0,row0}.  The \code{pmReadout} data
    306329level has additional information to specify the details of the readout
    307 process.  The elements \code{psReadout.colParity,rowParity} specify
    308 the parity of the specific readout (readout direction), while the
    309 elements \code{psReadout.colBins,rowBins} specify the binning factor
    310 in the two dimensions.  Note that the value of
    311 \code{psReadout.col0,row0} must be assigned in such a way that it
    312 represents the coordinate of the origin pixel in the actual image: the
    313 overscan or pre-scan pixels must be accounted for.  Putting all of
    314 these element together, we can see that the pixel coordinates in the
    315 camera grid may be determined from the pixel coordinates in the image
    316 grid from the following relationship:
    317 
    318 \begin{verbatim}
    319 psFPA(cell,row) = psChip.cell0,row0 + psCell.cell0,row0 + psReadout.cell0,row0 +
    320                   psReadout.cellParity,rowParity * psReadout.cellBins,rowBins *
     330process.  The elements \code{pmReadout.colBins,rowBins} specify the
     331binning factor in the two dimensions, while the sign indicates the
     332parity of the specific readout (readout direction).  Note that the
     333value of \code{pmReadout.col0,row0} must be assigned in such a way
     334that it represents the coordinate of the origin pixel in the actual
     335image: the overscan or pre-scan pixels must be accounted for.  Putting
     336all of these element together, we can see that the pixel coordinates
     337in the camera grid may be determined from the pixel coordinates in the
     338image grid from the following relationship:
     339
     340\begin{verbatim}
     341pmFPA(cell,row) = pmChip.cell0,row0 + pmCell.cell0,row0 + pmReadout.cell0,row0 +
     342                  pmReadout.cellParity,rowParity * pmReadout.cellBins,rowBins *
    321343                  psImage.data(cell,row)
    322344\end{verbatim}
     345
     346\subsection{Input/Output of a Focal Plane Hierarchy}
     347
     348We specify two functions to construct a focal plane hierarchy from a
     349camera configuration and read from a FITS file.  These two operations
     350are decoupled so that the big investment of memory from the read only
     351occurs when it is necessary.
     352
     353\begin{prototype}
     354pmFPA *pmFPAConstruct(const psMetadata *camera, psDB *db);
     355bool pmFPARead(pmFPA *fpa, psFits *fits);
     356\end{prototype}
     357
     358\code{pmFPAConstruct} shall construct a focal plane hierarchy from a
     359\code{camera} configuration.  A \code{db} handle is also provided so
     360that may be set in the \code{pmFPA}.  The resultant \code{pmFPA} and
     361its lower-down components shall be ready for to read a FITS file into
     362it by setting the \code{extname} pointers at the appropriate levels to
     363the appropriate FITS extension name.
     364
     365\code{pmFPARead} shall read a \code{fits} file (the contents of which
     366are described by the previous \code{camera} configuration) into an
     367extant \code{fpa}.
     368
     369\tbd{Functions to remove things from an fpa so that only certain
     370pieces of the FITS file are read in, and not the whole thing?}
     371
     372We specify an additional two functions to write out a focal plane
     373hierarchy to a FITS file.
     374
     375\begin{prototype}
     376bool pmFPAMorph(pmFPA *toFPA, pmFPA *fromFPA, int chipNum, int cellNum);
     377bool pmFPAWrite(psFits *fits, pmFPA *fpa);
     378\end{prototype}
     379
     380\code{pmFPAMorph} shall morph the \code{fromFPA} focal plane hierarchy
     381to the \code{toFPA} focal plane hierarchy.  This allows us to write
     382the pixels out using a different (though consistent) camera
     383configuration.  In the event that the \code{toFPA} has different
     384levels than the \code{fromFPA}, only the chip and cell specified by
     385\code{chipNum} and \code{cellNum} shall be written; if the levels are
     386the same, these numbers are ignored.  This function shall break apart
     387pixel regions or splice them together where required in order to
     388satisfy the demands of the \code{toFPA}.  If the bias and trim
     389sections are specified by headers in the \code{toFPA}, these shall be
     390updated appropriately; otherwise, the function is permitted to fail,
     391in which case it shall return \code{false}.
     392
     393\tbd{pmFPAMorph is a fairly involved operation, since it must cover
     394several combinations.  IfA is working on a prototype --- do not
     395attempt to code yet.}
     396
     397\code{pmFPAWrite} shall write the focal plane hierarchy, \code{fpa},
     398to the specified \code{fits} file, returning \code{true} upon success
     399and \code{false} otherwise.  The \code{fpa} should contain sufficient
     400information with which to write the FITS images.
    323401
    324402%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    … …  
    376454%
    377455\begin{verbatim}
    378 psCell *psCellInFPA (const psPlane *coord, const psFPA *fpa);
    379 psChip *psChipInFPA (const psPlane *coord, const psFPA *fpa);
    380 psCell *psCellInChip(const psPlane *coord, const psChip *chip);
     456pmCell *pmCellInFPA (const psPlane *coord, const pmFPA *fpa);
     457pmChip *pmChipInFPA (const psPlane *coord, const pmFPA *fpa);
     458pmCell *pmCellInChip(const psPlane *coord, const pmChip *chip);
    381459\end{verbatim}
    382460
    … …  
    417495
    418496\begin{verbatim}
    419 psPlane *psCoordCellToChip (psPlane *out, const psPlane *in, const psCell *cell);
     497psPlane *pmCoordCellToChip (psPlane *out, const psPlane *in, const pmCell *cell);
    420498% astrometry comes from cell (no need for parent)
    421499\end{verbatim}
    … …  
    424502
    425503\begin{verbatim}
    426 psPlane *psCoordChipToFPA (psPlane *out, const psPlane *in, const psChip *chip);
     504psPlane *pmCoordChipToFPA (psPlane *out, const psPlane *in, const pmChip *chip);
    427505% astrometry comes from chip (no need for parent)
    428506\end{verbatim}
    … …  
    431509
    432510\begin{verbatim}
    433 psPlane *psCoordFPAToTP(psPlane *out, const psPlane *in, float color, float mag, const psFPA *fpa);
     511psPlane *pmCoordFPAToTP(psPlane *out, const psPlane *in, float color, float mag, const pmFPA *fpa);
    434512% astrometry comes from FPA (no need for parent)
    435513\end{verbatim}
    … …  
    441519
    442520\begin{verbatim}
    443 psSphere *psCoordTPToSky(psSphere *out, const psPlane *in, const psGrommit *grommit);
     521psSphere *pmCoordTPToSky(psSphere *out, const psPlane *in, const psProjection *projection);
    444522\end{verbatim}
    445523which converts the tangent plane coordinates \code{in} to (RA,Dec) on
    446 the sky, based on the environmental information specified by
    447 \code{grommit}.
     524the sky, using the specified \code{projection}.
    448525
    449526% astrometry comes from cell
    450527\begin{verbatim}
    451 psPlane *psCoordCellToFPA(psPlane *out, const psPlane *in, const psCell *cell);
     528psPlane *pmCoordCellToFPA(psPlane *out, const psPlane *in, const pmCell *cell);
    452529\end{verbatim}
    453530which performs the single-step conversion between Cell coordinates
    … …  
    456533% astrometry comes from cell,chip,fpa (PARENT IS NEEDED HERE)
    457534\begin{verbatim}
    458 psSphere *psCoordCellToSky(psSphere *out, const psPlane *in, float color, float mag, const psCell *cell);
     535psSphere *pmCoordCellToSky(psSphere *out, const psPlane *in, float color, float mag, const pmCell *cell);
    459536\end{verbatim}
    460537which converts coordinates on the specified cell to (RA,Dec).  This
    … …  
    463540Tangent Plane to Sky.  The information needed for each of these
    464541transformations is available in the \code{.parent} elements of
    465 \code{psCell} and \code{psChip}, and the \code{psFPA.exposure}
    466 element.  The \code{color} and magnitude (\code{mag}) of the source is
    467 necessary in order to perform the distortion between the focal plane
    468 and the tangent plane.
     542\code{pmCell} and \code{pmChip}, and the \code{pmFPA.projection}.  The
     543\code{color} and magnitude (\code{mag}) of the source is necessary in
     544order to perform the distortion between the focal plane and the
     545tangent plane.
    469546
    470547% astrometry comes from cell (no need for parent)
    471548\begin{verbatim}
    472 psSphere *psCoordCellToSkyQuick(psSphere *out, const psPlane *in, const psCell *cell);
     549psSphere *pmCoordCellToSkyQuick(psSphere *out, const psPlane *in, const pmCell *cell);
    473550\end{verbatim}
    474551which uses the 'quick-and-dirty' transformation to convert coordinates
    475552on the specified cell to (RA,Dec).  This transformation should use the
    476553locally linear transformation specified by the element
    477 \code{psCell.toTP}.  Although the accuracy of this transformation
     554\code{pmCell.toTP}.  Although the accuracy of this transformation
    478555is lower than the complete transformation above, the calculation is
    479556substantially faster as it only involves linear transformations.
    … …  
    483560
    484561\begin{verbatim}
    485 psPlane *psCoordSkyToTP(psPlane *out, const psSphere *in, const psGrommit *grommit);
     562psPlane *pmCoordSkyToTP(psPlane *out, const psSphere *in, const psProjection *projection);
    486563\end{verbatim}
    487564which converts (RA,Dec) coordinates \code{in} to tangent plane coords
    488 based on the enviromental information supplied by \code{grommit}.
    489 
    490 \begin{verbatim}
    491 psPlane *psCoordTPToFPA(psPlane *out, const psPlane *in, float color, float mag, const psFPA *fpa);
     565using the specified \code{projection}.
     566
     567\begin{verbatim}
     568psPlane *pmCoordTPToFPA(psPlane *out, const psPlane *in, float color, float mag, const pmFPA *fpa);
    492569\end{verbatim}
    493570which converts the tangent plane coordinates \code{in} to focal plane
    … …  
    497574
    498575\begin{verbatim}
    499 psPlane *psCoordFPAToChip (psPlane *out, const psPlane *in, const psChip *chip);
     576psPlane *pmCoordFPAToChip (psPlane *out, const psPlane *in, const pmChip *chip);
    500577\end{verbatim}
    501578which converts the specified FPA coordinates \code{in} to the
    502579coordinates on the given Chip.  The specified chip need not contain
    503580the input coordinate.  To find the chip which contains a particular
    504 coordinate, the function \code{psChipInFPA}, defined above, should be
     581coordinate, the function \code{pmChipInFPA}, defined above, should be
    505582used.
    506583
    507584\begin{verbatim}
    508 psPlane *psCoordChipToCell (psPlane *out, const psPlane *in, const psCell *cell);
     585psPlane *pmCoordChipToCell (psPlane *out, const psPlane *in, const pmCell *cell);
    509586\end{verbatim}
    510587which converts the specified Chip coordinate \code{in} to the
    511588coordinate on the given Cell.  The specified Cell need not contain the
    512589input coordinate.  To find the cell which contains a particular
    513 coordinate, the function \code{psCellInChip}, defined above, should be
     590coordinate, the function \code{pmCellInChip}, defined above, should be
    514591used.
    515592
    516593\begin{verbatim}
    517 psPlane *psCoordSkyToCell(psPlane *out, const psSphere *in, float color, float mag, psCell *cell);
     594psPlane *pmCoordSkyToCell(psPlane *out, const psSphere *in, float color, float mag, pmCell *cell);
    518595\end{verbatim}
    519596which directly converts (RA,Dec) \code{in} to coordinates on the
    … …  
    524601
    525602\begin{verbatim}
    526 psPlane *psCoordSkyToCellQuick(psPlane *out, const psSphere *in, psCell *cell);
     603psPlane *pmCoordSkyToCellQuick(psPlane *out, const psSphere *in, pmCell *cell);
    527604\end{verbatim}
    528605which directly converts (RA,Dec) \code{in} to coordinates on the
    529606specified cell.  The specified cell need not contain the input
    530607coordinates.  This transformation should use the locally linear
    531 transformation specified by the element \code{psCell.toTP}.
     608transformation specified by the element \code{pmCell.toTP}.
    532609Although the accuracy of this transformation is lower than the
    533610complete transformation above, the calculation is substantially faster
    … …  
    536613%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    537614
    538 \section{Astrometry and World Coordinate System}
     615\subsection{FITS World Coordinate System}
    539616
    540617The FITS World Coordinate System (WCS) headers are commonly employed
    … …  
    550627
    551628\begin{verbatim}
    552 bool psAstrometryReadWCS(psPlaneTransform **transform, // Output transformation
     629bool pmAstrometryReadWCS(psPlaneTransform **transform, // Output transformation
    553630                         psProjection **projection, // Output projection
    554631                         psMetadata *header // Input FITS header
    555632                         );
    556 bool psAstrometryWriteWCS(psMetadata *header, // Output FITS header
     633bool pmAstrometryWriteWCS(psMetadata *header, // Output FITS header
    557634                          psPlaneTransform *transform, // Input transformation
    558                           psProjection *projection, // Input projection
    559                           double color, // Mean color to use
    560                           double magnitude, // Mean magnitude to use
     635                          psProjection *projection, // Input projection
     636                          double color, // Mean color to use
     637                          double magnitude, // Mean magnitude to use
    561638                          );
    562 bool psAstrometrySimplify(psPlaneTransform **transform, // Output transformation
     639bool pmAstrometrySimplify(psPlaneTransform **transform, // Output transformation
    563640                          psProjection **projection, // Output projection
    564                           psCell *cell // Cell for which to generate transform and projection
     641                          pmCell *cell // Cell for which to generate transform and projection
    565642                          );
    566 \end{verbatim}                 
     643\end{verbatim}
    567644
    568645\code{pmReadAstrometry} shall parse the specified FITS \code{header},
    … …  
    588665output; otherwise it shall return \code{false}.
    589666
    590 \section{Observatory data}
    591 
    592 We need a container for the observatory data that doesn't change per
    593 exposure.
    594 
    595 \begin{verbatim}
    596 typedef struct {
    597     const char *name;                   ///< Name of observatory
    598     const double latitude;              ///< Latitude of observatory, east positive
    599     const double longitude;             ///< Longitude of observatory
    600     const double height;                ///< Height of observatory
    601     const double tlr;                   ///< Tropospheric Lapse Rate
    602 } psObservatory;
    603 \end{verbatim}
    604 
    605 The constructor for \code{psObservatory} shall be:
    606 \begin{verbatim}
    607 psObservatory *psObservatoryAlloc(const char *name, double latitude, double longitude,
    608                                   double height, double tlr);
    609 \end{verbatim}
    610 
    611 \section{Exposure information}
    612 
    613 We need several quantities from the telescope in order to make a
    614 first guess at the astrometric solution.  From these quantities,
    615 further quantities can be derived and stored for later use.
    616 
    617 \begin{verbatim}
    618 typedef struct {
    619     const double ra, dec;               ///< Telescope boresight
    620     const double ha;                    ///< Hour angle
    621     const double zd;                    ///< Zenith distance
    622     const double az;                    ///< Azimuth
    623     const psTime *time;                 ///< Time of observation
    624     const float rotAngle;               ///< Rotator position angle
    625     const float temp;                   ///< Air temperature, for estimating refraction
    626     const float pressure;               ///< Air pressure, for calculating refraction
    627     const float humidity;               ///< Relative humidity, for calculating refraction
    628     const float exptime;                ///< Exposure time
    629     const float wavelength;             ///< Wavelength of observation
    630     const psObservatory *observatory;   ///< Observatory data
    631     /* Derived quantities */
    632     const psTime lst;                   ///< Local Sidereal Time
    633     const float posAngle;               ///< Position angle
    634     const float parallactic;            ///< Parallactic angle
    635     const float airmass;                ///< Airmass, calculated from zenith distance
    636     const float pf;                     ///< Parallactic factor
    637     const char *cameraName;             ///< name of camera which provided exposure
    638     const char *telescopeName;          ///< name of telescope which provided exposure
    639 } psExposure;
    640 \end{verbatim}
    641 
    642 The constructor for \code{psExposure} shall be:
    643 \begin{verbatim}
    644 psExposure *psExposureAlloc(double ra, double dec, double ha, double zd, double az,
    645                             const psTime *time, float rotAngle, float temp, float pressure, float humidity,
    646                             float exptime, float wavelength, const psObservatory *observatory);
    647 \end{verbatim}
    648 
Note: See TracChangeset for help on using the changeset viewer.