\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}

