IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Feb 10, 2006, 3:25:23 PM (20 years ago)
Author:
Paul Price
Message:

Updating focal plane hierarchy functions: new functions; updating old functions; using pmFile.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/modules/CameraImages.tex

    r6019 r6421  
    129129\begin{verbatim}
    130130typedef struct {
    131     // Position on the cell
    132     int col0;                          // Offset from the left of cell.
    133     int row0;                          // Offset from the bottom of cell.
    134     int colBins;                       // Amount of binning in x-dimension and parity (from sign)
    135     int rowBins;                       // Amount of binning in y-dimension and parity (from sign)
    136131    // Information
     132    psMetadata *analysis;              // Readout-level analysis metadata
     133    pmCell *parent;                    // Parent cell
     134    // Data
    137135    psImage *image;                    // Imaging area of readout
    138136    psImage *mask;                     // Mask for image
    139137    psImage *weight;                   // Weight for image
    140138    psList *bias;                      // List of bias section (sub-)images
    141     psMetadata *analysis;              // Readout-level analysis metadata
    142     pmCell *parent;                    // Parent cell
    143139} pmReadout;
    144140\end{verbatim}   
    … …  
    146142The constructor for \code{pmReadout} shall be:
    147143\begin{verbatim}
    148 pmReadout *pmReadoutAlloc(pmCell *cell);
    149 \end{verbatim}
    150 The constructor shall make an empty \code{pmReadout}.  If the parent
    151 \code{cell} is not \code{NULL}, the \code{parent} link is made and the
    152 readout shall be placed in the parent's array of \code{readouts}.  The
    153 metadata containers shall be allocated.  All other pointers in the
    154 structure shall be initialized to \code{NULL}.
     144pmReadout *pmReadoutAlloc(void);
     145\end{verbatim}
     146The constructor shall make an empty \code{pmReadout}.  The metadata
     147container and the \code{bias} list shall be allocated.  All other
     148pointers in the structure shall be initialized to \code{NULL}.
    155149
    156150\subsubsection{A Cell}
    … …  
    177171\begin{verbatim}
    178172typedef struct {
    179     // Offset specifying position on chip
    180     int col0;                          // Offset from the left of chip.
    181     int row0;                          // Offset from the bottom of chip.
    182173    // Astrometric transformations
    183174    psPlaneTransform* toChip;          // Transformations from cell to chip coordinates
    … …  
    186177    // Information
    187178    psMetadata *concepts;              // Cache for PS concepts
    188     psMetadata *camera;                // Camera information
     179    psMetadata *camera;                // Camera information
    189180    psMetadata *analysis;              // Cell-level analysis metadata
     181    bool process;                      // Do we want to process?
     182    bool exists;                       // Does the data exist?
     183    // Levels   
    190184    psArray *readouts;                 // The readouts (referred to by number)
    191185    pmChip *parent;                    // Parent chip
    192     bool valid;                        // Do we bother about reading and working with this cell?
    193     p_pmHDU *hdu;                      // FITS data
     186    // Sources
     187    pmFile *imageSource;               // Image file on disk
     188    pmFile *maskSource;                // Mask file on disk
     189    pmFile *weightSource;              // Weight file on disk
    194190} pmCell;
    195191\end{verbatim}
    … …  
    197193The constructor for \code{pmCell} shall be:
    198194\begin{verbatim}
    199 pmCell *pmCellAlloc(pmChip *chip, psMetadata *cameraData, psString name);
    200 \end{verbatim}
    201 The constructor shall make an empty \code{pmCell}.  If the parent
    202 \code{chip} is not \code{NULL}, the \code{parent} link is made and the
    203 cell shall be placed in the parent's array of \code{cells}.  The
     195pmCell *pmCellAlloc(psMetadata *cameraData, psString name);
     196\end{verbatim}
     197The constructor shall make an empty \code{pmCell}.  The
    204198\code{readouts} array shall be allocated with a zero size, and the
    205199metadata containers constructed.  The cell's \code{camera} pointer
    206 shall be set to the provided \code{cameraData}, and the \code{name}
    207 shall be used to set \code{CELL.NAME} in the \code{concepts}.  All
    208 other pointers in the structure shall be initialized to \code{NULL}.
     200shall be set to the provided \code{cameraData}, the \code{exists}
     201boolean shall be set to \code{false}, the \code{process} boolean shall
     202be set to \code{true}, and the \code{name} shall be used to set
     203\code{CELL.NAME} in the \code{concepts}.  All other pointers in the
     204structure shall be initialized to \code{NULL}.
     205
     206\tbd{The astrometric transformations will likely disappear into the
     207analysis metadata in the future.}
    209208
    210209\subsubsection{A Chip}
    … …  
    224223\begin{verbatim}
    225224typedef struct {
    226     // Offset specifying position on focal plane
    227     int col0;                          // Offset from the left of FPA.
    228     int row0;                          // Offset from the bottom of FPA.
    229225    // Astrometric transformations
    230226    psPlaneTransform* toFPA;           // Transformation from chip to FPA coordinates
    … …  
    233229    psMetadata *concepts;              // Cache for PS concepts
    234230    psMetadata *analysis;              // Chip-level analysis metadata
     231    bool process;                      // Do we want to process?
     232    bool exists;                       // Does the data exist?
     233    // Levels
    235234    psArray *cells;                    // The cells (referred to by name)
    236235    pmFPA *parent;                     // Parent FPA
    237     bool valid;                        // Do we bother about reading and working with this chip?
    238     p_pmHDU *hdu;                       // FITS data
     236    // Sources
     237    pmFile *imageSource;               // Image file on disk
     238    pmFile *maskSource;                // Mask file on disk
     239    pmFile *weightSource;              // Weight file on disk
    239240} pmChip;
    240241\end{verbatim}
    … …  
    242243The constructor for \code{pmChip} shall be:
    243244\begin{verbatim}
    244 pmChip *pmChipAlloc(pmFPA *fpa, psString name);
    245 \end{verbatim}
    246 The constructor shall make an empty \code{pmChip}.  If the parent
    247 \code{fpa} is not NULL, the \code{parent} link is made and the chip
    248 shall be placed in the parent's array of \code{chips}.  The
    249 \code{cells} array shall be allocated with a zero size, and the
    250 metadata containers constructed.  The \code{name} shall be used to set
    251 \code{CHIP.NAME} in the \code{concepts}.  All other pointers in the
    252 structure shall be initialized to \code{NULL}.
     245pmChip *pmChipAlloc(psString name);
     246\end{verbatim}
     247The constructor shall make an empty \code{pmChip}.  The \code{cells}
     248array shall be allocated with a zero size, the metadata containers
     249constructed, the \code{exists} boolean shall be set to \code{false},
     250the \code{process} boolean shall be set to \code{true}, andhe
     251\code{name} shall be used to set \code{CHIP.NAME} in the
     252\code{concepts}.  All other pointers in the structure shall be
     253initialized to \code{NULL}.
     254
     255\tbd{The astrometric transformations will likely disappear into the
     256analysis metadata in the future.}
    253257
    254258\subsubsection{A Focal Plane}
    … …  
    278282    psMetadata *analysis;              // FPA-level analysis metadata
    279283    const psMetadata *camera;          // Camera configuration
     284    // Levels
    280285    psArray *chips;                    // The chips
    281     p_pmHDU *hdu;                      // FITS data
    282     psMetadata *phu;                   // Primary Header
     286    // Sources
     287    pmFile *imageSource;               // Image file on disk
     288    pmFile *maskSource;                // Mask file on disk
     289    pmFile *weightSource;              // Weight file on disk
    283290} pmFPA;
    284291\end{verbatim}
    … …  
    289296\end{verbatim}
    290297The constructor shall make an empty \code{pmFPA}.  The \code{chips}
    291 array shall be allocated with a zero size, the \code{camera} and
    292 \code{db} pointers set to the values provided, and the \code{concepts}
    293 metadata constructed. All other pointers in the structure shall be
    294 initialized to \code{NULL}.
    295 
     298array shall be allocated with a zero size, the \code{camera} pointer
     299set to the value provided, and the \code{concepts} metadata
     300constructed. All other pointers in the structure shall be initialized
     301to \code{NULL}.
     302
     303\tbd{The astrometric transformations will likely disappear into the
     304analysis metadata in the future.}
     305
     306\subsubsection{Disk files}
     307
     308Each of the levels in the hierarchy have a place to hold a
     309\code{pmFile}, which is the representation of a FITS file and ``header
     310data unit'':
     311\begin{datatype}
     312typedef struct {
     313    const char *filename;               // Name of file
     314    psFits *fits;                       // FITS file
     315    psMetadata *phu;                    // Primary extension
     316    const char *extname;                // Extension name, or NULL
     317    psMetadata *header;                 // The FITS header, or NULL if primary
     318    psArray *images;                    // The pixel data
     319    psDB *database;                     // Database handle for concepts
     320} pmFile;
     321\end{datatype}
     322
     323
     324\subsubsection{Links between levels}
     325
     326We provide functions to attach readouts, cells and chips with their
     327parents:
     328\begin{prototype}
     329bool pmReadoutParent(pmReadout *readout, pmCell *cell);
     330bool pmCellParent(pmCell *cell, pmChip *chip);
     331bool pmChipParent(pmChip *chip, pmFPA *fpa);
     332\end{prototype}
     333In the case of \code{pmReadoutParent}, the function shall set the
     334\code{parent} pointer for the \code{readout} to \code{cell}, and add
     335the \code{readout} to the array of \code{readouts} in the \code{cell}.
     336The other cases are similar.  \textit{Note that, in order to avoid
     337infinite loops when freeing, the reference counter should \textbf{not}
     338be incremented when attaching to the \code{parent} pointer, and the
     339deallocators should \textbf{not} free the parent.}
     340
     341The following functions remove all levels below that specified:
     342\begin{prototype}
     343void pmCellFreeReadouts(pmCell *cell);
     344void pmChipFreeCells(pmChip *chip);
     345void pmFPAFreeChips(pmFPA *fpa);
     346\end{prototype}
    296347
    297348The inclusion of hierarchical links pointing both down (via the
    … …  
    299350For this reason, we specify a utility function to manage the
    300351collection of upward-pointing links:
    301 \begin{verbatim}
    302 bool pmFPACheckParents(pmFPA *fpa);
    303 \end{verbatim}
     352\begin{prototype}
     353bool pmFPACheckLinks(pmFPA *fpa);
     354\end{prototype}
    304355This function checks the validity of the \code{parent} links in the
    305 FPA hierarchy.  If a \code{parent} link is not set (or not set
    306 correctly), it is corrected, and the function shall return
    307 \code{false}.  If all the \code{parent} pointers were correct, the
    308 function shall return \code{true}.
    309 
    310 
    311 Each of the levels in the hierarchy have a place to hold a
    312 \code{p_pmHDU}, which is the disk representation of the image:
    313 \begin{datatype}
    314 typedef struct {
    315     const char *extname;                // Extension name, if it corresponds to this level
    316     psMetadata *header;                 // The FITS header, if it corresponds to this level
    317     psArray *images;                    // The pixel data, if it corresponds to this level
    318     psArray *masks;                     // The mask data, if it corresponds to this level
    319     psArray *weights;                   // The weight data, if it corresponds to this level
    320 } p_pmHDU;
    321 \end{datatype}
     356FPA hierarchy.  If any \code{parent} link in the (entire) hierarchy is
     357not set (or not set correctly), it is corrected, and the function
     358shall return \code{false}.  If all the \code{parent} pointers were
     359correct, the function shall return \code{true}.
     360
    322361
    323362\subsection{Detector Coordinate Transformations}
     363
     364\tbd{The implementation of this section may change slightly if the
     365coordinate transformations in the focal plane hierarchy are pushed
     366into the metadata --- the math shouldn't change, just how the values
     367are accessed.}
    324368
    325369\begin{figure}
    … …  
    380424
    381425\begin{prototype}
    382 pmFPA *pmFPAConstruct(const psMetadata *camera, psDB *db);
     426pmFPA *pmFPAConstruct(const psMetadata *camera);
     427bool pmFPADatabase(pmFPA *fpa, psDB *db);
    383428bool pmFPARead(pmFPA *fpa, psFits *fits);
     429bool pmFPAWrite(psFits *fits, pmFPA *fpa);
    384430\end{prototype}
    385431
    386432\code{pmFPAConstruct} shall construct a focal plane hierarchy from a
    387 \code{camera} configuration.  A \code{db} handle is also provided so
    388 that may be set in the \code{pmFPA}.  The resultant \code{pmFPA} and
    389 its lower-down components shall be ready for to read a FITS file into
    390 it by setting the \code{extname} pointers at the appropriate levels to
    391 the appropriate FITS extension name.
     433\code{camera} configuration.  The resultant \code{pmFPA} and its
     434lower-down components shall be ready for to read a FITS file into it
     435by setting \code{filename} and \code{extname} in the \code{file}
     436pointers at the appropriate levels.
     437
     438\code{pmFPADatabase} shall set the \code{database} of the \code{file}
     439pointers within the hierarchy to the supplied \code{db}.
    392440
    393441\code{pmFPARead} shall read a \code{fits} file (the contents of which
    394442are described by the previous \code{camera} configuration) into an
    395 extant \code{fpa}.  This involves reading the headers and pixels, as
    396 well as ingesting all the concepts.
     443extant \code{fpa}, for those components which don't already
     444\code{exist} and are marked to be \code{process}ed.  This involves
     445reading the headers and pixels into the \code{pmFile}, ingesting all
     446the concepts for that level, and making subimages for the
     447\code{readout->image} (from \code{CELL.TRIMSEC}) and
     448\code{readout->bias} (from \code{CELL.BIASSEC}).
     449
     450\code{pmFPAWrite} shall write those elements focal plane hierarchy
     451(\code{fpa}) that \code{exist} and are marked to be \code{process}ed
     452to the specified \code{fits} file, returning \code{true} upon success
     453and \code{false} otherwise.  If the provided \code{fits} file is
     454\code{NULL}, the information within the \code{pmFile *image}
     455components is used for the output.  The \code{fpa} should contain
     456sufficient information with which to write the FITS images.
     457
     458\subsubsection{Mask and weight input/output}
     459
     460We carry mask and weight images, since these are useful for downstream
     461processing.  A mask value of zero for a pixel shall indicate that the
     462pixel is not suspect.  The weight images shall be the variance (the
     463square of the standard deviation).
     464
     465We desire to access the mask and weight images without specifying a
     466particular file name.  We introduce the \code{SUPPLEMENTARY} metadata
     467entry in the camera configuration file, which allows identification of
     468the location for the mask and weight images, based on the value of
     469some of the ``concepts'':
     470
     471\begin{verbatim}
     472# How to get the supplementary stuff: mask and weight
     473SUPPLEMENTARY   METADATA
     474        MASK.SOURCE     STR     FILE                    # Source type for mask: EXT | FILE
     475        MASK.NAME       STR     {FPA.NAME}_mask.fits    # Name for mask extension or filename
     476        WEIGHT.SOURCE   STR     EXT                     # Source type for weight: EXT | FILE
     477        WEIGHT.NAME     STR     {CELL.NAME}_weight.fits # Name for weight extension or filename
     478END
     479\end{verbatim}
     480
     481How the mask (or weight) image is stored is specified by the
     482\code{MASK.SOURCE} (or \code{WEIGHT.SOURCE}) keyword.  The images may
     483be stored either in the same file as the pixels with a different
     484extension name (\code{EXT}), or they may be stored in a different file
     485with the same extension name (\code{FILE}).  The name of the file or
     486extension is specified by the \code{MASK.NAME} (or \code{WEIGHT.NAME})
     487keyword, with strings within curly brackets interpreted as concepts
     488that must be evaluated and replaced.
     489
     490\begin{prototype}
     491pmFPAReadMask(pmFPA *fpa, psFits *fits);
     492pmFPAWriteMask(psFits *fits, pmFPA *fpa);
     493pmFPAReadWeight(pmFPA *fpa, psFits *fits);
     494pmFPAWriteWeight(psFits *fits, pmFPA *fpa);
     495\end{prototype}
     496
     497\code{pmFPAReadMask} and \code{pmFPAReadWeight} are very similar to
     498\code{pmFPARead}, except that they shall read the \code{mask} and
     499\code{weight} elements (respectively) of the \code{pmReadout}s
     500comprising the \code{fpa}.
     501
     502\code{pmFPAWriteMask} and \code{pmFPAWriteWeight} is very similar to
     503\code{pmFPAWrite}, but it shall write the \code{mask} and
     504\code{weight} elements (respectively) of the \code{pmReadout}s
     505comprising the \code{fpa}.
     506
     507We also provide functions to generate the mask and weight images:
     508\begin{prototype}
     509bool pmCellDetectorMask(pmCell *cell);
     510bool pmCellDetectorWeight(pmCell *cell);
     511\end{prototype}
     512
     513\code{pmCellPhotonMask} shall set the mask pixels based on the
     514\code{CELL.SATURATION} and \code{CELL.BAD} concepts.
     515\code{pmCellPhotonWeight} shall set the weight image based on the
     516photon statistics using the \code{CELL.GAIN} and \code{CELL.READNOISE}
     517concepts.
     518
     519\subsection{Iteration}
     520
     521Often we will desire to perform a function on all cells in the focal
     522plane, or all chips, etc.  Since this is a common operation, we
     523provide an iterator that performs the mind numbing part:
     524
     525\begin{datatype}
     526typedef bool (*pmFPAIterateFunc)(pmFPA *fpa, pmChip *chip, pmCell *cell);
     527\end{datatype}
     528\begin{prototype}
     529bool pmFPAIterate(pmFPA *fpa, bool doCells, pmFPAIterateFunc func);
     530\end{prototype}
     531
     532\code{pmFPAIterate} shall iterate through all chips (that \code{exist}
     533and are marked to be \code{process}ed) in the \code{fpa}, and if
     534\code{doCells} is \code{true}, all cells (that \code{exist} and are
     535marked to be \code{process}ed) in those chips.  For each, the function
     536shall call the iterator function, \code{func}.
     537
     538
     539\subsection{Selecting elements of the hierarchy for processing}
    397540
    398541\begin{prototype}
    … …  
    401544\end{prototype}
    402545
    403 These functions are provided to set the \code{valid} booleans within
     546These functions are provided to set the \code{process} booleans within
    404547an \code{fpa} so that only certain chips within the FITS file are read
    405548in.
    … …  
    418561have \code{valid} set to \code{true}.
    419562
    420 \tbd{make these functions richer: select by extention, extname, cell,
    421 options to invalidate all / validate all, etc}
     563\tbd{Provide a richer set of functions: select by extension, extname,
     564cell, options to invalidate all / validate all, etc}
     565
     566
     567\subsection{Mosaicking}
    422568
    423569\begin{prototype}
    424570bool pmFPAMorph(pmFPA *toFPA, pmFPA *fromFPA, bool positionDependent, int chipNum, int cellNum);
    425571\end{prototype}
    426 
    427572\code{pmFPAMorph} shall morph the \code{fromFPA} focal plane hierarchy
    428573to the \code{toFPA} focal plane hierarchy.  This allows us to write
    … …  
    447592suitable error message, in which case it shall return \code{false}.
    448593
    449 \begin{prototype}
    450 bool pmFPAWrite(psFits *fits, pmFPA *fpa);
    451 \end{prototype}
    452 
    453 \code{pmFPAWrite} shall write the focal plane hierarchy, \code{fpa},
    454 to the specified \code{fits} file, returning \code{true} upon success
    455 and \code{false} otherwise.  The \code{fpa} should contain sufficient
    456 information with which to write the FITS images.
    457 
    458 \begin{prototype}
    459 pmFPAWriteMask(psFits *fits, pmFPA *fpa);
    460 \end{prototype}
    461 
    462 \code{pmFPAWriteMask} is very similar to \code{pmFPAWrite}, but it
    463 shall write the \code{mask} elements of the \code{pmReadout}s
    464 comprising the \code{fpa}.
    465 
    466 \begin{prototype}
    467 pmFPAWriteWeight(psFits *fits, pmFPA *fpa);
    468 \end{prototype}
    469 
    470 \code{pmFPAWriteWeight} is very similar to \code{pmFPAWrite}, but it
    471 shall write the \code{weight} elements of the \code{pmReadout}s
    472 comprising the \code{fpa}.
     594\tbd{Don't code pmFPAMorph --- it's tricky, and maybe unnecessary.}
     595
     596\begin{prototype}
     597int pmChipMosaic(pmChip *chip, int xBinChip, int yBinChip);
     598\end{prototype}
     599
     600\code{pmChipMosaic} shall mosaic the cells within the provided
     601\code{chip}.  The mosaicking shall take into account the offsets of
     602the cells on the chip (\code{CELL.X0,CELL.Y0}), the cell binning
     603(\code{CELL.XBIN,CELL.YBIN}) and the desired (absolute, i.e., relative
     604to the physical pixels) binning level (\code{xBinChip,yBinChip}).  The
     605component cells and readouts shall be replaced with a single cell and
     606readout containing the mosaic.  \code{file} pointers within the
     607hierarchy and the concepts shall be updated.
     608
    473609
    474610%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Note: See TracChangeset for help on using the changeset viewer.