Context Navigation

← Previous Change
Next Change →

psLibSDRS.tex

Timestamp:

Mar 23, 2004, 5:39:01 PM (22 years ago)

Author:

Paul Price

Message:

Updated APIs. APIs in this file should be correct as of the current
version of the .h files.

File:

: 1 edited

trunk/doc/pslib/psLibSDRS.tex (modified) (83 diffs)

Legend:

: Unmodified
: Added
: Removed

trunk/doc/pslib/psLibSDRS.tex

-              r288
+              r296
+%%% $Id: psLibSDRS.tex,v 1.9 2004-03-24 03:39:01 price Exp $
 \documentclass[panstarrs]{panstarrs}
 %\documentclass[panstarrs]{panstarrs}
 …
 \pagenumbering{arabic}
-%Here's a reference to another document:
-%\href{file:utils#psDlist}{utils.pdf}; the \code{#psDlist} points to
-%\CODE|\hlabel{psDlist}| in the file \file{utils.tex} (this is like
-%a regular \code{\label}, but defines the hyperlink too).
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 …
 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}
 …
 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;
+typedef struct {
+    const void *magic0;                 //!< initialised to p_psMEMMAGIC
+    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 refCounter;                     //!< how many times pointer is referenced
+    const void *magic;                  //!< initialised to p_psMEMMAGIC
+} psMemBlock;
 \end{verbatim}
 …
 \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);
+The types and function prototypes for the part of the memory API
+concerned with allocating and freeing memory are shown below.
+\begin{verbatim}
+/// Memory allocation. Underlying private function called by macro psAlloc.
+void *p_psAlloc(size_t size,            //!< Size required
+                const char *file,       //!< File of call
+                int lineno              //!< Line number of call
+                );
+/// Memory re-allocation.  Underlying private function called by macro psRealloc.
+void *p_psRealloc(void *ptr,            //!< Pointer to re-allocate
+                  size_t size,          //!< Size required
+                  const char *file,     //!< File of call
+                  int lineno            //!< Line number of call
+                  );
+/// Free memory.  Underlying private function called by macro psFree.
+void p_psFree(void *ptr,                //!< Pointer to free
+              const char *file,         //!< File of call
+              int lineno                //!< Line number of call
+              );
+/// Memory allocation. psAlloc sends file and line number to p_psAlloc.
 #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__)
+/// Memory re-allocation.  psRealloc sends file and line number to p_psRealloc.
 #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__)
+/// Free memory.  psFree sends file and line number to p_psFree.
 #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.
 …
 \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.
+  The header 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
 …
 \hlabel{secMemAdvanced}
+The types and function prototypes for this part of the memory API
+are shown below.
 \begin{table}
 \begin{verbatim}
+/// prototype of a basic callback used by memory functions
 typedef int (*psMemCallback)(const psMemBlock *ptr);
+typedef void (*psMemProblemCallback)(const psMemBlock *ptr,
+                                     const char *file, int lineno);
+/// prototype of a callback used in error conditions
+typedef void (*psMemProblemCallback)(const psMemBlock *ptr, const char *file, int lineno);
+/// prototype of a callback used when memory runs out
 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}.
+/// Set callback for problems
+psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func //!< Function to run
+                                       );
+/// Set callback for out-of-memory
+psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func //!< Function to run
+                                           );
+/// Set call back for when a particular memory block is allocated
+psMemCallback psMemAllocateSetCB(psMemCallback func //!< Function to run
+                                 );
+/// Set call back for when a particular memory block is freed
+psMemCallback psMemFreeSetCB(psMemCallback func
+                             );
+/// get next memory ID
+int psMemGetId(void);
+/// set p_psMemAllocateID to id
+long psMemSetAllocateID(long id         //!< ID to set
+                        );
+/// set p_psMemFreeID to id
+long psMemSetFreeID(long id             //!< ID to set
+                    );
+/// Check for memory leaks
+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)
+                    );
+/// Check for memory corruption
+int psMemCheckCorruption(int abort_on_error //!< Abort on detecting corruption?
+                         );
+\end{verbatim}
 \paragraph{Callback Routines}
 …
 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
+/// Return reference counter
+int psMemGetRefCounter(void *vptr       //!< Pointer to get refCounter for
+                       );
+/// Increment reference counter and return the pointer
+void *psMemIncrRefCounter(void *vptr    //!< Pointer to increment refCounter, and return
+                          );
+/// Decrement reference counter and return the pointer
+void *psMemDecrRefCounter(void *vptr    //!< Pointer to decrement refCounter, and return
+                          );
 \end{verbatim}
 …
 \subsubsubsection{Rationale}
+\begin{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:
 \begin{verbatim}
 typedef struct {
 …
+}
 \end{verbatim}
+\caption{An example of reference counting}
+\label{tabReferenceCounting}
+\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
 …
 \hlabel{psTrace}
+\begin{table}
+  \begin{verbatim}
+\begin{verbatim}
 #if defined(PS_NTRACE)
 #  define psTrace(facil, level, ...) /* do nothing */
 …
 #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}.
+/// Send a trace message
+void p_psTrace(const char *facil,       ///< facilty of interest
+               int level,               ///< desired trace level
+               ...                      ///< trace message arguments
+    );
+/// Set trace level
+int psSetTraceLevel(const char *facil,  ///< facilty of interest
+                    int level           ///< desired trace level
+    );
+/// Get the trace level
+int psGetTraceLevel(const char *name    ///< facilty of interest
+    );
+/// turn off all tracing, and free trace's allocated memory
+void psTraceReset(void);
+/// print trace levels
+void psPrintTraceLevels(void);
+\end{verbatim}
 \begin{itemize}
 …
     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
+    is defined, all occurrences of \code{psTrace} shall
     be replaced by whitespace.
 …
     \item
       There is no requirement that \code{psTrace} be usable from
       within the functions that implement \file{psTrace.h}
       or \file{psMemory.h} systems.
+      within the functions that implement the tracing or memory
+      management systems.
     \item
 …
 \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}.
+\begin{verbatim}
+enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO }; //!< Status codes for log messages
+enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT }; //!< Destinations for log messages
+/// Logs a message
+void psLogMsg(const char *name, int level, const char *fmt, ...);
+/// Logs a message from varargs
+void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap);
+/// Sets the log destination
+int psSetLogDestination(int dest);
+/// Sets the log level
+int psSetLogLevel(int level);
+/// sets the log format
+void psSetLogFormat(const char *fmt);
+\end{verbatim}
 The function \code{psSetLogLevel} may be used to set the current
 …
 \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}
+\PS{} supports doubly linked lists through a type \code{psDlist}.  The
+type consists of the following definitions:
+\begin{verbatim}
+/** Doubly-linked list element */
 typedef struct psDlistElem {
     struct psDlistElem *prev;           // previous link in list
     struct psDlistElem *next;           // next link in list
     void *data;                         // real data item
+   struct psDlistElem *prev;            //!< previous link in list
+   struct psDlistElem *next;            //!< next link in list
+   void *data;                          //!< real data item
 } psDlistElem;
+/** Doubly-linked list */
 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
+   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
 } 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
+/** Special values of index into list */
+enum {
+   PS_DLIST_HEAD = 0,                   //!< at head
+   PS_DLIST_TAIL = -1,                  //!< at tail
+   PS_DLIST_UNKNOWN = -2,               //!< unknown position
+   PS_DLIST_PREV = -3,                  //!< previous element
+   PS_DLIST_NEXT = -4                   //!< next element
 };
 \end{verbatim}
 …
 \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.
+/** Constructor */
+psDlist *psDlistAlloc(void *data        //!< initial data item; may be NULL
+                      );
+/** Destructor */
+void psDlistFree(psDlist *list,         //!< list to destroy
+                void (*elemFree)(void *) //!< destructor for data on list
+                 );
+/**** List maintainence functions ****/
+/** Add to list */
+psDlist *psDlistAdd(psDlist *list,      //!< list to add to (may be NULL)
+                    void *data,         //!< data item to add
+                    int where           //!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL
+                    );
+/** Append to a list */
+psDlist *psDlistAppend(psDlist *list,   //!< list to append to (may be NULL)
+                       void *data       //!< data item to add
+                       );
+/** Remove from a list */
+void *psDlistRemove(psDlist *list,      //!< list to remove element from
+                    void *data,         //!< data item to remove
+                    int which           //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+                                        //!< PS_DLIST_PREV
+                    );
+/** Retrieve from a list */
+void *psDlistGet(const psDlist *list,   //!< list to retrieve element from
+                 int which              //!< index of item, or PS_DLIST_NEXT, or PS_DLIST_PREV
+                 );
+/** Convert doubly-linked list to an array */
+psVoidPtrArray *psDlistToArray(psDlist *dlist //!< List to convert
+                               );
+/** Convert array to a doubly-linked list */
+psDlist *psArrayToDlist(psVoidPtrArray *arr //!< Array to convert
+                        );
+\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
 …
 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);
+/** Set the iterator */
+void psDlistSetIterator(psDlist *list,  //!< list to retrieve element from
+                        int where,      //!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL
+                        int which       //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+                                        //!< PS_DLIST_PREV
+                        );
+/** Get next element */
+void *psDlistGetNext(psDlist *list,     //!< list to retrieve element from
+                     int which          //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+                                        //!< PS_DLIST_PREV
+                     );
+/** Get previous element */
+void *psDlistGetPrev(psDlist *list,     //!< list to retrieve element from
+                     int which          //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
+                                        //!< PS_DLIST_PREV
+                     );
 \end{verbatim}
 in which the \code{where} argument must be \code{PS_DLIST_HEAD} or \code{PS_DLIST_TAIL},
 …
 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}, \code{PS_DECLARE_ARRAY_TYPE(psType)} and
+This type and functions may be declared and defined using two macros,
+\code{PS_DECLARE_ARRAY_TYPE(psType)} and
 \code{PS_CREATE_ARRAY_TYPE(psType)}.  The former defines the
 \code{typedef} and declares the prototypes (and is thus suitable for
 …
 \code{array}s.
 \begin{verbatim}
 #include "psUtils.h"
+#include "psLib.h"
 typedef struct {
 …
 \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}.
+The public APIs for the hash table (table \ref{tabPsHash}) are shown below.
 \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.}
+\begin{verbatim}
+typedef struct HashTable psHash;        ///< Opaque type for a hash table
+/// Allocate hash buckets in table.
+psHash *psHashAlloc(int nbucket         ///< initial number of buckets
+    );
+/// Free hash buckets from table.
+void psHashFree(psHash *table,          ///< hash table to be freed
+                void (*itemFree)(void *item) ///< how to free hashed data; or NULL
+    );
+/// Insert entry into table.
+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
+    );
+/// Lookup key in table.
+void *psHashLookup(psHash *table,       ///< table to lookup key in
+                   const char *key      ///< key to lookup
+    );
+/// Remove key from table.
+void *psHashRemove(psHash *table,       ///< table to lookup key in
+                   const char *key      ///< key to lookup
+    );
+\end{verbatim}
 A hash table is an abstract type \code{psHash}.  The argument
 …
 \subsection{Miscellaneous Utilities}
+\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
+\begin{verbatim}
 #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}
+/// Prints an error message and aborts
+void psAbort(const char *name,          ///< Category of code that caused the abort
+             const char *fmt,           ///< Format
+             ...                        ///< Extra arguments to use format
+             );
+/// Prints an error message and doesn't abort
+void psError(const char *name,          ///< Category of code that caused the abort
+             const char *fmt,           ///< Format
+             ...                        ///< Extra arguments to use format
+    );
+/// Allocates and returns a copy of a string
+char *psStringCopy(const char *str      ///< string to copy
+    );
+/// Allocates nChar and returns a copy of the string or segment
+char *psStringNCopy(const char *str,    ///< string to copy
+                    int nChar           //!< Number of characters (including \0 )
+    );
+\end{verbatim}
 \code{psAbort} shall call \code{psMsgLog} with a level of \code{PS_LOG_ABORT},
 …
             char *operator,             ///< operator
             void *in2                   ///< second input
 );
+    );
 \end{verbatim}
 …
            void *in,                    ///< input
            char *operator,              ///< operator
 );
+    );
 \end{verbatim}
 …
 \begin{verbatim}
+/** private structure used to pass constant values into the math operators. */
 typedef struct {
     psType type;
     union {
+        int i;
+        float f;
+        double d;
+        complex float c;
+    }
+    psType type;                        ///< data type information
+    union {
+        int i;                          ///< integer value entry
+        float f;                        ///< float value entry
+        double d;                       ///< double value entry
+        complex float c;                ///< complex value entry
+    } val;
 } p_psScalar;
 \end{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
+    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
+        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
+        psComplex **rows_complex;       //!< pointers to psComplex data
     } rows;
     struct psImage *parent;             ///< parent, if a subimage
     struct psImage *children;           ///< children of this region
     int Nchildren;                      ///< number of subimages
+    psImage *parent;                    ///< parent, if a subimage
+    int Nchildren;                      ///< number of subimages
+    psImage *children;                  ///< children of this region; array of Nchildren pointers
 } psImage;
 \end{verbatim}
 …
 outside of the parent image.
 \begin{verbatim}
+/// Create a subimage of the specified area.
 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)
+psImageSubset(psImage *out,             //!< Subimage to return, or NULL
+              const 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}
 …
 \begin{verbatim}
 psImage *
+psImageCopy (psImage *output,           ///< target structure for output image data
+             psImage *input)            ///< copy this image
+psImageCopy(psImage *output,            ///< target structure for output image data
+            const psImage *input        ///< copy this image
+    );
 \end{verbatim}
 …
 \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
+psImageSlice(psFloatArray *out,         //!< Vector to output, or NULL
+             const 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
+             const psStats *stats       ///< defines statistics used to find output values
+    );
 \end{verbatim}
 …
 \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
+psImageCut(psFloatArray *out,           //!< Vector to output, or NULL
+           const 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
+           const psStats *stats         ///< defines statistics used to find output values
+    );
  \end{verbatim}
 …
 \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}
+psImageRadialCut(psFloatArray *out,     //!< Vector to output, or NULL
+                 const 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
+                 const psStats *stats   ///< defines statistics used to find output values
+    );
+\end{verbatim}
 Rebin image to new scale.  A new image is constructed in which the
 …
 \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
+psImageRebin(psImage *out,              //!< Image to output, or NULL
+             const psImage *input,      ///< rebin this image
+             float scale,               ///< rebinning scale: doutput = scale*dinput
+             const psStats *stats       ///< defines statistics used to find output values
+    );
 \end{verbatim}
 …
 \begin{verbatim}
 psImage *
+psImageRotate (psImage *input,          ///< rotate this image
+               float angle)             ///< rotate by this amount (degrees)
+psImageRotate(psImage *out,             //!< Image to output, or NULL
+              const psImage *input,     ///< rotate this image
+              float angle               ///< rotate by this amount anti-clockwise (degrees)
+    );
 \end{verbatim}
 …
 \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
+psImageShift(psImage *out,              //!< Image to output, or NULL
+             const 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}
 …
 \begin{verbatim}
 psImage *
+psImageRoll (psImage *input,            ///< roll this image
+             int dx,                    ///< roll this amount in x
+             int dy)                    ///< roll this amount in y
+psImageRoll(psImage *out,               //!< Image to output, or NULL
+            const psImage *input,       ///< roll this image
+            int dx,                     ///< roll this amount in x
+            int dy                      ///< roll this amount in y
+    );
 \end{verbatim}
 …
 \begin{verbatim}
 psStats *
+psImageGetStats (psImage *input,        ///< image (or subimage) to calculate stats
+                 psStats *stats)        ///< defines statistics to be calculated
+psImageGetStats(const psImage *input,   ///< image (or subimage) to calculate stats
+                psStats *stats          ///< defines statistics to be calculated & target
+    );
 \end{verbatim}
 …
 \begin{verbatim}
 psHistogram *
+psImageHistogram (psHistogram *hist,    ///< input histogram description & target
+                  psImage *input)       ///< determine histogram of this image
+psImageHistogram(psHistogram *hist,     ///< input histogram description & target
+                 const psImage *input   ///< determine histogram of this image
+    );
 \end{verbatim}
 …
 \begin{verbatim}
 psPolynomial2D *
+psImageFitPolynomial (psImage *input,   ///< image to fit
+                      psPolynomial2D *coeffs) ///< coefficient structure carries in desired terms
+psImageFitPolynomial(const psImage *input, ///< image to fit
+                     psPolynomial2D *coeffs ///< coefficient structure carries in desired terms & target
+    );
 \end{verbatim}
 …
 \begin{verbatim}
 int
+psImageEvalPolynomial (psImage *input,  ///< image to fit
+                       psPolynomial2D *coeffs) ///< coefficient structure carries in desired terms
+psImageEvalPolynomial(const psImage *input, ///< image to fit
+                      const psPolynomial2D *coeffs ///< coefficient structure carries in desired terms
+    );
 \end{verbatim}
 …
 \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
+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
+                   const char *extname, ///< MEF extension name ("PHU" for primary header)
+                   int extnum,          ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+                   const char *filename ///< file to read data from
+    );
 \end{verbatim}
 …
 \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
+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
+                    const 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 data from
+    );
 \end{verbatim}
 …
 \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
+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
+                    const char *extname, ///< MEF extension name ("PHU" for primary header)
+                    int extnum,         ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+                    const char *filename ///< file to write data to
+    );
 \end{verbatim}
 …
 \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
+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
+                     const char *extname, ///< MEF extension name
+                     int extnum,        ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+                     FILE *f            ///< file descriptor to write data to
+    );
 \end{verbatim}
 …
 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
+psMetadata *
+psImageReadHeader(psMetadata *output,   ///< read data to this structure
+                  const char *extname,  ///< MEF extension name ("PHU" for primary header)
+                  int extnum,           ///< MEF extension number (-1 for "PHU", 0 : Nextend - 1)
+                  const char *filename  ///< file to read from
+    );
 \end{verbatim}
 …
 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
+psMetadata *
+psImageFReadHeader(psMetadata *output, ///< read data to this structure
+                   const 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}
 …
 \begin{verbatim}
 psImage *
+psImageFFT (psImage *input,             ///< image to FFT
+            int direction)              ///< FFT direction
+psImageFFT(psImage *output,             //!< Output image
+           const psImage *input,        ///< image to FFT
+           int direction                ///< FFT direction
+    );
 \end{verbatim}
 …
 \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
+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}
 …
 \begin{verbatim}
 int
+psImageClipNaN (psImage *input,         ///< clip this image
+                float value)            ///< set nan pixels to this value
+psImageClipNaN(psImage *input,          ///< clip this image & target
+               float value              ///< set nan pixels to this value
+    );
 \end{verbatim}
 …
 \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}
+psImageOverlaySection(psImage *image,   ///< input image & target
+                      const psImage *overlay, ///< image to overlay
+                      int x0,           ///< x offset of overlay subimage
+                      int y0,           ///< y offset of overlay subimage
+                      const char *operator ///< overlay operation
+    );
+\end{verbatim}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Astrometry}
 …
 typedef struct {
     int nCells;                         ///< Number of Cells assigned
     struct psCell *cells;               ///< Cells in the Chip
     psMetaDataSet *md;                  ///< Chip-level metadata
+    psCell *cells;                      ///< Cells in the Chip
+    psMetaDataSet *md;                  ///< Chip-level metadata
     psCoordXform *chipToFPA;            ///< Transformations from chip coordinates to FPA coordinates
+    struct psFPA *parentFPA;            ///< FPA which contains this chip
+    psCoordXform *FPAtoChip;            //!< Transformations from FPA coordinates to chip
+    struct psFPA *parentFPA;            ///< FPA which contains this chip
 } psChip;
 \end{verbatim}
 …
     int nChips;                         ///< Number of Cells assigned
     int nAlloc;                         ///< Number of Cells available
     struct psChip *chips;               ///< Chips in the Focal Plane Array
     psMetaDataSet *md;                  ///< FPA-level metadata
     psDistortion *TPtoFP;               ///< Transformation term from
     psDistortion *FPtoTP;               ///< Transformation term from
     psFixedPattern *pattern;            //!< Fixed pattern residual offsets
+    psChip *chips;                      ///< Chips in the Focal Plane Array
+    psMetaDataSet *md;                  ///< FPA-level metadata
+    psDistortion *TPtoFP;               ///< Transformation term from
+    psDistortion *FPtoTP;               ///< Transformation term from
+    psFixedPattern *pattern;            //!< Fixed pattern residual offsets
     psExposure *exp;                    ///< information about this exposure
     psPhotSystem colorPlus, colorMinus; ///< Colour reference
 …
 \begin{verbatim}
 /** Information needed (by SLALIB) to convert Apparent to Observed Position */
+/** Information needed (by SLALib) to convert Apparent to Observed Position */
 typedef struct {
     double latitude;                    ///< geodetic latitude (radians)
 …
 /** returns Chip in FPA which contains the given FPA coordinate */
 psChip *
+psChipInFPA (psFPA *fpa,                ///< FPA description
+             psCoord *coord             ///< coordinate in FPA
+             );
+psChipInFPA (psChip *out,               //!< Chip to return, or NULL
+             const psFPA *fpa,          ///< FPA description
+             const psCoord *coord       ///< coordinate in FPA
+             );
 \end{verbatim}
 …
 /** returns Cell in Chip which contains the given chip coordinate */
 psCell *
+psCellInChip (psChip *chip,             ///< chip description
+              psCoord *coord            ///< coordinate in chip
+              );
+psCellInChip(psCell *out,               //!< Cell to return, or NULL
+             const psChip *chip,        ///< chip description
+             const psCoord *coord       ///< coordinate in chip
+             );
 \end{verbatim}
 …
 /** Return the cell in FPA which contains the given FPA coordinates */
 psCell *
 psCellInFPA(psCell *out,                //!< Cell to return, or NULL
             psFPA *fpa,                 //!< FPA description
             psCoord *coord              //!< Coordinate in FPA
             );
+psCellInFPA(psCell *out,                //!< Cell to return, or NULL
+            const psFPA *fpa,           //!< FPA description
+            const psCoord *coord        //!< Coordinate in FPA
+            );
 \end{verbatim}
 …
 \begin{verbatim}
-/** returns Chip in FPA which contains the given FPA coordinate */
-psChip *
-psChipInFPA (psChip *out,               //!< Chip to return, or NULL
-             psFPA *fpa,                ///< FPA description
-             psCoord *coord             ///< coordinate in FPA
-             );
-\end{verbatim}
-\begin{verbatim}
-/** returns Cell in Chip which contains the given chip coordinate */
-psCell *
-psCellInChip(psCell *out,               //!< Cell to return, or NULL
-             psChip *chip,              ///< chip description
-             psCoord *coord             ///< coordinate in chip
-             );
-\end{verbatim}
-\begin{verbatim}
-/** Return the cell in FPA which contains the given FPA coordinates */
-psCell *
-psCellInFPA(psCell *out,                //!< Cell to return, or NULL
-            psFPA *fpa,                 //!< FPA description
-            psCoord *coord              //!< Coordinate in FPA
-            );
-\end{verbatim}
-\begin{verbatim}
 /** Convert (RA,Dec) to cell and cell coordinates */
 psCoord *
 …
 /** Convert cell and cell coordinate to (RA,Dec) */
 psCoord *
 psCoordCellToSky(psCoord *out,          //!< Coordinates to return, or NULL
                  const psCell *cell,    //!< Cell to get coordinates for
                  psCoord *coord         //!< cell coordinates to transform
                  );
+psCoordCellToSky(psCoord *out,          //!< Coordinates to return, or NULL
+                 const psCell *cell,    //!< Cell to get coordinates for
+                 const psCoord *coord   //!< cell coordinates to transform
+                 );
 \end{verbatim}
 …
 /** Quick and dirty cell to (RA,Dec) --- employs cellToSky transformation */
 psCoord *
 psCoordCellToSkyQuick(psCoord *out,     //!< Coordinates to return, or NULL
                       const psCell *cell, //!< Cell description
                       psCoord *coord    //!< cell coordinates to transform
                       );
+psCoordCellToSkyQuick(psCoord *out,     //!< Coordinates to return, or NULL
+                      const psCell *cell, //!< Cell description
+                      const psCoord *coord //!< cell coordinates to transform
+                      );
 \end{verbatim}
 …
 /** Convert (RA,Dec) to tangent plane coords */
 psCoord *
 psCoordSkyToTP(psCoord *out,            //!< Coordinates to return, or NULL
                psexposure *exp,         //!< Exposure description
                psCoord *coord           //!< input Sky coordinate
                );
+psCoordSkyToTP(psCoord *out,            //!< Coordinates to return, or NULL
+               const psExposure *exp,   //!< Exposure description
+               const psCoord *coord     //!< input Sky coordinate
+               );
 \end{verbatim}
 …
 /** Convert tangent plane coords to focal plane coordinates */
 psCoord *
 psCoordTPtoFPA(psCoord *out,            //!< Coordinates to return, or NULL
                const psFPA *fpa,        //!< FPA description
                psCoord *coord           //!< input TP coordinate
                );
+psCoordTPtoFPA(psCoord *out,            //!< Coordinates to return, or NULL
+               const psFPA *fpa,        //!< FPA description
+               const psCoord *coord     //!< input TP coordinate
+               );
 \end{verbatim}
 …
 /** converts the specified FPA coord to the coord on the given Chip */
 psCoord *
+psCoordFPAtoChip (psCoord *out,         //!< Coordinates to return, or NULL
+                  psFPA *fpa,           ///< FPA description
+                  psChip *chip,         ///< Chip of interest
+                  psCoord *coord        ///< input FPA coordinate
+                  );
+psCoordFPAtoChip (psCoord *out,         //!< Coordinates to return, or NULL
+                  const psChip *chip,   ///< Chip of interest
+                  const psCoord *coord  ///< input FPA coordinate
+                  );
 \end{verbatim}
 …
 /** converts the specified Chip coord to the coord on the given Cell */
 psCoord *
+psCoordChiptoCell (psCoord *out,        //!< Coordinates to return, or NULL
+                   psChip *chip,        ///< Chip description
+                   psCell *cell,        ///< Cell of interest
+                   psCoord *coord       ///< input Chip coordinate
+                   );
+psCoordChiptoCell (psCoord *out,        //!< Coordinates to return, or NULL
+                   const psCell *cell,  ///< Cell of interest
+                   const psCoord *coord ///< input Chip coordinate
+                   );
 \end{verbatim}
 …
 /** converts the specified Cell coord to the coord on the parent Chip */
 psCoord *
 psCoordCelltoChip (psCoord *out,        //!< Coordinates to return, or NULL
                    psCell *cell,        ///< Cell description
                    psCoord *coord       ///< input Cell coordinate
                    );
+psCoordCelltoChip (psCoord *out,        //!< Coordinates to return, or NULL
+                   const psCell *cell,  ///< Cell description
+                   const psCoord *coord ///< input Cell coordinate
+                   );
 \end{verbatim}
 …
 /** converts the specified Chip coord to the coord on the parent FPA */
 psCoord *
 psCoordChiptoFPA (psCoord *out,         //!< Coordinates to return, or NULL
                   psChip *chip,         ///< Chip description
                   psCoord *coord        ///< input Chip coordinate
                   );
+psCoordChiptoFPA (psCoord *out,         //!< Coordinates to return, or NULL
+                  const psChip *chip,   ///< Chip description
+                  const psCoord *coord  ///< input Chip coordinate
+                  );
 \end{verbatim}
 …
 /** Convert focal plane coords to tangent plane coordinates */
 psCoord *
 psCoordFPAToTP(psCoord *out,            //!< Coordinates to return, or NULL
                psFPA *fpa,              //!< FPA description
                psCoord *coord           //!< input FPA coordinate
                );
+psCoordFPAToTP(psCoord *out,            //!< Coordinates to return, or NULL
+               const psFPA *fpa,        //!< FPA description
+               const psCoord *coord     //!< input FPA coordinate
+               );
 \end{verbatim}
 …
 /** Convert tangent plane coords to (RA,Dec) */
 psCoord *
 psCoordTPtoSky(psCoord *out,            //!< Coordinates to return, or NULL
                psExposure *exp,         //!< Exposure description
                psCoord *coord           //!< input TP coordinate
                );
+psCoordTPtoSky(psCoord *out,            //!< Coordinates to return, or NULL
+               const psExposure *exp,   //!< Exposure description
+               const psCoord *coord     //!< input TP coordinate
+               );
 \end{verbatim}
 …
 /** Convert Cell coords to FPA coordinates */
 psCoord *
 psCoordCellToFPA(psCoord *out,          //!< Coordinates to return, or NULL
                  psCell *cell,          //!< Cell description
                  psCoord *coord         //!< Input cell coordinates
                  );
+psCoordCellToFPA(psCoord *out,          //!< Coordinates to return, or NULL
+                 const psCell *cell,    //!< Cell description
+                 const psCoord *coord   //!< Input cell coordinates
+                 );
 \end{verbatim}
 …
 fields:
 \begin{verbatim}
+/*
+ * A struct to define a single item of metadata
+ */
+/** 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 int id;                       //!< unique ID for this item
+    char *restrict name;                //!< Name of item
+    psMetaDataType type;                //!< type of this item
+    psMetaDataFlags flags;              //!< flags associated with 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)
+        float f;                        //!< floating value
+        int i;                          //!< integer value
+        void *v;                        //!< other type
+    } val;                              //!< value of metadata
+    char *comment;                      //!< optional comment ("", not NULL)
+    psDlist *restrict items;            //!< list of psMetaDataItems with the same name
 } psMetaDataItem;
 \end{verbatim}
 …
 \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
+/** Possible types of metadata. */
+typedef enum {                          //!< type of val is:
+    PS_META_ITEM_SET = 0,               //!< NULL; metadata is in psMetaDataType.items
+    PS_META_FLOAT,                      //!< float (.f)
+    PS_META_INT,                        //!< int (.i)
+    PS_META_STR,                        //!< string (.v)
+    PS_META_IMG,                        //!< image (.v)
+    PS_META_JPEG,                       //!< JPEG (.v)
+    PS_META_PNG,                        //!< PNG (.v)
+    PS_META_ASTROM,                     //!< astrometric coefficients (.v)
+    PS_META_UNKNOWN,                    //!< other (.v)
+    PS_META_NTYPE                       //!< Number of types; must be last
 } psMetaDataType;
 \end{verbatim}
 …
 \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
+PS_META_FLOAT & float & f & value, not pointer, is stored \\
+PS_META_INT & int & i &  value, not pointer, is stored \\
+PS_META_STR & string & v &  value, not pointer to original, is stored \\
+PS_META_IMG & psImage & v &  \\
+PS_META_JPEG & JPEG & v &  \\
+PS_META_PNG & PNG & v &  \\
+PS_META_ASTROM & psAstrom & v &  \\
+PS_META_UNKNOWN & other & v &  \\
+PS_META_NTYPE & (none) & & The number of types defined
 \end{tabular}
 \begin{caption}{Supported Metadata Types}
 …
 \begin{verbatim}
+/** A set of metadata */
 typedef struct {
     psDlist *list;                      // list of psMetaDataItem
     psHash *table;                      // hash table of the same metadata
+    psDlist *restrict list;             //!< list of psMetaDataItem
+    psHash *restrict table;             //!< hash table of the same metadata
 } psMetaDataSet;
 \end{verbatim}
 …
 \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
+/** Constructor */
+psMetaDataItem *psMetaDataItemAlloc(int typeFlags, //!< type of this piece of metadata + flags
+                                    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 in sprintf
+                                                      //!< format)
+                                    ... //!< possible arguments for name format
+    );
+/** Destructor */
+void psMetaDataItemFree(psMetaDataItem *ms //!< piece of metadata to destroy
+    );
+/** Constructor */
+psMetaDataSet *psMetaDataSetAlloc(void);   //!< make a new set of metadata
+/** Destructor */
+void psMetaDataSetFree(psMetaDataSet *ms //!< destroy a set of metadata
+    );
+/**** Utilities **********************************************************************/
+/// Add entry to the end of the metadata set
+psMetaDataItem *psMetaDataAppend(psMetaDataSet *restrict ms, //!< Metadata set to add to
+                                 psMetaDataItem *restrict item //!< Metatdata to add
+    );
+/// delete entry from the metadata set
+psMetaDataItem *psMetaDataRemove(psMetaDataSet *restrict ms, //!< Metadata set to delete from
+                                 const char *restrict key //!< Key to delete
+    );
+/// reset the iterator to the start of the list
+void psMetaDataSetIterator(psMetaDataSet *ms //!< Metadata set to set iterator for
+    );
+/// get the next entry in the sequence
+psMetaDataItem *psMetaDataGetNext(psMetaDataSet *restrict ms, //!< Metadata set to get from
+                                  const char *restrict match //!< Match this
+    );
+/// find the metadata with the specified key
+psMetaDataItem *psMetaDataLookup(const psMetaDataSet *restrict ms, //!< Metadata set to look up
+                                 const char *restrict key //!< Key to find
+    );
+/// print metadata item to the specified stream
+void psMetaDataItemPrint(FILE *fd,              //!< file descriptor to write to
+                         const psMetaDataItem *restrict ms, //!< item of metadata to print
+                         const char *prefix        //!< print this at the beginning of each line
+    );
 \end{verbatim}
 …
 \begin{verbatim}
 /** apply the coordinate transformation to the given coordinate */
+psCoord *psCoordXformApply (psCoordXform *frame, ///< coordinate transformation
+                            psCoord *coords) ///< input coordiate
+;
+psCoord *psCoordXformApply (psCoord *out, //!< Output coordinates, or NULL
+                            const psCoordXform *frame, ///< coordinate transformation
+                            const psCoord *coords ///< input coordiate
+    );
 \end{verbatim}
 \begin{verbatim}
 /** apply the optical distortion to the given coordinate, magnitude, color */
+psCoord *psDistortionApply (psDistortion *pattern, ///< optical distortion pattern
+psCoord *coords,                        ///< input coordinate
+float mag,                              ///< magnitude of object
+float color)                            ///< color of object
+;
+psCoord *psDistortionApply (psCoord *out, //!< Output coordinates, or NULL
+                            const psdistortion *pattern, ///< optical distortion pattern
+                            const psCoord *coords, ///< input coordinate
+                            float mag,  ///< magnitude of object
+                            float color ///< color of object
+    );
 \end{verbatim}
 …
 psCoord *
 psGetOffset(const psCoord *restrict position1, //!< Position 1
             const psCoord *restrict position2, //!< Position 2
             const char *type            //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
+            const psCoord *restrict position2, //!< Position 2
+            const char *type            //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
     );
 \end{verbatim}
 …
 psCoord *
 psApplyOffset(const psCoord *restrict position, //!< Position
               const psCoord *restrict offset, //!< Offset
               const char *type          //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
+              const psCoord *restrict offset, //!< Offset
+              const char *type          //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
     );
 \end{verbatim}
 …
 /** Get Sun Position */
 psCoord *
 psGetSunPos(float mjd)                  //!< MJD to get position for
+;
+psGetSunPos(float mjd                   //!< MJD to get position for
+    );
 \end{verbatim}
 …
 /** Get Moon position */
 psCoord *
 psGetMoonPos(float mjd,                 //!< MJD to get position for
              double latitude,           //!< Latitude for apparent position
              double longitude)          //!< Longitude for apparent position
+;
+psGetMoonPos(float mjd,                 //!< MJD to get position for
+             double latitude,           //!< Latitude for apparent position
+             double longitude           //!< Longitude for apparent position
+    );
 \end{verbatim}
 …
 /** Get Moon phase */
 float
 psGetMoonPhase(float mjd)               //!< MJD to get phase for
+;
+psGetMoonPhase(float mjd                //!< MJD to get phase for
+    );
 \end{verbatim}
 …
 /** Get Planet positions */
 psCoord *
 psGetSolarSystemPos(char *solarSystemObject, //!< Named S.S. object
                     float mjd)          //!< MJD to get position for
+;
+psGetSolarSystemPos(const char *solarSystemObject, //!< Named S.S. object
+                    float mjd           //!< MJD to get position for
+    );
 \end{verbatim}
 …
 /** Convert ICRS to Ecliptic */
 psCoord *
 psCoordinatesItoE(const psCoord *restrict coordinates) //!< ICRS coordinates to convert
+;
+psCoordinatesItoE(const psCoord *restrict coordinates //!< ICRS coordinates to convert
+    );
 \end{verbatim}
 …
 /** Convert Ecliptic to ICRS */
 psCoord *
 psCoordinatesEtoI(const psCoord *restrict coordinates) //!< Ecliptic coordinates to convert
+;
+psCoordinatesEtoI(const psCoord *restrict coordinates //!< Ecliptic coordinates to convert
+    );
 \end{verbatim}
 …
 /** Convert ICRS to Galactic */
 psCoord *
 psCoordinatesItoG(const psCoord *restrict coordinates) //!< ICRS coordinates to convert
+;
+psCoordinatesItoG(const psCoord *restrict coordinates //!< ICRS coordinates to convert
+    );
 \end{verbatim}
 …
 /** Convert Galactic to ICRS */
 psCoord *
 psCoordinatesGtoI(const psCoord *restrict coordinates) //!< Galactic coordinates to convert
+;
+psCoordinatesGtoI(const psCoord *restrict coordinates //!< Galactic coordinates to convert
+    );
 \end{verbatim}

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 296 for trunk/doc/pslib/psLibSDRS.tex

Legend:

trunk/doc/pslib/psLibSDRS.tex

Download in other formats: