Index: /trunk/doc/stamps/stampsICD.tex =================================================================== --- /trunk/doc/stamps/stampsICD.tex (revision 28064) +++ /trunk/doc/stamps/stampsICD.tex (revision 28065) @@ -9,6 +9,6 @@ \project{Pan-STARRS IPP} \organization{Institute for Astronomy} -\version{DR} -\docnumber{PSDC-940-xxx} +\version{1.0} +\docnumber{PSDC-940-011-00} \newcommand\ugriz{$u^\prime g^\prime r^\prime i^\prime z^\prime$} @@ -49,5 +49,5 @@ Each row in a request table contains a postage stamp request specification. Each request specification causes zero or more postage stamp jobs to be processed. -An image is added to the output file set for each successful job. +Images are added to the output file set for each successful job. The request specification give the parameters that the PSS uses to determine the images of interest @@ -125,5 +125,5 @@ \subsubsection{Image Types} -All requests need IMG\_TYPE. This parameter selects the stage in the processing pipeline +All requests need IMG\_TYPE. This parameter selects the stage of the processing pipeline for the images of interest. The allowed values for IMG\_TYPE are raw, chip, warp, diff, and stack. @@ -139,5 +139,5 @@ IMG\_TYPE that contain the center. The set of images of interest may be limited by specifying certain criteria as described -in Section \ref{ImageCuts}. NOTE: this request type is not yet implemented. +in Section \ref{ImageCuts}. \item{\textbf{byexp}} The image of interest is the image resulting from a particular exposure @@ -149,11 +149,11 @@ \item{\textbf{bydiff}} The image with given IMG\_TYPE corresponding to the difference image -whose IMAGEID is equal to ID. This type is useful for requesting stamps based on difference detections. +whose diff\_skyfile\_id is equal to ID. This type is useful for requesting stamps based on difference detections. \item{\textbf{byskycell}} Images are selected from the skycell with skycell\_id equal to the value for COMPONENT from the tessellation identified by TESS\_ID. This request type may be -used only with IMG\_TYPE warp, stack, and diff. +used with IMG\_TYPE warp, stack, and diff. The set of images may be limited by filter and date as described in Section \ref{ImageCuts}. -NOTE: this request type is not yet implemented. + \end{itemize} @@ -231,7 +231,7 @@ the stamps are created the cells are mosaicked into a single image.) -Any fractional parts in pixel coordinate values are ignored. (XXX: is that true?) - -For JOB\_TYPE stamp the value of \code{OPTION\_MASK} is used to select various other options. +\subsection{Request Options} + +For \code{JOB_TYPE} stamp the value of \code{OPTION_MASK} is used to select various other options. It is a bitwise OR of the following values. @@ -239,17 +239,19 @@ \begin{center} \caption{}\label{optionmask} -\begin{tabular}{ll} -\hline -\hline -{\bf OPTION\_MASK value} & {\bf Description } \\ -\hline -1 & create postage stamp of the image pixels \\ -2 & create postage stamp of the mask pixels \\ -4 & create postage stamp of the variance pixels \\ -8 & return the sources file (.cmf) for the images' run \\ -16 & return the psf file for the images' run \\ -32 & return the background model file for the images chipRun (applies only for chip) \\ -1024 & make stamps from inverse difference images (applies only for diff) \\ -2048 & make stamps from unconvolved stack images (applies only for stack) \\ +\begin{tabular}{lll} +\hline +\hline +{\bf C Macro name} & {\bf Value} & {\bf Description } \\ +\hline +PSTAMP\_SELECT\_IMAGE & 1 & create postage stamp of the image pixels \\ +PSTAMP\_SELECT\_MASK & 2 & create postage stamp of the mask pixels \\ +PSTAMP\_SELECT\_VARIANCE & 4 & create postage stamp of the variance pixels \\ +PSTAMP\_SELECT\_CMF & 8 & return the sources file (.cmf) for the images' run \\ +PSTAMP\_SELECT\_PSF & 16 & return the psf file for the images' run \\ +PSTAMP\_SELECT\_BACKMDL & 32 & return the background model file for the images chipRun (applies only for chip) \\ +PSTAMP\_SELECT\_INVERSE & 1024 & make stamps from inverse difference images (applies only for diff) \\ +PSTAMP\_SELECT\_UNCONV & 2048 & make stamps from unconvolved stack images (applies only for stack) \\ +PSTAMP\_USE\_IMFILE\_ID & 16384 & for byid requests select images using image id instead of stage id \\ +PSTAMP\_NO\_WAIT\_FOR\_UPDATE & 32768 & if images are not available because they have been cleaned don't wait \\ \hline \end{tabular} @@ -264,6 +266,37 @@ For requests with IMG\_TYPE diff or if \code{REQ_TYPE} is bydiff and the corresponding difference run is a 'bothways' diff the images are selected based on the inverse difference -images if \code{(OPTION_MASK & 1024)} is non-zero. Otherwise from the images are selected based -on the 'positive' images. +images if \code{(OPTION_MASK & PSTAMP_SELECT_INVERSE)} is non-zero. +Otherwise from the images are selected based on the 'positive' images. + +For \code{REQ_TYPE} byid normally the \code{ID} value is the "Stage ID" or "Run ID" of the requested image. +If the bit \code{PSTAMP_USE_IMFILE_ID} is included in the \code{OPTION_MASK} for a byid request, +the \code{ID} for the request is the "Image ID" instead of the "Stage ID". +Table ~\ref{byid_ids} gives the IPP database column that corresponds to these identefiers for the various +stages. The "Image ID" is useful because it may be used to select component of a run. For example +the chip\_imfile\_id values are recorded in the DVO image table so it is easy to create a postage +stamp request from a DVO measurement. XXX: point to an example. + +\begin{table}[h] +\begin{center} +\caption{}\label{byid_ids} +\begin{tabular}{lll} +\hline +\hline +{\bf IMG\_TYPE/stage} & {\bf stage ID} & {\bf Image ID } \\ +\hline +raw & exp\_id & raw\_imfile\_id \\ +chip & chip\_id & chip\_imfile\_id \\ +warp & warp\_id & warp\_skyfile\_id \\ +diff & diff\_id & diff\_skyfile\_id \\ +stack & stack\_id & stack\_id \\ +\hline +\end{tabular} +\end{center} +\end{table} +Due to limited space on the IPP cluster, images files are deleted some time after they are created. Data in +this state is referred to as "cleaned". By default the postage stamp server will automatically regenerate +the pixels for requested images, if possible. This is referred to as the update process. +If the user does not wish to wait for the updates to complete he should include +\code{PSTAMP_NO_WAIT_FOR_UPDATE} in the \code{OPTION_MASK}. @@ -306,4 +339,5 @@ \code{ROWNUM} & U32 & identifier for this row in table\\ \code{ERROR_CODE} & U32 & Error code (see text) \\ +\code{ERROR_STR} & U32 & Name corresponding to \code{ERROR_CODE}\\ \code{IMG_NAME} & string & Name of image in Data Store file set \\ \code{JOB_ID} & S64 & Internal postage stamp server job id that produced this image \\ @@ -383,10 +417,10 @@ PSTAMP\_INVALID\_REQUEST & 21 & Error in a request specification. See parse\_error.txt \\ PSTAMP\_UNKNOWN\_PRODUCT & 22 & Unknown product in request specification \\ -PSTAMP\_NO\_IMAGE\_MATCH & 23 & No images matched the request \\ +PSTAMP\_NO\_IMAGE\_MATCH & 23 & No images matched the request \\ PSTAMP\_NOT\_DESTREAKED & 24 & Image matched, but not yet de-streaked \\ PSTAMP\_NOT\_AVAILABLE & 25 & Image not available (temporary) \\ -PSTAMP\_GONE & 26 & Image is no longer available \\ -PSTAMP\_NO\_JOBS\_QUEUED & 27 & Request specification yielded no jobs. See parse\_error.txt \\ -PSTAMP\_NO\_OVERLAP & 28 & Center not contained in any image of interest \\ +PSTAMP\_GONE & 26 & Image is no longer available \\ +PSTAMP\_NO\_JOBS\_QUEUED & 27 & Request specification yielded no jobs. See parse\_error.txt \\ +PSTAMP\_NO\_OVERLAP & 28 & Center coordinates are not contained in any image of interest \\ \hline