Index: trunk/doc/stamps/Makefile =================================================================== --- trunk/doc/stamps/Makefile (revision 18744) +++ trunk/doc/stamps/Makefile (revision 18745) @@ -1,3 +1,3 @@ -# $Id: Makefile,v 1.2 2007-12-20 23:37:47 bills Exp $ +# $Id: Makefile,v 1.3 2008-07-26 02:09:09 bills Exp $ PDFLATEX = env TEXINPUTS=.:LaTeX:$(TEXINPUTS): pdflatex @@ -6,5 +6,5 @@ help: @echo "USAGE: make (target)" - @echo " targets: all cd design" + @echo " targets: all cd design icd" cd: stampsCD.pdf @@ -12,5 +12,7 @@ design: stampsDesign.pdf -all : cd design +icd: stampsICD.pdf + +all : cd design icd CD = stampsCD.tex @@ -20,4 +22,6 @@ stampsDesign.pdf: $(DESIGN) + +stampsICD.pdf: stampsICD.tex add-tag: Index: trunk/doc/stamps/stampsICD.tex =================================================================== --- trunk/doc/stamps/stampsICD.tex (revision 18745) +++ trunk/doc/stamps/stampsICD.tex (revision 18745) @@ -0,0 +1,368 @@ +\documentclass[panstarrs,spec]{panstarrs} + +\title{IPP Postage Stamp Server} % put in your title +\subtitle{ICD} +\author{Bill Sweeney} +\audience{IPP} +\shorttitle{Postage Stamp ICD} +\group{Pan-STARRS IPP} +\project{Pan-STARRS IPP} +\organization{Institute for Astronomy} +\version{DR} +\docnumber{PSDC-940-xxx} + +\newcommand\ugriz{$u^\prime g^\prime r^\prime i^\prime z^\prime$} +\newcommand\grizy{$g r i z y$} + + +\begin{document} + +\maketitle +\tableofcontents + +\pagebreak +\pagenumbering{arabic} + +\section{Overview} + +The basic functionality of the postage stamp server is to accept lists +of postage stamp requests, determine the corresponding images, extract +the desired pixels from the images, and return the postage stamps to +the user. The nominal mode of interaction as an interface to MOPS and +the other Science Clients is for the postage stamp requests to be FITS tables +which are placed as incoming data on the IPP Data Store (or the data +store of the requesting system) and for the results to be placed back +on the IPP Data Store, along with a FITS table description of the +resulting output image files. For the generic user, the requests and +the result may be accessed directly via a web server. + +The basic information needed to by the postage stamp server (PSS) to honor a +request consists of: 1) the image of interest and 2) the region on the +image desired (ROI). This information may be represented in a number of ways +which are discussed in section 2.1. % How do I include a reference by tag? + +\section{Postage Stamp Requests} + + +Postage stamp requests are packaged for submission to the PSS in a file set containing +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. +An image is 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. + +\subsection{Request Table Contents} + +The required header keywords for a request table +are given in Table~\ref{RHeaderDef}. +The definition for the table's columns is in Table~\ref{RTableDef}. + +\begin{table}[h] +\begin{center} +\caption{Postage Stamp Request File Header Keywords}\label{RHeaderDef} +\begin{tabular}{lll} +\hline +\hline +{\bf FITS Keyword} & {\bf Datatype} & {\bf Description } \\ +\hline +\code{EXTNAME} & string & \code{PS1_PS_REQUEST} \\ +\code{EXTVER} & string & 1 \\ +\code{REQ_NAME} & string & unique name of the request (see text) \\ +\hline +\end{tabular} +\end{center} +\end{table} + +The IPP will be configured to periodicly query a set of Data Stores for new request file sets. +We will refer to each Data Store as a \emph{requestor}. +Each request table submitted by a given requstor must have a unique value for +the keyword \code{REQ_NAME}. 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 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} a copy +of the selected image(s) with (satelite streaks removed) will be placed on the output file set. +Finally if the \code{JOB_TYPE} is \emph{list} the results file will list the input selected images +but no postage stamps will be made. + +\begin{table}[h] +\begin{center} +\caption{Postage Stamp Request Table Columns}\label{RTableDef} +\begin{tabular}{llll} +\hline +\hline +{\bf Column Name} & {\bf Datatype} & {\bf Values} & {\bf Notes } \\ +\hline +\code{ROWNUM} & U32 & & must be unique in file\\ +\code{PROJECT} & string & TBD & \\ +\code{JOB_TYPE} & string & stamp or get\_image & \\ +\\ +\code{STAMP_NAME} & string & letters, numbers, '.', '\-' and '\_' & \\ +\code{OPTION_MASK} & U32 & \code{[0-5]} see text & \\ +\\ +\code{REQ_TYPE} & string & bycoord, byexp, or byid & \\ +\code{IMG_TYPE} & string & raw, chip, warp, diff, or stack & \\ +\code{ID} & string & depends on project and REQ\_TYPE& \\ +\code{CLASS_ID} & string & see text & not null for byid raw \& byexp raw \\ +\\ +\code{COORD_MASK} & U32 & \code{[0-3]} see text & not null if \code{JOB_TYPE} = stamp \\ +\code{CENTER_X} & F64 & see text & not null if \code{JOB_TYPE} = stamp \\ +\code{CENTER_Y} & F64 & see text & not null if \code{JOB_TYPE} = stamp \\ +\code{WIDTH} & F64 & see text & not null if \code{JOB_TYPE} = stamp \\ +\code{HEIGHT} & F64 & see text & not null if \code{JOB_TYPE} = stamp \\ +\\ +\code{REQFILT} & string & any & used only for \code{REQ_TYPE} = bycoord \\ +\code{MJD_MIN} & F64 & Modified Julian Day & used only for \code{REQ_TYPE} = bycoord \\ +\code{MJD_MAX} & F64 & & used only for \code{REQ_TYPE} = bycoord \\ +\\ +\hline +\end{tabular} +\end{center} +\end{table} + +\subsubsection{Image Types} +All requests need IMG\_TYPE. This parameter selects the stage in the processing pipeline +for the images of interest. +The allowed values for IMG\_TYPE are raw, chip, warp, diff, and stack. + +\subsubsection{Request Types} +The method used to select the images of interest is determined by the value of the REQ\_TYPE column. +There are three alllowed values. + +\begin{itemize} + +\item{\textbf{bycoord}} The center of the region of interest is specifed in celestial coordinates. +Images are selected by querying the project's DVO database for images with the provided +IMG\_TYPE that contain the center. +The set of images of interest may be limited by specifying certain criteria as described +in Section \ref{ImageFilters}. + +\item{\textbf{byexp}} The image of interest is the image resulting from a particular exposure +name given by the value of the ID column. + +\item{\textbf{byid}} The image with given IMG\_TYPE and ID is the image of interest. +The ID parameter refers to IPP image database key that corresponds to the IMG\_TYPE. +e.g: either exp\_id, chip\_id, warp\_id, diff\_id, or stack\_id. +\end{itemize} + +CLASS\_ID must also be supplied for request specifications where all of the following are true + +\begin{itemize} + +\item the ROI center is specified in pixel coordinates + +\item JOB\_TYPE=stamp + +\item REQ\_TYPE=byexp or REQ\_TYPE=byid + +\item IMG\_TYPE=chip or IMG\_TYPE=raw + +\end{itemize} + + +\subsubsection{Image Selection Filters}\label{ImageFilters} + +A request for given celestial coordinates 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. + +The REQFILT parameter may be used to restrict the search for images taken with a given filter. +XXX: What is the namespace for filter names. For example Megacam has filter names like U.9301 which +IPP maps to u. Which name do we allow? Probably should used the mapped names g r i etc. + +\subsection{The Region of Interest} + +Postage stamps are extracted from a rectangular region on the input image. The region is defined by +a center, width, and height. + +The center is defined by the columns CENTER\_X and CENTER\_Y and the dimenions of the rectangle are +the values of WIDTH and HEIGHT. The two least signficant bits in value for the column COORD\_MASK +determine the type for the coordinates + +\begin{table}[h] +\begin{center} +\caption{}\label{Rcoordmask} +\begin{tabular}{ll} +\hline +\hline +{\bf COORD\_MASK value} & {\bf Description } \\ +\hline +0 & center in RA/DEC; width \& height in arcseconds\\ +1 & center in pixel coordinates; width and height in arcseconds\\ +2 & center in RA/DEC; width and height in pixels\\ +3 & center x/y, width, and height in pixel coordinates\\ +\hline +\end{tabular} +\end{center} +\end{table} + +Another way to describe this is that COORD\_MASK is two bit mask that bitmask that +determines the format of the ROI values. In the C language: + +\begin{itemize} +\item\code{#define PSTAMP_CENTER_IN_PIXELS 1} +\item\code{#define PSTAMP_RANGE_IN_PIXELS 2} +\end{itemize} + +If \code{COORD_MASK & PSTAMP_CENTER_IN_PIXELS} is zero, CENTER\_X is the right ascension of +the ROI center in degrees and CENTER\_Y is its declination in degrees. + +If \code{COORD_MASK & PSTAMP_RANGE_IN_PIXELS} is zero, WIDTH and HEIGHT are measured in seconds of arc. + +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 mosaiced into a single image.) + +Any fractional parts in pixel coordinate values are ignored. + +The value of \code{OPTION_MASK} is used to select various other options. It is a bitwise or of the following +values. + +\begin{table}[h] +\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 weight pixels \\ +8 & convert WCS to approximate linear transformation in the stamp images\\ +\hline +\end{tabular} +\end{center} +\end{table} + + +\section{Results File} + +Each request specification (each row in a request file) results in zero or more postage stamp jobs +to be queued and executed. Each job results in a row in the Postage stamp server results table. + + +\subsection{Results Table Contents} + +The required header keywords for a results table +are given in Table~\ref{ResHeaderDef}. +The definition for the table's columns is in Table~\ref{ResTableDef}. + +\begin{table}[h] +\begin{center} +\caption{Postage Stamp Results File Header Keywords}\label{ResHeaderDef} +\begin{tabular}{lll} +\hline +\hline +{\bf FITS Keyword} & {\bf Datatype} & {\bf Description } \\ +\hline +\code{EXTNAME} & string & \code{PS1_PS_RESULTS} \\ +\code{EXTVER} & string & 1 \\ +\code{REQ_NAME} & string & name of the request the results correspond to ) \\ +\code{REQ_ID} & S64 & internal postage stamp id for the request \\ +\hline +\end{tabular} +\end{center} +\end{table} + +\begin{table}[h] +\begin{center} +\caption{Postage Stamp Results Table Columns}\label{ResTableDef} +\begin{tabular}{lll} +\hline +\hline +{\bf Column Name} & {\bf Datatype} & {\bf Values} \\ +\code{ROWNUM} & U32 & identifier for this row in table\\ +\code{ERROR_CODE} & U32 & Error code (see text) \\ +\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 \\ +\\ +\code{RA_DEG} & F64 & RA of stamp center in degrees \\ +\code{DEC_DEG} & F64 & Declination of stamp center in degrees \\ +\\ +\code{MJD_OBS} & F64 & actual start time of exposure \\ +\code{RA_OBS} & F64 & J2000 field center RA at start of exposure MJD \\ +\code{DEC_OBS} & F64 & J2000 field center Dec at start of exposure MJD \\ +\code{FILTER} & string & Actual filter retrieved (may differ from REQFILT\\ +\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\\ +\code{JOB_TYPE} & string & \\ +\\ +\code{REQ_TYPE} & string & \\ +\code{IMG_TYPE} & string & \\ +\code{CLASS_ID} & string & \\ +\\ +\code{COORD_MASK} & U32 & \\ +\code{CENTER_X} & F64 & \\ +\code{CENTER_Y} & F64 & \\ +\code{WIDTH} & F64 & \\ +\code{HEIGHT} & F64 & \\ +\\ +\code{REQFILT} & string & \\ +\code{MJD_MIN} & F64 & \\ +\code{MJD_MAX} & F64 & \\ +\\ +\hline +\end{tabular} +\end{center} +\end{table} + +Each line in the results file corresponds to a job to create a postage stamp image. ROWNUM gives +the corresponding row in the request file. +Note that if more than one bit is set in the OPTION\_MASK, a single job may generate multiple images +and so there may be multiple rows in the results file with the same value of ROWNUM. + +IMG\_NAME give the name of the image in the Data Store file set. + +If no STAMP\_NAME is provided in the request specifiction the image file names will be in the form +\code{ROWNUM_I.fits} where I is an integer that ranges from 1 to the number of jobs that the request +specification generated. Mask images will be named \code{ROWNUM_I.mk.fits} and weight images will +have the name \code{ROWNUM_I.mk.fits} + +If STAMP\_NAME is provided in the resquest specification, the name of the image, mask, and weight files +will be +\begin{itemize} +\item\code{ROWNUM_I_STAMP_NAME.fits} +\item\code{ROWNUM_I_STAMP_NAME.mk.fits}, +\item\code{ROWNUM_I_STAMP_NAME.wt.fits} +\end{itemize} + +JOB\_ID is the value of the postage stamp server's internal job id. This is provided primarily as a debugging +aid. + +The column named PROJECT and following columns are copies from the input request specification. + +If ERROR\_CODE is non-zero one or more errors occured processing the request specification. +The value of ERROR\_CODE is a bitwise or of the values given in the table\ref{Rerrorcodes}. + + + +\begin{table}[h] +\begin{center} +\caption{Postage Stamp Error Codes}\label{Rerrorcodes} +\begin{tabular}{lll} +\hline +\hline +{\bf Name} & {\bf ERROR\_CODE value} & {\bf Description } \\ +\hline +NO\_ERROR & 0 & \\ +NO\_MATCHING\_IMAGE & 1 & No image matches the request specification \\ +RA\_DEC\_NOT\_ON\_PIXEL & 2 & The central RA, DEC are on a blind area (for example a inter-chip gap) \\ +RA\_DEC\_NOT\_IN\_FOV & 4 & Wrong position on sky for given MJD \\ +NO\_IMAGE\_FOR\_FILTER & 8 & Image is not in the filter requested \\ +NOT\_AVAILABLE\_PERM & 16 & Image matched but is permanantly unavailable\\ +NOT\_AVAILABLE\_TEMP & 32 & Image matched but is currently unaccessible\\ +INVALID\_REQUEST & 64 & request specification was invalid \\ +SYSTEM\_ERROR & 128 & system error \\ +\hline +\end{tabular} +\end{center} +\end{table} + +In the case of an error parsing the request table a file containing a textual description of the errror +may be added to the resulting file set. + +\end{document} +