Changeset 276

Timestamp:

Mar 22, 2004, 12:23:02 PM (22 years ago)

Author:

eugene

Message:

merged in utils.tex (RHL), metadata.tex (RHL), and psLibSubset.tex (EAM)
added an appendix with all functions listed

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (8 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -4 +4 @@
 % basic document variables
 \title{Pan-STARRS IPP Library Design}
-\author{}
+\author{Paul Price, Eugene Magnier, Robert Lupton}
 \shorttitle{PSLib Design}
 \group{Pan-STARRS Algorithm Group}
@@ -67 +67 @@
 \section{System Utilities}
 
-\note{INSERT HERE STUFF FROM RHL'S \file{utils.pdf}}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Memory Management}
+\hlabel{psMemBlock}
+
+\subsubsection{Introduction}
+
+The \PS{} software system will need a level of memory management
+placed between the operating system (malloc/free) and the high level
+routines (e.g. \code{psMetaDataAlloc}).
+
+This layer is in addition to the possibility that specific heavily
+used data types may need their own special-purpose memory managers;
+but as we have specified that all user-level objects be allocated via
+\code{typeAlloc/typeFree} functions, we will easily be able to
+implement such functionality without impacting on the facilities
+described here.
+
+All of the memory management APIs should be provided in a header file
+\file{psMemory.h} which is included by \file{psUtils.h}.
+
+\subsubsection{Rationale}
+
+We wish to insert our own layer of memory management for a number of
+reasons:
+
+\begin{itemize}
+\item
+  We wish to insulate ourselves from the details of the system-provided
+  \code{malloc}.  There is no guarantee that the goals of the system
+  architect align with those of the \PS{} processing
+
+\item
+  We need at least a wrapper layer which handles failed memory
+  requests without requiring the application programmer to check
+  every attempted allocation.
+
+\item
+  We need to provide a mechanism for tracking and fixing memory
+  leaks.  While it is possible to do this by linking with external
+  libraries (\tbd{reference}), it is convenient to do so within the
+  \PS{} framework.
+
+\item
+  Similarly, we wish to provide convenient hooks to detect and diagnose
+  memory corruption.
+
+\item
+  While debugging complex scientific code, it is very useful to be
+  able to trace a given data structure as it passed through the
+  processing pipeline.
+
+\item
+  There may be other features that we wish to add in the future (e.g.
+  associating a type with every allocation).
+\end{itemize}
+
+\subsubsection{A Minimal Specification}
+
+The previous section laid out a number of desiderata for a memory
+management system.  Rather than implement our own heap-manager at this
+stage of the project, I propose that we put in place a sufficient
+set of data structures and APIs, but initially implement only
+a simple subset (e.g. that we not implement a multi-bucket memory
+manager that takes in 100Mb chunks from the system and performs
+sophisticated defragmentation and garbage collection).
+
+Subject to agreement with the IfA, some of the functions proposed
+here may be omitted from the initial implementation; in particular
+the routines \code{psMemCheckCorruption} and \code{psMemCheckLeaks}
+may be hard to build efficiently in a simple implementation based
+upon adding extra fields to allocation requests.
+
+\paragraph{Extra information to be saved by Memory Allocation Functions}
+
+It is required that a table of all allocated memory blocks be
+maintained by the \PS{} memory system.
+
+Each allocated block should preserve at least the information present
+in the following struct definition:
+\begin{verbatim}
+  typedef struct {
+      const unsigned long id;           // a unique ID for this allocation
+      const char *file;                 // set from __FILE__ in e.g. p_psAlloc
+      const int lineno;                 // set from __LINE__ in e.g. p_psAlloc
+      int refcntr;                      // how many times pointer is referenced
+      const void *magic;                // initialised to P_PS_MEMMAGIC
+  } psMemBlock;
+\end{verbatim}
+
+The value of \code{P_PS_MEMMAGIC} shall be \code{(void *)0xdeadbeef}%
+\footnote{Why this choice? Tradition, and because it's easy to notice
+  in a hex dump.}
+
+\paragraph{APIs for using Memory Allocation Functions}
+
+\begin{table}
+\begin{verbatim}
+void *psAlloc(size_t size);
+void *psRealloc(void *ptr, size_t size);
+void psFree(void *ptr);
+
+void *p_psAlloc(size_t size, const char *file, int lineno);
+void *p_psRealloc(void *ptr, size_t size, const char *file, int lineno);
+void p_psFree(void *ptr, const char *file, int lineno);
+
+#define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__)
+#define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__)
+#define psFree(size) p_psFree(size, __FILE__, __LINE__)
+\end{verbatim}
+\begin{caption}{The APIs required to use the \PS{} memory allocation routines}
+  \hlabel{tabUsageAPI}
+  The APIs required to use the \PS{} memory allocation routines, and as
+  provided by \file{psMemory.h}.
+\end{caption}
+\end{table}
+
+The types and function prototypes for the part of the memory API
+concerned with allocating and freeing memory are given in table
+\ref{tabUsageAPI}).
+
+N.b.
+\begin{itemize}
+\item
+  The functions \code{psAlloc}, \code{psRealloc}, and
+  \code{psFree} are defined, and are required to be equivalent to
+  \code{p_psAlloc}, \code{p_psRealloc}, and \code{p_psFree}
+  with the final two arguments \code{"(unknown)"} and \code{0}.
+
+  In the descriptions that follow, I shall not distinguish between the
+  functions with and without the \code{p_} prefix.
+
+\item
+  Except as specified below, the functions \code{psAlloc},
+  \code{psRealloc}, and \code{psFree} have identical semantics
+  to the standard C library functins \code{malloc}, \code{realloc},
+  and \code{free}.
+  
+\item
+  The file \file{psMemory.h} shall take steps to ensure that
+  code calling the functions \code{malloc}, \code{calloc}, \code{realloc},
+  or \code{free} shall not compile (\eg{} \code{#define malloc(S) for})
+  unless the symbol \code{PS_ALLOC_MALLOC} is defined.
+
+\item
+  In all cases, application code will call
+  \code{p_\{psAlloc,psRealloc,psFree\}} via the macros defined above.
+  
+\item
+  The functions \code{psAlloc} and \code{psRealloc} shall never
+  return a \code{NULL} pointer. If they are unable to provide
+  the requested memory they should attempt to obtain the desired
+  memory by calling the routine registered by \code{psMemExhaustedSetCB} (see
+  subsubsection \ref{secMemAdvanced}), and if still unsuccessful,
+  call \code{abort()}.
+
+\item
+  The memory management routines shall maintain the field
+  \code{psMemBlock.refcntr}. It should be set to \code{1}
+  when a block is returned to the user. It is an error to
+  attempt to free a block with \code{psMemBlock.refcntr != 1}
+  (see subsubsection \ref{secMemRefcounter}).
+  
+\item
+  Where practical and efficient, the memory manager shall call
+  the routine registered using the \code{psMemProblemSetCB}
+  (see section \ref{secMemAdvanced})
+  whenever a corrupted block of memory is discovered. For example,
+  doubly-freed blocks can be detected by checking \code{psMemBlock.refcntr}.
+
+\item
+  There is no \code{psCalloc} function. Initialisation of data is
+  almost always more complex than setting all bytes to 0.
+\end{itemize}
+
+\paragraph{APIs for Tracing and Debugging Memory}
+\hlabel{secMemAdvanced}
+
+\begin{table}
+\begin{verbatim}
+typedef int (*psMemCallback)(const psMemBlock *ptr);
+typedef void (*psMemProblemCallback)(const psMemBlock *ptr,
+                                     const char *file, int lineno);
+typedef void *(*psMemExhaustedCallback)(size_t size);
+
+psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func);
+psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func);
+
+psMemCallback psMemAllocateSetCB(psMemCallback func);
+psMemCallback psMemFreeSetCB(psMemCallback func);
+
+int psMemGetId(void);                   // get next memory ID
+
+long psMemSetAllocateID(long id);       // set p_psMemAllocateID to id
+long psMemSetFreeID(long id);           // set p_psMemFreeID to id
+
+int psMemCheckLeaks(
+    int id0,                            // don't list blocks with id < id0
+    psMemBlock ***arr,                  // pointer to array of pointers to
+                                        //leaked blocks, or NULL
+    FILE *fd);                          // print list of leaks to fd (or NULL)
+int psMemCheckCorruption(int abort_on_error);
+\end{verbatim}
+\begin{caption}{The APIs required to use the \PS{} memory allocation routines}
+  \hlabel{tabCallbackAPI}
+  The APIs required to use the callback and tracing facilities
+  in \PS{} memory allocation routines, as defined in \file{psMemory.h}.
+\end{caption}
+\end{table}
+
+The types and function prototypes for this part of the memory API
+are given in table \ref{tabCallbackAPI}.
+
+\paragraph{Callback Routines}
+
+The four `\code{SetCB}' routines are:
+
+\begin{tabular}{ll|l}
+\textbf{type} &  \textbf{Name} & \textbf{Function of callback} \\
+psMemProblemCallback & psMemProblemSetCB &
+Called when a problem is detected with data being managed on the heap \\
+psMemExhaustedCallback & psMemExhaustedSetCB &
+Called when \code{psAlloc} is unable to satisfy a memory request. \\
+psMemCallback & psMemAllocateSetCB &
+Callback is called when the \code{psMemBlock} with a specified ID is
+allocated. \\
+psMemCallback & psMemFreeSetCB &
+Callback is called when the \code{psMemBlock} with a specified ID is
+freed. \\
+\end{tabular}
+
+N.b.
+\begin{itemize}
+\item
+  In all cases, the `\code{SetCB}' routine takes a pointer to the
+  desired callback function, and returns a pointer to the one that was
+  previously installed. If the function pointer is \code{NULL}, the
+  default callback function is reinstalled.
+
+\item
+  The routine installed by \code{psMemExhaustedSetCB} should return
+  a pointer to the desired memory or \code{NULL}; in the latter case
+  \code{psAlloc} will call \code{abort()}
+
+\item
+  \code{psMemGetId} returns the current value of \code{psMemBlock.id}.
+
+\item
+  The handler specified by \code{psMemAllocateSetCB} is called just
+  before the pointer with \code{psMemBlock.id} equal to
+  \code{p_psMemAllocateID} is returned to the user. The variable
+  \code{p_psMemAllocateID} should not be set directly in any
+  delivered code, \code{psMemSetAllocateID} should be used instead.
+
+\item
+  The handler specified by \code{psMemFreeSetCB} is called just
+  before the pointer with \code{psMemBlock.id} equal to
+  \code{p_psMemFreeID} is freed. The variable
+  \code{p_psMemFreeID} should not be set directly in any delivered
+  code, \code{psMemSetFreeID} should be used instead.
+
+\item
+  The routines \code{psMemSetFreeID} and \code{psMemSetAllocateID}
+  accept the desired ID value (see previous two items) and return
+  the old value to the user.
+
+\item
+  The return values of the handlers installed by \code{psMemAllocateSetCB}
+  and \code{psMemFreeSetCB} are used to increment the values of
+  \code{p_psMemAllocateID} and \code{p_psMemFreeID} respectively.
+
+  For example, the return value \code{0} implies that the value is unchanged;
+  if the value is \code{2} the callback will be called again when the
+  memory ID counter has increased by two.
+\end{itemize}
+
+\paragraph{Memory Tracing and Corruption Routines}
+
+The routine \code{psMemCheckLeaks} may be used to check for memory
+leaks. The return value is the number of blocks that have been
+allocated but not freed.
+
+Only blocks with \code{psMemBlock.id} greater than \code{id0}
+are checked; this allows the user to ignore blocks allocated
+by initialisation routines.
+
+If the argument \code{arr} is non-\code{NULL}, then upon entering
+the call \code{**arr} should be \code{NULL}. Upon return it is set
+to an array of \code{psMemBlock *} pointers, one for each block
+allocated but not freed.  It is the caller's responsibility to free
+this array with \code{psFree}.
+
+If the argument \code{fd} is non\code{NULL}, a one-line summary
+of each block that has been allocated but not freed is written to that
+file descriptor.
+
+The routine \code{psMemCheckCorruption} checks the entire heap for
+corruption, calling the routine registered with
+\code{psMemProblemSetCB} for each block detected as being corrupted.
+The return value is the number of corrupted blocks detected. If the
+argument \code{abort_on_error} is true,
+\code{psMemCheckCorruption} shall call \code{abort()} as soon as
+memory corruption is detected.
+
+\paragraph{Reference Counting}
+\hlabel{secMemRefcounter}
+
+The memory management routines include a field
+\code{psMemBlock.refcntr} which must equal \code{1} whenever
+a pointer is presented to \code{psFree}.
+
+The API for this field is:
+\begin{verbatim}
+int psMemGetRefCounter(void *vptr);        // return refcounter
+void *psMemIncrRefCounter(void *vptr);     // increment refcounter and return vptr
+void *psMemDecrRefCounter(void *vptr);     // decrement refcounter and return vptr
+\end{verbatim}
+
+The functions \code{psMemIncrRefCounter} and \code{psMemDecrRefCounter} shall
+return \code{NULL} if passed a \code{NULL} pointer.
+
+\subsubsubsection{Rationale}
+
+\begin{table}
+\begin{verbatim}
+typedef struct {
+    char *name;
+    int value;
+} psSimple;
+
+psSimple *psSimpleAlloc(const char *name, int val)
+{
+    psSimple *simp = psAlloc(sizeof(psSimple));
+    simp->name = strcpy(psAlloc(strlen(name) + 1), name);
+    simp->value = val;
+
+    return simp;
+}
+
+void psSimpleFree(psSimple *simp)
+{
+    if (simp == NULL) { return; }
+
+    if (psMemGetRefCounter(simp) > 1) {
+        (void)psMemDecrRefCounter(simp);
+        return;
+    }
+}
+\end{verbatim}
+\begin{caption}{An example of reference counting}
+  \hlabel{tabReferenceCounting}
+  An example of using reference counting
+\end{caption}
+\end{table}
+
+The \code{psMemBlock.refcounter} is clearly useful for detecting
+attempts to free memory that is already free.  A more complex
+application is for allowing pointers to complex data-objects (e.g.
+images) to appear in more than one data structure simultaneously
+(see table \ref{tabReferenceCounting}).
+
+Because of the use of the \code{refcounter} field, we can safely put items of
+this type onto many lists:
+\goodbreak
+\begin{verbatim}
+simp = psSimpleAlloc("RHL", 0);
+psDlistAppend(list1, psMemIncrRefCounter(simp));
+psDlistAppend(list2, psMemIncrRefCounter(simp));
+psSimpleFree(simp);
+\end{verbatim}
+
+(Note: in fact there is no need to explicitly increment the counter
+in this case, as the \code{psDlistAppend} (section \ref{psDlist})
+API specifies that it
+does it for you.)
+
+\subsection{Tracing and Logging}
+
+This document defines the \PS{} Tracing and Logging APIs; the former
+refers to debug information that we wish to be able to turn on and off
+without recompiling (although it will \emph{not} be available in
+production code); the latter means information about the processing
+that must be collected and saved, even in the production system.
+
+We envision that we will make extensive use of \code{psTrace} throughout
+the \PS{} code.
+
+\subsubsection{Tracing APIs}
+\hlabel{psTrace}
+
+\begin{table}
+  \begin{verbatim}
+#if defined(PS_NTRACE)
+#  define psTrace(facil, level, ...) /* do nothing */
+#else
+#  define psTrace(facil, level, ...) \
+          p_psTrace(facil, level, __VA_ARGS__)
+#endif
+
+void p_psTrace(const char *facil, int level, ...);
+
+int psSetTraceLevel(const char *facil,  // facilty of interest
+                    int level);         // desired trace level
+int psGetTraceLevel(const char *name);  // facilty of interest
+
+void psTraceReset(void);                // turn off all tracing, and free trace's allocated memory
+
+void psPrintTraceLevels(void);          // print trace levels
+  \end{verbatim}
+  \begin{caption}{The public API for the trace facility
+      from \file{psTrace.h}.}
+    \hlabel{tabTraceAPI}
+  \end{caption}
+\end{table}
+
+The public API for the trace facility (table \ref{tabTraceAPI})
+should be provided in a header file \file{psTrace.h} which
+is included by \file{psUtils.h}.
+
+\begin{itemize}
+  \item
+    Logging is provided by the function \code{psTrace},
+    which is actually a macro.  When the macro \code{PS_NTRACE}
+    is defined, all occurrences of  \code{psTrace} shall
+    be replaced by whitespace.
+
+  \item
+    The first argument to \code{psTrace} is a name of the form
+    \code{aaa.bbb.ccc}. The second is an integer,
+    \code{level}. The remaining arguments are a printf-style format
+    and a (possibly empty) set of values for that formatting
+    string. When this trace is active, \code{psTrace} shall generate
+    the requested output on \code{stdout}, preceded by \code{level}
+    spaces.
+
+  \item
+    The call \code{psSetTraceLevel(name, level)} shall set the trace
+    level for \code{name} to \code{level}.
+
+  \item
+    The call \code{psGetTraceLevel(name)} shall return the level
+    associated with \code{name}.  If \code{name} has not been
+    associated with a level, the routine shall remove the \textit{last}
+    element of \code{name} and attempt to look up its level; this
+    procedure shall be applied recursively until the name is reduced
+    to \code{""}; if this name has no level associated with
+    it, then the value \code{0} shall be returned (see examples
+    below).
+
+    \item
+      The call \code{psTrace(name, level, ...)}
+      shall print the message if and only if
+      \code{psGetTraceLevel(name)} returns a value greater than
+      or equal to \code{level}.
+
+    \item
+      \code{psPrintTraceLevels} shall print a listing of all
+      declared levels, displayed as a hierarchy with sub-components
+      sorted within each component (see examples below).
+
+      Note in particular that the root of the tree, the name \code{""}
+      should print as \code{(root)}, and nodes which have not
+      been assigned a value should list their level as \code{.}.
+
+    \item
+      All of the tracing facilities shall be SWIGed, with the exception
+      of \code{p_psTrace}.
+
+    \item
+      There is no requirement that \code{psTrace} be usable from
+      within the functions that implement \file{psTrace.h}
+      or \file{psMemory.h} systems.
+
+    \item
+      \code{psTraceReset} shall reset all tracing to the state that it
+      had at program initiation, including freeing any memory that the
+      tracing subsystem may have allocated.
+\end{itemize}
+
+\paragraph{Examples of the use of Tracing Facilities}
+
+For example, after the commands:
+\begin{verbatim}
+    psSetTraceLevel("utils.dlist.add.head", 9);
+    psSetTraceLevel("utils.dlist.add", 3);
+    psSetTraceLevel("utils.dlist.remove", 4);
+    psSetTraceLevel("coadd", 2);
+    psSetTraceLevel("coadd.CR.remove.morphology", 5);
+    psSetTraceLevel("utils.hash", 2);
+    psSetTraceLevel("utils.dlist.add", 9);
+    psSetTraceLevel("utils", 1);
+\end{verbatim}
+the command \code{psPrintTraceLevels()} should print:
+\begin{verbatim}
+(root)               0
+ utils               1
+  hash               2
+  dlist              .
+   remove            4
+   add               9
+    head             9
+ coadd               2
+  CR                 .
+   remove            .
+    morphology       5
+\end{verbatim}
+where \code{.} means that the trace level should be inherited from its parent.
+
+After this set of \code{psSetTraceLevel} commands, and if
+\code{PS_NTRACE} is not defined, the following commands
+\begin{verbatim}
+    psTrace("utils.dlist.remove", 2, "Removing psDList key \"%s\"\n", "my_key");
+    psTrace("utils", 2, "Initialising utilities library\n");
+    psTrace("", 2, "This is turned on by trace component \"\"");
+    psTrace("utils.dlist", 2, "Initialising psDList\n");
+    psTrace("utils.dlist.remove", 4, "Removing psDList key \"%s\" (value: \"%d\")\n", "my_key", 12345);
+    psTrace("utils.hash.remove", 4, "Removing hash key \"%s\" (value: \"%d\")\n", "my_key", 12345);
+    psTrace("utils.dlist.add", 1, "Adding psDList key \"%s\"\n", "your_key");
+    psTrace("utils.dlist.find", 2, "Looking up psDList key \"%s\"\n", "some_key");
+    psTrace("coadd.CR.remove", 4, "Removing CRs\n");
+    psTrace("coadd.CR.remove.morphology", 4, "CRs are not fuzzy\n");
+\end{verbatim}
+should produce this output:
+\begin{verbatim}
+  Removing psDList key "my_key"
+    Removing psDList key "my_key" (value: "12345")
+ Adding psDList key "your_key"
+    CRs are not fuzzy
+\end{verbatim}
+
+Note that
+\begin{description}
+\item
+  \code{utils.dlist} messages are at level 1, inherited from \code{utils}, so the
+  \code{Initialising utilities library}, \code{Initialising psDList}, and
+  \code{Looking up psDList key} messages are \emph{not} printed (the traces are at level 2).
+
+\item
+  \code{utils.dlist.remove} messages are at level 4, and are printed.
+
+\item
+  \code{utils.hash} messages are at level 2, and are not printed (the traces are at level 4)
+
+\item
+  \code{coadd.CR.remove} is at level 2 (inherited from \code{coadd}) so \code{Removing CRs}
+  isn't printed.  \code{coadd.CR.remove.morphology} is at level 4, so \code{CRs are not fuzzy} is printed.
+\end{description}
+
+\subsubsection{Message Logging}
+\hlabel{psLogMsg}
+
+\begin{table}
+  \begin{verbatim}
+enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO };
+
+enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT };
+
+void psLogMsg(const char *name, int level, const char *fmt, ...);
+void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap);
+
+int psSetLogDestination(int dest);
+void psSetLogFormat(const char *fmt);
+
+int psSetLogLevel(int level);
+  \end{verbatim}
+  \begin{caption}{API for message logging}
+    \hlabel{tabLogMsgAPI}
+    The API for message logging.
+  \end{caption}
+\end{table}
+
+The public API for the logging facility (table \ref{tabLogMsgAPI})
+should be provided in a header file \file{psLogMsg.h} which
+is included by \file{psUtils.h}.
+
+The function \code{psSetLogLevel} may be used to set the current
+level of logging; the previous value is returned.
+The default value is \code{PS_LOG_INFO}. Valid values are 0---9
+inclusive (note that only the first four are required to have
+symbolic names).
+
+A call to \code{psLogMsg(name, level, msg, ...)} shall generate
+a log message if \code{level} is less than or equal to the
+value most recently set using \code{psSetLogLevel}. The function
+\code{p_psLogMsg} is identical, except that it expects a
+final \code{va_list} argument.
+
+The format of the log message shall be of the form:
+\begin{verbatim}
+YYYY:MM:DD hh:mm:ssZ|hostname|l|name            |msg
+\end{verbatim}
+\code{YYYY}, \code{MM}, \code{DD}, \code{hh}, \code{mm}, and \code{ss}
+are the year, month (Jan == 1), day of the month, hours (0--23),
+minutes, and seconds when the log message was received.  Note that the
+timestamp is in ISO order, and that the timezone is GMT (hence the
+\code{Z}).
+
+The \code{hostname} is returned by \code{gethostname}, \code{l} is a
+letter associated with the level (\code{A}, \code{E}, \code{W}, and
+\code{I} for \code{PS_LOG_ABORT}, \code{PS_LOG_ERROR}, \code{PS_LOG_WARN},
+and \code{PS_LOG_INFO} respectively. Other levels are represented
+numerically (\code{5} etc.). The other two field, \code{name} and
+\code{msg} are arguments to \code{psLogMsg}; note that \code{name} has
+a fixed width of 15 characters. If \code{msg} doesn't end in a newline,
+a single newline is emitted to terminate the message.
+
+An example message is:
+\begin{verbatim}
+2004:02:24 20:14:18Z|alibaba.IfA.Hawaii.Edu|I|utils          |Hello World
+\end{verbatim}
+
+Log messages are sent to the destination most recently set using
+\code{psSetLogDestination}.  The only two values that are initially
+defined are \code{PS_LOG_TO_STDERR} and \code{PS_LOG_TO_STDOUT} to
+write to \code{stderr} and \code{stdout} respectively.
+
+The fields included in the log message may be controlled using \code{psSetLogFormat} which
+expects a string consisting of the letters \code{H} (host), \code{L} (level), \code{M} (message),
+\code{N} (name), and \code{T} (time).  The default is \code{HLMNT}.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -84 +698 @@
 \end{itemize}
 
-\note{INSERT HERE STUFF FROM RHL'S \file{utils.pdf}}
+\subsection{The Pan-STARRS \texttt{psDlist} doubly-linked list type}
+\hlabel{psDlist}
+
+Pan-STARRS supports doubly linked lists through a type \code{psDlist}.
+The type is defined in the header file \file{psDlist.h}, and consists
+of the following definitions:
+
+\begin{verbatim}
+typedef struct psDlistElem {
+    struct psDlistElem *prev;           // previous link in list
+    struct psDlistElem *next;           // next link in list
+    void *data;                         // real data item
+} psDlistElem;
+
+typedef struct {
+    int n;                              // number of elements on list
+    psDlistElem *head;                  // first element on list (may be NULL)
+    psDlistElem *tail;                  // last element on list (may be NULL)
+    psDlistElem *iter;                  // iteration cursor; private
+} psDlist;
+
+enum {                                  // Special values of index into list
+    psDlistHead = 0,                    // at head
+    psDlistTail = -1,                   // at tail
+    psDlistUnknown = -2,                // unknown position
+    psDlistPrev = -3,                   // previous element
+    psDlistNext = -4                    // next element
+};
+\end{verbatim}
+
+The API is:
+
+\begin{verbatim}
+psDlist *psDlistAlloc(void *data);        // initial data item; may be NULL
+
+void psDlistFree(psDlist *list,          // list to destroy
+                void (*elemFree)(void *)); // destructor for list data, or NULL
+
+/*
+ * List maintainence functions
+ */
+psDlist *psDlistAdd(psDlist *list,      // list to add to (may be NULL)
+                    void *data,         // data item to add
+                    int where);         // index, psDlistHead, or psDlistTail
+psDlist *psDlistAppend(psDlist *list,   // list to append to (may be NULL)
+                       void *data);     // data item to add
+void *psDlistRemove(psDlist *list,      // list to remove element from
+                    void *data,         // data item to remove
+                    int which);         // index of item, or psDlistUnknown,
+                                        // or psDlistNext, or psDlistPrev
+void *psDlistGet(const psDlist *list,   // list to retrieve element from
+                 int which);            // index of item, or psDlistNext,
+                                        // or psDlistPrev
+/*
+ * Conversions to/from arrays
+ */
+psVoidPtrArray *psDlistToArray(psDlist *dlist);
+psDlist *psArrayToDlist(psVoidPtrArray *arr);
+\end{verbatim}
+
+All data items placed onto lists (e.g. with \code{psDlistAdd})
+shall have their reference counters (section \ref{secMemRefcounter}) incremented.
+When elements
+are removed from a list with \code{psDlistRemove}, they shall
+have their reference counters decremented. The action of retrieving
+data from a list (with \code{psDlistGet}) shall not affect
+their reference counter.
+
+If \code{psDlistFree}'s argument \code{elemFree} is NULL, the
+list should be deleted, but not the elements on it (although their
+\code{refcounter}'s should be decremented).
+
+Iteration over all elements of the list is provided by the functions:
+\begin{verbatim}
+void psDlistSetIterator(psDlist *list, int where, int which);
+void *psDlistGetNext(psDlist *list, int which);
+void *psDlistGetPrev(psDlist *list, int which);
+\end{verbatim}
+in which the \code{where} argument must be \code{PS_DLIST_HEAD} or \code{PS_DLIST_TAIL},
+to start at the head or tail of the list, and \code{psDlistGetNext} and \code{psDlistGetPrev}
+return the next/previous element. The argument \code{which} identifies which of potentially
+many iteration cursors should be used; it must currently always be \code{0}.
+
+Explicit traversal of the list using the \code{psDlistElem}'s
+\code{prev} and \code{next} pointers is also supported.
+
+The routines to convert to and from \code{psVoidPtrArray}s,
+\code{psDlistToArray} and \code{psArrayToDlist} shall ensure that the
+objects on the arrays and lists have had their reference pointers
+correctly incremented (see section \ref{secArrayVoidPtr}) (\eg{} that
+\code{psArrayToDlist(psDlistToArray(list))} returns a properly-formed
+\code{psDlist}).
+
+\subsection{The \PS{} Array types}
+
+\begin{table}
+  \begin{verbatim}
+  \end{verbatim}
+  \begin{caption}{The array creation macros defined in \file{psArray.h}}
+    \hlabel{tabPsArray}
+  \end{caption}
+\end{table}
+
+\subsubsection{Arrays of Simple Types}
+
+Any \PS/ datatype \code{psType} may be associated with an array type
+\code{psTypeArray}:
+\begin{verbatim}
+typedef struct {
+  int size;
+  int n;
+  psType *arr;
+} psTypeArray;
+\end{verbatim}
+with associated constructors and a destructor:
+\begin{verbatim}
+psTypeArray *psTypeAlloc(int n, int size);
+psTypeArray *psTypeRealloc(psTypeArray *arr, int n);
+void psTypeFree(psTypeArray *arr);  
+\end{verbatim}
+
+The argument \code{n} is the dimension of the array; \code{size}
+is the number of elements allocated ($s \ge n$).
+
+This type and functions may be declared and defined using two macros
+from \file{psArray.h} (table \ref{tabPsArray}),
+\code{PS_DECLARE_ARRAY_TYPE(psType)} and
+\code{PS_CREATE_ARRAY_TYPE(psType)}.  The former defines the typedef
+and declares the prototypes (and is thus suitable for use in a
+header file); the latter generates the code for the three functions
+\code{psType(Alloc|Realloc|Free} (and should thus appear in exactly one
+source file for a given type).
+
+The \code{psType} should be a single word (e.g. \code{psXY}); in particular,
+there is no requirement to support a pointer type (\eg{} \code{psXY *});
+see next section.
+
+\subsubsection{Arrays of Pointer Types}
+
+The data type created with \code{PS_CREATE_ARRAY_TYPE} (\code{psType})
+contains an array of \code{psType}s not
+pointers to \code{psType}s; this means that the individual elements are
+not allocated using \code{psTypeAlloc}, are not correctly initialized,
+and shouldn't be individually deleted with \code{psTypeFree};
+
+If you wish to use arrays of pointers, use the macros
+\code{PS_DECLARE_ARRAY_PTR_TYPE(psType)} and
+\code{PS_CREATE_ARRAY_PTR_TYPE(psType)} (table \ref{tabPsArray}). These
+create types \code{typedef psType *psTypePtr} and \code{psTypePtrArray}:
+\begin{verbatim}
+typedef struct {
+  int size;
+  int n;
+  psTypePtr *arr;
+} psTypePtrArray;
+\end{verbatim}
+with associated constructors and a destructor:
+\begin{verbatim}
+psTypePtrArray *psTypePtrAlloc(int n, int size);
+psTypePtrArray *psTypePtrRealloc(psTypePtrArray *arr, int n);
+void psTypePtrArrayFree(psTypePtrArray *arr);  
+\end{verbatim}
+
+These constructors create arrays of \code{psType *} and call
+\code{psTypeAlloc} and \code{psTypeFree} to allocate and free the
+elements. As for the simple arrays, The former defines the typedef and
+declares the prototypes (and is thus suitable for use in a header
+file) and the latter generates the code for the three functions
+\code{psType(Alloc|Realloc|Free} (and should thus appear in exactly one
+source file for a given type).
+
+The objects pointed to by these types have had their \code{refCounter}s
+incremented (see \ref{secMemRefcounter}); to remove an element from the array you
+need to say something like:
+\begin{verbatim}
+  psTypePtrArray *pt = psTypePtrArrayAlloc(10, 10);
+  psType *xy = psMemDecrRefCounter(pt->arr[0]);
+  pt->arr[0] = NULL;
+\end{verbatim}
+
+\subsubsection{Arrays of \texttt{void *}}
+\hlabel{secArrayVoidPtr}
+
+Arrays of \code{void *} are different, as the need an explicitly-specified
+destructor.
+
+\file{psArray.h} shall specify a type \code{psVoidPtrArray} that
+behaves in all respects as if it had been created with:
+\begin{verbatim}
+typedef void *psVoidPtr;
+PS_DECLARE_ARRAY_TYPE(psVoidPtr);
+PS_CREATE_ARRAY_TYPE(psVoidPtr);
+\end{verbatim}
+except that its destructor is specified as:
+\begin{verbatim}
+void psVoidPtrArrayFree(psVoidPtrArray *arr,      // array to destroy
+                       void (*elemFree)(void *)); // destructor for array data
+\end{verbatim}
+
+The routine \code{psVoidPtrArrayFree} assumes that all pointers
+had their reference counters incremented
+when they were inserted onto the array.\footnote{%
+  \eg{} \code{va->arr[i] = psMemIncrRefCounter(ptr);}}
+
+If \code{psVoidPtrArrayFree}'s argument \code{elemFree} is NULL, the
+list should be deleted, but not the elements on it (although their
+\code{refcounter}'s should be decremented).
+
+\subsubsection{Examples of Array Types}
+
+The following is a complete C program that illustrates the use of
+\code{array}s.
+\begin{verbatim}
+#include "psUtils.h"
+
+typedef struct {
+    int x, y;
+} psXY;
+
+psXY *psXYAlloc(void)
+{
+    return psAlloc(sizeof(psXY));
+}
+
+void psXYFree(psXY *xy)
+{
+    psFree(xy);
+}
+
+PS_DECLARE_ARRAY_TYPE(psXY);
+PS_CREATE_ARRAY_TYPE(psXY);
+
+PS_DECLARE_ARRAY_PTR_TYPE(psXY);
+PS_CREATE_ARRAY_PTR_TYPE(psXY);
+
+int main(void)
+{
+    psXYArray *t = psXYArrayAlloc(10, 15);
+    psXYPtrArray *pt = psXYPtrArrayAlloc(10, 10);
+
+    for (int i = 0; i < t->n; i++) {
+        t->arr[i].x = i;
+        pt->arr[i]->y = 10*i;
+    }
+
+    t = psXYArrayRealloc(t, 5);
+    t = psXYArrayRealloc(t, 8);
+
+    for (int i = 0; i < t->n; i++) {
+        printf("%d %d  ", t->arr[i].x, pt->arr[i]->y);
+    }
+    printf("\n");
+    
+    psXYArrayFree(t);
+
+    psXY *xy = psMemDecrRefCounter(pt->arr[0]);
+    pt->arr[0] = NULL;
+    psXYFree(xy);    
+    
+    psXYPtrArrayFree(pt);
+
+    psMemCheckLeaks(0, NULL, stderr);
+
+    return 0;
+}
+\end{verbatim}
+
+\subsection{Hash Tables}
+\hlabel{psHash}
+
+\begin{table}
+  \begin{verbatim}
+typedef struct HashTable psHash;
+
+psHash *psHashAlloc(int nbucket);       // initial number of buckets
+void psHashFree(psHash *table,          // hash table to be freed
+               void (*itemFree)(void *item)); // how to free hashed data;
+                                        // or NULL
+
+void *psHashInsert(psHash *table,       // table to insert in
+                   const char *key,     // key to use
+                   void *data,          // data to insert
+                   void (*itemFree)(void *item)); // how to free hashed data;
+                                        // or NULL
+void *psHashLookup(psHash *table,       // table to lookup key in
+                   const char *key);    // key to lookup
+
+void *psHashRemove(psHash *table,       // table to lookup key in
+                   const char *key);    // key to lookup
+  \end{verbatim}
+  \begin{caption}{The public API for hash tables from \file{psHash.h}}
+    \hlabel{tabPsHash}
+  \end{caption}
+\end{table}
+
+The public API for the hash table (table \ref{tabPsHash})
+should be provided in a header file \file{psHash.h} which
+is included by \file{psUtils.h}.
+\footnote{
+  We choose not to use the posix function \code{hcreate},
+  \code{hdestroy}, and \code{hsearch} as they only support
+  a single hash table at any one time.}
+
+A hash table is an abstract type \code{psHash}.  The argument
+\code{nbucket} to \code{psHashAlloc} is a non-binding suggestion
+from the user for the initial size of the hash table.
+
+If the \code{itemFree} argument to \code{psHashFree} is non-NULL,
+it will be used to delete the data items that have been stored
+in the hash table; if it is NULL this is the responsibility of
+the caller.
+
+The routine \code{psHashInsert} must provide a non-NULL \code{itemFree}
+argument if it wishes to change the value previously inserted keys;
+if \code{itemFree} is NULL attempting to insert a pre-existing key
+is an error, and the routine will return NULL.  If  \code{psHashInsert}
+succeeds it returns \code{data}.
+
+\code{psHashLookup} returns the \code{data} associated with the
+key, or NULL if the key's invalid.
+
+\code{psHashRemove} removes the entry associated with the
+key from the table, and returns the \code{data}; if the key's invalid it returns NULL.
+
+\subsection{Miscellaneous Utilities}
+
+The API for miscellaneous \PS{} utilities is provided by \file{psMisc.h}
+which shall be included by \file{psUtils.h}.
+
+\begin{table}
+  \begin{verbatim}
+#define PS_CONCAT(A, B) A ## B          // Expands to AB
+#define PS_CONCAT2(A, B) PS_CONCAT(A, B) // Also expands to AB
+#define PS_CONCAT3(A, B, C) A ## B ## C // Expands to ABC
+
+#define PS_STRING(S) #S                 // converts argument S to string
+    
+void psAbort(const char *name, const char *fmt, ...);
+void psError(const char *name, const char *fmt, ...);
+char *psStringCopy(const char *str);
+  \end{verbatim}
+  \begin{caption}{The utilities provided by \file{psMisc.h}}
+      \hlabel{psMisc}
+  \end{caption}
+\end{table}
+
+\code{psAbort} shall call \code{psMsgLog} with a level of \code{PS_LOG_ABORT},
+and then call \code{abort}.
+\code{psError} shall call \code{psMsgLog} with a level of \code{PS_LOG_ERROR},
+and then return.
+In cases of doubt, a good choice for
+\code{name} is \code{__func__}.
+
+\code{psStringCopy} shall allocate and return a copy of the input string.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -641 +1608 @@
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Image handling}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Basic Images}
+
+The most important data product produced by the telescope is an image.
+The simplest image is a 2-D collection of pixels, each with some
+value.  We require a basic image data type:
+
+\begin{verbatim}
+/// basic image data structure.
+typedef struct psImage {
+    psType type;                        ///< image data type and dimension
+    int nx, ny;                         ///< size of image 
+    int x0, y0;                         ///< data region relative to parent 
+    union {
+        psF32 **rows;                   ///< == rows_f32 
+        psS8  **rows_s8;                ///< pointers to psS8 data 
+        psS16 **rows_s16;               ///< pointers to psS16 data 
+        psS32 **rows_s32;               ///< pointers to psS32 data 
+        psU8  **rows_u8;                ///< pointers to psU8 data 
+        psU16 **rows_u16;               ///< pointers to psU16 data 
+        psU32 **rows_u32;               ///< pointers to psU32 data 
+        psF32 **rows_f32;               ///< pointers to psF32 data 
+        psF64 **rows_f64;               ///< pointers to psF64 data 
+    } rows;
+    struct psImage *parent;             ///< parent, if a subimage 
+    struct psImage *children;           ///< children of this region 
+    int Nchildren;                      ///< number of subimages 
+} psImage;
+\end{verbatim}
+
+This structure represents an image consisting of a 2-D array of
+pixels.  The size of this array is given by the elements \code{(nx,
+ny)}.  The data type of the pixel is defined by the \code{psType type}
+entry (see \ref{TBD}).  (n.b. that for FITS images, these values are
+restricted to the datatypes equivalent to the valid BITPIX values 8,
+16, 32, -32, -64).  The image represented in the data structure may
+represent a subset of the pixels in a complete array.  The offset of
+the \code{(0,0)} pixel in this array relative to the parent array is
+given by the elements \code{(x0,y0)}.  The structure may include
+references to subrasters (\code{children, Nchildren}) and/or to a
+containing array (\code{parent}).
+
+We require a variety of functions to manipulate these image
+structures, including creation, destruction, input, output, and
+various manipulations of the pixels.  The required functions are
+listed below.
+
+Create an image of a specified width, height, and data type.  This
+function must allow any of the valid image data types and not restrict
+to the valid FITS BITPIX types.
+\begin{verbatim}
+psImage *
+psImageAlloc (int nx,                   ///< image width 
+              int ny,                   ///< image height 
+              psType type)              ///< image data type 
+\end{verbatim}
+
+Define a subimage of the specified area of the given image.  This
+function must return an error if the requested subset area lies
+outside of the parent image.
+\begin{verbatim}
+psImage *
+psImageSubset (psImage *image,          ///< parent image 
+               int nx,                  ///< subimage width (<= image.nx - x0)  
+               int ny,                  ///< subimage width (<= image.ny - y0)  
+               int x0,                  ///< subimage x-offset (0 <= x0 < nx)   
+               int y0)                  ///< subimage y-offset (0 <= y0 < ny)   
+\end{verbatim}
+
+Free the memory associated with a specific image.  \note{does this
+  free the input structure or just the allocated elements?}  Free the
+  children of the image if they exist.
+\begin{verbatim}
+void 
+psImageFree (psImage *image)            ///< free this image
+\end{verbatim}
+
+Free the memory associated with the children of a specific image.  
+\begin{verbatim}
+int 
+psImageFreeChildren (psImage *image)    ///< free children of this image
+\end{verbatim}
+
+Create a copy of the specified image.  If the output target pointer is
+not NULL, place the result in the specified structure.
+\begin{verbatim}
+psImage *
+psImageCopy (psImage *output,           ///< target structure for output image data
+             psImage *input)            ///< copy this image 
+\end{verbatim}
+
+Extract pixels from rectlinear region to a vector (array of floats).
+The output vector contains either \code{nx} or \code{ny} elements,
+based on the value of the direction: e.g., if \code{direction} is
+\tbd{+x}, there are \code{nx} elements.  The input region is collapsed
+in the perpendicular direction, and each element of the output vectors
+is derived from the statistics of the pixels at that direction
+coordinate.  The statistic used to derive the output vector value is
+specified by \code{psStats stats}.
+\begin{verbatim}
+psFloatArray *
+psImageSlice (psImage *input,           ///< extract slice from this image
+              int x,                    ///< starting x coord of region to slice
+              int y,                    ///< starting y coord of region to slice
+              int nx,                   ///< width of region in x
+              int ny,                   ///< width of region in y
+              int direction,            ///< direction of vector along slice
+              psStats *stats)           ///< defines statistics used to find output values
+\end{verbatim}
+
+Extract pixels from an image along a line to a vector (array of
+floats).  The vector \code{xs,ys} - \code{xe,ye} forms the basis of
+the output vector.  Pixels are considered in a rectangular region of
+width \code{dw} about this vector.  The input region is collapsed in
+the perpendicular direction, and each element of the output vector
+represents a pixel-sized boxes, where the value is derived from the
+statistics of the pixels interpolated along the perpendicular
+direction.  The statistic used to derive the output vector value is
+specified by \code{psStats stats}.
+\begin{verbatim}
+psFloatArray *
+psImageCut (psImage *input,             ///< extract cut from this image
+            float xs,                   ///< starting x coord of cut
+            float ys,                   ///< starting y coord of cut
+            float xe,                   ///< ending x coord of cut
+            float ye,                   ///< ending y coord of cut
+            float dw,                   ///< width of cut
+            psStats *stats)             ///< defines statistics used to find output values
+ \end{verbatim}
+
+
+Extract radial annulii data to a vector.  A vector is constructed
+where each vector elements is derived from the statistics of the
+pixels which land in one of a sequence of annulii.  The annulii are
+centered on the image pixel coordinate \code{x,y}, and have width
+\code{dr}.  The number of annulii is $radius / dr$.  The statistic
+used to derive the output vector value is specified by \code{psStats
+stats}
+\begin{verbatim}
+psFloatArray *
+psImageRadialCut (psImage *input,       ///< extract profile from this image
+                  float x,              ///< center x coord of annulii
+                  float y,              ///< center y coord of annulii
+                  float radius,         ///< outer radius of annulii
+                  float dr,             ///< radial step size of annulii
+                  psStats *stats)       ///< defines statistics used to find output values 
+\end{verbatim}
+
+%/// Extract a 2-d contour from an image at the given threshold.
+%\begin{verbatim}
+%psFloatArray *
+%psImageContour (psImage *input,        ///< create contour for this image
+%               float threshold,        ///< contour image at this threshold
+%               int binning)            ///< bin image by this value for contour calculation
+%\end{verbatim}
+
+Rebin image to new scale.  A new image is constructed in which the
+dimensions are reduced by a factor of \code{scale}.  The output image
+represents a one-to-one mapping of the pixels in the input image,
+except for edge effects.  Each pixel in the output image is derived
+from the statistics of the corresponding input image pixels based on
+the statistics specified by \code{psStats stats}.
+\tbd{interpolation?}
+\begin{verbatim}
+psImage *
+psImageRebin (psImage *input,           ///< rebin this image
+              float scale,              ///< rebinning scale: doutput = scale*dinput
+              psStats *stats)           ///< defines statistics used to find output values
+\end{verbatim}
+
+Rotate the input image by given angle, specified in degrees.  The
+output image must contain all of the pixels from the input image in
+their new frame.  Pixels in the output image which do not map to input
+pixels should be set of \tbd{value}.  The center of rotation is always
+the center pixel of the image.  The rotation is specified in the sense
+that a positive value is a clock-wise rotation.  
+\begin{verbatim}
+psImage *
+psImageRotate (psImage *input,          ///< rotate this image
+               float angle)             ///< rotate by this amount (degrees)
+\end{verbatim}
+
+Shift image by an arbitrary number of pixels (\code{dx,dy}) in either
+direction.  If the shift values are fractional, the output pixel
+values shoul interpolate between the input pixel values.  The output
+image has the same dimensions as the input image.  Pixels which fall
+off the edge of the output image are loast.  Newly exposed pixels are
+set to the value given by \code{exposed}.  
+\begin{verbatim}
+psImage *
+psImageShift (psImage *input,           ///< shift this image
+              float dx,                 ///< shift by this amount in x
+              float dy,                 ///< shift by this amount in y
+              float exposed)            ///< set exposed pixels to this value
+\end{verbatim}
+
+Roll image by an integer number of pixels in either direction.  The
+output image is the same dimensions as the input image.  Edge pixels
+wrap to the other side (no values are lost).
+\begin{verbatim}
+psImage *
+psImageRoll (psImage *input,            ///< roll this image
+             int dx,                    ///< roll this amount in x
+             int dy)                    ///< roll this amount in y
+\end{verbatim}
+
+Determine statistics for image (or subimage).  The statistics to be
+determined are specified by \code{psStats stats}.
+\begin{verbatim}
+psStats *
+psImageGetStats (psImage *input,        ///< image (or subimage) to calculate stats
+                 psStats *stats)        ///< defines statistics to be calculated
+\end{verbatim}
+
+Construct a histogram from an image (or subimage).  The histogram to
+generate is specified by \code{psHistogram hist}.
+\begin{verbatim}
+psHistogram *
+psImageHistogram (psHistogram *hist,    ///< input histogram description & target
+                  psImage *input)       ///< determine histogram of this image
+\end{verbatim}
+
+Fit a 2-D polynomial surface to an image.  The input structure
+\code{coeffs} contains the desired order and terms of interest.
+\tbd{how do we specify the renomalization?}
+\begin{verbatim}
+psPolynomial2D *
+psImageFitPolynomial (psImage *input,   ///< image to fit
+                      psPolynomial2D *coeffs) ///< coefficient structure carries in desired terms
+\end{verbatim}
+
+Evaluate a 2-D polynomial surface to image pixels.  Given the input
+polynomial coefficients, return an image generated on the basis of the
+input image pixels which evaluates the polynomial for all pixels in
+the image.a
+\begin{verbatim}
+int
+psImageEvalPolynomial (psImage *input,  ///< image to fit
+                       psPolynomial2D *coeffs) ///< coefficient structure carries in desired terms
+\end{verbatim}
+
+Read an image or subimage from a named file.  This function is a
+wrapper to the FITS library function.  The input parameters allow or a
+subimage to be read.  The starting pixel of the region is specified by
+\code{x,y}, while the dimensions of the requested region are specified
+by \code{nx,ny}.  A value of -1 for these two parameters specifies the
+full array of the requested image.  If the native image is a cube, the
+value of z specifies the requested slice of the image.  The data is
+read from the extension specified by extname (matching the EXTNAME
+keyword) or by the extnum value (with -1 representing the PHU, 0 the
+first extension, etc).  This function must return an error if any of
+the specified parameters are out of range for the data in the image
+file, if the specified image file does not exist.  \tbd{what do we do
+with a 0D or 1D image?}
+\begin{verbatim}
+psImage *
+psImageReadSection (psImage *output,    ///< place data in this structure for output 
+                    int x,              ///< starting x coord of region
+                    int y,              ///< starting y coord of region
+                    int nx,             ///< x size of region (-1 for full range)
+                    int ny,             ///< y size of region (-1 for full range)
+                    int z,              ///< plane of interest
+                    char *extname,      ///< MEF extension name ("PHU" for primary header)
+                    int extnum,         ///< MEF extension sequence number (-1 for PHU)
+                    char *filename)     ///< file to read data from
+\end{verbatim}
+ 
+Read an image or subimage from file descriptor.  The input parameters
+and their behavior for this function are identical with those in
+\code{psImageReadSection}.
+\begin{verbatim}
+psImage *
+psImageFReadSection (psImage *output,   ///< place data in this structure for output 
+                     int x,             ///< starting x coord of region            
+                     int y,             ///< starting y coord of region            
+                     int dx,            ///< x size of region (-1 for full range)          
+                     int dy,            ///< y size of region (-1 for full range)          
+                     int z,             ///< plane of interest                     
+                     char *extname,     ///< MEF extension name ("PHU" for primary header)                         
+                     FILE *f)           ///< file descriptor to read data from             
+\end{verbatim}
+
+Write an image section to named file, which may exist.  This
+operatation may write a portion of an image over the existing bytes of
+an existing image.  If the file does not exist, it should be created.
+If the specified extention does not exist, it should be created.  If
+an extension is specified and no PHU exists, a basic PHU should be
+created.  
+\begin{verbatim}
+psImage *
+psImageWriteSection (psImage *input,    ///< image to write out
+                     int x,             ///< starting x coord of region            
+                     int y,             ///< starting y coord of region            
+                     int z,             ///< plane of interest                     
+                     char *extname,     ///< MEF extension name ("PHU" for primary header)                         
+                     char *filename)    ///< file to write data to                 
+\end{verbatim}
+
+Write an image section to file descriptor.
+\begin{verbatim}
+psImage *
+psImageFWriteSection(psImage *input,    ///< image to write out
+                     int x,             ///< starting x coord of region            
+                     int y,             ///< starting y coord of region            
+                     int z,             ///< plane of interest                     
+                     char *extname,     ///< MEF extension name                    
+                     FILE *f)           ///< file descriptor to write data to              
+\end{verbatim}
+
+Read header data from a FITS image file into a \code{psMetaData}
+structure.  If the named extension does not exist, the function should
+return an error.  
+\begin{verbatim}
+struct psMetadata *
+psImageReadHeader(struct psMetadata *output,    ///< read data to this structure
+                  char *extname,        ///< MEF extension name ("PHU" for primary header)
+                  int extnum,           ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+                  char *filename)       ///< file to read from
+\end{verbatim}
+
+Read header data from a FITS image file descriptor into a \code{psMetaData}
+structure.  
+\begin{verbatim}
+struct psMetadata *
+psImageFReadHeader (struct psMetadata *output, ///< read data to this structure
+                   char *extname,       ///< MEF extension name ("PHU" for primary header)
+                   int extnum,          ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+                   FILE *f)             ///< file descriptor to read from
+\end{verbatim}
+
+Perform a 2-D FFT on the specified image. 
+\begin{verbatim}
+psImage *
+psImageFFT (psImage *input,             ///< image to FFT
+            int direction)              ///< FFT direction 
+\end{verbatim}
+
+Clip image values outside of range to given values.  All pixels with
+values $<$ min are set to the value vmin. All pixels with values $>$
+max are set to the value vmax.
+\begin{verbatim}
+int
+psImageClip (psImage *input,            ///< clip this image
+             float min,                 ///< clip pixels with values < min
+             float vmin,                ///< set min-clipped pixels to vmin
+             float max,                 ///< clip pixels with values > max
+             float vmax)                ///< set max-clipped pixels to vmax
+\end{verbatim}
+
+Clip NaN image pixels to given value.  Pixels with NaN or Inf values
+are set to the specified value.
+\begin{verbatim}
+int
+psImageClipNaN (psImage *input,         ///< clip this image
+                float value)            ///< set nan pixels to this value
+\end{verbatim}
+
+Overlay subregion of image with another image.  Replace the pixels in
+the \code{image} which correspond to the pixels in \code{overlay} with
+values derived from the values in \code{image} and \code{overlay}
+based on the given operator.  Valid operators are ``='' (set image
+value to overlay value), ``+'' (add overlay value to image value),
+``-'' (subtract overlay from image), ``*'' (multiply overlay times
+image), ``/'' (divide image by overlay).  
+\begin{verbatim}
+int 
+psImageOverlaySection (psImage *image,          ///< input image 
+                psImage *overlay,       ///< image to overlay 
+                int x0,                 ///< x offset of overlay subimage 
+                int y0,                 ///< y offset of overlay subimage 
+                char *operator)         ///< overlay operation 
+\end{verbatim}
 
 \subsection{Astrometry}
@@ -1181 +2523 @@
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \subsection{Dates and times}
 
@@ -1186 +2529 @@
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Image handling}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Gene --- done.
 
 \subsection{Metadata}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Gene --- done.
+
+This section addresses the question of how \PS{} metadata should be
+represented in memory. We do not (yet) address how it should be
+represented on disk.
+
+\subsubsection{Metadata Representation}
+
+We propose that an item of metadata be represented as a C structure with at least the following
+fields:
+\begin{verbatim}
+/*
+ * A struct to define a single item of metadata
+ */
+typedef struct {
+    const int id;                       // unique ID for this item
+    
+    char *name;                         // Name of item
+    psMetaDataType type;                // type of this item
+    const union {
+        float f;                        // floating value
+        int i;                          // integer value
+        void *v;                        // other type
+    } val;                              // value of metadata
+    char *comment;                      // optional comment ("", not NULL)
+} psMetaDataItem;
+\end{verbatim}
+
+The \code{id} is a unique identifier for this item of metadata; experience
+shows that such tags are useful.
+
+The \code{psMetaDataType type} entry specifies the type of the data
+being represented; the possibilities are listed in section \ref{metadataTypes}.
+
+\paragraph{Possible Types of Metadata}
+\label{metadataTypes}
+
+The possible types of metadata are identified by the enumerated type
+\code{psMetaDataType} (see also table \ref{tabMetaDataTypes}); the initial defined values are:
+\begin{verbatim}
+/*
+ * Possible types of metadata.  
+ */
+typedef enum {                          // type of val is:
+    psMetaFloat,                        // float (.f)
+    psMetaInt,                          // int (.i)
+    psMetaStr,                          // string (.v)
+    psMetaImg,                          // image (.v)
+    psMetaJPEG,                         // JPEG (.v)
+    psMetaPNG,                          // PNG (.v)
+    psMetaAstrom,                       // astrometric coefficients (.v)
+    psMetaUnknown,                      // other (.v)
+    psMetaNType                         // Number of types; must be last
+} psMetaDataType;
+\end{verbatim}
+
+\begin{table}
+\begin{tabular}{llll}
+\textbf{Value} & \textbf{Type} & \textbf{member of union} & \textbf{Comments}\\
+\hline
+psMetaFloat & float & f & value, not pointer, is stored \\
+psMetaInt & int & i &  value, not pointer, is stored \\
+psMetaStr & string & v &  value, not pointer to original, is stored \\
+psMetaImg & psImage & v &  \\
+psMetaJPEG & JPEG & v &  \\
+psMetaPNG & PNG & v &  \\
+psMetaAstrom & psAstrom & v &  \\
+psMetaUnknown & other & v &  \\
+psMetaNType & (none) & & The number of types defined
+\end{tabular}
+\begin{caption}{Supported Metadata Types}
+\label{tabMetaDataTypes}
+  Possible types of metadata
+\end{caption}
+\end{table}
+
+\subsubsection{Collections of Metadata}
+
+\begin{verbatim}
+typedef struct {
+    psDlist *list;                      // list of psMetaDataItem
+    psHash *table;                      // hash table of the same metadata
+} psMetaDataSet;
+\end{verbatim}
+
+The type \code{psMetaDataSet} is a container class for metadata. Note that there are
+in fact \emph{two} representations of the metadata (each \code{psMetaDataItem} appears
+on both).
+
+We are using the standard \PS{} doubly-linked list types \code{psDlist} and  \code{psHash}
+(see \href{file:utils#psDlist}{utils.pdf:psDlist} and \href{file:utils#psHash}{utils.pdf:psHash} for details).
+For example:
+\begin{verbatim}
+    for (int i = 0; i < 10; i += 5) {
+        float sqrti = sqrt(i);
+        psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_INT, &i, NULL, "const.%d", i));
+        psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_FLOAT, &sqrti, "square root", "const.sqrt%d", i));
+    }
+    psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR, "Bonjour", "French", "lang.hello"));
+    /*
+     * Remove a key
+     */
+    psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello"));
+    /*
+     * Print all metadata
+     */
+    fprintf(stdout, "------\n");
+    psMetaDataSetIterator(ms);
+    while ((meta = psMetaDataGetNext(ms, NULL)) != NULL) {
+        psMetaDataItemPrint(stdout, meta, "");
+    }
+    /*
+     * Look up a key by name
+     */
+    fprintf(stdout, "------\n");
+    fprintf(stdout, "Looking up by name:\n");
+    meta = psMetaDataLookup(ms, "const.5");
+    if (meta != NULL) {
+        psMetaDataItemPrint(stdout, meta, "");
+    }
+\end{verbatim}
+
+\subsubsection{Naming convention for MetaData}
+
+The \code{psMetaDataItem} struct includes a name.  This name should be of
+the form \code{name1.name2.name3$\cdots$}, e.g.\hfil\break
+\null\qquad\qquad\code{IPP.phase1.ota12.biassec}.
+
+We shall set in place a system for assigning the top-level `domains'
+to responsible individuals, and for gathering a complete list of
+all metadata names in use throughout the project.
+
+\paragraph{Support for Multiple Values for a Given Name}
+
+\begin{verbatim}
+    psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
+                                           "Bonjour", "French", "lang.hello"));
+    psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
+                                           "Aloha", "Hawaiian", "lang.hello"));
+    psMetaDataAppend(ms, psMetaDataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
+                                           "Good Morning", "English", "lang.hello"));
+    /*
+     * Print all metadata starting "lang"
+     */
+    psMetaDataSetIterator(ms);
+    while ((meta = psMetaDataGetNext(ms, "lang")) != NULL) {
+        psMetaDataItemPrint(stdout, meta, "");
+    }
+\end{verbatim}
+
+It is an unfortunate fact that certain metadata keywords (such as \code{COMMENT} in a FITS header)
+may be repeated with different values.  The \code{psMetaDataAppend} routine is required
+to check that all metadata names are unique unless the type is qualified as \code{PS_META_NON_UNIQUE};
+in this case a unique integer will be added to each name that you specify. In this case,
+you may either delete individual element separately or as a complete set:
+\begin{verbatim}
+psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello.0"));
+psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello"));
+\end{verbatim}
+
+\subsubsection{MetaData APIs}
+
+\begin{verbatim}
+psMetaDataItem *psMetaDataItemAlloc(
+    psMetaDataType type,                // type of this piece of metadata
+    const void *val,                    // value of new item
+                                        // N.b. a pointer even if the item
+                                        // is of type e.g. int
+    const char *comment,                // comment associated with item
+    const char *name,                   // name of new item of metadata (may be an sprintf format)
+    ...);                               // possible arguments for name format
+
+void psMetaDataItemFree(psMetaDataItem *ms); // piece of metadata to destroy
+
+psMetaDataSet *psMetaDataSetAlloc(void);          // make a new set of metadata
+void psMetaDataSetDel(psMetaDataSet *ms); // destroy a set of metadata
+
+/*****************************************************************************/
+/*
+ * Utilities
+ */
+psMetaDataItem *psMetaDataAppend(psMetaDataSet *restrict ms, psMetaDataItem *restrict item);
+psMetaDataItem *psMetaDataRemove(psMetaDataSet *restrict ms, const char *restrict key);
+
+void psMetaDataSetIterator(psMetaDataSet *ms);
+psMetaDataItem *psMetaDataGetNext(psMetaDataSet *ms);
+psMetaDataItem *psMetaDataLookup(const psMetaDataSet *ms, const char *key);
+
+void psMetaDataItemPrint(FILE *fd,              // file descriptor to write to
+                         const psMetaDataItem *ms); // item of metadata to print
+\end{verbatim}
 
 \subsection{Detector and sky positions}
@@ -1375 +2903 @@
 \subsection{Photometry}
 
-Gene --- done.
+
+Photometric observations are performed in a photometric system, and
+are must be related to other photometric systems.  We require a data
+structure which defines a photometric system, as well as a structure
+to define the transformation between photometric systems.  
+
+The photometric system is defined by the psPhotSystem structure.  
+A photometric system is identified by a human-readable \code{name}
+(ie, SDSS.g, Landolt92.B, GPC1.OTA32.r).  Each photometric system is
+given a unique identifier \code{ID}.  Observations taken with a
+specific camera, detector, and filter represent their own photometric
+system, and it may be necessary to perform transformations between
+these systems.  Photometric systems associated with observations from
+a specific camera/detector/filter combination can be associated with
+those components.
+\begin{verbatim}
+typedef struct {
+    int ID;
+    char *name;
+    char *camera;
+    char *filter;
+    char *detector;
+} psPhotSystem;
+\end{verbatim}
+
+The following structure defines the transformation between two
+photometric systems.
+\begin{verbatim}
+typedef struct {
+    psPhotSystem src;
+    psPhotSystem dst;
+    psPhotSystem pP, pM;        ///< Colour reference
+    psPhotSystem sP, sM;        ///< Colour reference
+    float pA, sA;               ///< 
+    psPolynomial3D transform;   
+} psPhotTransform;
+\end{verbatim}
+
+The transformation between two photometric systems may depend on the
+airmass of the observation and on the colors of the object of
+interest.  For a specific observation, such a transformations can be
+defined as a polynomial function of the color the star and the airmass
+of the observations.  If sufficient data exists, the transformation
+between the photometric systems may include more than one color,
+constraining the curvature of the stellar spectral energy
+distributions.  This latter term may be significant for stars which
+are highly reddened, for example.  Derived photometric quantities may
+have been corrected for airmass variations, in which case only color
+terms may be measureable.  The structure defines the transformation
+between a source photometric system (\code{src}) and a target
+photometric system (\code{dst}).  The photometric system of a primary
+color is defined by \code{pP, pM} such that the color is constructed
+as $pP - pM$.  A secondary color is defined by \code{sP, sM}.  For
+both, a reference color is specified (\code{pA, sA}): the polynomial
+transformation terms refer to colors in the form $pP - pM - pA$.  The
+transformation is specified as a 3D polynomial.  For a star of
+magnitude $M_{\rm src}$ in the source photometric system, with
+additional magnitude information in the other systems $M_{\rm pP}$,
+$M_{\rm pM}$, $M_{\rm sP}$, $M_{\rm sM}$, observed at an airmass of
+$z$, the magnitude of the star in the target system $M_{\rm dst}$ is
+given by: 
+$M_{\rm dst} = M_{\rm src} + transform(z, M_{\rm pP} - M_{\rm pM} - pA, M_{\rm sP} - M_{\rm sM} - sA)$
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1381 +2970 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\appendix
+
+\section{API Summary: all functions}
+
+\subsection{System Utilities}
+\begin{CompactItemize}
+\item 
+int {\bf ps\-Set\-Log\-Destination} (int dest)
+\begin{CompactList}\small\item\em Sets the log destination.\item\end{CompactList}\item 
+int {\bf ps\-Set\-Log\-Level} (int level)
+\begin{CompactList}\small\item\em Sets the log level.\item\end{CompactList}\item 
+void {\bf ps\-Set\-Log\-Format} (const char $\ast$fmt)
+\begin{CompactList}\small\item\em sets the log format\item\end{CompactList}\item 
+void {\bf ps\-Log\-Msg} (const char $\ast$name, int level, const char $\ast$fmt,...)
+\begin{CompactList}\small\item\em Logs a message.\item\end{CompactList}\item 
+void {\bf p\_\-ps\-VLog\-Msg} (const char $\ast$name, int level, const char $\ast$fmt, va\_\-list ap)
+\begin{CompactList}\small\item\em Logs a message from varargs.\item\end{CompactList}\item 
+void $\ast$ {\bf p\_\-ps\-Alloc} (size\_\-t size, const char $\ast$file, int lineno)
+\begin{CompactList}\small\item\em Memory allocation. Underlying private function called by macro ps\-Alloc.\item\end{CompactList}\item 
+void $\ast$ {\bf p\_\-ps\-Realloc} (void $\ast$ptr, size\_\-t size, const char $\ast$file, int lineno)
+\begin{CompactList}\small\item\em Memory re-allocation. Underlying private function called by macro ps\-Realloc.\item\end{CompactList}\item 
+void {\bf p\_\-ps\-Free} (void $\ast$ptr, const char $\ast$file, int lineno)
+\begin{CompactList}\small\item\em Free memory. Underlying private function called by macro ps\-Free.\item\end{CompactList}\item 
+int {\bf ps\-Mem\-Check\-Leaks} (int id0, {\bf ps\-Mem\-Block} $\ast$$\ast$$\ast$arr, FILE $\ast$fd)
+\begin{CompactList}\small\item\em Check for memory leaks.\item\end{CompactList}\item 
+int {\bf ps\-Mem\-Check\-Corruption} (int abort\_\-on\_\-error)
+\begin{CompactList}\small\item\em Check for memory corruption.\item\end{CompactList}\item 
+int {\bf ps\-Mem\-Get\-Ref\-Counter} (void $\ast$vptr)
+\begin{CompactList}\small\item\em Return reference counter.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Mem\-Incr\-Ref\-Counter} (void $\ast$vptr)
+\begin{CompactList}\small\item\em Increment reference counter and return the pointer.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Mem\-Decr\-Ref\-Counter} (void $\ast$vptr)
+\begin{CompactList}\small\item\em Decrement reference counter and return the pointer.\item\end{CompactList}\item 
+{\bf ps\-Mem\-Problem\-Callback} {\bf ps\-Mem\-Problem\-Set\-CB} ({\bf ps\-Mem\-Problem\-Callback} func)
+\begin{CompactList}\small\item\em Set callback for problems.\item\end{CompactList}\item 
+{\bf ps\-Mem\-Exhausted\-Callback} {\bf ps\-Mem\-Exhausted\-Set\-CB} ({\bf ps\-Mem\-Exhausted\-Callback} func)
+\begin{CompactList}\small\item\em Set callback for out-of-memory.\item\end{CompactList}\item 
+{\bf ps\-Mem\-Callback} {\bf ps\-Mem\-Allocate\-Set\-CB} ({\bf ps\-Mem\-Callback} func)
+\begin{CompactList}\small\item\em Set call back for when a particular memory block is allocated.\item\end{CompactList}\item 
+{\bf ps\-Mem\-Callback} {\bf ps\-Mem\-Free\-Set\-CB} ({\bf ps\-Mem\-Callback} func)
+\begin{CompactList}\small\item\em Set call back for when a particular memory block is freed.\item\end{CompactList}\item 
+int {\bf ps\-Mem\-Get\-Id} (void)
+\begin{CompactList}\small\item\em get next memory ID\item\end{CompactList}\item 
+long {\bf ps\-Mem\-Set\-Allocate\-ID} (long id)
+\begin{CompactList}\small\item\em set p\_\-ps\-Mem\-Allocate\-ID to id\item\end{CompactList}\item 
+long {\bf ps\-Mem\-Set\-Free\-ID} (long id)
+\begin{CompactList}\small\item\em set p\_\-ps\-Mem\-Free\-ID to id\item\end{CompactList}\item 
+void {\bf ps\-Abort} (const char $\ast$name, const char $\ast$fmt,...)
+\begin{CompactList}\small\item\em Prints an error message and aborts.\item\end{CompactList}\item 
+void {\bf ps\-Error} (const char $\ast$name, const char $\ast$fmt,...)
+\begin{CompactList}\small\item\em Prints an error message and doesn't abort.\item\end{CompactList}\item 
+char $\ast$ {\bf ps\-String\-Copy} (const char $\ast$str)
+\begin{CompactList}\small\item\em Allocates and returns a copy of a string.\item\end{CompactList}\item 
+void {\bf p\_\-ps\-Trace} (const char $\ast$facil, int level,...)
+\begin{CompactList}\small\item\em Send a trace message.\item\end{CompactList}\item 
+int {\bf ps\-Set\-Trace\-Level} (const char $\ast$facil, int level)
+\begin{CompactList}\small\item\em Set trace level.\item\end{CompactList}\item 
+int {\bf ps\-Get\-Trace\-Level} (const char $\ast$name)
+\begin{CompactList}\small\item\em Get the trace level.\item\end{CompactList}\item 
+void {\bf ps\-Trace\-Reset} (void)
+\begin{CompactList}\small\item\em turn off all tracing, and free trace's allocated memory\item\end{CompactList}\item 
+void {\bf ps\-Print\-Trace\-Levels} (void)
+\begin{CompactList}\small\item\em print trace levels\item\end{CompactList}\end{CompactItemize}
+
+\subsection{Data Containers}
+\begin{CompactItemize}
+\item 
+{\bf ps\-Dlist} $\ast$ {\bf ps\-Dlist\-Alloc} (void $\ast$data)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+void {\bf ps\-Dlist\-Free} ({\bf ps\-Dlist} $\ast$list, void($\ast$elem\-Free)(void $\ast$))
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Dlist} $\ast$ {\bf ps\-Dlist\-Add} ({\bf ps\-Dlist} $\ast$list, void $\ast$data, int where)
+\begin{CompactList}\small\item\em Add to list.\item\end{CompactList}\item 
+{\bf ps\-Dlist} $\ast$ {\bf ps\-Dlist\-Append} ({\bf ps\-Dlist} $\ast$list, void $\ast$data)
+\begin{CompactList}\small\item\em Append to a list.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Dlist\-Remove} ({\bf ps\-Dlist} $\ast$list, void $\ast$data, int which)
+\begin{CompactList}\small\item\em PS\_\-DLIST\_\-PREV.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Dlist\-Get} (const {\bf ps\-Dlist} $\ast$list, int which)
+\begin{CompactList}\small\item\em Retrieve from a list.\item\end{CompactList}\item 
+void {\bf ps\-Dlist\-Set\-Iterator} ({\bf ps\-Dlist} $\ast$list, int where, int which)
+\begin{CompactList}\small\item\em PS\_\-DLIST\_\-PREV.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Dlist\-Get\-Next} ({\bf ps\-Dlist} $\ast$list, int which)
+\begin{CompactList}\small\item\em PS\_\-DLIST\_\-PREV.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Dlist\-Get\-Prev} ({\bf ps\-Dlist} $\ast$list, int which)
+\begin{CompactList}\small\item\em PS\_\-DLIST\_\-PREV.\item\end{CompactList}\item 
+{\bf ps\-Void\-Ptr\-Array} $\ast$ {\bf ps\-Dlist\-To\-Array} ({\bf ps\-Dlist} $\ast$dlist)
+\begin{CompactList}\small\item\em Convert doubly-linked list to an array.\item\end{CompactList}\item 
+{\bf ps\-Dlist} $\ast$ {\bf ps\-Array\-To\-Dlist} ({\bf ps\-Void\-Ptr\-Array} $\ast$arr)
+\begin{CompactList}\small\item\em Convert array to a doubly-linked list.\item\end{CompactList}\item 
+{\bf ps\-Hash} $\ast$ {\bf ps\-Hash\-Alloc} (int nbucket)
+\begin{CompactList}\small\item\em Allocate hash buckets in table.\item\end{CompactList}\item 
+void {\bf ps\-Hash\-Free} ({\bf ps\-Hash} $\ast$table, void($\ast$item\-Free)(void $\ast$item))
+\begin{CompactList}\small\item\em Free hash buckets from table.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Hash\-Insert} ({\bf ps\-Hash} $\ast$table, const char $\ast$key, void $\ast$data, void($\ast$item\-Free)(void $\ast$item))
+\begin{CompactList}\small\item\em Insert entry into table.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Hash\-Lookup} ({\bf ps\-Hash} $\ast$table, const char $\ast$key)
+\begin{CompactList}\small\item\em Lookup key in table.\item\end{CompactList}\item 
+void $\ast$ {\bf ps\-Hash\-Remove} ({\bf ps\-Hash} $\ast$table, const char $\ast$key)
+\begin{CompactList}\small\item\em Remove key from table.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Float\-Array\-Alloc} (int s, int n)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Float\-Array\-Realloc} ({\bf ps\-Float\-Array} $\ast$my\-Array, int s)
+\begin{CompactList}\small\item\em Reallocator.\item\end{CompactList}\item 
+void {\bf ps\-Float\-Array\-Free} ({\bf ps\-Float\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Complex\-Array} $\ast$ {\bf ps\-Complex\-Array\-Alloc} (int s, int n)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+{\bf ps\-Complex\-Array} $\ast$ {\bf ps\-Complex\-Array\-Realloc} ({\bf ps\-Complex\-Array} $\ast$my\-Array, int s)
+\begin{CompactList}\small\item\em Reallocator.\item\end{CompactList}\item 
+void {\bf ps\-Complex\-Array\-Free} ({\bf ps\-Complex\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Int\-Array} $\ast$ {\bf ps\-Int\-Array\-Alloc} (int s, int n)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+{\bf ps\-Int\-Array} $\ast$ {\bf ps\-Int\-Array\-Realloc} ({\bf ps\-Int\-Array} $\ast$my\-Array, int s)
+\begin{CompactList}\small\item\em Reallocator.\item\end{CompactList}\item 
+void {\bf ps\-Int\-Array\-Free} ({\bf ps\-Int\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Double\-Array} $\ast$ {\bf ps\-Double\-Array\-Alloc} (int s, int n)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+{\bf ps\-Double\-Array} $\ast$ {\bf ps\-Double\-Array\-Realloc} ({\bf ps\-Double\-Array} $\ast$my\-Array, int s)
+\begin{CompactList}\small\item\em Reallocator.\item\end{CompactList}\item 
+void {\bf ps\-Double\-Array\-Free} ({\bf ps\-Double\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Vector\-Array} $\ast$ {\bf ps\-Vector\-Array\-Alloc} (int s, int n)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+{\bf ps\-Vector\-Array} $\ast$ {\bf ps\-Vector\-Array\-Realloc} ({\bf ps\-Vector\-Array} $\ast$my\-Array, int s)
+\begin{CompactList}\small\item\em Reallocator.\item\end{CompactList}\item 
+void {\bf ps\-Vector\-Array\-Free} ({\bf ps\-Vector\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Void\-Ptr\-Array} $\ast$ {\bf ps\-Void\-Ptr\-Array\-Alloc} (int n, int s)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+{\bf ps\-Void\-Ptr\-Array} $\ast$ {\bf ps\-Void\-Ptr\-Array\-Realloc} ({\bf ps\-Void\-Ptr\-Array} $\ast$arr, int n)
+\begin{CompactList}\small\item\em Reallocate.\item\end{CompactList}\item 
+void {\bf ps\-Void\-Ptr\-Array\-Free} ({\bf ps\-Void\-Ptr\-Array} $\ast$arr, void($\ast$elem\-Free)(void $\ast$))
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\end{CompactItemize}
+
+\subsection{Math Utilities}
+\begin{CompactItemize}
+\item 
+{\bf ps\-Bit\-Mask} $\ast$ {\bf ps\-Bit\-Mask\-Alloc} (int n)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+void {\bf ps\-Bit\-Mask\-Free} ({\bf ps\-Bit\-Mask} $\ast$restrict my\-Mask)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Bit\-Mask} $\ast$ {\bf ps\-Bit\-Mask\-Set} ({\bf ps\-Bit\-Mask} $\ast$out\-Mask, const {\bf ps\-Bit\-Mask} $\ast$my\-Mask, int bit)
+\begin{CompactList}\small\item\em Set a bit mask.\item\end{CompactList}\item 
+int {\bf ps\-Bit\-Mask\-Test} (const {\bf ps\-Bit\-Mask} $\ast$check\-Mask, int bit)
+\begin{CompactList}\small\item\em Check a bit mask.\item\end{CompactList}\item 
+{\bf ps\-Bit\-Mask} $\ast$ {\bf ps\-Bit\-Mask\-Op} ({\bf ps\-Bit\-Mask} $\ast$out\-Mask, const {\bf ps\-Bit\-Mask} $\ast$restrict in\-Mask1, char $\ast$operator, const {\bf ps\-Bit\-Mask} $\ast$restrict in\-Mask2)
+\begin{CompactList}\small\item\em apply the given operator to two bit masks\item\end{CompactList}\item 
+{\bf ps\-Complex\-Array} $\ast$ {\bf ps\-Real\-FFT} ({\bf ps\-Complex\-Array} $\ast$restrict out, const {\bf ps\-Float\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Return Fourier Transform of an array.\item\end{CompactList}\item 
+{\bf ps\-Complex\-Array} $\ast$ {\bf ps\-Complex\-FFT} ({\bf ps\-Complex\-Array} $\ast$restrict out, const {\bf ps\-Complex\-Array} $\ast$restrict my\-Array, int sign)
+\begin{CompactList}\small\item\em Return [inverse?] Fourier Transform of a complex array.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Power\-Spec} ({\bf ps\-Float\-Array} $\ast$restrict out, const {\bf ps\-Float\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Return Power spectrum of a array.\item\end{CompactList}\item 
+{\bf ps\-Polynomial1D} $\ast$ {\bf ps\-Polynomial1DAlloc} (int n)
+\begin{CompactList}\small\item\em Constructors.\item\end{CompactList}\item 
+{\bf ps\-Polynomial2D} $\ast$ {\bf ps\-Polynomial2DAlloc} (int n\-X, int n\-Y)
+\item 
+{\bf ps\-Polynomial3D} $\ast$ {\bf ps\-Polynomial3DAlloc} (int n\-X, int n\-Y, int n\-Z)
+\item 
+{\bf ps\-Polynomial4D} $\ast$ {\bf ps\-Polynomial4DAlloc} (int n\-W, int n\-X, int n\-Y, int n\-Z)
+\item 
+void {\bf ps\-Polynomial1DFree} ({\bf ps\-Polynomial1D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Destructors.\item\end{CompactList}\item 
+void {\bf ps\-Polynomial2DFree} ({\bf ps\-Polynomial2D} $\ast$restrict my\-Poly)
+\item 
+void {\bf ps\-Polynomial3DFree} ({\bf ps\-Polynomial3D} $\ast$restrict my\-Poly)
+\item 
+void {\bf ps\-Polynomial4DFree} ({\bf ps\-Polynomial4D} $\ast$restrict my\-Poly)
+\item 
+float {\bf ps\-Eval\-Polynomial1D} (float x, const {\bf ps\-Polynomial1D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 1D polynomial.\item\end{CompactList}\item 
+float {\bf ps\-Eval\-Polynomial2D} (float x, float y, const {\bf ps\-Polynomial2D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 2D polynomial.\item\end{CompactList}\item 
+float {\bf ps\-Eval\-Polynomial3D} (float x, float y, float z, const {\bf ps\-Polynomial3D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 3D polynomial.\item\end{CompactList}\item 
+float {\bf ps\-Eval\-Polynomial4D} (float w, float x, float y, float z, const {\bf ps\-Polynomial4D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 4D polynomial.\item\end{CompactList}\item 
+{\bf ps\-DPolynomial1D} $\ast$ {\bf ps\-DPolynomial1DAlloc} (int n)
+\begin{CompactList}\small\item\em Constructors.\item\end{CompactList}\item 
+{\bf ps\-DPolynomial2D} $\ast$ {\bf ps\-DPolynomial2DAlloc} (int n\-X, int n\-Y)
+\item 
+{\bf ps\-DPolynomial3D} $\ast$ {\bf ps\-DPolynomial3DAlloc} (int n\-X, int n\-Y, int n\-Z)
+\item 
+{\bf ps\-DPolynomial4D} $\ast$ {\bf ps\-DPolynomial4DAlloc} (int n\-W, int n\-X, int n\-Y, int n\-Z)
+\item 
+void {\bf ps\-DPolynomial1DFree} ({\bf ps\-DPolynomial1D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Destructors.\item\end{CompactList}\item 
+void {\bf ps\-DPolynomial2DFree} ({\bf ps\-DPolynomial2D} $\ast$restrict my\-Poly)
+\item 
+void {\bf ps\-DPolynomial3DFree} ({\bf ps\-DPolynomial3D} $\ast$restrict my\-Poly)
+\item 
+void {\bf ps\-DPolynomial4DFree} ({\bf ps\-DPolynomial4D} $\ast$restrict my\-Poly)
+\item 
+double {\bf ps\-Eval\-DPolynomial1D} (double x, const {\bf ps\-DPolynomial1D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 1D polynomial (double precision).\item\end{CompactList}\item 
+double {\bf ps\-Eval\-DPolynomial2D} (double x, double y, const {\bf ps\-DPolynomial2D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 2D polynomial (double precision).\item\end{CompactList}\item 
+double {\bf ps\-Eval\-DPolynomial3D} (double x, double y, double z, const {\bf ps\-DPolynomial3D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 3D polynomial (double precision).\item\end{CompactList}\item 
+double {\bf ps\-Eval\-DPolynomial4D} (double w, double x, double y, double z, const {\bf ps\-DPolynomial4D} $\ast$restrict my\-Poly)
+\begin{CompactList}\small\item\em Evaluate 4D polynomial (double precision).\item\end{CompactList}\item 
+{\bf ps\-Type} $\ast$ {\bf ps\-Binary\-Op} (void $\ast$out, void $\ast$in1, char $\ast$operator, void $\ast$in2)
+\begin{CompactList}\small\item\em Perform a binary operation on two data items ({\bf ps\-Image} {\rm (p.\,\pageref{structpsImage})}, ps\-Vector, ps\-Scalar).\item\end{CompactList}\item 
+{\bf ps\-Type} $\ast$ {\bf ps\-Unary\-Op} (void $\ast$out, void $\ast$in, char $\ast$operator)
+\begin{CompactList}\small\item\em Perform a binary operation on two data items ({\bf ps\-Image} {\rm (p.\,\pageref{structpsImage})}, ps\-Vector, ps\-Scalar).\item\end{CompactList}\item 
+{\bf p\_\-ps\-Scalar} $\ast$ {\bf ps\-Scalar} (double value)
+\begin{CompactList}\small\item\em create a {\bf ps\-Type} {\rm (p.\,\pageref{structpsType})}-ed structure from a constant double value.\item\end{CompactList}\item 
+{\bf p\_\-ps\-Scalar} $\ast$ {\bf ps\-Scalar\-Type} (char $\ast$mode,...)
+\begin{CompactList}\small\item\em create a {\bf ps\-Type} {\rm (p.\,\pageref{structpsType})}-ed structure from a specified type\item\end{CompactList}\item 
+{\bf ps\-Matrix} $\ast$ {\bf ps\-Matrix\-Alloc} (int Xdimen, int Ydimen)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+void {\bf ps\-Matrix\-Free} ({\bf ps\-Matrix} $\ast$restrict my\-Matrix)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Matrix} $\ast$ {\bf ps\-Matrix\-Invert} ({\bf ps\-Matrix} $\ast$out, const {\bf ps\-Matrix} $\ast$my\-Matrix, float $\ast$restrict determinant)
+\begin{CompactList}\small\item\em Invert matrix.\item\end{CompactList}\item 
+float {\bf ps\-Matrix\-Determinant} (const {\bf ps\-Matrix} $\ast$restrict my\-Matrix)
+\begin{CompactList}\small\item\em Matrix determinant.\item\end{CompactList}\item 
+{\bf ps\-Matrix} $\ast$ {\bf ps\-Matrix\-Op} ({\bf ps\-Matrix} $\ast$out, const {\bf ps\-Matrix} $\ast$matrix1, const char $\ast$op, const {\bf ps\-Matrix} $\ast$matrix2)
+\begin{CompactList}\small\item\em Matrix operations.\item\end{CompactList}\item 
+{\bf ps\-Matrix} $\ast$ {\bf ps\-Matrix\-Transpose} ({\bf ps\-Matrix} $\ast$out, const {\bf ps\-Matrix} $\ast$my\-Matrix)
+\begin{CompactList}\small\item\em Transpose Matrix.\item\end{CompactList}\item 
+{\bf ps\-Vector} $\ast$ {\bf ps\-Matrix\-To\-Vector} ({\bf ps\-Matrix} $\ast$my\-Matrix)
+\begin{CompactList}\small\item\em Convert matrix to vector.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Minimize} (float($\ast$my\-Function)(const {\bf ps\-Float\-Array} $\ast$restrict), {\bf ps\-Float\-Array} $\ast$restrict initial\-Guess)
+\begin{CompactList}\small\item\em Minimize a particular function.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Minimize\-Chi2} (float($\ast$eval\-Model)(const {\bf ps\-Float\-Array} $\ast$restrict, const {\bf ps\-Float\-Array} $\ast$restrict), const {\bf ps\-Float\-Array} $\ast$restrict domain, const {\bf ps\-Float\-Array} $\ast$restrict data, const {\bf ps\-Float\-Array} $\ast$restrict errors, {\bf ps\-Float\-Array} $\ast$restrict initial\-Guess, const {\bf ps\-Int\-Array} $\ast$restrict guess\-Mask)
+\begin{CompactList}\small\item\em Minimize chi$^\wedge$2 for input data.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Get\-Array\-Polynomial} (const {\bf ps\-Float\-Array} $\ast$restrict ord, const {\bf ps\-Float\-Array} $\ast$restrict coord)
+\begin{CompactList}\small\item\em Derive a polynomial that goes through the points --- can be done analytically.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Sort} ({\bf ps\-Float\-Array} $\ast$out, const {\bf ps\-Float\-Array} $\ast$my\-Array)
+\begin{CompactList}\small\item\em Sort an array.\item\end{CompactList}\item 
+{\bf ps\-Int\-Array} $\ast$ {\bf ps\-Sort\-Index} ({\bf ps\-Int\-Array} $\ast$restrict out, const {\bf ps\-Float\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Sort an array, along with some other stuff.\item\end{CompactList}\item 
+{\bf ps\-Stats} $\ast$ {\bf ps\-Array\-Stats} (const {\bf ps\-Float\-Array} $\ast$restrict my\-Array, const {\bf ps\-Int\-Array} $\ast$restrict mask\-Array, unsigned int mask\-Val, {\bf ps\-Stats} $\ast$stats)
+\begin{CompactList}\small\item\em Do Statistics on an array.\item\end{CompactList}\item 
+{\bf ps\-Histogram} $\ast$ {\bf ps\-Histogram\-Alloc} (float lower, float upper, float size)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+{\bf ps\-Histogram} $\ast$ {\bf ps\-Histogram\-Alloc\-Generic} (const {\bf ps\-Float\-Array} $\ast$restrict lower, const {\bf ps\-Float\-Array} $\ast$restrict upper, float min\-Val, float max\-Val)
+\begin{CompactList}\small\item\em Generic constructor.\item\end{CompactList}\item 
+void {\bf ps\-Histogram\-Free} ({\bf ps\-Histogram} $\ast$restrict my\-Hist)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Histogram} $\ast$ {\bf ps\-Get\-Array\-Histogram} ({\bf ps\-Histogram} $\ast$restrict my\-Hist, const {\bf ps\-Float\-Array} $\ast$restrict my\-Array)
+\begin{CompactList}\small\item\em Calculate a histogram.\item\end{CompactList}\end{CompactItemize}
+
+\subsection{Astronomy Functions}
+\begin{CompactItemize}
+\item 
+{\bf ps\-Chip} $\ast$ {\bf ps\-Chip\-In\-FPA} ({\bf ps\-FPA} $\ast$fpa, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em returns Chip in FPA which contains the given FPA coordinate\item\end{CompactList}\item 
+{\bf ps\-Cell} $\ast$ {\bf ps\-Cell\-In\-Chip} ({\bf ps\-Chip} $\ast$chip, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em returns Cell in Chip which contains the given chip coordinate\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-Sky\-To\-TP} ({\bf ps\-Exposure} $\ast$exp, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em Convert (RA,Dec) to tangent plane coords.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-TPto\-FPA} ({\bf ps\-FPA} $\ast$fpa, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em Convert tangent plane coords to focal plane coordinates.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-FPAto\-Chip} ({\bf ps\-FPA} $\ast$fpa, {\bf ps\-Chip} $\ast$chip, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em converts the specified FPA coord to the coord on the given Chip\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-Chipto\-Cell} ({\bf ps\-Chip} $\ast$chip, {\bf ps\-Cell} $\ast$cell, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em converts the specified Chip coord to the coord on the given Cell\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-Cellto\-Chip} ({\bf ps\-Cell} $\ast$cell, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em converts the specified Cell coord to the coord on the parent Chip\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-Chipto\-FPA} ({\bf ps\-Chip} $\ast$chip, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em converts the specified Chip coord to the coord on the parent FPA\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-FPATo\-TP} ({\bf ps\-FPA} $\ast$fpa, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em Convert focal plane coords to tangent plane coordinates.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-TPto\-Sky} ({\bf ps\-Exposure} $\ast$exp, {\bf ps\-Coord} $\ast$coord)
+\begin{CompactList}\small\item\em Convert tangent plane coords to (RA,Dec).\item\end{CompactList}\item 
+float {\bf ps\-Get\-Airmass} ({\bf ps\-Coord} $\ast$coord, double sidereal\-Time)
+\begin{CompactList}\small\item\em Get the airmass for a given position and sidereal time.\item\end{CompactList}\item 
+float {\bf ps\-Get\-Parallactic} ({\bf ps\-Coord} $\ast$coord, double sidereal\-Time)
+\begin{CompactList}\small\item\em Get the parallactic angle for a given position and sidereal time.\item\end{CompactList}\item 
+float {\bf ps\-Get\-Refraction} (float colour, {\bf ps\-Phot\-System} color\-Plus, {\bf ps\-Phot\-System} color\-Minus, {\bf ps\-Exposure} $\ast$exp)
+\begin{CompactList}\small\item\em Estimate atmospheric refraction, along the parallactic.\item\end{CompactList}\item 
+{\bf ps\-Exposure} $\ast$ {\bf ps\-Exposure\-Alloc} (double ra, double dec, double ha, double zd, double az, double lst, float mjd, float rot\-Angle, float temp, float pressure, float humidity, float exptime)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+void {\bf ps\-Exposure\-Free} ({\bf ps\-Exposure} $\ast$restrict my\-Exp)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+double {\bf ps\-Get\-MJD} (void)
+\begin{CompactList}\small\item\em Get current MJD, for a timestamp.\item\end{CompactList}\item 
+double {\bf ps\-Get\-Sidereal} (float mjd, float longitude)
+\begin{CompactList}\small\item\em Get current sidereal time at longitude.\item\end{CompactList}\item 
+char $\ast$ {\bf ps\-Time\-To\-ISOTime} (ps\-Time time)
+\begin{CompactList}\small\item\em Convert ps\-Time to ISOTime (Human-readable date/time string YYYY/MM/DD,HH:MM:SS.SSS).\item\end{CompactList}\item 
+double {\bf ps\-Time\-To\-UTC} (ps\-Time time)
+\begin{CompactList}\small\item\em Convert ps\-Time to UTC.\item\end{CompactList}\item 
+double {\bf ps\-Time\-To\-MJD} (ps\-Time time)
+\begin{CompactList}\small\item\em Convert ps\-Time to MJD.\item\end{CompactList}\item 
+double {\bf ps\-Time\-To\-JD} (ps\-Time time)
+\begin{CompactList}\small\item\em Convert ps\-Time to JD.\item\end{CompactList}\item 
+timeval $\ast$ {\bf ps\-Time\-To\-Timeval} (ps\-Time time)
+\begin{CompactList}\small\item\em Convert ps\-Time to timeval (struct timeval).\item\end{CompactList}\item 
+tm $\ast$ {\bf ps\-Time\-To\-Tm} (ps\-Time time)
+\begin{CompactList}\small\item\em Convert ps\-Time to broken-down time (struct tm).\item\end{CompactList}\item 
+ps\-Time $\ast$ {\bf ps\-ISOTime\-To\-Time} (char $\ast$input)
+\begin{CompactList}\small\item\em Convert ISOTime (Human-readable date/time string YYYY/MM/DD,HH:MM:SS.SSS) to ps\-Time.\item\end{CompactList}\item 
+ps\-Time $\ast$ {\bf ps\-UTCTo\-Time} (double input)
+\begin{CompactList}\small\item\em Convert UTC to ps\-Time.\item\end{CompactList}\item 
+ps\-Time $\ast$ {\bf ps\-MJDTo\-Time} (double input)
+\begin{CompactList}\small\item\em Convert MJD to ps\-Time.\item\end{CompactList}\item 
+ps\-Time $\ast$ {\bf ps\-JDTo\-Time} (double input)
+\begin{CompactList}\small\item\em Convert JD to ps\-Time.\item\end{CompactList}\item 
+ps\-Time $\ast$ {\bf ps\-Timeval\-To\-Time} (struct timeval $\ast$input)
+\begin{CompactList}\small\item\em Convert timeval to ps\-Time (struct timeval).\item\end{CompactList}\item 
+ps\-Time $\ast$ {\bf ps\-TMto\-Time} (struct tm $\ast$input)
+\begin{CompactList}\small\item\em Convert broken-to ps\-Time down time (struct tm).\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Alloc} (int nx, int ny, {\bf ps\-Type} type)
+\begin{CompactList}\small\item\em Create an image of the specified size and type.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Subset} ({\bf ps\-Image} $\ast$image, int nx, int ny, int x0, int y0)
+\begin{CompactList}\small\item\em Create a subimage of the specified area.\item\end{CompactList}\item 
+void {\bf ps\-Image\-Free} ({\bf ps\-Image} $\ast$image)
+\begin{CompactList}\small\item\em Destroy the specified image (destroy children if they exist).\item\end{CompactList}\item 
+int {\bf ps\-Image\-Free\-Children} ({\bf ps\-Image} $\ast$image)
+\begin{CompactList}\small\item\em Destroy the children of the specified image.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Copy} ({\bf ps\-Image} $\ast$output, {\bf ps\-Image} $\ast$input)
+\begin{CompactList}\small\item\em Create a copy of the specified image.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Image\-Slice} ({\bf ps\-Image} $\ast$input, int x, int y, int nx, int ny, int direction, {\bf ps\-Stats} $\ast$stats)
+\begin{CompactList}\small\item\em Extract pixels from rectlinear region to a vector.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Image\-Cut} ({\bf ps\-Image} $\ast$input, float xs, float ys, float xe, float ye, float dw, {\bf ps\-Stats} $\ast$stats)
+\begin{CompactList}\small\item\em Extract pixels along a line to a vector.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Image\-Radial\-Cut} ({\bf ps\-Image} $\ast$input, float x, float y, float radius, float dr, {\bf ps\-Stats} $\ast$stats)
+\begin{CompactList}\small\item\em Extract radial annulii data to a vector.\item\end{CompactList}\item 
+{\bf ps\-Float\-Array} $\ast$ {\bf ps\-Image\-Contour} ({\bf ps\-Image} $\ast$input, float threshold, int binning)
+\begin{CompactList}\small\item\em Extract a 2-d contour from an image at the given threshold.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Rebin} ({\bf ps\-Image} $\ast$input, float scale, {\bf ps\-Stats} $\ast$stats)
+\begin{CompactList}\small\item\em Rebin image to new scale.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Rotate} ({\bf ps\-Image} $\ast$input, float angle)
+\begin{CompactList}\small\item\em Rotate image by given angle.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Shift} ({\bf ps\-Image} $\ast$input, float dx, float dy, float exposed)
+\begin{CompactList}\small\item\em Shift image by an arbitrary number of pixels in either direction.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Roll} ({\bf ps\-Image} $\ast$input, int dx, int dy)
+\begin{CompactList}\small\item\em Roll image by an integer number of pixels in either direction.\item\end{CompactList}\item 
+{\bf ps\-Stats} $\ast$ {\bf ps\-Image\-Get\-Stats} ({\bf ps\-Image} $\ast$input, {\bf ps\-Stats} $\ast$stats)
+\begin{CompactList}\small\item\em defines statistics to be calculated\item\end{CompactList}\item 
+{\bf ps\-Histogram} $\ast$ {\bf ps\-Image\-Histogram} ({\bf ps\-Histogram} $\ast$hist, {\bf ps\-Image} $\ast$input)
+\begin{CompactList}\small\item\em Construct a histogram from an image (or subimage).\item\end{CompactList}\item 
+{\bf ps\-Polynomial2D} $\ast$ {\bf ps\-Image\-Fit\-Polynomial} ({\bf ps\-Image} $\ast$input, {\bf ps\-Polynomial2D} $\ast$coeffs)
+\begin{CompactList}\small\item\em Fit a 2-D polynomial surface to an image.\item\end{CompactList}\item 
+int {\bf ps\-Image\-Eval\-Polynomial} ({\bf ps\-Image} $\ast$input, {\bf ps\-Polynomial2D} $\ast$coeffs)
+\begin{CompactList}\small\item\em Evaluate a 2-D polynomial surface to image pixels.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Read\-Section} ({\bf ps\-Image} $\ast$output, int x, int y, int dx, int dy, int z, char $\ast$extname, char $\ast$filename)
+\begin{CompactList}\small\item\em Read an image or subimage from a named file.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-FRead\-Section} ({\bf ps\-Image} $\ast$output, int x, int y, int dx, int dy, int z, char $\ast$extname, FILE $\ast$f)
+\begin{CompactList}\small\item\em Read an image or subimage from file descriptor.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Write\-Section} ({\bf ps\-Image} $\ast$input, int x, int y, int z, char $\ast$extname, char $\ast$filename)
+\begin{CompactList}\small\item\em Write an image section to named file (which may exist).\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-FWrite\-Section} ({\bf ps\-Image} $\ast$input, int x, int y, int z, char $\ast$extname, FILE $\ast$f)
+\begin{CompactList}\small\item\em Write an image section to named file (which may exist).\item\end{CompactList}\item 
+ps\-Metadata $\ast$ {\bf ps\-Image\-Read\-Header} (struct ps\-Metadata $\ast$output, char $\ast$extname, char $\ast$filename)
+\begin{CompactList}\small\item\em Read only header from image file.\item\end{CompactList}\item 
+ps\-Metadata $\ast$ {\bf ps\-Image\-FRead\-Header} (struct ps\-Metadata $\ast$output, char $\ast$extname, FILE $\ast$f)
+\begin{CompactList}\small\item\em Read only header from image file descriptor.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-FFT} ({\bf ps\-Image} $\ast$input, int direction)
+\begin{CompactList}\small\item\em Perform an FFT on the image.\item\end{CompactList}\item 
+int {\bf ps\-Image\-Clip} ({\bf ps\-Image} $\ast$input, float min, float vmin, float max, float vmax)
+\begin{CompactList}\small\item\em Clip image values outside of range to given values.\item\end{CompactList}\item 
+int {\bf ps\-Image\-Clip\-Na\-N} ({\bf ps\-Image} $\ast$input, float value)
+\begin{CompactList}\small\item\em Clip Na\-N image pixels to given value.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Binary\-Op} ({\bf ps\-Image} $\ast$out, {\bf ps\-Image} $\ast$in1, char $\ast$operator, {\bf ps\-Image} $\ast$in2)
+\begin{CompactList}\small\item\em Perform a binary operation on two images.\item\end{CompactList}\item 
+{\bf ps\-Image} $\ast$ {\bf ps\-Image\-Unary\-Op} ({\bf ps\-Image} $\ast$out, {\bf ps\-Image} $\ast$in1, char $\ast$operator)
+\begin{CompactList}\small\item\em Perform a unary operation on an image.\item\end{CompactList}\item 
+int {\bf ps\-Image\-Overlay\-Section} ({\bf ps\-Image} $\ast$image, {\bf ps\-Image} $\ast$overlay, int x0, int y0, char $\ast$operator)
+\begin{CompactList}\small\item\em Overlay subregion of image with another image.\item\end{CompactList}\item 
+{\bf ps\-Meta\-Data\-Item} $\ast$ {\bf ps\-Meta\-Data\-Item\-Alloc} (int type\-Flags, const void $\ast$val, const char $\ast$comment, const char $\ast$name,...)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+void {\bf ps\-Meta\-Data\-Item\-Free} ({\bf ps\-Meta\-Data\-Item} $\ast$ms)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Meta\-Data\-Set} $\ast$ {\bf ps\-Meta\-Data\-Set\-Alloc} (void)
+\begin{CompactList}\small\item\em Constructor.\item\end{CompactList}\item 
+void {\bf ps\-Meta\-Data\-Set\-Free} ({\bf ps\-Meta\-Data\-Set} $\ast$ms)
+\begin{CompactList}\small\item\em Destructor.\item\end{CompactList}\item 
+{\bf ps\-Meta\-Data\-Item} $\ast$ {\bf ps\-Meta\-Data\-Append} ({\bf ps\-Meta\-Data\-Set} $\ast$restrict ms, {\bf ps\-Meta\-Data\-Item} $\ast$restrict item)
+\item 
+{\bf ps\-Meta\-Data\-Item} $\ast$ {\bf ps\-Meta\-Data\-Remove} ({\bf ps\-Meta\-Data\-Set} $\ast$restrict ms, const char $\ast$restrict key)
+\item 
+void {\bf ps\-Meta\-Data\-Set\-Iterator} ({\bf ps\-Meta\-Data\-Set} $\ast$ms)
+\item 
+{\bf ps\-Meta\-Data\-Item} $\ast$ {\bf ps\-Meta\-Data\-Get\-Next} ({\bf ps\-Meta\-Data\-Set} $\ast$restrict ms, const char $\ast$restrict match)
+\item 
+{\bf ps\-Meta\-Data\-Item} $\ast$ {\bf ps\-Meta\-Data\-Lookup} (const {\bf ps\-Meta\-Data\-Set} $\ast$restrict ms, const char $\ast$restrict key)
+\item 
+void {\bf ps\-Meta\-Data\-Item\-Print} (FILE $\ast$fd, const {\bf ps\-Meta\-Data\-Item} $\ast$restrict ms, const char $\ast$prefix)
+\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coord\-Xform\-Apply} ({\bf ps\-Coord\-Xform} $\ast$frame, {\bf ps\-Coord} $\ast$coords)
+\begin{CompactList}\small\item\em apply the coordinate transformation to the given coordinate\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Distortion\-Apply} ({\bf ps\-Distortion} $\ast$pattern, {\bf ps\-Coord} $\ast$coords, float mag, float color)
+\begin{CompactList}\small\item\em apply the optical distortion to the given coordinate, magnitude, color\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Get\-Offset} (const {\bf ps\-Coord} $\ast$restrict position1, const {\bf ps\-Coord} $\ast$restrict position2, char $\ast$system)
+\begin{CompactList}\small\item\em Get offset (RA,Dec) on the sky between two positions position1 and position2 may not be identical.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Apply\-Offset} (const {\bf ps\-Coord} $\ast$restrict position, const {\bf ps\-Coord} $\ast$restrict offset, char $\ast$system)
+\begin{CompactList}\small\item\em Apply an offset to a position.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Get\-Sun\-Pos} (float mjd)
+\begin{CompactList}\small\item\em Get Sun Position.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Get\-Moon\-Pos} (float mjd, double latitude, double longitude)
+\begin{CompactList}\small\item\em Get Moon position.\item\end{CompactList}\item 
+float {\bf ps\-Get\-Moon\-Phase} (float mjd)
+\begin{CompactList}\small\item\em Get Moon phase.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Get\-Solar\-System\-Pos} (char $\ast$solar\-System\-Object, float mjd)
+\begin{CompactList}\small\item\em Get Planet positions.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coordinates\-Ito\-E} (const {\bf ps\-Coord} $\ast$restrict coordinates)
+\begin{CompactList}\small\item\em Convert ICRS to Ecliptic.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coordinates\-Eto\-I} (const {\bf ps\-Coord} $\ast$restrict coordinates)
+\begin{CompactList}\small\item\em Convert Ecliptic to ICRS.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coordinates\-Ito\-G} (const {\bf ps\-Coord} $\ast$restrict coordinates)
+\begin{CompactList}\small\item\em Convert ICRS to Galactic.\item\end{CompactList}\item 
+{\bf ps\-Coord} $\ast$ {\bf ps\-Coordinates\-Gto\-I} (const {\bf ps\-Coord} $\ast$restrict coordinates)
+\begin{CompactList}\small\item\em Convert Galactic to ICRS.\item\end{CompactList}\end{CompactItemize}
+
+
 \bibliographystyle{plain} \bibliography{panstarrs}