Changeset 28065

Timestamp:

May 21, 2010, 11:51:17 AM (16 years ago)

Author:

bills

Message:

Version 1 of postage stamp ICD

File:

• trunk/doc/stamps/stampsICD.tex (modified) (10 diffs)

trunk/doc/stamps/stampsICD.tex

@@ -9 +9 @@
 \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 +49 @@
 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 +125 @@
 
 \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 +139 @@
 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 +149 @@
 
 \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 +231 @@
 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 +239 @@
 \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 +266 @@
 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 +339 @@
 \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 +417 @@
 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