Index: /trunk/doc/stamps/stampsICD.tex =================================================================== --- /trunk/doc/stamps/stampsICD.tex (revision 35494) +++ /trunk/doc/stamps/stampsICD.tex (revision 35495) @@ -9,5 +9,5 @@ \project{Pan-STARRS IPP} \organization{Institute for Astronomy} -\version{1.0} +\version{2.0} \docnumber{PSDC-940-011-00} @@ -48,9 +48,12 @@ one or more FITS binary tables called \emph{request tables}. 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. +Each request specification causes zero or more postage stamp jobs to be created. 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 and the Region of Interest. + +Note: The value "null" for strings or 0 for numbers may be used to disable the application of +certain parameters. \subsection{Request Table Contents} @@ -69,6 +72,8 @@ \hline \code{EXTNAME} & string & \code{PS1_PS_REQUEST} \\ -\code{EXTVER} & string & 1 \\ +\code{EXTVER} & string & 2 \\ \code{REQ_NAME} & string & unique name of the request (see text) \\ +\code{ACTION} & string & PROCESS \\ +\code{EMAIL} & string & Email address of submitting user\\ \hline \end{tabular} @@ -81,9 +86,10 @@ This value is used for the name of the request's output file set. -The postage stamp server supports three types of "postage stamp" job specified by the value + +The postage stamp server supports two types of "postage stamp" job specified by the value the column \code{JOB_TYPE}. If the value is \emph{stamp} postage stamp images will be extracted from the images of interest. If the value of \code{JOB_TYPE} is \emph{get\_image} -the data from the selected images' "runs" with (satellite streaks removed) are bundled -in and placed on the output file set. +the data from the selected images' "runs" are bundled in the format used by the IPP distribution system +and are placed on the output file set. \begin{table}[h] @@ -97,4 +103,6 @@ \code{ROWNUM} & U32 & & must be unique in file\\ \code{PROJECT} & string & gpc1 & \\ +\code{SURVEY_NAME} & string & PS1 survey names & see table 3 \\ +\code{IPP_RELEASE} & string & IPP release name & e.g. 3PI.PV1, 3PI.nightly \\ \code{JOB_TYPE} & string & stamp or get\_image & \\ \\ @@ -117,6 +125,9 @@ \code{MJD_MIN} & F64 & Modified Julian Day & \\ \code{MJD_MAX} & F64 & & \\ -\\ -\code{COMMENT} & string & copied to the results flie & \\ +\code{RUN_TYPE} & string & stack or diff type & deep, reference, nightly, warp-stack, etc.\\ +\code{FWHM_MIN} & F64 & minimum measured seeing (pixels) & \\ +\code{FWHM_MAX} & F64 & maximum measured seeing (pixels) & \\ +\\ +\code{COMMENT} & string & copied to the results file & \\ \hline \end{tabular} @@ -159,5 +170,5 @@ \end{itemize} -Note that at this time the REQ\_TYPE byexp is not implemented for IMG\_TYPE stack. +Note that REQ\_TYPE byexp is not implemented for IMG\_TYPE stack. COMPONENT must also be supplied for request specifications where all of the following are true @@ -173,18 +184,67 @@ \end{itemize} -The special value 'all' may be used to select all component images but this is not recommended. +The special value "all" may be used to select all component components (chips or skycells) of a run. + \subsubsection{Image Selection Cuts}\label{ImageCuts} -A request specification may refer to many images. The scope of the search can be -limited to certain dates with the parameters MJD\_MIN and MJD\_MAX. The specified range is inclusive. -Note: these cuts have no effect for stack stage requests. +A request specification may refer to many images. The scope of the search can be reduced by providing +the selection parameters. + +SURVEY\_NAME (new in version 2) restricts the queries to images for a given PS1 survey. Valid values are +shown in the table below. The value "null" may also be used. + +\begin{table}[h] +\begin{center} +\caption{PS1 SURVEYNAME Values}\label{surveys} +\begin{tabular}{ll} +\hline +\hline +{\bf SURVEY\_NAME} & {\bf Description } \\ +\hline +3PI & PS1 3PI Survey \\ +MD01 & PS1 MD01 XMM-LSS-DXS 022224-043000 \\ +MD02 & PS1 MD02 CDFS/GOODS/GEMS 033224-274800 \\ +MD03 & PS1 MD03 IFA/Lynx 084300+444000 \\ +MD04 & PS1 MD04 COSMOS 100000+021200 \\ +MD05 & PS1 MD05 Lockman-DXS 110000+570000 \\ +MD06 & PS1 MD06 NGC 4258 121857+471814 \\ +MD07 & PS1 MD07 VISTA-Video1 140000+050000 \\ +MD08 & PS1 MD08 EliasN1-DXS 160000+570000 \\ +MD09 & PS1 MD09 Vimos4-DXS-SSA 220000+003000 \\ +MD10 & PS1 MD10 Deep2 233000+000000 \\ +M31 & PS1 M31 Andromeda 004242+411600 \\ +STS1 & PS1 STS1 Outskirts of Bulge 195048+170339 \\ +STS2 & PS1 STS2 Hyades 004000+150000 \\ +STS3 & PS1 STS3 Praesepe 083000+200000 \\ +SSS & PS1 Solar System Survey \\ +\hline +\end{tabular} +\end{center} +\end{table} + +IPP\_RELEASE (new in version 2) restricts the search for data from a particular "release" of IPP data. +If "null" the system choses data from the highest priority release ("best") of the given exposure or skycell. DATA\_GROUP restricts the search to runs with the given value. Note that the SQL database lookups -are done with a "LIKE" comparison so SQL wild cards may be used. +are done with a "LIKE" comparison so SQL wild cards may be used. With Version 2 of this specification +use of DATA\_GROUP is deprecated. It is ignored if a non null value for SURVEY\_NAME or IPP\_RELEASE is +supplied. + +Searches may be limited to certain dates with the parameters MJD\_MIN and MJD\_MAX. The specified range is inclusive. +Note: For stack stage requests, these cuts will have no effect on queries for deep or reference stacks. The REQFILT parameter may be used to restrict the search for images taken with a given filter. -If the filter is a single character (g, r, i, z, y) the server appends a '\%' character to the -sql query. +If the filter is a single character (g, r, i, z, y, w) the server appends a '\%' character to the +sql query. If "null" data from all filters is queried. + +The optional parameter RUN\_TYPE is used for specify the type of stack or difference images to consider as +images of interest. + +For difference images valid values are warp\_warp warp\_stack and stack\_stack. + +For stacks valid values are "deep", "reference", "nightly", and "notnightly". For stacks, this selector +is only applied if SURVEY\_NAME or IPP\_RELEASE is supplied. + @@ -230,4 +290,7 @@ When pixel coordinates are used the coordinate system is that of the image. (For chip level images, before the stamps are created the cells are mosaicked into a single image.) + +Note: If the width and height are both equal to zero, the entire input image is included in the stamp. Otherwise +values less than or equal to zero will generate an error. \subsection{Request Options} @@ -252,5 +315,5 @@ 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\_RESTORE\_BACKGROUND & 4096 & (TODO) restore background correction to chip stage images before making stamp \\ +PSTAMP\_RESTORE\_BACKGROUND & 4096 & restore background correction to chip stage images before making stamp \\ 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 \\ @@ -299,5 +362,6 @@ 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}. +\code{PSTAMP_NO_WAIT_FOR_UPDATE} in the \code{OPTION_MASK}. In this case the row will receive the error +code PSTAMP\_NOT\_AVAIALABLE. @@ -353,6 +417,10 @@ \code{EXPTIME} & F64 & exposure time of parent image \\ \code{FPA_ID} & string & orginal FPA\_ID used at injection \\ -\\ -\code{PROJECT} & string & Values from initial request specification\\ +\hline +& Values from corresponding row in the request file\\ +\hline +\code{PROJECT} & string & \\ +\code{SURVEY_NAME} & string & \\ +\code{IPP_RELEASE} & string & \\ \code{JOB_TYPE} & string & \\ \\ @@ -372,4 +440,7 @@ \code{MJD_MAX} & F64 & \\ \code{DATA_GROUP} & string & \\ +\code{RUN_TYPE} & string & \\ +\code{FWHM_MIN} & F64 & \\ +\code{FWHM_MAX} & F64 & \\ \code{COMMENT} & string & \\ \\ @@ -393,8 +464,8 @@ have the name \code{ROWNUM_I.mk.fits} -JOB\_ID is the value of the postage stamp server's internal job id. (This is provided primarily as a debugging +JOB\_ID is the value of the postage stamp server's internal job id. aid.) -The column named PROJECT and following columns are copies from the input request specification. +The column named PROJECT and following columns are copied from the input request specification. If ERROR\_CODE is non-zero an error occurred when processing the request specification or the job. @@ -419,9 +490,10 @@ PSTAMP\_UNKNOWN\_PRODUCT & 22 & Unknown product in request specification \\ PSTAMP\_NO\_IMAGE\_MATCH & 23 & No images matched the request \\ -PSTAMP\_NOT\_DESTREAKED & 24 & Image matched, but not yet de-streaked \\ +PSTAMP\_NOT\_DESTREAKED & 24 & Obsolete - No longer used\\ 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 coordinates are not contained in any image of interest \\ +PSTAMP\_NOT\_AUTHORIZED & 29 & user is not allowed access to the selected data\\ \hline