IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Feb 10, 2006, 5:16:55 PM (20 years ago)
Author:
Paul Price
Message:

Adding concepts functions, including reading, writing, blanking, registering, initialising.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/modules/ModulesSDRS.tex

    r6400 r6422  
    1 %%% $Id: ModulesSDRS.tex,v 1.73 2006-02-09 19:44:21 price Exp $
     1%%% $Id: ModulesSDRS.tex,v 1.74 2006-02-11 03:16:55 price Exp $
    22\documentclass[panstarrs,spec]{panstarrs}
    33
    … …  
    144144  \item \code{DBPASSWORD} of type \code{STR}: The corresponding
    145145    database password for \code{psDBInit}.
     146  \item \code{DBNAME} of type \code{STR}: The database name for
     147    \code{psDBInit}.
    146148  \end{itemize}
    147149\item \code{CAMERAS} of type \code{METADATA}: A list of instruments
    … …  
    346348
    347349\paragraph{Deriving concept values}
     350\label{sec:derivingconcepts}
    348351
    349352The PS concepts are described in more detail in \S\ref{sec:concepts}.
    … …  
    454457        PHASE1          STR     lris_phase1.config
    455458        PHASE2          STR     lris_phase2.config
    456         PHASE4          STR     lris_phase4.config
     459        PHASE4          STR     lris_phase4.config
    457460END
    458461\end{verbatim}
    … …  
    465468
    466469\subsection{PS Concepts}
    467 \label{sec:concepts}
    468 
    469 Each image has associated with it what we will call {\it concepts}
    470 (for want of a better word).  These are values corresponding to
    471 general quantities and qualities necessary to understand and interpret
    472 the data such as airmass, date, read noise and filter.  The values of
    473 each of the below concepts shall be determined when the FPA is read
    474 into memory (via \code{pmFPARead}), and stored at the appropriate
    475 level in the focal plane hierarchy.
    476 
    477 Below is a list of concepts that the IPP requires, with the
    478 expected type and a short description.
    479 
    480 \begin{itemize}
    481 \item \code{FPA.AIRMASS} (F32): Airmass at which the observation is made (boresight).
    482 \item \code{FPA.FILTER} (STR): Filter used in observation
    483 \item \code{FPA.POSANGLE} (F32): Position angle for camera
    484 \item \code{FPA.RA} (F64): Right Ascension of boresight in radians
    485 \item \code{FPA.DEC} (F64): Declination of boresight in radians
    486 \item \code{FPA.RADECSYS} (STR): System of RA,Dec (e.g., J2000 or ICRS)
    487 \item \code{FPA.NAME} (STR): An identifier (e.g., observation number) for the FPA instance
    488 \item \code{CHIP.NAME} (STR): The name of the chip (unique within the FPA) --- set at FITS read
    489 \item \code{CELL.NAME} (STR): The name of the cell (unique within the parent chip) --- set at FITS read
    490 \item \code{CELL.TIME} (\code{psTime}): Time of observation start
    491 \item \code{CELL.READDIR} (S32): Read direction: line (1) or column (2)
    492 \item \code{CELL.BIASSEC} (STR): Overscan region(s)
    493 \item \code{CELL.TRIMSEC} (STR): Trim region
    494 \item \code{CELL.GAIN} (F32): CCD gain (e/ADU)
    495 \item \code{CELL.READNOISE} (F32): CCD read noise (e)
    496 \item \code{CELL.SATURATION} (F32): CCD saturation point (ADU)
    497 \item \code{CELL.BAD} (F32): CCD bad pixel point (ADU)
    498 \item \code{CELL.XBIN} (S32): CCD binning in x
    499 \item \code{CELL.YBIN} (S32): CCD binning in y
    500 \item \code{CELL.XPARITY} (S32): Direction of CCD readout in x relative to the rest of the chip
    501 \item \code{CELL.YPARITY} (S32): Direction of CCD readout in y relative to the rest of the chip
    502 \item \code{CELL.EXPOSURE} (F32): Exposure time of image (sec)
    503 \item \code{CELL.DARKTIME} (F32): Dark time for image (sec)
    504 \end{itemize}
    505 
    506 \tbd{Note that CELL.EXPOSURE, CELL.DARKTIME and CELL.TIME should
    507 actually be specified at the readout level.  However, at this present
    508 time, we're not sure how these should be specified, and so we move
    509 them up to the cell level and assume that all readouts are of the same
    510 exposure and dark time.}
     470
     471\subsubsection{Ingest}
    511472
    512473For different camera systems, these concepts are not always known by
    513474the same name, nor are they generally obtained in the same manner, and
    514475so their source or value must be specified in the camera configuration
    515 file.  The value of a concept shall be found by searching in the
    516 following order:
     476file.  At ingest, the value of a concept shall be found by searching in
     477the following order:
    517478\begin{itemize}
    518479\item The cell data from the \code{CELLS} metadata in the camera configuration.
    … …  
    521482\item The \code{DEFAULTS} value.
    522483\end{itemize}
    523 
    524 After ingest (performed by \code{pmFPARead}, the user may safely
    525 assume that all of the above concepts exist (defined at the
    526 appropriate level), is of the specified type and in the specified
    527 format.
    528484
    529485\subsubsection{Dependencies for defaults}
    … …  
    766722\end{verbatim}
    767723
     724%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     725
     726\section{``Concepts''}
     727\label{sec:concepts}
     728
     729Each image from an astronomical instrument has associated with it what
     730we will call {\it concepts} (for want of a better word; \tbd{we would
     731like to call this ``metadata'', but unfortunately that name is already
     732taken}).  These are values corresponding to general quantities and
     733qualities necessary to understand and interpret the data, such as
     734airmass, date, read noise and filter.  The values of each of the below
     735concepts shall be determined when the FPA is read into memory (via
     736\code{pmFPARead}), and stored at the appropriate level in the focal
     737plane hierarchy.
     738
     739After ingest (performed in \code{pmFPARead}, the user may safely
     740assume that all of the above concepts exist at the appropriate level
     741(meaning the user needn't be hampered by excessive error checking), is
     742of the specified type (meaning the user doesn't need to worry about
     743whether the value of interest is stored in, e.g., floating point or
     744double precision or even a colon-delimited string) and in the
     745specified format (meaning the user doesn't need to know, e.g., whether
     746the right ascension is in radians or degrees) --- all the conversions
     747are handled by the ``concepts'' functions at ingest.
     748
     749Most of the structures and functions in this section are intended to
     750be ``private'', since there is no need envisioned for the user to call
     751them directly.
     752
     753\subsection{Specifying a concept}
     754
     755Specifying a ``concept'' requires a (meaningful) name (preferably with
     756the level in the name, e.g., \code{CELL.EXPOSURE}), a
     757comment/description, a type, a default or blank value, functions to
     758read and write, and a level that the concept applies to
     759(FPA/Chip/Cell).
     760
     761\begin{datatype}
     762typedef psMetadataItem* (*p_pmConceptReadFunc)(pmFPA *fpa, pmChip *chip, pmCell *cell, psDB *db);
     763typedef bool (*p_pmConceptWriteFunc)(pmFPA *fpa, pmChip *chip, pmCell *cell, psDB *db);
     764typedef struct {
     765    psMetadataItem *blank;          // Blank value of concept; also contains the name
     766    p_pmConceptReadFunc read;       // Function to call to read the concept
     767    p_pmConceptWriteFunc write;     // Function to call to write the concept
     768} p_pmConceptSpec;
     769\end{datatype}
     770
     771\code{blank} is a \code{psMetadataItem} that provides the name, type
     772and default/blank value for the concept.  \code{read} and \code{write}
     773provide the functions to read and write.
     774
     775A concept specification may be allocated:
     776\begin{prototype}
     777p_pmConceptSpec *p_pmConceptSpecAlloc(psMetadataItem *blank, pmConceptReadFunc read,
     778                                      pmConceptWriteFunc write);
     779\end{prototype}
     780
     781\subsection{Registering a concept}
     782
     783The concept specifications that have been registered shall be stored in
     784three \code{psMetadata}s, one for each level (FPA, chip, cell).
     785
     786Registering a concept is achieved by:
     787\begin{prototype}
     788bool pmConceptRegister(psMetadataItem *blank, pmConceptReadFunc read,
     789                       pmConceptWriteFunc write, pmConceptLevel level);
     790\end{prototype}
     791
     792\code{pmConceptRegister} shall generate a concept specification from
     793the provided \code{blank}, and \code{read} and \code{write} functions,
     794and register it in the metadata specified by the \code{level}.
     795
     796\code{pmConceptLevel} simply specifies which level in the focal plane
     797hiearchy the concept applies to:
     798\begin{datatype}
     799typedef enum {
     800    PM_CONCEPT_LEVEL_FPA,               // Store in the FPA
     801    PM_CONCEPT_LEVEL_CHIP,              // Store in the chip
     802    PM_CONCEPT_LEVEL_CELL               // Store in the cell
     803} pmConceptLevel;
     804\end{datatype}
     805
     806A \code{read} function of \code{NULL} indicates that there is no
     807special interpretation of the concept required, and that it can be
     808used as read.  A \code{write} function of \code{NULL} indicates that
     809no special formatting of the concept is required, and that it can be
     810written as is.
     811
     812
     813\subsection{Default concepts}
     814
     815Below is a list of concepts that the IPP will use, with the expected
     816type and a short description.
     817
     818\begin{itemize}
     819\item \code{FPA.NAME} (\code{psString}): An identifier (e.g., observation number) for the FPA instance
     820\item \code{FPA.AIRMASS} (F32): Airmass at which the observation is made (boresight)
     821\item \code{FPA.FILTER} (\code{psString}): Filter used in observation
     822\item \code{FPA.POSANGLE} (F32): Position angle for camera
     823\item \code{FPA.RADECSYS} (\code{psString}): System of RA,Dec (e.g., J2000 or ICRS)
     824\item \code{FPA.RA} (F64): Right Ascension of boresight in radians
     825\item \code{FPA.DEC} (F64): Declination of boresight in radians
     826\item \code{CHIP.NAME} (\code{psString}): The name of the chip (unique within the FPA) --- set at FITS read
     827\item \code{CELL.NAME} (\code{psString}): The name of the cell (unique within the parent chip) --- set at FITS read
     828\item \code{CELL.GAIN} (F32): CCD gain (e/ADU)
     829\item \code{CELL.READNOISE} (F32): CCD read noise (e)
     830\item \code{CELL.SATURATION} (F32): CCD saturation point (ADU)
     831\item \code{CELL.BAD} (F32): CCD bad pixel point (ADU)
     832\item \code{CELL.XPARITY} (S32): Direction of CCD readout in x relative to the rest of the chip
     833\item \code{CELL.YPARITY} (S32): Direction of CCD readout in y relative to the rest of the chip
     834\item \code{CELL.READDIR} (S32): Read direction: line (1) or column (2)
     835\item \code{CELL.EXPOSURE} (F32): Exposure time of image (sec)
     836\item \code{CELL.DARKTIME} (F32): Dark time for image (sec)
     837\item \code{CELL.TRIMSEC} (\code{psRegion*}): Trim region
     838\item \code{CELL.BIASSEC} (\code{psList*} of \code{psRegion*}): Overscan region(s)
     839\item \code{CELL.XBIN} (S32): CCD binning in x
     840\item \code{CELL.YBIN} (S32): CCD binning in y
     841\item \code{CELL.TIMESYS} (\code{psTimeType}): Time system in use
     842\item \code{CELL.TIME} (\code{psTime*}): Time of observation start
     843\item \code{CELL.X0} (S32): x position of cell (0,0) on the chip
     844\item \code{CELL.Y0} (S32): y position of cell (0,0) on the chip
     845\end{itemize}
     846
     847\tbd{CELL.EXPOSURE, CELL.DARKTIME and CELL.TIME should actually be
     848specified at the readout level.  However, at this present time, we're
     849not sure how these should be specified, and so we move them up to the
     850cell level and assume that all readouts are of the same exposure and
     851dark time.}
     852
     853The concept specifications for the above shall be registered by
     854\code{pmConceptsInit}:
     855\begin{prototype}
     856bool pmConceptsInit(void);
     857\end{prototype}
     858
     859Since defined concept specifications are required before any concept
     860ingest can take place, all functions that work with the concepts must
     861call \code{pmConceptsInit} first.
     862
     863The concept specification metadata containers and the concept
     864specifications that have been registered shall all be freed by
     865\code{pmConceptsDone}:
     866\begin{prototype}
     867void pmConceptsDone(void);
     868\end{prototype}
     869Calling \code{pmConceptsDone} is required in order to avoid a memory
     870leak, since the metadata containers are defined \code{static}.
     871
     872\subsection{Reading, Writing and Blanking}
     873
     874Reading concepts is the act of determining their values and setting
     875them in the \code{concepts} metadata in the focal plane hierarchy.
     876Writing concepts is the act of taking the \code{concepts} metadata
     877which is in the focal plane hierarchy and preparing them for output.
     878By ``blanking'', we mean setting the concepts to a default or blank
     879value (e.g., \code{NaN} for floating point); this takes place before
     880reading, and can be used to set up a focal plane hierarchy without
     881reading from any particular source.
     882
     883The following functions shall read, write or blank (as appropriate)
     884the concepts at the appropriate level in the focal plane hierarchy:
     885\begin{prototype}
     886bool p_pmConceptsReadFPA(pmFPA *fpa);
     887bool p_pmConceptsReadChip(pmChip *chip);
     888bool p_pmConceptsReadCell(pmCell *cell);
     889bool p_pmConceptsWriteFPA(pmFPA *fpa);
     890bool p_pmConceptsWriteChip(pmChip *chip);
     891bool p_pmConceptsWriteCell(pmCell *cell);
     892bool p_pmConceptsBlankFPA(pmFPA *fpa);
     893bool p_pmConceptsBlankChip(pmChip *chip);
     894bool p_pmConceptsBlankCell(pmCell *cell);
     895\end{prototype}
     896
     897Under ordinary circumstances, these functions will be called by
     898\code{pmFPARead}, \code{pmFPAWrite} and \code{pmFPAConstruct}.
     899
     900
     901\subsection{Copying concepts}
     902
     903The values of concepts may be copied from one source to another:
     904\begin{prototype}
     905bool pmFPACopyConcepts(pmFPA *target, pmFPA *source);
     906\end{prototype}
     907
     908\code{pmFPACopyConcepts} shall iterate through the focal plane
     909hierarchy, copying the values of the concepts from the \code{source}
     910to the \code{target}.
     911
     912
     913%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     914
    768915\input{CameraImages.tex}
    769916
    … …  
    8671014pmReadout *pmSubtractBias(pmReadout *in, pmOverscanOptions *overscanOpts,
    8681015                          psRegion imageRegion, psList *overscanRegions,
    869                           const pmReadout *bias, const pmReadout *dark);
     1016                          const pmReadout *bias, const pmReadout *dark);
    8701017\end{prototype}
    8711018
    … …  
    9701117pmOverscanOptions *pmOverscanOptionsAlloc(bool single, bool scanRows,
    9711118                                          pmFit fitType, unsigned int order,
    972                                           psStats *stat);
     1119                                          psStats *stat);
    9731120\end{prototype}
    9741121
    … …  
    17261873  float Peak;               // peak counts above sky
    17271874  float Sky;                // sky level (background)
    1728   float SN;                 // approx signal-to-noise
     1875  float SN;                 // approx signal-to-noise
    17291876  int   nPixels;            // number of pixels used
    17301877} pmMoments;
    … …  
    18131960  psS32 nIter;              // number of iterations
    18141961  pmModelStatus status;     // fit status
    1815   float radius;             // fit radius actually used
     1962  float radius;             // fit radius actually used
    18161963} pmModel;
    18171964\end{datatype}
    … …  
    20892236\begin{datatype}
    20902237typedef struct {
    2091     pmModelType type;                   ///< PSF Model in use
    2092     psArray *params;                    ///< Model parameters (psPolynomial2D)
    2093     psPolynomial4D *ApTrend;            ///< ApResid vs (x,y,rflux) (rflux = ten(0.4*mInst)
    2094     pmGrowthCurve *growth;              ///< apMag vs Radius
    2095     float ApResid;                      ///< ???
    2096     float dApResid;                     ///< ???
    2097     float skyBias;                      ///< ???
    2098     float skySat;                       ///< ???
    2099     float chisq;                        ///< PSF goodness statistic
    2100     int nPSFstars;                      ///< number of stars used to measure PSF
    2101     int nApResid;                       ///< number of stars used to measure ApResid
     2238    pmModelType type;                   ///< PSF Model in use
     2239    psArray *params;                    ///< Model parameters (psPolynomial2D)
     2240    psPolynomial4D *ApTrend;            ///< ApResid vs (x,y,rflux) (rflux = ten(0.4*mInst)
     2241    pmGrowthCurve *growth;              ///< apMag vs Radius
     2242    float ApResid;                      ///< ???
     2243    float dApResid;                     ///< ???
     2244    float skyBias;                      ///< ???
     2245    float skySat;                       ///< ???
     2246    float chisq;                        ///< PSF goodness statistic
     2247    int nPSFstars;                      ///< number of stars used to measure PSF
     2248    int nApResid;                       ///< number of stars used to measure ApResid
    21022249} pmPSF;
    21032250\end{datatype}
    … …  
    21972344    PSFTRY_MASK_EXT_FAIL = 0x02, // 2: ext model failed to converge
    21982345    PSFTRY_MASK_PSF_FAIL = 0x04, // 3: psf model failed to converge
    2199     PSFTRY_MASK_BAD_PHOT = 0x08, // 4: invalid source photometry           
     2346    PSFTRY_MASK_BAD_PHOT = 0x08, // 4: invalid source photometry           
    22002347    PSFTRY_MASK_ALL      = 0x0f,
    22012348} pmPSFtryMaskValues;
    … …  
    22722419\begin{prototype}
    22732420bool pmSourceDefinePixels(pmSource *mySource,
    2274                           pmReadout *readout,
    2275                           psF32 x,
    2276                           psF32 y,
    2277                           psF32 Radius)
     2421                          pmReadout *readout,
     2422                          psF32 x,
     2423                          psF32 y,
     2424                          psF32 Radius)
    22782425
    22792426bool pmSourceRedefinePixels(pmSource *mySource,
    22802427                            pmReadout *readout,
    22812428                            psF32 x,
    2282                             psF32 y,
    2283                             psF32 Radius)
     2429                            psF32 y,
     2430                            psF32 Radius)
    22842431\end{prototype}
    22852432
    … …  
    23042451pmSource *pmSourceLocalSky(pmSource *source,
    23052452                           psStatsOptions statsOptions,
    2306                            float Radius)
     2453                           float Radius)
    23072454\end{prototype}
    23082455
    … …  
    25032650bool pmSourcePhotometry (float *fitMag,  // integrated fit magnitude
    25042651                         float *obsMag,  // aperture flux magnitude
    2505                         pmModel *model, // model used for photometry
    2506                         psImage *image, // image pixels to be used
    2507                         psImage *mask   // mask of pixels to ignore
     2652                        pmModel *model, // model used for photometry
     2653                        psImage *image, // image pixels to be used
     2654                        psImage *mask   // mask of pixels to ignore
    25082655);
    25092656\end{prototype}
    … …  
    25262673\begin{verbatim}
    25272674PM_SOURCE_DEFECT:       8
    2528 PM_SOURCE_SATURATED:    8
    2529 PM_SOURCE_SATSTAR:      10
    2530 PM_SOURCE_PSFSTAR:      1
    2531 PM_SOURCE_GOODSTAR:     1
     2675PM_SOURCE_SATURATED:    8
     2676PM_SOURCE_SATSTAR:      10
     2677PM_SOURCE_PSFSTAR:      1
     2678PM_SOURCE_GOODSTAR:     1
    25322679PM_SOURCE_POOR_FIT_PSF: 7
    25332680PM_SOURCE_FAIL_FIT_PSF: 4
    2534 PM_SOURCE_FAINTSTAR:    4
    2535 PM_SOURCE_GALAXY:       2
     2681PM_SOURCE_FAINTSTAR:    4
     2682PM_SOURCE_GALAXY:       2
    25362683PM_SOURCE_FAINT_GALAXY: 2
    2537 PM_SOURCE_DROP_GALAXY:  2
     2684PM_SOURCE_DROP_GALAXY:  2
    25382685PM_SOURCE_FAIL_FIT_GAL: 2
    25392686PM_SOURCE_POOR_FIT_GAL: 2
    2540 PM_SOURCE_OTHER:        ?
     2687PM_SOURCE_OTHER:        ?
    25412688\end{verbatim}
    25422689
Note: See TracChangeset for help on using the changeset viewer.