\documentclass[panstarrs,spec]{panstarrs}

\title{Postage Stamp Server} % put in your title
\subtitle{Conceptual Design}
\author{Eugene Magnier}
\audience{IPP}
\shorttitle{Postage Stamp CD}
\group{Pan-STARRS IPP}
\project{Pan-STARRS IPP}
\organization{Institute for Astronomy}
\version{DR}
\docnumber{PSDC-430-xxx}

\newcommand\ugriz{$u^\prime g^\prime r^\prime i^\prime z^\prime$}
\newcommand\grizy{$g r i z y$}

\begin{document}
\maketitle

\section{Overview}

The basic functionality of the postage stamp server is to accept lists
of postage stamp requests, determine the corresponding images, extract
the needed pixels from the images, and return the postage stamps to
the user.  The nominal mode of interation as an interface to MOPS and
the other Science Clients is for the postage lists 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 sent directly via a web server.  

\section{Inputs}

The basic information needed to by the postage stamp server to honor a
request consists of: 1) the image of interest and 2) the region on the
image desired.  This information may potentially be represented in a
wide number of ways.

\subsection{Image of Interest}

Within the IPP, there are a number of different derived image products
which may be produced for a given exposure, and other which are not
specifically coupled to a given exposures (eg, static sky image
stacks).  In addition, within a given IPP installation, there may be
multiple IPP projects with different representations of the same image
data.  There are a number of ways which the end users may want to
specify the desired images.  These are listed as follows, in order of
simplicity for the program, but in reverse order of simplicity for the
user.  

\begin{itemize}

\item {\bf Project \& Image ID set}.  The easiest way to define the
  input image, in terms of programming, is to explicitly specify the
  database ID which uniquely identifies the output image, and the IPP
  Project in which that ID is found.  Within the IPP pipeline
  database, there is not a single value which is the image ID for all
  images.  Instead, it is necessary to supply some additional
  information about which type of image is desired:
  
  \begin{tabular}{ll}
    DB table                   & keys \\
    \code{rawImfile}           & \code{exp_id} + \code{class_id} \\
    \code{chipProcessedImfile} & \code{exp_id} + \code{chip_id} \\
    \code{warpSkyfile} 	       & \code{warp_id} \\
    \code{diffSkyfile} 	       & \code{diff_id} \\
    \code{stackSumSkyfile}     & \code{stack_id} \\
  \end{tabular}

  The URI of the necessary input file can be determined from the
  specified data by simply doing a query on the specific table of
  interest.  In the event that the image is no longer on disk, the
  postage stamp server would need to have the ability of re-creating
  the image by re-running the needed IPP analysis steps.

 \item {\bf Project \& Exposure \& Type}.  A somewhat more abstract
 way to define the desired image would be to specify the exposure ID
 and the type of exposure (raw, chipProcessed, warped, etc), and make
 some additional assumptions to find the desired data.  For example,
 the coordinates specified may define which chip within an exposure or
 which output skyfile from a warp is desired.  The assumption could be
 made that, for a given type, the last of all versions available that
 match should be used.  The stack is ambiguous, but some choice could
 be made, such as the deepest or latest stack which includes the
 specified exposure.

 \item {\bf Project \& RA \& DEC \& Type}.  One step beyond the previous
 example would be to specify the coordinates to define the image(s) of
 interest.  To determine the images which overlap the given
 coordinates, a query can be made to the appropriate DVO instance.
 The will in general be more than one overlapping image.  The postage
 stamp server should be able to either return a collection of multiple
 images which match, or additional information, such as the time of
 the exposure or a version number, should be used to limit the result
 set.

\end{itemize}

\subsection{Region of Interest}

The postage stamp server needs to know which pixels to return from the
specified image(s).  The output images will be rectangular, so we need
only specify the center coordinate and the width \& height.  There
main options are:

\begin{tabular}{ll}
  Center Coordinate       & Size \\
  X,Y pixels              & dX,dY pixels \\
  $\alpha,\delta$ degrees & dX,dY pixels \\
  X,Y pixels              & d$\alpha$,d$\delta$ arcmin \\
  $\alpha,\delta$ degrees & d$\alpha$,d$\delta$ arcmin \\
\end{tabular}

If the measurements are given in celestial coordinates, the image
astrometry (the best available from the camera analysis table) should
be used to convert to pixel coordinates.  The postage stamp server
should given an error if the requested region does not itersect with
the requested image pixels.


\section{Components}

\begin{itemize}

\item {\bf stamp extraction tool} : this program accepts the image URI
  (or image set?), the region information (center, width, height), and
  and output URI.  It selects the image and extracts the pixels into a
  new image which it writes to the specified URI.

\item {\bf request parser} : this program accepts a FITS table with
  the requests in all possible formats listed above, examine the IPP
  database(s), and constructs the list of requests in the basic format
  of the image URI + region description.  This program need not
  determine if the desired image exists.

\item {\bf image regeneration tool} : this program takes the
  definition of the desired image (in the form of the table and the
  database IDs) and determines the steps needed to re-create that
  output image.  This tool should use the information in the database
  + the output result files as needed to recreate the original
  analysis, using, eg, the same detrend images, and the same
  astrometric calibration, etc.

\item {\bf pantasks postage stamp tasks} : the postage stamp server
  should be automated by defining a set of pantasks tasks for each of
  the steps.  One task would examine the data store for new requests,
  A second tasks would take the requests and send them to the request
  parse.  A third task would perform the extractions and either return
  the result to the data store or send the result to the next task.
  The last task would invoke the image regeneration tool for images
  which no longer exist on the spinning disks.

\end{itemize}

\end{document}
