Changeset 1092

Timestamp:

Jun 24, 2004, 5:10:26 PM (22 years ago)

Author:

eugene

Message:

resolved conflicts

File:

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

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.58 2004-06-22 18:48:22 rhl Exp $
+%%% $Id: psLibSDRS.tex,v 1.59 2004-06-25 03:10:26 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -10 +10 @@
 \project{Pan-STARRS Image Processing Pipeline}
 \organization{Institute for Astronomy}
-\version{01}
+\version{02}
 \docnumber{PSDC-430-007}
 % note the use of the docnumber & version number:
@@ -31 +31 @@
 00 & 2004 Apr 1  & First version, sent to MHPCC \\ \hline
 01 & 2004 May 19 & Extensive modifications, see appendix \\ \hline
+02 & 2004 Jun 22 & Incorporation of Bugzilla PRs (up to 69) \\ \hline
 \RevisionsEnd
 
@@ -36 +37 @@
 
 \DocumentsInternal
-PSCD-130-001  &   PS-1 Design Reference Mission \\ \hline
-PSCD-430-004  &   Pan-STARRS IPP C Code Conventions \\ \hline
-PSCD-430-005  &   Pan-STARRS IPP SRS \\ \hline
-PSCD-430-006  &   Pan-STARRS IPP ADD \\ \hline
-PSCD-430-008  &   Pan-STARRS IPP Architecture SDR \\ 
+PSDC-130-001  &   PS-1 Design Reference Mission \\ \hline
+PSDC-430-004  &   Pan-STARRS IPP C Code Conventions \\ \hline
+PSDC-430-005  &   Pan-STARRS IPP SRS \\ \hline
+PSDC-430-006  &   Pan-STARRS IPP ADD \\ \hline
+PSDC-430-008  &   Pan-STARRS IPP Architecture SDR \\ 
 \DocumentsExternal
 Posix Standard & Open Group Based Specifications Issue 6, IEEE Std 1003.1, 2003 \\
@@ -335 +336 @@
 routine registered by \code{psMemExhaustedSetCallback} (see
 \S\ref{secMemAdvanced}), and if still unsuccessful, call
-\code{psAbort()}.
+\code{psAbort()}.  The same behavior is true for constructors of rich
+structures, with names of the form \code{psFooAlloc}.
 
 Note that we have not specified an equivalent of the \code{calloc}
@@ -951 +953 @@
 may be registered with the PSLib error handler using the function:
 \begin{verbatim}
-void psErrorRegisterSet(const psErrorDescription *errors, int nerror);
+void psErrorRegister(const psErrorDescription *errors, int nerror);
 \end{verbatim}
 where the errors are represented internally as follows:
@@ -961 +963 @@
 \end{verbatim}
 PSLib internal errors must be registered with the function
-\code{psErrorRegisterSet}, which should be called as part of the
+\code{psErrorRegister}, which should be called as part of the
 program initialization to set up the error codes.  It is left to the
 external project to produce their own error registration functions
@@ -1290 +1292 @@
 
 \begin{verbatim}
-psList *psListAdd(psList *list, void *data, int where);
+bool psListAdd(psList *list, void *data, int where);
 \end{verbatim}
 Add an entry to the list with this function, which takes a pointer to
-the list and also returns a pointer to the list.  The returned pointer
-must be used as the value of \code{psList} may have changed.  The
-value of \code{where} specifies if the specified data item should be
-placed on the front of the list (\code{PS_DLIST_HEAD}), at the end of
-the list (\code{PS_DLIST_TAIL}), to add after (\code{PS_DLIST_NEXT})
-or before (\code{PS_DLIST_PREV}) the current element (specified by the
-iteration cursor), or an index that the new \code{data} should
-inhabit.
+the list and returns a boolean giving the success or failure of the
+operation. The value of \code{where} specifies if the specified data
+item should be placed on the front of the list (\code{PS_LIST_HEAD}),
+at the end of the list (\code{PS_LIST_TAIL}), to add after
+(\code{PS_LIST_NEXT}) or before (\code{PS_LIST_PREV}) the current
+element (specified by the iteration cursor), or an index that the new
+\code{data} should inhabit.
 
 \begin{verbatim}
@@ -1307 +1308 @@
 A data item may be retrieved from the list with this function.  The
 value of \code{which} may be the numerical index or it may be one of
-the special values: \code{PS_DLIST_HEAD}, \code{PS_DLIST_TAIL},
-\code{PS_DLIST_PREV}, and \code{PS_DLIST_NEXT}, all of which are
+the special values: \code{PS_LIST_HEAD}, \code{PS_LIST_TAIL},
+\code{PS_LIST_PREV}, and \code{PS_LIST_NEXT}, all of which are
 defined as negative integers, allowing \code{where} to also be the
 index of one of the data items.
 
 \begin{verbatim}
-void *psListRemove(psList *list, void *data, int which);
+bool psListRemove(psList *list, void *data, int which);
 \end{verbatim}
 A data item may be removed from the list with this function.  The
 value of \code{which} may be the numerical index or it may be one of
-the special values: \code{PS_DLIST_HEAD}, \code{PS_DLIST_TAIL},
-\code{PS_DLIST_PREV}, \code{PS_DLIST_UNKNOWN}, and
-\code{PS_DLIST_NEXT}, all of which are defined as negative integers.
-If the value of \code{which} is \code{PS_DLIST_UNKNOWN}, then the data
+the special values: \code{PS_LIST_HEAD}, \code{PS_LIST_TAIL},
+\code{PS_LIST_PREV}, \code{PS_LIST_UNKNOWN}, and
+\code{PS_LIST_NEXT}, all of which are defined as negative integers.
+If the value of \code{which} is \code{PS_LIST_UNKNOWN}, then the data
 item is identified by matching the pointer value with \code{void
-*data}.
+*data}.  The function returns a value of \code{true} if the operation
+was successfull, and \code{false} otherwise.
 
 All data items placed onto lists (\code{psListAdd}) must have their
 reference counters (section \ref{secMemRefcounter}) incremented.  When
 elements are removed from a list with \code{psListRemove}, they must
-have their reference counters decremented. The action of retrieving
-data from a list (with \code{psListGet}) must not affect their
-reference counter.
+have their reference counters decremented.  The action of retrieving
+data from a list (with \code{psListGet}) also increments the reference
+counter.
 
 \begin{verbatim}
@@ -1340 +1342 @@
 
 \begin{verbatim}
-psVector *psListToVector(psList *dlist);
-psList *psVectorToDlist(psVector *vector);
+psVector *psListToVector(psList *list);
+psList *psVectorToList(psVector *vector);
 \end{verbatim}
 These two functions are available to convert between the
@@ -1356 +1358 @@
 \code{iter} is provided by these functions.  The first of these
 functions uses the value of \code{where} to set the iteration cursor
-for the given list to the beginning \code{PS_DLIST_HEAD} or the end
-\code{PS_DLIST_TAIL} for the iterator specified by \code{which}.  The
+for the given list to the beginning \code{PS_LIST_HEAD} or the end
+\code{PS_LIST_TAIL} for the iterator specified by \code{which}.  The
 next two functions move the iteration cursor forward or backwards,
 returning the data item from the resulting list entry, or returning
@@ -1426 +1428 @@
 A data item may be added to the hash table with the function:
 \begin{verbatim}
-void *psHashInsert(psHash *table, char *key, void *data, void (*itemFree)(void *item));
+bool psHashAdd(psHash *table, char *key, void *data);
 \end{verbatim}
 In this function, the value of the string \code{key} is used to
 construct the hash value, find the appropriate bucket set, and add the
-new element \code{data} to the list.  The element destructor,
-\code{itemFree}, is provided to destroy an existing element with the
-same value of \code{key}.  The routine \code{psHashInsert} must
-provide a non-NULL \code{itemFree} argument if it wishes to change the
-value for 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}.
+new element \code{data} to the list.  An exiting element with the same
+value of \code{key} is destroyed using its registered destructor
+(\code{psMemBlock}). The return value of the function is a boolean
+defining the success or failure of the operation.
 
 The data associated with a given key may be found with the function:
@@ -1449 +1447 @@
 void *psHashRemove(psHash *table, char *key);
 \end{verbatim}
-the return value of which is the value at the key that is removed (or
-NULL if no match is found).
+The function returns a value of \code{true} if the operation was
+successfull, and \code{false} otherwise.
 
 A complete hash table may be freed by calling:
@@ -1616 +1614 @@
 
 \begin{verbatim}
-psStats *psVectorStats(const psVector *restrict in, 
+psStats *psVectorStats(psStats *stats,
+                       const psVector *restrict in, 
                        const psVector *restrict mask, 
-                       unsigned int maskVal, 
-                       psStats *stats);
-\end{verbatim}
-\tbd{psStats *psVectorStats (psStats *stats, psVector *in, psVector *mask, int maskVal);}
+                       unsigned int maskVal);
+\end{verbatim}
 %
 This function takes the input data in \code{in} (with optional masking
@@ -1630 +1627 @@
 used to specify a value range for which the statistics are calculated.
 \code{binsize} specifies a choice for the robust statistics histogram
-bin size.  If these are to be used, the user should set the
+bin size.  If these are to be used, the user must set the
 corresponding \code{options} bits \code{PS_STAT_USE_RANGE} or
 \code{PS_STAT_USE_BINSIZE}.  \code{clipSigma} specifies the number of
@@ -1643 +1640 @@
 \code{PS_STAT_ROBUST_FOR_SAMPLE} in \code{options} must be set in this
 case.  The cutoff for this decision must be made on the basis of the
-value in \code{sampleLimit},which should have a default of \tbd{3e5}.
-Default input field values must be set by the \code{psStats}
+value in \code{sampleLimit}, which should have a default of $3 \times
+10^{5}$.  Default input field values must be set by the \code{psStats}
 constructor.  The input vector may be of type \code{psU8},
 \code{psU16}, \code{psF32}, \code{psF64}; the mask must be of type
@@ -1765 +1762 @@
 structure.  
 \begin{verbatim}
-psHistogram *psHistogramVector(psHistogram *restrict out, const psVector *restrict in);
-\end{verbatim}
-\tbd{psHistogram *psHistogramVector (psHistogram *out, psVector *in);}
+psHistogram *psVectorHistogram(psHistogram *out, 
+                               const psVector *restrict in,
+                               const psVector *restrict mask,
+                               unsigned int maskVal);
+\end{verbatim}
 The input vector may be of types \code{psU8, psU16, psF32, psF64}.
 
@@ -1987 +1986 @@
                        int x, int y, int nx, int ny, 
                        int direction, const psStats *stats);
+typedef enum {
+    PS_CUT_X_POS;
+    PS_CUT_X_NEG;
+    PS_CUT_Y_POS;
+    PS_CUT_Y_NEG;
+} psImageCutDirection;
 \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{stats}.  Only one of the statistics choices may be
-specified, otherwise the function must return an error.  This function
-must be defined for the following types: \code{psU8}, \code{psU16},
-\code{psF32}, \code{psF64}.
+\code{PS_CUT_X_POS}, 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{stats}.  Only one of the statistics
+choices may be specified, otherwise the function must return an error.
+This function must be defined for the following types: \code{psU8},
+\code{psU16}, \code{psF32}, \code{psF64}.
 
 \begin{verbatim}
@@ -2012 +2017 @@
 represents 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{stats}.  Only one of the statistics choices may be
-specified, otherwise the function must return an error.  This function
-must be defined for the following types: \code{psU8}, \code{psU16},
-\code{psF32}, \code{psF64}
+direction.  The specific algorithm which must be used is described in
+the PSLib ADD (PSDC-430-006).  The statistic used to derive the output
+vector value is specified by \code{stats}.  Only one of the statistics
+choices may be specified, otherwise the function must return an error.
+This function must be defined for the following types: \code{psU8},
+\code{psU16}, \code{psF32}, \code{psF64}
 
 \begin{verbatim}
@@ -2022 +2028 @@
                            const psVector *radii, const psStats *stats);
 \end{verbatim}
-Extract radial annuli data to a vector.  A vector is constructed where
+Extract radial region 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 annuli.  The annuli are centered on
-the image pixel coordinate \code{x,y}, and have width \code{dr}.  The
-number of annuli is $radius / dr$.  The statistic used to derive the
-output vector value is specified by \code{stats}.  Only one of the
-statistics choices may be specified, otherwise the function must
-return an error.  This function must be defined for the following
-types: \code{psU8}, \code{psU16}, \code{psF32}, \code{psF64}.
+which land within one of a sequence of radii.  The radii are centered
+on the image pixel coordinate \code{x,y}, and are defined by the
+sequence of values in the vector \code{radii}.  The specific algorithm
+which must be used is described in the PSLib ADD (PSDC-430-006).  The
+statistic used to derive the output vector value is specified by
+\code{stats}.  Only one of the statistics choices may be specified,
+otherwise the function must return an error.  This function must be
+defined for the following types: \code{psU8}, \code{psU16},
+\code{psF32}, \code{psF64}.
 
 \subsubsection{Image Geometry Manipulation}
@@ -2051 +2059 @@
 
 \begin{verbatim}
-psImage *psImageRotate(psImage *out, const psImage *input, float angle);
+psImage *psImageRotate(psImage *out, const psImage *input, float
+angle, float exposed);
 \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 to \tbd{value}.  The center of rotation is always
-the center pixel of the image.  The rotation is specified in the sense
-that a positive angle is an anti-clockwise rotation.  This function
-must be defined for the following types: \code{psU8}, \code{psU16},
-\code{psS8}, \code{psS16}, \code{psF32}, \code{psF64}, \code{psC32},
-\code{psC64}.
+pixels should be set to \code{exposed}.  The center of rotation is
+always the center pixel of the image.  The rotation is specified in
+the sense that a positive angle is an anti-clockwise rotation.  This
+function must be defined for the following types: \code{psU8},
+\code{psU16}, \code{psS8}, \code{psS16}, \code{psF32}, \code{psF64},
+\code{psC32}, \code{psC64}.
 
 \begin{verbatim}
@@ -2090 +2099 @@
 
 \begin{verbatim}
-psStats *psImageGetStats(psStats *stats, const psImage *input);
-\end{verbatim}
-\tbd{psStats *psImageStats(psStats *stats, psImage *in, psImage *mask, int maskVal);}
+psStats *psImageStats(psStats *stats, 
+                      const psImage *restrict in,
+                      const psImage *restrict mask,
+                      unsigned int maskVal);
+\end{verbatim}
 Determine statistics for image (or subimage).  The statistics to be
-determined are specified by \code{stats}.  This function must be
-defined for the following types: \code{psU8}, \code{psU16},
-\code{psF32}, \code{psF64}.
-
-\begin{verbatim}
-psHistogram *psImageHistogram(psHistogram *hist, const psImage *input);
-\end{verbatim}
-\tbd{psHistogram *psImageHistogram(psHistogram *out, psImage *in, psImage *mask, int maskVal);}
+determined are specified by \code{stats}.  The \code{mask} allows
+pixels to be excluded if their corresponding mask pixel value matches
+the value of \code{maskVal}.  This function must be defined for the
+following types: \code{psU8}, \code{psU16}, \code{psF32},
+\code{psF64}.
+
+\begin{verbatim}
+psHistogram *psImageHistogram(psHistogram *out, 
+                              const psImage *restrict in, 
+                              const psImage *restrict mask, 
+                              unsigned int maskVal);
+\end{verbatim}
 Construct a histogram from an image (or subimage).  The histogram to
 generate is specified by \code{psHistogram hist} (see
@@ -2177 +2192 @@
 number of clipped pixels.  This function must be defined for the
 following types: \code{psU8}, \code{psU16}, \code{psS8}, \code{psS16},
-\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}.
+\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}.  The arguments
+(\code{min}, \code{max}, etc) must be cast to the appropriate types to
+match the image data.  If the input parameters \code{vmin} or
+\code{vmax} are out of bounds for the image pixel type, the function
+must raise an error.  It is not an error for \code{min} or \code{max}
+to be out of range.  In the case of complex numbers, the input
+parameters \code{min} and \code{max} must be compared against the
+absolute value of the pixel values.  The values to which complex image
+data are clipped employ the provided value for the real component and
+0.0 for the imaginary component.
 
 \begin{verbatim}
@@ -2186 +2210 @@
 Returns the number of clipped pixels.  This function must be defined
 for the following types: \code{psF32}, \code{psF64}, \code{psC32},
-\code{psC64}.
+\code{psC64}.  In the case of complex values, if either the real or
+imaginary part have the value \code{NaN}, then that component will be
+set to the specified value.
 
 \begin{verbatim}
@@ -2213 +2239 @@
 images, e.g.\ dividing one image by another, subtracting a vector
 from an image, etc.  Both binary operations and unary operations are
-required.  To avoid the burden of memorizing a ton of APIs, we specify
+required.  To avoid the burden of memorizing a plethora of APIs, we specify
 two generic APIs for the binary and unary operations.
 
@@ -2227 +2253 @@
 expected that the implementation of these functions will employ
 pre-processor macros to perform the onerous task of creating the
-loops.  Also note that \code{psVector} is equivalent to
-\code{psVector}.  An attempt to perform an arithmetic operation on
-an object of dimension \code{PS_DIMEN_OTHER} should produce an error.
+loops.  An attempt to perform an arithmetic operation on an object of
+dimension \code{PS_DIMEN_OTHER} should produce an error.  Operations
+between data structures with different types (e.g., \code{psS32} and
+\code{psF32}) are not allowed and must raise an error (it is the
+responsibility of calling functions to perform type conversions).
+Operations between data structures with incompatible sizes are not
+allowed.  However, operations between data elements of different rank
+(scalar, vector, image) are allowed, and defined below.
 
 Binary operations between an image and a vector have a potential
@@ -2236 +2267 @@
 (\code{PS_DIMEN_VECTOR}), and a ``transposed vector''
 (\code{PS_DIMEN_TRANSV}).  We specify that a ``vector'', when involved
-in binary operations on an image, acts on the rows, while a
-``transposed vector'' in the same context acts on the columns.
+in binary operations on an image, acts on all rows of the image, while
+a ``transposed vector'' in the same context acts on all columns.
 Vectors, when created, will be created as ``vectors'', but may be
 converted to ``transposed vectors'' using the following function:
@@ -2688 +2719 @@
 Certain metadata names (such as the FITS keywords \code{COMMENT} and
 \code{HISTORY} in a FITS header) may be repeated with different
-values.  The \code{psMetadataAppend} routine is required to check that
+values.  The \code{psMetadataAdd} 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 must be added
@@ -2738 +2769 @@
 item may be added by appending a \code{psMetadataItem} which has
 already been created; and secondly by directly providing the data to
-be appended.  In both cases, the \code{psMetadataItem} that is
-appended to the metadata is returned.  The second function,
-\code{psMetadataAppend} takes a pointer or value which is interpretted
-by the \code{va_list} operators in the function.
-%
-\begin{verbatim}
-psMetadataItem *psMetadataAppendItem(psMetadata *restrict md, 
+be appended.  In both cases, the return value defines the success
+(\code{true}) or failure of the operation.  The second function,
+\code{psMetadataAdd} takes a pointer or value which is interpretted
+by the \code{va_list} operators in the function.  Both functions take
+an parameter \code{where} which specifies where in the list to place
+the element, following the conventions for the \code{psList}.  Care
+should be taken not to leak memory when appending an item for which
+the key already exists in the metadata (and is not
+\code{PS_META_NON_UNIQUE}).
+%
+\begin{verbatim}
+bool psMetadataAddItem(psMetadata *restrict md, int where,
                                      psMetadataItem *restrict item);
-psMetadataItem *psMetadataAppend(psMetadata *restrict md, const char *name, 
-                                 int format, const char *comment, ...);
-\end{verbatim}
-
-Items may be removed from the metadata by specifying a key.  If the
-key matches a metadata item, the item is removed from the metadata and
-returned; otherwise, \code{NULL} is returned.  If the key is not
-unique, then \emph{all} items corresponding to the key are removed,
-and the first item is returned.  Care should be taken not to leak
-memory when appending an item for which the key already exists in the
-metadata (and is not \code{PS_META_NON_UNIQUE}).
-%
-\begin{verbatim}
-psMetadataItem *psMetadataRemove(psMetadata *restrict md, const char *restrict key);
-\end{verbatim}
-
-The metadata may be iterated over by (re-)setting the iterator for the
-appropriate \code{psMetadata}, and getting the next item.
-\code{psMetadataGetNext} has the ability to match the beginning of a
-key, e.g., if the user only wants to iterate through
+bool psMetadataAdd(psMetadata *restrict md, int where, 
+                                 const char *name, int format, const char *comment, ...);
+\end{verbatim}
+
+Items may be removed from the metadata by specifying a key or a
+location in the list.  If the value of \code{name} is \code{NULL}, the
+value of \code{where} is used.  If the value of \code{name} is not
+\code{NULL}, then \code{where} must be set to \code{PS_LIST_UNKNOWN}.
+If the key matches a metadata item, the item is removed from the
+metadata and \code{true} is returned; otherwise, \code{false} is
+returned.  If the key is not unique, then \emph{all} items
+corresponding to the key are removed, and \code{true} is returned.
+%
+\begin{verbatim}
+bool psMetadataRemove(psMetadata *restrict md, int where, const char *restrict key);
+\end{verbatim}
+
+Items may be found within the metadata by providing a key.  In the
+event that the key is non-unique, the first item is returned.
+\begin{verbatim}
+psMetadataItem *psMetadataLookup(const psMetadata *restrict md, 
+                                 const char *restrict key);
+\end{verbatim}
+
+Items may be retrieved from the metadata by their entry position.  The
+value of which specifies the desired entry in the fashion of
+\code{psList}.
+\begin{verbatim}
+psMetadataItem *psMetadataGet(const psMetadata *restrict md, int which);
+\end{verbatim}
+
+The metadata may be iterated over by (re-)setting the iterator to a
+location in the \code{psMetadata} list, and getting the previous or
+next item.  \code{psMetadataGetNext} has the ability to match the
+beginning of a key, e.g., if the user only wants to iterate through
 \code{IPP.machines.sky} and doesn't want to bother with
 \code{IPP.machines.detector}.  The iterator should iterate over every
-item of metadata --- even those that are non-unique.
-\begin{verbatim}
-void psMetadataSetIterator(psMetadata *md);
-psMetadataItem *psMetadataGetNext(psMetadata *restrict md, const char *restrict match);
-\end{verbatim}
-
-Items may be found within the metadata by providing a key.  In the
-event that the key is non-unique, the first item is returned.
-\begin{verbatim}
-psMetadataItem *psMetadataLookup(const psMetadata *restrict md, 
-                                 const char *restrict key);
+item of metadata --- even those that are non-unique.  The value
+\code{which} specifies the iterator to be used.  In setting the
+iterator, the position of the iterator is defined by \code{where},
+which follows the conventions of the \code{psList} iterators.
+\begin{verbatim}
+void psMetadataSetIterator(psMetadata *md, int where);
+psMetadataItem *psMetadataGetNext(psMetadata *restrict md, const char *restrict match, int which);
+psMetadataItem *psMetadataGetPrevious(psMetadata *restrict md, const char *restrict match, int which);
 \end{verbatim}
 
@@ -2983 +3031 @@
 The following functions simply return the appropriate
 \code{psSphereTransform} to convert between predefined spherical
-coordinate systems (i.e., {\bf I}CRS, {\bf E}cliptic and {\bf
-G}alactic).
-%
-\begin{verbatim}
-psSphereTransform *psSphereTransformItoE(void);
-psSphereTransform *psSphereTransformEtoI(void);
-psSphereTransform *psSphereTransformItoG(void);
-psSphereTransform *psSphereTransformGtoI(void);
+coordinate systems (i.e., ICRS, Ecliptic and Galactic).
+%
+\begin{verbatim}
+psSphereTransform *psSphereTransformICRSToEcliptic(void);
+psSphereTransform *psSphereTransformEclipticToICRS(void);
+psSphereTransform *psSphereTransformICRSToGalactic(void);
+psSphereTransform *psSphereTransformGalacticToICRS(void);
 \end{verbatim}
 
@@ -3438 +3485 @@
 
 \begin{verbatim}
-psPlane *psCoordCelltoChip (psPlane *out, const psPlane *in, const psCell *cell);
+psPlane *psCoordCellToChip (psPlane *out, const psPlane *in, const psCell *cell);
 \end{verbatim}
 which converts coordindates \code{in} on the specified \code{cell} to
@@ -3444 +3491 @@
 
 \begin{verbatim}
-psPlane *psCoordChiptoFPA (psPlane *out, const psPlane *in, const psChip *chip);
+psPlane *psCoordChipToFPA (psPlane *out, const psPlane *in, const psChip *chip);
 \end{verbatim}
 which converts the coordinates \code{in} on the specified \code{chip}
@@ -3457 +3504 @@
 
 \begin{verbatim}
-psSphere *psCoordTPtoSky(psSphere *out, const psPlane *in, const psGrommit *grommit);
+psSphere *psCoordTPToSky(psSphere *out, const psPlane *in, const psGrommit *grommit);
 \end{verbatim}
 which converts the tangent plane coordinates \code{in} to (RA,Dec) on
@@ -3481 +3528 @@
 
 \begin{verbatim}
-psSphere *psCoordCellToSkyQD(psSphere *out, const psPlane *in, const psCell *cell);
+psSphere *psCoordCellToSkyQuick(psSphere *out, const psPlane *in, const psCell *cell);
 \end{verbatim}
 which uses the 'quick-and-dirty' transformation to convert coordinates
@@ -3500 +3547 @@
 
 \begin{verbatim}
-psPlane *psCoordTPtoFPA(psPlane *out, const psPlane *in, const psFPA *fpa);
+psPlane *psCoordTPToFPA(psPlane *out, const psPlane *in, const psFPA *fpa);
 \end{verbatim}
 which converts the tangent plane coordinates \code{in} to focal plane coordinates.
 
 \begin{verbatim}
-psPlane *psCoordFPAtoChip (psPlane *out, const psPlane *in, const psChip *chip);
+psPlane *psCoordFPAToChip (psPlane *out, const psPlane *in, const psChip *chip);
 \end{verbatim}
 which converts the specified FPA coordinates \code{in} to the
@@ -3514 +3561 @@
 
 \begin{verbatim}
-psPlane *psCoordChiptoCell (psPlane *out, const psPlane *in, const psCell *cell);
+psPlane *psCoordChipToCell (psPlane *out, const psPlane *in, const psCell *cell);
 \end{verbatim}
 which converts the specified Chip coordinate \code{in} to the
@@ -3530 +3577 @@
 
 \begin{verbatim}
-psPlane *psCoordSkyToCellQD(psPlane *out, const psSphere *in, psCell *cell);
+psPlane *psCoordSkyToCellQuick(psPlane *out, const psSphere *in, psCell *cell);
 \end{verbatim}
 which directly converts (RA,Dec) \code{in} to coordinates on the
@@ -3700 +3747 @@
     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));
+        psMetadataAdd(ms, psMetadataItemAlloc(PS_META_INT, &i, NULL, "const.%d", i));
+        psMetadataAdd(ms, psMetadataItemAlloc(PS_META_FLOAT, &sqrti, "square root", "const.sqrt%d", i));
     }
-    psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR, "Bonjour", "French", "lang.hello"));
+    psMetadataAdd(ms, psMetadataItemAlloc(PS_META_STR, "Bonjour", "French", "lang.hello"));
     /*
      * Remove a key
@@ -3740 +3787 @@
 
 \begin{verbatim}
-    psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
+    psMetadataAdd(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
                                            "Bonjour", "French", "lang.hello"));
-    psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
+    psMetadataAdd(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
                                            "Aloha", "Hawaiian", "lang.hello"));
-    psMetadataAppend(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
+    psMetadataAdd(ms, psMetadataItemAlloc(PS_META_STR | PS_META_NON_UNIQUE,
                                            "Good Morning", "English", "lang.hello"));
     /*