IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Changeset 4021


Ignore:
Timestamp:
May 24, 2005, 1:44:45 PM (21 years ago)
Author:
jhoblitt
Message:

convert verbatim environments that contain function prototypes & datatypes to be either a prototype block or a datatype environment

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/pslib/psLibSDRS.tex

    r3992 r4021  
    1 %%% $Id: psLibSDRS.tex,v 1.231 2005-05-20 00:43:57 price Exp $
     1%%% $Id: psLibSDRS.tex,v 1.232 2005-05-24 23:44:45 jhoblitt Exp $
    22\documentclass[panstarrs,spec]{panstarrs}
    33
    … …  
    195195as determined from CVS tags.
    196196
    197 \begin{verbatim}
     197\begin{prototype}
    198198const char *psLibVersion(void);
    199 \end{verbatim}
     199\end{prototype}
    200200
    201201\subsection{Initialization}
    … …  
    211211
    212212The prototype is:
    213 \begin{verbatim}
     213\begin{prototype}
    214214void psLibInit(const char *timeConfig);
    215 \end{verbatim}
     215\end{prototype}
    216216
    217217\code{timeConfig} specifies the filename of the configuration file
    … …  
    220220\subsection{Finalization}
    221221
    222 \begin{verbatim}
     222\begin{prototype}
    223223void psFinalize(void);
    224 \end{verbatim}
     224\end{prototype}
    225225
    226226\code{psLibFinalize} shall free memory that was allocated by
    … …  
    327327follows:
    328328%
    329 \filbreak
    330 \begin{verbatim}
     329%\filbreak
     330\begin{datatype}
    331331typedef struct {
    332332    const void* startblock;             ///< initialised to p_psMEMMAGIC
    … …  
    347347typedef unsigned long psMemoryId;
    348348typedef unsigned long psReferenceCount;
    349 \end{verbatim}
     349\end{datatype}
    350350%
    351351The PSLib memory management system must maintain the collection of
    … …  
    421421blocks:
    422422%
    423 \begin{verbatim}
     423\begin{prototype}
    424424void *psAlloc(size_t size);
    425425void *psRealloc(void *ptr, size_t size);
    426426void *psFree(void *ptr);
    427 \end{verbatim}
     427\end{prototype}
    428428%
    429429From the user's perspective, the functions \code{psAlloc},
    … …  
    433433preprocessor macros which call the following private functions:
    434434%
    435 \begin{verbatim}
     435\begin{prototype}
    436436void *p_psAlloc(size_t size, const char *file, int line);
    437437void *p_psRealloc(void *ptr, size_t size, const char *file, int line);
    438438void p_psFree(void *ptr, const char *file, int line);
    439 \end{verbatim}
     439\end{prototype}
    440440%
    441441In these function calls, \code{size} is the number of bytes required
    … …  
    480480usually insufficient.
    481481
    482 \begin{verbatim}
     482\begin{prototype}
    483483void psMemSetDeallocator(void* ptr, psFreeFcn freeFcn);     
    484484psFreeFcn psMemGetDeallocator(void* ptr);     
    485 \end{verbatim}
     485\end{prototype}
    486486
    487487A free function handles any deallocation procedures of an object
    … …  
    551551following form:
    552552%
    553 \begin{verbatim}
     553\begin{datatype}
    554554typedef void (*psMemExhaustedCallback)(size_t size);
     555\end{datatype}
     556
     557\begin{prototype}
    555558psMemExhaustedCallback psMemExhaustedCallbackSet(psMemExhaustedCallback func);
    556 \end{verbatim}
     559\end{prototype}
    557560%
    558561The callback function is called with the attempted size and is
    … …  
    569572has the following form:
    570573%
    571 \begin{verbatim}
     574\begin{datatype}
    572575typedef void (*psMemProblemCallback)(psMemBlock *ptr, char *file, int lineno);
     576\end{datatype}
     577
     578\begin{prototype}
    573579psMemProblemCallback psMemProblemCallbackSet(psMemProblemCallback func);
    574 \end{verbatim}
     580\end{prototype}
    575581%
    576582This callback may be used to report the error and other status
    … …  
    595601following two functions:
    596602%
    597 \begin{verbatim}
     603\begin{prototype}
    598604psMemoryId psMemAllocateCallbackSetID(psMemoryId id);
    599605psMemoryId psMemFreeCallbackSetID(psMemoryId id);
    600 \end{verbatim}
     606\end{prototype}
    601607%
    602608The corresponding callbacks have the following form:
    603609%
    604 \begin{verbatim}
     610\begin{datatype}
    605611typedef psMemoryId (*psMemAllocateCallback)(const psMemBlock *ptr);
     612\end{datatype}
     613
     614\begin{prototype}
    606615psMemAllocateCallback psMemAllocateCallbackSet(psMemAllocateCallback func);
     616\end{prototype}
     617
     618\begin{datatype}
    607619typedef psMemoryId (*psMemFreeCallback)(const psMemBlock *ptr);
     620\end{datatype}
     621
     622\begin{prototype}
    608623psMemFreeCallback psMemFreeCallbackSet(psMemFreeCallback func);
    609624psMemoryId psMemGetId(void);
    610 \end{verbatim}
     625\end{prototype}
    611626%
    612627The callback functions are called with a pointer to the corresponding
    … …  
    633648this part of the memory API are shown below.
    634649%
    635 \begin{verbatim}
     650\begin{prototype}
    636651int psMemCheckLeaks(psMemoryId id0, psMemBlock ***array, FILE *fd, bool persistence);
    637652int psMemCheckCorruption(bool abort_on_error);
    638 \end{verbatim}
     653\end{prototype}
    639654%
    640655The routine \code{psMemCheckLeaks} may be used to check for memory
    … …  
    687702APIs are:
    688703%
    689 \begin{verbatim}
     704\begin{prototype}
    690705psReferenceCount psMemGetRefCounter(const void *vptr);
    691706void *psMemIncrRefCounter(const void *vptr);
    692707void *psMemDecrRefCounter(void *vptr);
    693 \end{verbatim}
     708\end{prototype}
    694709%
    695710The functions all take a pointer to the start of a user block of
    … …  
    812827its trace level and facility, is:
    813828%
    814 \begin{verbatim}
     829\begin{prototype}
    815830void psTrace(const char *facil, int myLevel,...);
    816 \end{verbatim}
     831\end{prototype}
    817832%
    818833where the last argument is a printf-style formatting code and possible
    … …  
    826841following function:
    827842%
    828 \begin{verbatim}
     843\begin{prototype}
    829844int psTraceSetLevel(const char *facil, int level);
    830 \end{verbatim}
     845\end{prototype}
    831846%
    832847where \code{level} specifies the current trace level for the facility
    … …  
    834849facility may be determined by the function:
    835850%
    836 \begin{verbatim}
     851\begin{prototype}
    837852int psTraceGetLevel(const char *facil);
    838 \end{verbatim}
     853\end{prototype}
    839854%
    840855which returns the trace level of the named facility following the
    … …  
    849864levels of all facilities:
    850865%
    851 \begin{verbatim}
     866\begin{prototype}
    852867void psTracePrintLevels(void);
    853 \end{verbatim}. 
     868\end{prototype}
    854869%
    855870This function prints the hierarchy of trace facilities along with the
    … …  
    914929The trace may optionally be written to a file on specifying a filename
    915930with \code{psTraceSetDestination}:
    916 \begin{verbatim}
     931\begin{prototype}
    917932void psTraceSetDestination(FILE *fp);
    918 \end{verbatim}
     933\end{prototype}
    919934If the \code{fp} is \code{NULL}, then the trace is sent to standard
    920935output, otherwise it is sent to the specified file pointer.
    … …  
    940955A log message is placed in the code with the command:
    941956%
    942 \begin{verbatim}
     957\begin{prototype}
    943958void psLogMsg(const char *name, int myLevel, const char *fmt, ...);
    944959void psLogMsgV(const char *name, int myLevel, const char *fmt, va_list ap);
    945 \end{verbatim}
     960\end{prototype}
    946961where \code{name} is a word to describe the source of the message,
    947962\code{myLevel} is the severity level of this message, and \code{fmt}
    … …  
    954969the first 4 levels are associated with symbolic names:
    955970%
    956 \begin{verbatim}
     971\begin{datatype}
    957972enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO };
    958 \end{verbatim}
     973\end{datatype}
    959974%
    960975
    … …  
    962977above which log messages are ignored, using the function:
    963978%
    964 \begin{verbatim}
     979\begin{prototype}
    965980int psLogSetLevel(int level);           
    966 \end{verbatim}
     981\end{prototype}
    967982%
    968983This function returns the previous log level.  A specific message
    … …  
    974989Log messages are sent to the destination most recently set using:
    975990%
    976 \begin{verbatim}
     991\begin{prototype}
    977992bool psLogSetDestination(const char *dest);     
    978 \end{verbatim}
     993\end{prototype}
    979994%
    980995The destination string consists of a URL in the form
    … …  
    9901005The output format is controlled with the function:
    9911006%
    992 \begin{verbatim}
     1007\begin{prototype}
    9931008bool psLogSetFormat(const char *fmt);
    994 \end{verbatim}
     1009\end{prototype}
    9951010%
    9961011which expects a string consisting of the letters \code{H} (host),
    … …  
    10431058\code{psError} prints an error message and doesn't abort, but instead
    10441059returns the error code.
    1045 \begin{verbatim}
     1060\begin{prototype}
    10461061psErrorCode p_psError(const char *file, int lineno, const char *func, psErrorCode code, bool new,
    10471062                      const char *fmt, ...);
     1063\end{prototype}
     1064\begin{datatype}
    10481065#define psError(code, new, fmt, ...) psError(__FILE__, __LINE__, __func__, code, new, fmt, __VA_ARGS__)
    1049 \end{verbatim}
     1066\end{datatype}
    10501067
    10511068\code{psError} is a macro definition that allows the filename, line
    … …  
    10661083
    10671084The errors on the error stack are defined as the following:
    1068 \begin{verbatim}
     1085\begin{datatype}
    10691086typedef struct {
    10701087    char *name;                         ///< category of code that caused the error
    … …  
    10721089    char *msg;                          ///< the message associated with the error
    10731090} psErr;
    1074 \end{verbatim}
     1091\end{datatype}
    10751092
    10761093The last error reported is available from \code{psErrorLast}; if no
    … …  
    10811098The error stack may be completely cleared with \code{psErrorClear}.
    10821099%
    1083 \begin{verbatim}
     1100\begin{prototype}
    10841101unsigned int psErrorGetStackSize(void);
    10851102const psErr *psErrorGet(int which);
    10861103const psErr *psErrorLast(void);
    10871104void psErrorClear(void);
    1088 \end{verbatim}
     1105\end{prototype}
    10891106
    10901107\code{psErrorGetStackSize} shall return the number of errors on the
    … …  
    10991116\code{psErrorStackPrintV} must not invoke \code{va_end}.
    11001117%
    1101 \begin{verbatim}
     1118\begin{prototype}
    11021119void psErrorStackPrint(FILE *fd, const char *fmt, ...);
    11031120void psErrorStackPrintV(FILE *fd, const char *fmt, va_list va);
    1104 \end{verbatim}
     1121\end{prototype}
    11051122
    11061123Any \code{errorCode}s less then or equal to \code{PS_ERR_BASE} (see
    … …  
    11111128The routine \code{psErrorCodeString} returns the string associated
    11121129with an error code:
    1113 \begin{verbatim}
     1130\begin{prototype}
    11141131const char *psErrorCodeString(psErrorCode code);
    1115 \end{verbatim}
     1132\end{prototype}
    11161133
    11171134\subsubsection{Error Codes}
    … …  
    11281145error codes and associated message strings.  An array of error codes
    11291146may be registered with the PSLib error handler using the function:
    1130 \begin{verbatim}
     1147\begin{prototype}
    11311148void psErrorRegister(const psErrorDescription *errors, int nerror);
    1132 \end{verbatim}
     1149\end{prototype}
    11331150where the errors are represented internally as follows:
    1134 \begin{verbatim}
     1151\begin{datatype}
    11351152typedef struct {
    11361153    psErrorCode code;                  ///< An error code
    11371154    const char *descrip;               ///< the associated description
    11381155} psErrorDescription;
    1139 \end{verbatim}
     1156\end{datatype}
    11401157PSLib internal errors must be registered with the function
    11411158\code{psErrorRegister}, which should be called as part of the
    … …  
    11791196enumerated type \code{psErrorCode} with elements \code{PS_ERR_NAME}
    11801197and values as specified in \file{psErrorCodes.dat}, e.g.
    1181 \begin{verbatim}
     1198\begin{datatype}
    11821199#if !defined(PS_ERROR_CODES_H)
    11831200#define PS_ERROR_CODES_H
    … …  
    11931210} psErrorCode;
    11941211#endif
    1195 \end{verbatim}
     1212\end{datatype}
    11961213
    11971214Any \code{errorCode}s less then or equal to \code{PS_ERR_BASE} must be
    … …  
    12081225\code{PS_LOG_ABORT}, and then call \code{abort}.
    12091226
    1210 \begin{verbatim}
     1227\begin{prototype}
    12111228void psAbort(const char *name, const char *fmt,...);
    1212 \end{verbatim}
     1229\end{prototype}
    12131230
    12141231%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    … …  
    12601277Supported data types must be defined by a structure in which
    12611278the first element is always of type \code{psType}:
    1262 \begin{verbatim}
     1279\begin{datatype}
    12631280typedef struct {
    12641281    psDimen dimen;                      ///< The dimensionality
    12651282    psElemType type;                    ///< The type
    12661283} psType;
    1267 \end{verbatim}
     1284\end{datatype}
    12681285where \code{psDimen dimen} defines the dimensionality of the data and
    12691286\code{psElemType type} defines the data type of each element.  These
    12701287two variable types are defined as:
    1271 \begin{verbatim}
     1288\begin{datatype}
    12721289typedef enum {
    12731290    PS_DIMEN_SCALAR,                    ///< Scalar
    … …  
    12771294    PS_DIMEN_OTHER                      ///< Not supported for arithmetic
    12781295} psDimen;
    1279 \end{verbatim}
     1296\end{datatype}
    12801297and
    1281 \begin{verbatim}
     1298\begin{datatype}
    12821299typedef enum {
    12831300    PS_TYPE_S8,                         ///< Character
    … …  
    12951312    PS_TYPE_BOOL                        ///< Boolean value
    12961313} psElemType;
    1297 \end{verbatim}
     1314\end{datatype}
    12981315We discuss the application of \code{psType} in more detail in
    12991316section~\ref{sec:arithmetic}. 
    … …  
    13051322which interpret the data type from the structure when deciding how to
    13061323perform an operation.  The basic scalar structure is:
    1307 \begin{verbatim}
     1324\begin{datatype}
    13081325typedef struct {
    13091326    psType type;                        ///< data type information
    … …  
    13191336    } data;
    13201337} psScalar;
    1321 \end{verbatim}
     1338\end{datatype}
    13221339
    13231340In addition, we specify two functions for working with \code{psScalar} data:
    1324 \begin{verbatim}
     1341\begin{prototype}
    13251342psScalar *psScalarAlloc(psC64 value, psElemType dataType);
    13261343psScalar *psScalarCopy(const psScalar *value);
    1327 \end{verbatim}
     1344\end{prototype}
    13281345The first creates a \code{psType}-ed structure from a constant value,
    13291346casting it as appropriate based on the \code{dataType}.  The second
    … …  
    13401357single structure, \code{psVector} to represent these concepts:
    13411358%
    1342 \begin{verbatim}
     1359\begin{datatype}
    13431360typedef struct {
    13441361    psType type;                        ///< vector data type and dimension
    … …  
    13601377    } data;
    13611378} psVector;
    1362 \end{verbatim}
     1379\end{datatype}
    13631380%
    13641381In this structure, the argument \code{n} is the length of the array
    … …  
    13721389associated with a constructor and reallocator:
    13731390%
    1374 \begin{verbatim}
     1391\begin{prototype}
    13751392psVector *psVectorAlloc(int nalloc, psElemType type);
    13761393psVector *psVectorRealloc(psVector *vector, int nalloc);
    13771394psVector *psVectorRecycle(psVector *vector, int nalloc, psElemType type);
    1378 \end{verbatim}
     1395\end{prototype}
    13791396%
    13801397In these functions, \code{nalloc} is the number of elements to
    … …  
    13961413shall be allocated and returned.
    13971414
    1398 \begin{verbatim}
     1415\begin{prototype}
    13991416psVector *psVectorExtend(psVector *vector, int delta, int nExtend);
    1400 \end{verbatim}
     1417\end{prototype}
    14011418
    14021419This function increments \code{psVector.n}, the number of elements in
    … …  
    14081425Here is an example of how \code{psVectorExtend} is used to
    14091426automatically increment the vector length.
    1410 \begin{verbatim}
     1427\begin{datatype}
    14111428  // create data vector
    14121429  psVector *y = psVectorAlloc (100);
    … …  
    14191436    // increments n by 1, extends length if needed by 100
    14201437  }
    1421 \end{verbatim}
     1438\end{datatype}
    14221439Note that the specification that the allocation always be greater than
    14231440the number of elements by twice the number of new elements implies
    … …  
    14251442elements, as in this example.
    14261443
    1427 \begin{verbatim}
     1444\begin{prototype}
    14281445psVector *psVectorCopy(psVector *output, const psVector *input, psElemType type);
    1429 \end{verbatim}
     1446\end{prototype}
    14301447
    14311448\code{psVectorCopy} shall copy the elements in the \code{input} vector
    … …  
    14411458value.  We require a basic image data type:
    14421459
    1443 \begin{verbatim}
     1460\begin{datatype}
    14441461typedef struct psImage {
    14451462    psType type;                        ///< image data type and dimension
    … …  
    14631480    psArray *children;                  ///< children of this region
    14641481} psImage;
    1465 \end{verbatim}
     1482\end{datatype}
    14661483
    14671484This structure represents an image consisting of a 2-D array of
    … …  
    14851502psS16, psU8, psU16, psF32, psF64, psC32, psC64}.
    14861503
    1487 \begin{verbatim}
     1504\begin{prototype}
    14881505psImage *psImageAlloc (int width, int height, psElemType type);
    14891506psImage* psImageRecycle(psImage* old, int numCols, int numRows, const psElemType type);
    1490 \end{verbatim}
     1507\end{prototype}
    14911508
    14921509\code{psImageAlloc} shall create an image of a specified \code{width}, \code{height}, and data
    … …  
    15011518shall be allocated and returned.
    15021519
    1503 \begin{verbatim}
     1520\begin{prototype}
    15041521int psImageFreeChildren(psImage* image);
    1505 \end{verbatim}
     1522\end{prototype}
    15061523
    15071524\code{psImageFreeChildren} shall free all child images of the given
    … …  
    15151532data type testing may be safely performed. 
    15161533
    1517 \begin{verbatim}
     1534\begin{datatype}
    15181535typedef struct {
    15191536    psType type;                        ///< data type information
    15201537} psMath;
    1521 \end{verbatim}
     1538\end{datatype}
    15221539
    15231540\subsection{Simple Arrays}
    … …  
    15261543define \code{psArray} to carry such a collection:
    15271544%
    1528 \begin{verbatim}
     1545\begin{datatype}
    15291546typedef struct {
    15301547    const int n;                        ///< size of array
    … …  
    15321549    void **data;                        ///< pointer to data block
    15331550} psArray;
    1534 \end{verbatim}
     1551\end{datatype}
    15351552%
    15361553In this structure, the argument \code{n} is the length of the array
    … …  
    15401557destructor:
    15411558%
    1542 \begin{verbatim}
     1559\begin{prototype}
    15431560psArray *psArrayAlloc(int nalloc);
    15441561psArray *psArrayRealloc(const psArray *array, int nalloc);
    1545 \end{verbatim}
     1562\end{prototype}
    15461563%
    15471564In these functions, \code{nalloc} is the number of elements to
    … …  
    15581575error.
    15591576
    1560 \begin{verbatim}
     1577\begin{prototype}
    15611578psArray *psArrayAdd(psArray *array, int delta, const void *value);
    1562 \end{verbatim}
     1579\end{prototype}
    15631580
    15641581This function adds a value to the end of an array.  If the current
    … …  
    15681585value is less than 1, 10 shall be used).
    15691586
    1570 \begin{verbatim}
     1587\begin{prototype}
    15711588psBool psArrayRemove(psArray *array, const psPtr value);
    1572 \end{verbatim}
     1589\end{prototype}
    15731590
    15741591This function removes all entries of \code{value} in the \code{array},
    … …  
    15771594\code{FALSE}.
    15781595
    1579 \begin{verbatim}
     1596\begin{prototype}
    15801597psBool psArraySet(psArray* in, psU32 position, const void* value);
    15811598void* psArrayGet(const psArray* in, psU32 position);
    1582 \end{verbatim}
     1599\end{prototype}
    15831600
    15841601These accessor functions are provided as a convenience to the user.
    … …  
    15881605specified \code{position}.
    15891606
    1590 \begin{verbatim}
     1607\begin{prototype}
    15911608psArray *psArraySort(psArray *array, int (*compare)(const void **a, const void **b) );
    1592 \end{verbatim}
     1609\end{prototype}
    15931610An array may be sorted using \code{psArraySort}, which requires the
    15941611specification of a comparison function to specify how the objects on
    … …  
    16021619\PS{} shall support doubly linked lists through a type \code{psList}:
    16031620%
    1604 \begin{verbatim}
     1621\begin{datatype}
    16051622typedef struct {
    16061623   unsigned int size;                  ///< number of elements on list
    … …  
    16101627   pthread_mutex_t lock;               ///< mutex to lock a node during changes
    16111628} psList;
    1612 \end{verbatim}
     1629\end{datatype}
    16131630%
    16141631The type \code{psList} represents the container of the list.  It has a
    … …  
    16211638The elements of the list are defined by the type \code{psListElem}:
    16221639%
    1623 \begin{verbatim}
     1640\begin{datatype}
    16241641typedef struct psListElem {
    16251642   struct psListElem *prev;            ///< previous link in list
    … …  
    16271644   void *data;                         ///< real data item
    16281645} psListElem;
    1629 \end{verbatim}
     1646\end{datatype}
    16301647%
    16311648which includes a pointer to the next element in the list
    … …  
    16341651element.    The following supporting functions are required:
    16351652
    1636 \begin{verbatim}
     1653\begin{prototype}
    16371654psList *psListAlloc(const void *data);
    1638 \end{verbatim}
     1655\end{prototype}
    16391656Create a list.  This function may take a pointer to a data item, or it
    16401657may take \code{NULL}.  The allocator creates both the \code{psList}
    … …  
    16561673Iteration on the list shall be achieved by means of a list iterator
    16571674type:
    1658 \begin{verbatim}
     1675\begin{datatype}
    16591676typedef struct {
    16601677    psList *list;                      ///< List iterator works on
    … …  
    16641681    bool mutable;                      ///< Is it permissible to modify the list?
    16651682} psListIterator;
    1666 \end{verbatim}
     1683\end{datatype}
    16671684The \code{psListIterator} keeps track of which list element the
    16681685iterator \code{cursor} is currently pointing at.  \code{index} is the
    … …  
    16781695
    16791696The corresponding constructor shall be:
    1680 \begin{verbatim}
     1697\begin{prototype}
    16811698psListIterator *psListIteratorAlloc(const psList *list, int location, bool mutable);
    1682 \end{verbatim}
     1699\end{prototype}
    16831700Here, \code{list} is the \code{psList} on which the iterator will
    16841701iterate, and \code{location} is the initial starting point, and may be
    … …  
    16961713A list \code{iterator} shall be set to a specific \code{location} on
    16971714the list upon calling \code{psListIteratorSet}:
    1698 \begin{verbatim}
     1715\begin{prototype}
    16991716bool psListIteratorSet(psListIterator *iterator, int location);
    1700 \end{verbatim}
     1717\end{prototype}
    17011718Again, the \code{location} may be a numerical index or it may be one
    17021719of the special values: \code{PS_LIST_HEAD} or \code{PS_LIST_TAIL},
    … …  
    17061723otherwise.
    17071724
    1708 \begin{verbatim}
     1725\begin{prototype}
    17091726bool psListAdd(psList *list, int location, const void *data);
    17101727bool psListAddAfter(psListIterator *iterator, const void *data);
    17111728bool psListAddBefore(psListIterator *iterator, const void *data);
    1712 \end{verbatim}
     1729\end{prototype}
    17131730the first function, \code{psListAdd}, adds an entry to the \code{list}
    17141731and returns a boolean giving the success or failure of the
    … …  
    17241741cursor position of the \code{iterator}.
    17251742
    1726 \begin{verbatim}
     1743\begin{prototype}
    17271744void *psListGet(psList *list, int location);
    17281745void *psListGetAndIncrement(psListIterator *iterator);
    17291746void *psListGetAndDecrement(psListIterator *iterator);
    1730 \end{verbatim}
     1747\end{prototype}
    17311748A data item may be retrieved from the list with these functions.  The
    17321749first function, \code{psListGet} simply returns the value specified by
    … …  
    17541771longer off the end of the list.
    17551772
    1756 \begin{verbatim}
     1773\begin{prototype}
    17571774bool psListRemove(psList *list, int location)
    17581775bool psListRemoveData(psList *list, const void *data);
    1759 \end{verbatim}
     1776\end{prototype}
    17601777A data item may be removed from the list with these functions.  For
    17611778\code{psListRemove}, the value of \code{location} may be the numerical
    … …  
    17731790\code{false}.
    17741791
    1775 \begin{verbatim}
     1792\begin{prototype}
    17761793psArray *psListToArray(const psList *list);
    17771794psList  *psArrayToList(const psArray *array);
    1778 \end{verbatim}
     1795\end{prototype}
    17791796These two functions are available to convert between the
    17801797\code{psList} and \code{psArray} containers.  These functions do not
    … …  
    17821799increment the reference counter for each of the elements.
    17831800
    1784 \begin{verbatim}
     1801\begin{prototype}
    17851802psList *psListSort(psList *list, int (*compare)(const void **a, const void **b) );
    1786 \end{verbatim}
     1803\end{prototype}
    17871804A list may be sorted using \code{psListSort}, which requires the
    17881805specification of a comparison function to specify how the objects on
    … …  
    18141831table at any one time.}
    18151832%
    1816 \begin{verbatim}
     1833\begin{datatype}
    18171834typedef struct {
    18181835    int nbucket;                        ///< number of buckets
    18191836    psHashBucket **buckets;             ///< the buckets themselves
    18201837} psHash;
    1821 \end{verbatim}
     1838\end{datatype}
    18221839%
    18231840where \code{nbucket} is the number of buckets defined for the hash
    … …  
    18251842individual buckets, each of which is defined by:
    18261843%
    1827 \begin{verbatim}
     1844\begin{datatype}
    18281845typedef struct psHashBucket {
    18291846    char *key;                          ///< key for this item of data
    … …  
    18311848    struct psHashBucket *next;          ///< list of other possible keys
    18321849} psHashBucket;
    1833 \end{verbatim}
     1850\end{datatype}
    18341851where each bucket contains the value of the \code{key}, a pointer to
    18351852the \code{data}, and a pointer to the \code{next} list entry in the
    … …  
    18371854
    18381855A hash table is created with the following function:
    1839 \begin{verbatim}
     1856\begin{prototype}
    18401857psHash *psHashAlloc(int nbuckets);
    1841 \end{verbatim}
     1858\end{prototype}
    18421859which allocates the space for the hash table, creating and
    18431860initializing \code{nbuckets} hash buckets.
    … …  
    18461863
    18471864A data item may be added to the hash table with the function:
    1848 \begin{verbatim}
     1865\begin{prototype}
    18491866bool psHashAdd(psHash *table, const char *key, const void *data);
    1850 \end{verbatim}
     1867\end{prototype}
    18511868In this function, the value of the string \code{key} is used to
    18521869construct the hash value, find the appropriate bucket set, and add the
    … …  
    18571874
    18581875The data associated with a given key may be found with the function:
    1859 \begin{verbatim}
     1876\begin{prototype}
    18601877void *psHashLookup(const psHash *table, const char *key);
    1861 \end{verbatim}
     1878\end{prototype}
    18621879which returns the data value pointed to by the element associated with
    18631880\code{key}, or the value \code{NULL} if no match is found.  Similarly,
    18641881a specific key may be removed (deleted) with the function:
    1865 \begin{verbatim}
     1882\begin{prototype}
    18661883bool psHashRemove(psHash *table, const char *key);
    1867 \end{verbatim}
     1884\end{prototype}
    18681885The function returns a value of \code{true} if the operation was
    18691886successfull, and \code{false} otherwise.
    18701887
    18711888The function
    1872 \begin{verbatim}
     1889\begin{prototype}
    18731890psList *psHashKeyList(const psHash *table);
    1874 \end{verbatim}
     1891\end{prototype}
    18751892returns the complete list of defined keys associated with the
    18761893\code{psHash} table as a linked list.
    18771894
    1878 \begin{verbatim}
     1895\begin{prototype}
    18791896psArray *psHashToArray(const psHash *hash);
    1880 \end{verbatim}
     1897\end{prototype}
    18811898This function places the data in a \code{psHash} into a \code{psArray}
    18821899container.  This function does not free the elements or destroy the
    … …  
    18961913generally useful, and so we specify a separate function that may be
    18971914called independently:
    1898 \begin{verbatim}
     1915\begin{prototype}
    18991916psArray *psVectorsReadFromFile(const char *filename, const char *format);
    1900 \end{verbatim}
     1917\end{prototype}
    19011918\code{psVectorsReadFromFile} shall return an array of
    19021919\code{psVector}s, read from the specified \code{filename}.  The file
    … …  
    19111928is to be skipped.
    19121929
    1913 
    1914 \begin{verbatim}
     1930\begin{datatype}
    19151931typedef struct {
    19161932    const char *filename;               ///< File from which data is to be read
    … …  
    19211937    const psF64 validFrom, validTo;     ///< Range of validity
    19221938} psLookupTable;
    1923 \end{verbatim}
     1939\end{datatype}
    19241940
    19251941\code{filename} shall specify the file from which the lookup table
    … …  
    19381954
    19391955The constructor shall be:
    1940 \begin{verbatim}
     1956\begin{prototype}
    19411957psLookupTable *psLookupTableAlloc(const char *filename, ///< File from which to read
    19421958                                  const char *format ///< scanf-like format string
    19431959                                  int indexCol ///< Column of the index vector (starting at zero)
    19441960                                  );
    1945 \end{verbatim}
     1961\end{prototype}
    19461962This function shall allocate a \code{psLookupTable}, and set the
    19471963appropriate values, but it shall not read the lookup table.  This is
    … …  
    19511967The destructor shall free all the components.
    19521968
    1953 \begin{verbatim}
     1969\begin{prototype}
    19541970psLookupTable *psLookupTableImport(psLookupTable *table, ///< Lookup table into which to import
    19551971                                   const psArray *vectors, ///< Array of vectors
    19561972                                   int indexCol ///< Index of the index vector in the array of vectors
    19571973                                   );
    1958 \end{verbatim}
     1974\end{prototype}
    19591975\code{psLookupTableImport} shall import an array of vectors into a
    19601976\code{table}.  If \code{table} is \code{NULL}, a new
    … …  
    19711987function returning.
    19721988
    1973 \begin{verbatim}
     1989\begin{prototype}
    19741990int psLookupTableRead(psLookupTable *table);
    1975 \end{verbatim}
     1991\end{prototype}
    19761992\code{psLookupTableRead} combines \code{psVectorsReadFromFile} and
    19771993\code{psLookupTableImport} to read the appropriate file and import the
    … …  
    19831999Interpolation on a lookup table is performed by the following
    19842000functions:
    1985 \begin{verbatim}
     2001\begin{prototype}
    19862002psF64 psLookupTableInterpolate(const psLookupTable *table, psF64 index, int column, psLookupStatusType *status);
    19872003psVector *psLookupTableInterpolateAll(const psLookupTable *table, psF64 index, psVector *stats);
    1988 \end{verbatim}
     2004\end{prototype}
    19892005Both functions shall interpolate the \code{table} at the provided
    19902006\code{index}.  For \code{psLookupTableInterpolate}, only the value in
    … …  
    20292045\code{ceil(n/8)} bytes must be allocated.  The bitset structure is
    20302046define by:
    2031 \begin{verbatim}
     2047\begin{datatype}
    20322048typedef struct {
    20332049    int n;                              ///< Number of chars that form the bitset
    20342050    char *bits;                         ///< The bits
    20352051} psBitSet;
    2036 \end{verbatim}
     2052\end{datatype}
    20372053
    20382054We also require the corresponding constructor and destructor:
    2039 \begin{verbatim}
     2055\begin{prototype}
    20402056psBitSet *psBitSetAlloc(int n);
    2041 \end{verbatim}
     2057\end{prototype}
    20422058where \code{n} is the requested number of bits.
    20432059
    … …  
    20512067The corresponding APIs are defined below:
    20522068
    2053 \begin{verbatim}
     2069\begin{prototype}
    20542070psBitSet *psBitSetSet(psBitSet *myBits, int bit);
    20552071psBitSet* psBitSetClear(psBitSet* inBits, int bit);
    … …  
    20582074bool psBitSetTest(const psBitSet *checkBits, int bit);
    20592075char *psBitSetToString(const pBitSet* bits);
    2060 \end{verbatim}
     2076\end{prototype}
    20612077
    20622078\code{psBitSetSet} sets the specified \code{bit} in the
    … …  
    20952111psF64}.  The input and output vectors must have the same type.
    20962112
    2097 \begin{verbatim}
     2113\begin{prototype}
    20982114psVector *psVectorSort(psVector *out, const psVector *in);
    2099 \end{verbatim}
     2115\end{prototype}
    21002116
    21012117We also require the ability to sort one vector based on another.  For
    … …  
    21092125input types \code{psS8, psU16, psF32, psF64}.
    21102126
    2111 \begin{verbatim}
     2127\begin{prototype}
    21122128psVector *psVectorSortIndex(psVector *out; const psVector *in);
    2113 \end{verbatim}
     2129\end{prototype}
    21142130
    21152131The sorted vectors may be accessed in the following manner:
    … …  
    21532169function:
    21542170
    2155 \begin{verbatim}
     2171\begin{prototype}
    21562172psStats *psVectorStats(psStats *stats,
    21572173                       const psVector *in,
    … …  
    21602176                       unsigned int maskVal
    21612177                       );
    2162 \end{verbatim}
     2178\end{prototype}
    21632179%
    21642180This function takes the input data in \code{in} (with optional
    … …  
    21922208desired statistical quantities:
    21932209
    2194 \begin{verbatim}
     2210\begin{datatype}
    21952211/** generic statistics structure */
    21962212typedef struct {
    … …  
    22182234    psStatsOptions options;             ///< bitmask of calculated values
    22192235} psStats;
    2220 \end{verbatim}
     2236\end{datatype}
    22212237where \code{psStatsOptions} is defined with entries to turn on the
    22222238calculation of each of the statistics:
    22232239
    2224 \begin{verbatim}
     2240\begin{datatype}
    22252241/** statistics which may be calculated */
    22262242typedef enum {
    … …  
    22412257    PS_STAT_USE_BINSIZE           = 0x004000
    22422258} psStatsOptions;                         
    2243 \end{verbatim}
     2259\end{datatype}
    22442260
    22452261A constructor is also required:
    22462262%
    2247 \begin{verbatim}
     2263\begin{prototype}
    22482264psStats *psStatsAlloc(psStatsOptions options);
    2249 \end{verbatim}
     2265\end{prototype}
    22502266
    22512267\subsubsection{Histograms}
    … …  
    22552271upper and lower bounds for each of the bins.  We define the following
    22562272data structure to represent a histogram:
    2257 \begin{verbatim}
     2273\begin{datatype}
    22582274typedef struct {
    22592275    const psVector *bounds;             ///< Bounds for the bins
    … …  
    22622278    bool uniform;                       ///< Is it a uniform distribution?
    22632279} psHistogram;
    2264 \end{verbatim}
     2280\end{datatype}
    22652281In this structure, the vector \code{bounds} specifies the boundaries
    22662282of the histogram bins, and must of type \code{psF32}, while
    … …  
    22772293with the size of the bins.
    22782294
    2279 \begin{verbatim}
     2295\begin{prototype}
    22802296psHistogram *psHistogramAlloc(float lower, float upper, int n);
    2281 \end{verbatim}
     2297\end{prototype}
    22822298where \code{lower} specifies the lower bound of the histogram range,
    22832299\code{upper} specified the upper bound of the histogram range, and
    … …  
    22872303A histogram with a more flexible bin set may be constructed with the
    22882304following constructor:
    2289 \begin{verbatim}
     2305\begin{prototype}
    22902306psHistogram *psHistogramAllocGeneric(const psVector *bounds);
    2291 \end{verbatim}
     2307\end{prototype}
    22922308where the \code{psVector *bounds} (of type \code{psF32}) is defined by
    22932309the user to specify the boundaries of the histogram bins. This
    … …  
    22972313vector (\code{values}), and optionally the \code{errors} in the input
    22982314values.  It alters and returns the histogram \code{out} structure.
    2299 \begin{verbatim}
     2315\begin{prototype}
    23002316psHistogram *psVectorHistogram(psHistogram *out,
    23012317                               const psVector *values,
    … …  
    23032319                               const psVector *mask,
    23042320                               unsigned int maskVal);
    2305 \end{verbatim}
     2321\end{prototype}
    23062322The \code{values} vector may be of types \code{psU8, psU16, psF32,
    23072323psF64}, with the \code{errors} vector of the corresponding type.
    … …  
    23302346This leads us to define the following polynomial types:
    23312347
    2332 \begin{verbatim}
     2348\begin{datatype}
    23332349/** One-dimensional polynomial */
    23342350typedef struct {
    … …  
    23392355    char *mask;                         ///< Coefficient mask
    23402356} psPolynomial1D;
    2341 \end{verbatim}
    2342 
    2343 \begin{verbatim}
     2357\end{datatype}
     2358
     2359\begin{datatype}
    23442360/** Two-dimensional polynomial */
    23452361typedef struct {
    … …  
    23502366    char **mask;                        ///< Coefficients mask
    23512367} psPolynomial2D;
    2352 \end{verbatim}
     2368\end{datatype}
    23532369
    23542370etc., up to four dimensions.  \code{psPolynomialType} is an
    … …  
    23562372or Chebyshev:
    23572373
    2358 \begin{verbatim}
     2374\begin{datatype}
    23592375typedef enum {
    23602376    PS_POLYNOMIAL_ORD,                  ///< Ordinary polynomial
    23612377    PS_POLYNOMIAL_CHEB                  ///< Chebyshev polynomial
    23622378} psPolynomialType;
    2363 \end{verbatim}
     2379\end{datatype}
    23642380
    23652381We also define double-precision versions of the polynomials:
    23662382
    2367 \begin{verbatim}
     2383\begin{datatype}
    23682384/** Double-precision one-dimensional polynomial */
    23692385typedef struct {
    … …  
    23742390    char *mask;                         ///< Coefficient mask
    23752391} psDPolynomial1D;
    2376 \end{verbatim}
    2377 
    2378 \begin{verbatim}
     2392\end{datatype}
     2393
     2394\begin{datatype}
    23792395/** Double-precision two-dimensional polynomial */
    23802396typedef struct {
    … …  
    23852401    char **mask;                        ///< Coefficients mask
    23862402} psDPolynomial2D;
    2387 \end{verbatim}
     2403\end{datatype}
    23882404
    23892405etc.  In what follows, we only show the version for double-precision
    … …  
    23922408
    23932409The constructor is:
    2394 \begin{verbatim}
     2410\begin{prototype}
    23952411psDPolynomial2D *psDPolynomial2DAlloc(int nX, int nY, psPolynomialType type);
    2396 \end{verbatim}
     2412\end{prototype}
    23972413where \code{nX} and \code{nY} are the number of terms in x and y
    23982414respectively.  The coefficients, errors and masks are set initially to
    … …  
    24002416
    24012417To evaluate the polynomials at specific coordinates, we define:
    2402 \begin{verbatim}
     2418\begin{prototype}
    24032419double psDPolynomial2DEval(const psDPolynomial2D *myPoly, double x, double y);
    2404 \end{verbatim}
     2420\end{prototype}
    24052421
    24062422In the event that several evaluations are required, we also define:
    2407 \begin{verbatim}
     2423\begin{prototype}
    24082424psVector *psDPolynomial2DEvalVector(const psDPolynomial2D *myPoly, const psVector *x, const psVector *y);
    2409 \end{verbatim}
     2425\end{prototype}
    24102426If the \code{x} and \code{y} vectors do not match the precision of the
    24112427polynomial, the function shall generate a warning, and convert the
    … …  
    24252441incorporated into PSLib:
    24262442
    2427 \begin{verbatim}
     2443\begin{datatype}
    24282444typedef struct {
    24292445    int n;                              ///< Number of spline pieces
    … …  
    24312447    psVector *knots;                    ///< The boundaries between each spline piece.  Size is n+1.
    24322448} psSpline1D;
    2433 \end{verbatim}
     2449\end{datatype}
    24342450
    24352451The \code{psSpline1D} structure consists of an array of \code{n}
    … …  
    24442460
    24452461Of course, we require the appropriate constructors and destructor:
    2446 \begin{verbatim}
     2462\begin{prototype}
    24472463psSpline1D *psSpline1DAlloc(int n, int order, float min, float max);
    24482464psSpline1D *psSpline1DAllocGeneric(const psVector *bounds, int order);
    2449 \end{verbatim}
     2465\end{prototype}
    24502466
    24512467\code{psSpline1DAlloc} shall allocate and return a \code{psSpline1D},
    … …  
    24692485for an input vector of ordinates.
    24702486
    2471 \begin{verbatim}
     2487\begin{prototype}
    24722488float psSpline1DEval(const psSpline1D *spline, float x);
    24732489psVector *psSpline1DEvalVector(const psSpline1D *spline, const psVector *x);
    2474 \end{verbatim}
     2490\end{prototype}
    24752491
    24762492\subsubsection{Gaussians}
    … …  
    24812497
    24822498The Gaussian evaluation is provide by:
    2483 \begin{verbatim}
     2499\begin{prototype}
    24842500float psGaussian(float x, float mean, float sigma, bool normal);
    2485 \end{verbatim}
     2501\end{prototype}
    24862502which evaluates a Gaussian with the given \code{mean} and \code{sigma}
    24872503at the given coordinate \code{x}.  If \code{normal} is true, the
    … …  
    25172533(\code{lastDelta}).
    25182534
    2519 \begin{verbatim}
     2535\begin{datatype}
    25202536typedef struct {
    25212537    const int maxIter;                  ///< Maximum number of iterations
    … …  
    25252541    float lastDelta;                    ///< Last change before quitting
    25262542} psMinimization;
    2527 \end{verbatim}
     2543\end{datatype}
    25282544
    25292545The corresponding allocator is:
    2530 \begin{verbatim}
     2546\begin{prototype}
    25312547psMinimization *psMinimizationAlloc(int maxIter, float tol);
    2532 \end{verbatim}
     2548\end{prototype}
    25332549
    25342550\subsubsection{Levenberg-Marquardt}
    … …  
    25392555parameters and coordinate vectors, along with the derivatives of the
    25402556function with respect to each of the parameters, \code{deriv}:
    2541 \begin{verbatim}
     2557\begin{datatype}
    25422558typedef float (*psMinimizeLMChi2Func)(psVector *deriv, const psVector *params, const psVector *x);
    2543 \end{verbatim}
     2559\end{datatype}
    25442560
    25452561Then \code{psMinimizeLMChi2} shall fit the specified function,
    … …  
    25472563Levenberg-Marquardt method:
    25482564
    2549 \begin{verbatim}
     2565\begin{prototype}
    25502566bool psMinimizeLMChi2(psMinimization *min, psImage *covar, psVector *params,
    25512567                      const psVector *paramMask, const psArray *x, const psVector *y,
    25522568                      const psVector *yErr, psMinimizeLMChi2Func func);
    2553 \end{verbatim}
     2569\end{prototype}
    25542570
    25552571The function shall return \code{false} in the event that there was an
    … …  
    25942610%% minimization, used for the purpose of performing $\chi^2$ fitting:
    25952611
    2596 %% \begin{verbatim}
     2612%% \begin{prototype}
    25972613%% psMinimizeLMChi2Func psMinimizeLMChi2Gauss1D;
    25982614%% psMinimizeLMChi2Func psMinimizeLMChi2Gauss2D;
    2599 %% \end{verbatim}
     2615%% \end{prototype}
    26002616
    26012617%% \code{psMinimizeChi2LMGauss1D} shall take as \code{params}, the
    … …  
    26202636the parameters and coordinate vectors, but now the derivatives are not
    26212637known:
    2622 \begin{verbatim}
     2638\begin{datatype}
    26232639typedef float (*psMinimizePowellFunc)(const psVector *params, const psArray *coords);
    2624 \end{verbatim}
     2640\end{datatype}
    26252641
    26262642Then \code{psMinimizePowell} shall minimize the specified function,
    26272643\code{func}, using the Powell method:
    26282644
    2629 \begin{verbatim}
     2645\begin{prototype}
    26302646bool psMinimizePowell(psMinimization *min, psVector *params, const psVector *paramMask,
    26312647                      const psArray *coords, psMinimizePowellFunc func);
    2632 \end{verbatim}
     2648\end{prototype}
    26332649
    26342650The inputs and general behavior of this function is the same as for
    … …  
    26412657general functions to data.
    26422658
    2643 \begin{verbatim}
     2659\begin{datatype}
    26442660typedef psVector* (*psMinimizeChi2PowellFunc)(const psVector *params, const psArray *coords);
    2645 
     2661\end{datatype}
     2662
     2663\begin{prototype}
    26462664bool psMinimizeChi2Powell(psMinimization *min, psVector *params, const psVector *paramMask,
    26472665                          const psArray *coords, const psVector *value, const psVector *error,
    26482666                          psMinimizeChi2PowellFunc model);
    2649 \end{verbatim}
     2667\end{prototype}
    26502668
    26512669The inputs and general behavior of \code{psMinimizeChi2Powell} is
    … …  
    26722690\subsubsection{Analytical fits}
    26732691
    2674 \begin{verbatim}
     2692\begin{prototype}
    26752693psPolynomial1D *psVectorFitPolynomial1D(psPolynomial1D *myPoly, const psVector *x, const psVector *y,
    26762694                                        const psVector *yErr);
    2677 \end{verbatim}
     2695\end{prototype}
    26782696\code{psVectorFitPolynomial1d} returns the polynomial that best fits the
    26792697observations.  The input parameters are a polynomial that specifies
    … …  
    26862704function must be valid only for types \code{psF32}, \code{psF64}.
    26872705
    2688 \begin{verbatim}
     2706\begin{prototype}
    26892707psSpline1D *psVectorFitSpline1D(const psVector *x, const psVector *y, int nKnots);
    2690 \end{verbatim}
     2708\end{prototype}
    26912709\code{psVectorFitSpline1D} shall return the spline that best fits the
    26922710given combination of ordinates (\code{x}) and coordinates (\code{y}).
    … …  
    27102728In many places, we need to refer to a rectangular area.  We define a
    27112729structure to represent a rectangle:
    2712 \begin{verbatim}
     2730\begin{datatype}
    27132731typedef struct {
    27142732  float x0;
    … …  
    27172735  float y1;
    27182736} psRegion;
    2719 \end{verbatim}
     2737\end{datatype}
    27202738This structure is used in psLib as an abbreviation for the four
    27212739floats, and is defined statically.  Functions which accept or return a
    … …  
    27312749\code{psRegion} to the corresponding IRAF description.
    27322750
    2733 \begin{verbatim}
     2751\begin{prototype}
    27342752psRegion psRegionSet(float x0, float x1, float y0, float y1);
    27352753psRegion psRegionFromString(const char *region);
    27362754char *psRegionToString(const psRegion region);
    2737 \end{verbatim}
     2755\end{prototype}
    27382756
    27392757All functions which use a psRegion must interpret the definition of
    … …  
    27482766\subsubsection{Image Structure Manipulation}
    27492767
    2750 \begin{verbatim}
     2768\begin{prototype}
    27512769psImage *psImageSubset(psImage *image, psRegion region);
    2752 \end{verbatim}
     2770\end{prototype}
    27532771Define a subimage of the specified area of the given image.  This
    27542772function must raise an error if the requested subset area lies outside
    … …  
    27662784\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}.
    27672785
    2768 \begin{verbatim}
     2786\begin{prototype}
    27692787psImage *psImageCopy(psImage *output, const psImage *input, psElemType type);
    2770 \end{verbatim}
     2788\end{prototype}
    27712789Create a copy of the specified image, converting the type in the
    27722790process.  If the output target pointer is not \code{NULL}, place the
    … …  
    27782796\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}.
    27792797
    2780 \begin{verbatim}
     2798\begin{prototype}
    27812799psImage *psImageTrim(psImage *image, psRegion region);
    2782 \end{verbatim}
     2800\end{prototype}
    27832801Trim the specified \code{image} in-place, which involves shuffling the
    27842802pixels around in memory.  The region to be kept is defined by the
    … …  
    27972815\subsubsection{Image Pixel Extractions}
    27982816
    2799 \begin{verbatim}
     2817\begin{datatype}
    28002818typedef enum {
    28012819    PS_CUT_X_POS,                     ///< Cut in positive x direction
    … …  
    28042822    PS_CUT_Y_NEG                      ///< Cut in negative y direction
    28052823} psImageCutDirection;
    2806 
     2824\end{datatype}
     2825
     2826\begin{prototype}
    28072827psVector *psImageSlice(psVector *out,
    28082828                       psVector *coords,
    … …  
    28132833                       psImageCutDirection direction,
    28142834                       const psStats *stats);
    2815 \end{verbatim}
     2835\end{prototype}
    28162836Extract pixels from rectilinear region to a vector (array of floats).
    28172837The output vector contains either \code{region.x1-region.x0} or
    … …  
    28392859\code{psF32}, \code{psF64}.
    28402860
    2841 \begin{verbatim}
     2861\begin{prototype}
    28422862psVector *psImageCut(psVector *out,
    28432863                     psVector *coords,
    … …  
    28482868                     unsigned int nSamples,
    28492869                     psImageInterpolateMode mode);
    2850 \end{verbatim}
     2870\end{prototype}
    28512871Extract pixels along a line segment, \code{(region.x0,region.y0)} to
    28522872\code{(region.x1,region.y1)}, on the image to a vector of the same
    … …  
    28602880\code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}.
    28612881
    2862 \begin{verbatim}
     2882\begin{prototype}
    28632883psVector *psImageRadialCut(psVector *out,
    28642884                           const psImage *input,
    … …  
    28692889                           const psVector *radii,
    28702890                           const psStats *stats);
    2871 \end{verbatim}
     2891\end{prototype}
    28722892Extract radial region data to a vector.  A vector is constructed where
    28732893each vector elements is derived from the statistics of the pixels
    … …  
    28892909specification of the interpolation scheme to be used.  This
    28902910information is carried by the following enum:
    2891 \begin{verbatim}
     2911\begin{datatype}
    28922912typedef enum {
    28932913    PS_INTERPOLATE_FLAT,
    … …  
    29012921    PS_INTERPOLATE_LANCZOS4_VARIANCE
    29022922} psImageInterpolateMode mode;
    2903 \end{verbatim}
     2923\end{datatype}
    29042924
    29052925The first five are fairly straightforward.  The last four, however,
    … …  
    29122932the noise (adding in quadrature).
    29132933
    2914 \begin{verbatim}
     2934\begin{prototype}
    29152935psImage *psImageRebin(psImage *out, const psImage *in,
    29162936                      const psImage *mask,
    29172937                      unsigned int maskVal,
    29182938                      int scale, const psStats *stats);
    2919 \end{verbatim}
     2939\end{prototype}
    29202940Rebin image to new scale.  A new image is constructed in which the
    29212941dimensions are reduced by a factor of \code{1 / scale}.  The
    … …  
    29352955\code{psU16}, \code{psF32} and \code{psF64}.
    29362956
    2937 \begin{verbatim}
     2957\begin{prototype}
    29382958psImage *psImageResample(psImage *out, const psImage *in,
    29392959                         int scale, psImageInterpolateMode mode);
    2940 \end{verbatim}
     2960\end{prototype}
    29412961Resample image to new scale.  A new image is constructed in which the
    29422962dimensions are increased by a factor of \code{scale}.  The
    … …  
    29462966pixels using the specified interpolation method (\code{mode}).
    29472967
    2948 \begin{verbatim}
     2968\begin{prototype}
    29492969psImage *psImageRotate(psImage *out, const psImage *input, float angle,
    29502970                       psC64 exposed, psImageInterpolateMode mode);
    2951 \end{verbatim}
     2971\end{prototype}
    29522972Rotate the input image by given angle, specified in radians.  The
    29532973output image must contain all of the pixels from the input image in
    … …  
    29602980\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}.
    29612981
    2962 \begin{verbatim}
     2982\begin{prototype}
    29632983psImage *psImageShift(psImage *out, const psImage *input,
    29642984                      float dx, float dy, psC64 exposed, psImageInterpolateMode mode);
    2965 \end{verbatim}
     2985\end{prototype}
    29662986Shift image by an arbitrary number of pixels (\code{dx,dy}) in either
    29672987direction.  If the shift values are fractional, the output pixel
    … …  
    29742994\code{psF64}, \code{psC32}, \code{psC64}.
    29752995
    2976 \begin{verbatim}
     2996\begin{prototype}
    29772997psImage *psImageRoll(psImage *out, const psImage *input, int dx, int dy);
    2978 \end{verbatim}
     2998\end{prototype}
    29792999Roll image by an integer number of pixels (\code{dx,dy}) in either
    29803000direction.  The output image is the same dimensions as the input
    … …  
    29843004\code{psC32}, \code{psC64}.
    29853005
    2986 \begin{verbatim}
     3006\begin{prototype}
    29873007psImage *psImageTransform(psImage *output,
    29883008                          psArray **blankPixels,
    … …  
    29953015                          psImageInterpolateMode mode,
    29963016                          double exposedValue);
    2997 \end{verbatim}
     3017\end{prototype}
    29983018Transform the \code{input} image according the supplied
    29993019transformation.  The size of the transformed image is defined by the
    … …  
    30273047\subsubsection{Image Statistical Functions}
    30283048
    3029 \begin{verbatim}
     3049\begin{prototype}
    30303050psStats *psImageStats(psStats *stats,
    30313051                      const psImage *in,
    30323052                      const psImage *mask,
    30333053                      unsigned int maskVal);
    3034 \end{verbatim}
     3054\end{prototype}
    30353055Determine statistics for image (or subimage).  The statistics to be
    30363056determined are specified by \code{stats}.  The \code{mask} allows
    … …  
    30403060\code{psF64}.
    30413061
    3042 \begin{verbatim}
     3062\begin{prototype}
    30433063psHistogram *psImageHistogram(psHistogram *out,
    30443064                              const psImage *in,
    30453065                              const psImage *mask,
    30463066                              unsigned int maskVal);
    3047 \end{verbatim}
     3067\end{prototype}
    30483068Construct a histogram from an image (or subimage).  The histogram to
    30493069generate is specified by \code{psHistogram hist} (see
    … …  
    30543074\code{psF64}.
    30553075
    3056 \begin{verbatim}
     3076\begin{prototype}
    30573077psPolynomial2D *psImageFitPolynomial(psPolynomial2D *coeffs, const psImage *input);
    3058 \end{verbatim}
     3078\end{prototype}
    30593079Fit a 2-D Chebychev polynomial surface to an image.  The input
    30603080structure \code{coeffs} contains the desired order and terms of
    … …  
    30623082following types: \code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}.
    30633083
    3064 \begin{verbatim}
     3084\begin{prototype}
    30653085psImage *psImageEvalPolynomial(psImage *input, const psPolynomial2D *coeffs);
    3066 \end{verbatim}
     3086\end{prototype}
    30673087Evaluate a 2-D polynomial surface for the image pixels.  Given the
    30683088input polynomial coefficients, set the image pixel values on the basis
    … …  
    30703090following types: \code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}.
    30713091
    3072 \begin{verbatim}
     3092\begin{prototype}
    30733093psC64 psImagePixelInterpolate(const psImage *input, float x, float y,
    30743094                              const psImage *mask, unsigned int maskVal,
    30753095                              psC64 unexposedValue, psImageInterpolateMode mode);
    3076 \end{verbatim}
     3096\end{prototype}
    30773097Perform interpolation of image pixel values to the given fractional
    30783098coordinate \code{x,y}.  The function returns the interpolated value of
    … …  
    30873107\subsubsection{Image Pixel Manipulations}
    30883108
    3089 \begin{verbatim}
     3109\begin{prototype}
    30903110int psImageClip(psImage *input, double min, double vmin, double max, double vmax);
    3091 \end{verbatim}
     3111\end{prototype}
    30923112Clip image values outside of range to given values.  All pixels with
    30933113values \code{< min} are set to the value \code{vmin}. All pixels with
    … …  
    310631260.0 for the imaginary component.
    31073127
    3108 \begin{verbatim}
     3128\begin{prototype}
    31093129int psImageClipComplexRegion(psImage *input, complex double min, complex double vmin,
    31103130                             complex double max, complex double vmax);
    3111 \end{verbatim}
     3131\end{prototype}
    31123132Clip image values outside of range to given values.  All pixels with
    31133133values \code{< min} are set to the value \code{vmin}. All pixels with
    … …  
    31243144\code{min} or \code{max} to be out of range.
    31253145
    3126 \begin{verbatim}
     3146\begin{prototype}
    31273147int psImageClipNaN(psImage *input, float value);
    3128 \end{verbatim}
     3148\end{prototype}
    31293149Clip \code{NaN} image pixels to given value.  Pixels with \code{NaN},
    31303150\code{+Inf} or \code{-Inf} values are set to the specified value.
    … …  
    31353155set to the specified value.
    31363156
    3137 \begin{verbatim}
     3157\begin{prototype}
    31383158int psImageOverlaySection(psImage *image, const psImage *overlay,
    31393159                          int x0, int y0, const char *op);
    3140 \end{verbatim}
     3160\end{prototype}
    31413161Overlay subregion of image with another image.  Replace the pixels in
    31423162the \code{image} which correspond to the pixels in \code{overlay} with
    … …  
    31543174\subsubsection{Mask operations}
    31553175
    3156 \begin{verbatim}
     3176\begin{prototype}
    31573177psImage *psImageGrowMask(psImage *out, const psImage *in, unsigned int maskVal,
    31583178                         unsigned int growSize, unsigned int growValue);
    3159 \end{verbatim}
     3179\end{prototype}
    31603180
    31613181\code{psImageGrowMask} grows specified values on the input mask image,
    … …  
    31843204through an entire mask image checking each pixel.
    31853205
    3186 \begin{verbatim}
     3206\begin{datatype}
    31873207typedef struct {
    31883208    int x;                      // x coordinate
    … …  
    31953215    psPixelCoord *data;         // The pixel coordinates
    31963216} psPixels;
    3197 \end{verbatim}
    3198 
    3199 \begin{verbatim}
     3217\end{datatype}
     3218
     3219\begin{prototype}
    32003220psPixels *psPixelsAlloc(int nalloc);
    32013221psPixels *psPixelsRealloc(psPixels *pixels, int nalloc);
    3202 \end{verbatim}
     3222\end{prototype}
    32033223
    32043224\code{psPixelsAlloc} and \code{psPixelsRealloc} provide dynamic
    … …  
    32063226by \code{psVectorAlloc} and \code{psVectorRealloc}.
    32073227
    3208 \begin{verbatim}
     3228\begin{prototype}
    32093229psImage *psPixelsToMask(psImage *out, const psPixels *pixels, const psRegion region, unsigned int maskVal);
    32103230psPixels *psPixelsFromMask(psPixels *out, const psImage *mask, unsigned int maskVal);
    3211 \end{verbatim}
     3231\end{prototype}
    32123232
    32133233\code{psPixelsToMask} shall return an image of type U8 with the
    … …  
    32283248\code{NULL}.
    32293249
    3230 \begin{verbatim}
     3250\begin{prototype}
    32313251psPixels *psPixelsCopy(psPixels *out, const psPixels *pixels);
    32323252psPixels *psPixelsConcatenate(psPixels *out, const psPixels *pixels);
    3233 \end{verbatim}
     3253\end{prototype}
    32343254
    32353255\code{psPixelsCopy} shall copy the contents of \code{pixels} to the
    … …  
    32593279specify two generic APIs for the binary and unary operations.
    32603280
    3261 \begin{verbatim}
     3281\begin{prototype}
    32623282psType *psBinaryOp(void *out, const void *in1, const char *op, const void *in2);
    32633283psType *psUnaryOp(void *out, const void *in, const char *op);
    3264 \end{verbatim}
     3284\end{prototype}
    32653285These functions determine the type of the operands on the basis of
    32663286their \code{psType} elements, which always are the first elements.
    … …  
    33593379In the event of an error, the matrix functions shall return \code{NULL}.
    33603380
    3361 \begin{verbatim}
     3381\begin{prototype}
    33623382psImage *psMatrixLUD(psImage *out, psVector **perm, const psImage *in);
    33633383psVector *psMatrixLUSolve(psVector *out, const psImage *LU, const psVector *RHS, const psVector *perm);
    3364 \end{verbatim}
     3384\end{prototype}
    33653385The above functions decompose a matrix, \code{in}, into its $LU$
    33663386representation (\code{psMatrixLUD}, which returns the decomposed
    … …  
    33783398\code{NULL} on calling \code{psMatrixLUD}.
    33793399
    3380 \begin{verbatim}
     3400\begin{prototype}
    33813401psImage *psMatrixInvert(psImage *out, const psImage *in, float *determinant);
    3382 \end{verbatim}
     3402\end{prototype}
    33833403\code{psMatrixInvert} returns the inverse of the specified matrix
    33843404(\code{in}), along with the \code{determinant}, if the \code{float}
    … …  
    33903410the specified matrix, \code{in}.  This function is specified for data
    33913411types \code{psF32, psF64}.
    3392 \begin{verbatim}
     3412\begin{prototype}
    33933413float psMatrixDeterminant(const psImage *in);
    3394 \end{verbatim}
     3414\end{prototype}
    33953415
    33963416Matrix multiplication is supported through \code{psMatrixMultiply}.  This function is
    33973417specified for data types \code{psF32, psF64}.
    3398 \begin{verbatim}
     3418\begin{prototype}
    33993419psImage *psMatrixMultiply(psImage *out, const psImage *in1, const psImage *in2);
    3400 \end{verbatim}
     3420\end{prototype}
    34013421
    34023422The transpose of an input matrix, \code{in}, is returned by
    34033423\code{psMatrixTranspose}, optionally into the provided matrix
    34043424\code{out}.  This function is specified for data types \code{psF32,psF64}.
    3405 \begin{verbatim}
     3425\begin{prototype}
    34063426psImage *psMatrixTranspose(psImage *out, const psImage *in);
    3407 \end{verbatim}
     3427\end{prototype}
    34083428
    34093429Eigenvectors of a matrix are calculated by
    34103430\code{psMatrixEigenvectors}.  This function is specified for data
    34113431types \code{psF32, psF64}.  Input and output data types should match.
    3412 \begin{verbatim}
     3432\begin{prototype}
    34133433psImage *psMatrixEigenvectors(psImage *out, const psImage *in);
    3414 \end{verbatim}
     3434\end{prototype}
    34153435\tbd{Should this return an array of vectors?  Specified here as
    34163436currently implemented by MHPCC.}
    … …  
    34223442for data types \code{psF32, psF64}.  Input and output data types
    34233443should match.
    3424 \begin{verbatim}
     3444\begin{prototype}
    34253445psVector *psMatrixToVector(psVector *out, const psImage *in);
    34263446psImage *psVectorToMatrix(psImage *out, const psVector *in);
    3427 \end{verbatim}
     3447\end{prototype}
    34283448
    34293449%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    … …  
    34363456library.  We define the following APIs to support FFT operations on vectors:
    34373457
    3438 \begin{verbatim}
     3458\begin{prototype}
    34393459psVector *psVectorFFT(psVector *out, const psVector *in, psFFTFlags direction);
    34403460psVector *psVectorReal(psVector *out, const psVector *in);
    … …  
    34433463psVector *psVectorConjugate(psVector *out, const psVector *in);
    34443464psVector *psVectorPowerSpectrum(psVector *out, const psVector *in);
    3445 \end{verbatim}
     3465\end{prototype}
    34463466
    34473467The forward and reverse FFT is calculated using \code{psVectorFFT},
    … …  
    34713491by an enumerated type, \code{psFFTFlags}:
    34723492
    3473 \begin{verbatim}
     3493\begin{datatype}
    34743494/** Specify direction of FFT, and if the result is real or not */
    34753495typedef enum {
    … …  
    34803500                                        ///< parameter should appear as PS_FFT_REVERSE+PS_FFT_REAL_RESULT.
    34813501} psFFTFlags;
    3482 \end{verbatim}
     3502\end{datatype}
    34833503
    34843504The entry \code{PS_FFT_REAL_RESULT} means that the output of an
    … …  
    34963516In analogy with the vector FFT operations, we also define matching
    34973517image operations as follows:
    3498 \begin{verbatim}
     3518\begin{prototype}
    34993519psImage *psImageFFT(psImage *out, const psImage *image, psFFTFlags direction);
    35003520psImage *psImageReal(psImage *out, const psImage *in);
    … …  
    35033523psImage *psImageConjugate(psImage *out, const psImage *in);
    35043524psImage *psImagePowerSpectrum(psImage *out, const psImage *in);
    3505 \end{verbatim}
     3525\end{prototype}
    35063526
    35073527%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    … …  
    35283548\code{psImage} operations.  We define a \code{psKernel}:
    35293549
    3530 \begin{verbatim}
     3550\begin{datatype}
    35313551/** A convolution kernel */
    35323552typedef struct {
    … …  
    35373557    float **p_kernelRows;               ///< Pointer to the rows of the kernel data
    35383558} psKernel;
    3539 \end{verbatim}
     3559\end{datatype}
    35403560
    35413561The kernel data is carried primarily by the \code{data} member which
    … …  
    35573577
    35583578Of course, we require the appropriate constructor:
    3559 \begin{verbatim}
     3579\begin{prototype}
    35603580psKernel *psKernelAlloc(int xMin, int xMax, int yMin, int yMax);
    3561 \end{verbatim}
     3581\end{prototype}
    35623582
    35633583\code{psKernelAlloc} shall allocate a kernel.  In the event that one
    … …  
    35713591guiding), \code{psKernelGenerate} shall return the appropriate kernel.
    35723592The API shall be the following:
    3573 \begin{verbatim}
     3593\begin{prototype}
    35743594psKernel *psKernelGenerate(const psVector *tShifts, const psVector *xShifts,
    35753595                           const psVector *yShifts, bool relative);
    3576 \end{verbatim}
     3596\end{prototype}
    35773597
    35783598The vectors \code{xShifts} and \code{yShifts}, which are a list of
    … …  
    35953615\code{in}, with the kernel, \code{kernel} and return the convolved
    35963616image, \code{out}.  The API shall be the following:
    3597 \begin{verbatim}
     3617\begin{prototype}
    35983618psImage *psImageConvolve(psImage *out, const psImage *in, const psKernel *kernel, bool direct);
    3599 \end{verbatim}
     3619\end{prototype}
    36003620
    36013621Two methods shall be available for the convolution: if \code{direct}
    … …  
    36253645expansion in the future, depending upon user requirements.
    36263646
    3627 \begin{verbatim}
     3647\begin{datatype}
    36283648typedef enum {
    36293649    PS_RANDOM_TAUS                      ///< A maximally equidistributed combined Tausworthe generator
    … …  
    36343654    gsl_rng *gsl;                       ///< The RNG itself
    36353655} psRandom;
    3636 \end{verbatim}
     3656\end{datatype}
    36373657
    36383658We require the ability to seed the random number generator (RNG) with
    … …  
    36403660may be reproduced.
    36413661
    3642 \begin{verbatim}
     3662\begin{prototype}
    36433663psRandom *psRandomAlloc(psRandomType type, unsigned long seed);
    36443664void psRandomReset(psRandom *rand, unsigned long seed);
    3645 \end{verbatim}
     3665\end{prototype}
    36463666
    36473667\code{psRandomAlloc} shall construct a new instance of \code{psRandom}
    … …  
    36533673\code{psLogMsg} with a level of \code{PS_LOG_INFO}.
    36543674
    3655 \begin{verbatim}
     3675\begin{prototype}
    36563676double psRandomUniform(const psRandom *r);
    36573677double psRandomGaussian(const psRandom *r);
    36583678double psRandomPoisson(const psRandom *r, double mean);
    3659 \end{verbatim}
     3679\end{prototype}
    36603680
    36613681\code{psRandomUniform} shall return random numbers uniformly
    … …  
    37853805We define an item of metadata with the following structure:
    37863806\filbreak
    3787 \begin{verbatim}
     3807\begin{datatype}
    37883808typedef struct {
    37893809    const psS32 id;                     ///< unique ID for this item
    … …  
    38003820    char *comment;                      ///< optional comment ("", not NULL)
    38013821} psMetadataItem;
    3802 \end{verbatim}
     3822\end{datatype}
    38033823
    38043824The \code{id} is a unique identifier for this item of metadata;
    … …  
    38143834%
    38153835\filbreak
    3816 \begin{verbatim}
     3836\begin{datatype}
    38173837typedef enum {                         ///< type of item.data is:
    38183838    PS_META_S32  = PS_TYPE_S32,        ///< psS32 primitive data.
    … …  
    38343854    PS_META_MULTI                      ///< Used internally, do not create a metadata item of this type.
    38353855} psMetadataType;
    3836 \end{verbatim}
     3856\end{datatype}
    38373857The macro \code{PS_META_IS_PRIMITIVE(psMetadataType.type)} returns
    38383858true if the type is one of the primitive data types (S32, F64, etc).
    … …  
    38413861
    38423862A collection of metadata is represented by the \code{psMetadata} structure:
    3843 \begin{verbatim}
     3863\begin{datatype}
    38443864typedef struct {
    38453865    psList *list;                       ///< list of psMetadataItem
    38463866    psHash *table;                      ///< hash table of the same metadata
    38473867} psMetadata;
    3848 \end{verbatim}
     3868\end{datatype}
    38493869The type \code{psMetadata} is a container class for metadata. Note
    38503870that there are in fact \emph{two} representations of the metadata
    … …  
    38733893As a convenience to the user, the following type-specific functions are
    38743894also defined:
    3875 \begin{verbatim}
     3895\begin{prototype}
    38763896psMetadataItem* psMetadataItemAllocStr(const char* name, const char* comment, const char* value);
    38773897psMetadataItem* psMetadataItemAllocF32(const char* name, const char* comment, psF32 value);
    … …  
    38793899psMetadataItem* psMetadataItemAllocS32(const char* name, const char* comment, psS32 value);
    38803900psMetadataItem* psMetadataItemAllocBool(const char* name, const char* comment, psBool value);
    3881 \end{verbatim}
     3901\end{prototype}
    38823902
    38833903\subsubsection{Metadata APIs}
    38843904
    3885 \begin{verbatim}
     3905\begin{prototype}
    38863906psMetadata *psMetadataAlloc(void);
    3887 \end{verbatim}
     3907\end{prototype}
    38883908
    38893909The constructor for the collection of metadata, \code{psMetadata},
    … …  
    38923912free each of the \code{psMetadataItem}s.
    38933913
    3894 \begin{verbatim}
     3914\begin{prototype}
    38953915psMetadataItem *psMetadataItemAlloc(const char *name, psMetadataType type, const char *comment, ...);
    38963916psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type, const char *comment, va_list list);
    3897 \end{verbatim}
     3917\end{prototype}
    38983918
    38993919The allocator for \code{psMetadataItem} returns a full
    … …  
    39113931in the function.
    39123932
    3913 \begin{verbatim}
     3933\begin{prototype}
    39143934bool psMetadataAddItem(psMetadata *md, const psMetadataItem *item, int location, int mode);
    39153935bool psMetadataAdd(psMetadata *md, int location, const char *name, int format, const char *comment, ...);
    39163936bool psMetadataAddV(psMetadata *md, int location, const char *name, int format, const char *comment,
    39173937                    va_list list);
    3918 \end{verbatim}
     3938\end{prototype}
    39193939
    39203940Items may be added to the metadata in one of two ways --- firstly, an
    … …  
    39393959%
    39403960
    3941 \begin{verbatim}
     3961\begin{datatype}
    39423962typedef enum {                          ///< option flags for psMetadata functions
    39433963    PS_META_DEFAULT,                    ///< default behavior (0x0000) for use in mode above
    … …  
    39453965    PS_META_DUPLICATE_OK,               ///< allow entry to be replaced
    39463966} psMetadataFlags;
    3947 \end{verbatim}
     3967\end{datatype}
    39483968
    39493969The functions above take option flags which modify the behavior when
    … …  
    40214041As a convenience to the user, the following type-specific functions
    40224042are specified:
    4023 \begin{verbatim}
     4043\begin{prototype}
    40244044psBool psMetadataAddS32(psMetadata* md, psS32 location, const char* name, const char* comment, psS32 value);
    40254045psBool psMetadataAddF32(psMetadata* md, psS32 location, const char* name, const char* comment, psF32 value);
    … …  
    40414061psBool psMetadataAddMetadata(psMetadata* md, psS32 location, const char* name, const char* comment,
    40424062                             const psMetadata* value);
    4043 \end{verbatim}
     4063\end{prototype}
    40444064
    40454065
    … …  
    40544074returned.
    40554075%
    4056 \begin{verbatim}
     4076\begin{prototype}
    40574077bool psMetadataRemove(psMetadata *md, int location, const char *key);
    4058 \end{verbatim}
     4078\end{prototype}
    40594079
    40604080Items may be found within the metadata by providing a key.  In the
    40614081event that the key is non-unique, the first item is returned.
    4062 \begin{verbatim}
     4082\begin{prototype}
    40634083psMetadataItem *psMetadataLookup(const psMetadata *md, const char *key);
    4064 \end{verbatim}
     4084\end{prototype}
    40654085
    40664086Several utility functions are provided for simple cases.  These
    … …  
    40694089found.  If the pointer value of \code{status} is not \code{NULL}, it
    40704090is set to reflect the success or failure of the lookup.
    4071 \begin{verbatim}
     4091\begin{prototype}
    40724092void *psMetadataLookupPtr(bool *status, const psMetadata *md, const char *key);
    40734093psS32 psMetadataLookupS32(bool *status, const psMetadata *md, const char *key);
    40744094psF32 psMetadataLookupF32(bool *status, const psMetadata *md, const char *key);
    40754095psF64 psMetadataLookupF64(bool *status, const psMetadata *md, const char *key);
    4076 \end{verbatim}
     4096\end{prototype}
    40774097
    40784098Items may be retrieved from the metadata by their entry position.  The
    40794099value of which specifies the desired entry in the fashion of
    40804100\code{psList}.
    4081 \begin{verbatim}
     4101\begin{prototype}
    40824102psMetadataItem *psMetadataGet(const psMetadata *md, int location);
    4083 \end{verbatim}
     4103\end{prototype}
    40844104
    40854105The metadata list component may be iterated over by using a
    40864106\code{psMetadataIterator} in a fashion equivalent to the
    40874107\code{psListIterator}:
    4088 \begin{verbatim}
     4108\begin{datatype}
    40894109typedef struct {
    40904110    psListIterator* iter;              ///< iterator for the psMetadata's psList
    40914111    regex_t* regex;                     ///< the subsetting regular expression
    40924112} psMetadataIterator;
    4093 \end{verbatim}
     4113\end{datatype}
    40944114
    40954115The iterator may be set to a location in the \code{psMetadata} list,
    … …  
    41044124defined by \code{location}, which follows the conventions of the
    41054125\code{psList} iterators.
    4106 \begin{verbatim}
     4126\begin{prototype}
    41074127psMetadataIterator *psMetadataIteratorAlloc(psMetadata *md, int location, const char *regex);
    41084128bool psMetadataIteratorSet(psMetadataIterator *iterator, int location);
    41094129psMetadataItem *psMetadataGetAndIncrement(psMetadataIterator *iterator);
    41104130psMetadataItem *psMetadataGetAndDecrement(psMetadataIterator *iterator);
    4111 \end{verbatim}
     4131\end{prototype}
    41124132
    41134133Metadata items may be printed to an open file descriptor based on a
    … …  
    41194139for a string (\%s type of command).  If the metadata type is any other
    41204140data type, printing is not allowed.
    4121 \begin{verbatim}
     4141\begin{prototype}
    41224142bool psMetadataItemPrint(FILE *fd, const char *format, const psMetadataItem *md);
    4123 \end{verbatim}
     4143\end{prototype}
    41244144
    41254145\subsubsection{Configuration files}
    … …  
    41314151function \code{psMetadataConfigParse}, as described below.
    41324152
    4133 \begin{verbatim}
     4153\begin{prototype}
    41344154psMetadata *psMetadataConfigParse(psMetadata *md, int *nFail, const char *filename, bool overwrite);
    4135 \end{verbatim}
     4155\end{prototype}
    41364156
    41374157Given a metadata container, \code{md}, and the name of a configuration
    … …  
    41504170configuration.
    41514171
    4152 \begin{verbatim}
     4172\begin{prototype}
    41534173char *psMetadataConfigFormat(psMetadata *md);
    41544174bool psMetadataConfigWrite(psMetadata *md, const char *filename);
    4155 \end{verbatim}
     4175\end{prototype}
    41564176
    41574177The \code{psMetadataConfigFormat} function converts a \code{psMetadata}
    … …  
    43654385document in memory.  We wrap the \code{libxml2} version of an XML
    43664386document pointer for now:
    4367 \begin{verbatim}
     4387\begin{datatype}
    43684388typedef xmlDocPtr psXMLDoc;
     4389\end{datatype}
     4390
     4391\begin{prototype}
    43694392void psXMLDocFree(psXMLDoc *doc);
    4370 \end{verbatim}
     4393\end{prototype}
    43714394
    43724395The next pair of functions convert a \code{psMetadata} data structure
    43734396to a complete \code{psXMLDoc} (in memory) and vice versa:
    4374 \begin{verbatim}
     4397\begin{prototype}
    43754398psXMLDoc *psMetadataToXMLDoc(const psMetadata *metadata);
    43764399psMetadata *psXMLDocToMetadata(const psXMLDoc *doc);
    4377 \end{verbatim}
     4400\end{prototype}
    43784401
    43794402The next pair of functions loads the data in a named file into a
    43804403complete \code{psXMLDoc} (in memory) and write out the \code{psXMLDoc}
    43814404to a named file:
    4382 \begin{verbatim}
     4405\begin{prototype}
    43834406psXMLDoc *psXMLParseFile(const char *filename);
    43844407int psXMLDocToFile(const psXMLDoc *doc, const char *filename);
    4385 \end{verbatim}
     4408\end{prototype}
    43864409
    43874410The next pair of functions accepts a block of memory and parses it
    43884411into a complete \code{psXMLDoc} (also in memory), and vice versa:
    4389 \begin{verbatim}
     4412\begin{prototype}
    43904413psXMLDoc *psXMLParseMemory(const char *buffer, const int size);
    43914414int psXMLDocToMemory(const psXMLDoc *doc, char *buffer);
    4392 \end{verbatim}
     4415\end{prototype}
    43934416
    43944417The next pair of functions read from and write to a file descriptor.
    … …  
    43964419(also in memory), the second writes the \code{psXMLDoc} to the file
    43974420descriptor:
    4398 \begin{verbatim}
     4421\begin{prototype}
    43994422psXMLDoc *psXMLParseFD(int fd);
    44004423int psXMLDocToFD(const psXMLDoc *doc, int fd);
    4401 \end{verbatim}
     4424\end{prototype}
    44024425
    44034426\subsection{Database Functions}
    … …  
    44284451database connection:
    44294452
    4430 \begin{verbatim}
     4453\begin{datatype}
    44314454    typedef struct {
    44324455        MYSQL *mysql;
    44334456    } psDB;
    4434 \end{verbatim}
     4457\end{datatype}
    44354458
    44364459The following collection of functions provides basic database functionality:
    44374460
    4438 \begin{verbatim}
     4461\begin{prototype}
    44394462    // wraps mysql_init() & mysql_real_connect()
    44404463    psDB *psDBInit(const char *host, const char *user, const char *passwd, const char *dbname);
    … …  
    44514474    // wraps mysql_drop_db()
    44524475    bool psDBDrop(psDB *dbh, const char *dbname);
    4453 \end{verbatim}
     4476\end{prototype}
    44544477
    44554478For MySQL support, \code{psDBInit()} wraps \code{mysql_init()} and
    … …  
    44764499table and as part of the query restrictions.
    44774500
    4478 \begin{verbatim}
     4501\begin{prototype}
    44794502    bool psDBCreateTable(psDB *dbh, const char *tableName, const psMetadata *md);
    4480 \end{verbatim}
     4503\end{prototype}
    44814504
    44824505This function generates and executes the SQL needed to create a table
    … …  
    45034526whitespace.  The \code{comment} field is otherwise ignored.
    45044527
    4505 \begin{verbatim}
     4528\begin{prototype}
    45064529    bool psDBDropTable(psDB *dbh, const char *tableName);
    4507 \end{verbatim}
     4530\end{prototype}
    45084531
    45094532This function deletes the specified table.
    45104533
    4511 \begin{verbatim}
     4534\begin{prototype}
    45124535    bool p_psDBRunQuery(psDB *dbh, const char *query);
    4513 \end{verbatim}
     4536\end{prototype}
    45144537
    45154538This function will execute a string as a raw SQL query.  No additional
    … …  
    45174540dialect is provided.
    45184541
    4519 \begin{verbatim}
     4542\begin{prototype}
    45204543    psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, const psU64 limit);
    45214544    psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, psMetadataType type, const psU64 limit);
    4522 \end{verbatim}
     4545\end{prototype}
    45234546
    45244547These functions generates and executes the SQL needed to select an entire
    … …  
    45294552(NULL) if the requested field is not a numerical type.
    45304553
    4531 \begin{verbatim}
     4554\begin{prototype}
    45324555    psArray *psDBSelectRows(psDB *dbh, const char *tableName, psMetadata *where, const psU64 limit);
    4533 \end{verbatim}
     4556\end{prototype}
    45344557
    45354558This function returns rows from the specified table which match
    … …  
    45424565\code{psArray} of \code{psMetadata} values, one per row.
    45434566
    4544 \begin{verbatim}
     4567\begin{prototype}
    45454568    bool psDBInsertOneRow(psDB *dbh, const char *tableName, const psMetadata *row);
    4546 \end{verbatim}
     4569\end{prototype}
    45474570
    45484571Insert the data from \code{row} into \code{tableName}.  It should be noted in
    … …  
    45504573in \code{tablename}, the insert will fail.
    45514574
    4552 \begin{verbatim}
     4575\begin{prototype}
    45534576    bool psDBInsertRows(psDB *dbh, const char *tableName, const psArray *rowSet);
    4554 \end{verbatim}
     4577\end{prototype}
    45554578
    45564579Similar to \code{psDBInsertOneRow()}, this function inserts many rows at once
    45574580and is atomic for the complete set of rows.
    45584581
    4559 \begin{verbatim}
     4582\begin{prototype}
    45604583    psArray *psDBDumpRows(psDB *dbh, const char *tableName);
    4561 \end{verbatim}
     4584\end{prototype}
    45624585
    45634586Fetch all rows as an psArray of psMetadata.
    45644587
    4565 \begin{verbatim}
     4588\begin{prototype}
    45664589    psMetadata *psDBDumpCols(psDB *dbh, const char *tableName);
    4567 \end{verbatim}
     4590\end{prototype}
    45684591
    45694592Fetch all columns, as either a psVector or a psArray depending on whether or not
    … …  
    45714594psMetadataItem.name contains the column's name.
    45724595
    4573 \begin{verbatim}
     4596\begin{prototype}
    45744597psS64 psDBUpdateRows(psDB *dbh, const char *tableName, const psMetadata *where, const psMetadata *values);
    4575 \end{verbatim}
     4598\end{prototype}
    45764599
    45774600Update the columns contained in \code{values} in the row(s) that have a field
    … …  
    45824605an additional constraint.  e.g.  ``where foo = x and where bar = y''
    45834606
    4584 \begin{verbatim}
     4607\begin{prototype}
    45854608    psS64 psDBDeleteRows(psDB *dbh, const char *tableName, const psMetadata *where);
    4586 \end{verbatim}
     4609\end{prototype}
    45874610
    45884611Delete the rows that are matched by \code{where} using the same semantics for
    … …  
    46034626be the most basic versions.
    46044627
    4605 \begin{verbatim}
     4628\begin{datatype}
    46064629typedef struct {
    46074630    fitsfile fd;
    46084631} psFits;
    4609 \end{verbatim}
     4632\end{datatype}
    46104633We begin by defining a datatype to wrap the CFITSIO \code{fitsfile}
    46114634structure.  This is necessary to allow repeated access to the data in
    … …  
    46144637\subsubsection{FITS File Manipulations}
    46154638
    4616 \begin{verbatim}
     4639\begin{prototype}
    46174640psFits *psFitsAlloc(const char *filename);
    4618 \end{verbatim}
     4641\end{prototype}
    46194642
    46204643Opens a FITS file at positions the pointer to the PHU.
    46214644
    4622 \begin{verbatim}
     4645\begin{prototype}
    46234646bool psFitsMoveExtName(psFits *fits, const char *extname);
    4624 \end{verbatim}
     4647\end{prototype}
    46254648
    46264649Positions the pointer to the beginning of the specified
    … …  
    46284651shall fail. 
    46294652
    4630 \begin{verbatim}
     4653\begin{prototype}
    46314654bool psFitsMoveExtNum(psFits* fits, int extnum, bool relative);
    4632 \end{verbatim}
     4655\end{prototype}
    46334656
    46344657Moves the pointer to the beginning of the specified HDU number.  If
    … …  
    46374660extended data segments start at number 1.
    46384661
    4639 \begin{verbatim}
     4662\begin{prototype}
    46404663int psFitsGetExtNum(psFits* fits);
    4641 \end{verbatim}
     4664\end{prototype}
    46424665
    46434666Returns the current HDU number (i.e., file position). 
    46444667
    4645 \begin{verbatim}
     4668\begin{prototype}
    46464669int psFitsGetSize(psFits* fits);
    4647 \end{verbatim}
     4670\end{prototype}
    46484671
    46494672Returns the number of HDUs in the file.
    46504673
    4651 \begin{verbatim}
     4674\begin{prototype}
    46524675psFitsType psFitsGetExtType(psFits* fits);
    4653 \end{verbatim}
     4676\end{prototype}
    46544677
    46554678Gets the current HDU's type (table or image).
    46564679
    4657 \begin{verbatim}
     4680\begin{prototype}
    46584681char *psFitsGetExtName(psFits* fits);
    46594682bool psFitsSetExtName(psFits* fits, const char* name);
    4660 \end{verbatim}
     4683\end{prototype}
    46614684
    46624685\code{psFitsGetExtName} shall return the name of the current extension
    … …  
    46684691\subsubsection{FITS Header I/O Functions}
    46694692
    4670 \begin{verbatim}
     4693\begin{prototype}
    46714694psMetadata *psFitsReadHeader(psMetadata *out, psFits *fits);
    4672 \end{verbatim}
     4695\end{prototype}
    46734696Read header data into a \code{psMetadata} structure.  The data is read
    46744697from the current HDU pointed at by the \code{psFits *fits} entry.  If
    46754698\code{out} is \code{NULL}, a new psMetadata is created.
    46764699
    4677 \begin{verbatim}
     4700\begin{prototype}
    46784701psMetadata *psFitsReadHeaderSet (psFits *fits);
    4679 \end{verbatim}
     4702\end{prototype}
    46804703Load a complete set of headers from the \code{psFits} file pointer.
    46814704This function loads the headers from all extensions into a
    … …  
    46884711called.
    46894712
    4690 \begin{verbatim}
     4713\begin{prototype}
    46914714bool psFitsWriteHeader(psMetadata *output, psFits *fits);
    4692 \end{verbatim}
     4715\end{prototype}
    46934716Write metadata into the header of a FITS image file.  The header is
    46944717written at the current HDU.
    … …  
    46964719\subsubsection{FITS Image I/O Functions}
    46974720
    4698 \begin{verbatim}
     4721\begin{prototype}
    46994722psImage *psFitsReadImage(psImage *output, psFits *fits, psRegion region, int z);
    4700 \end{verbatim}
     4723\end{prototype}
    47014724Read an image or subimage from the \code{psFits} file pointer.  This
    47024725function is a wrapper to the CFITSIO library function.  The input
    … …  
    47154738type as needed with \code{psImageCopy}.
    47164739 
    4717 \begin{verbatim}
     4740\begin{prototype}
    47184741bool psFitsUpdateImage(psFits *fits, const psImage *input, psRegion region, int z);
    4719 \end{verbatim}
     4742\end{prototype}
    47204743Write an image section to the open \code{psFits} file pointer.  This
    47214744operation may write a portion of an image over the existing bytes of
    … …  
    47324755successful operation and 1 for an error.
    47334756
    4734 \begin{verbatim}
     4757\begin{prototype}
    47354758bool psFitsWriteImage(psFits *fits, const psMetadata *header, const psImage *input, int depth);
    4736 \end{verbatim}
     4759\end{prototype}
    47374760Create a new image based on the dimensions specified for the image and
    47384761the requested depth.  The header and image data segments are written
    … …  
    47464769\subsubsection{FITS Table I/O Functions}
    47474770
    4748 \begin{verbatim}
     4771\begin{prototype}
    47494772psMetadata *psFitsReadTableRow (psFits *fits, int row);
    4750 \end{verbatim}
     4773\end{prototype}
    47514774This function reads a single row of the table in the extension pointed
    47524775at by the \code{psFits} file pointer.  The row number to be read is
    … …  
    47604783the file pointer location, for that matter).}
    47614784
    4762 \begin{verbatim}
     4785\begin{prototype}
    47634786void *psFitsReadTableRowRaw (int *nBytes, psFits *fits, int row);
    4764 \end{verbatim}
     4787\end{prototype}
    47654788This function reads a single row of the table in the extension pointed
    47664789at by the \code{psFits} file pointer.  The row number to be read is
    … …  
    47734796somewhere (and the file pointer location, for that matter).}
    47744797
    4775 \begin{verbatim}
     4798\begin{prototype}
    47764799psArray *psFitsReadTableColumn (psFits *fits, const char *colname);
    4777 \end{verbatim}
     4800\end{prototype}
    47784801This function reads a single column of the table in the extension
    47794802pointed at by the \code{psFits} file pointer.  The column is specified
    … …  
    47824805column per array element.
    47834806
    4784 \begin{verbatim}
     4807\begin{prototype}
    47854808psVector *psFitsReadTableColumnNum (psFits *fits, const char *colname);
    4786 \end{verbatim}
     4809\end{prototype}
    47874810This function reads a single column of the table in the extension
    47884811pointed at by the \code{psFits} file pointer.  The column is specified
    … …  
    47924815per array element.
    47934816
    4794 \begin{verbatim}
     4817\begin{prototype}
    47954818psArray *psFitsReadTableRaw (int *nBytes, psFits *fits);
    4796 \end{verbatim}
     4819\end{prototype}
    47974820This function reads the entire data block from a table into the a
    47984821\code{psArray}, with one element of the array per row.  The number of
    … …  
    48014824description of the table data in the table header.
    48024825
    4803 \begin{verbatim}
     4826\begin{prototype}
    48044827psArray *psFitsReadTable (psFits *fits);
    4805 \end{verbatim}
     4828\end{prototype}
    48064829This function reads the entire data block from a table into the a
    48074830\code{psArray}, with one element of the array per row.  Each row is
    … …  
    48094832\code{psFitsReadTableRow}.
    48104833
    4811 \begin{verbatim}
     4834\begin{prototype}
    48124835bool psFitsWriteTable(psFits* fits, const psMetadata *header, const psArray* table);
    4813 \end{verbatim}
     4836\end{prototype}
    48144837Accepts a \code{psArray} of \code{psMetadata} and writes it to the
    48154838current HDU.  If the current HDU is not a table type, this will fail
    48164839and return FALSE.
    48174840
    4818 \begin{verbatim}
     4841\begin{prototype}
    48194842bool psFitsUpdateTable(psFits* fits, const psMetadata* data, int row);
    4820 \end{verbatim}
     4843\end{prototype}
    48214844Writes the \code{psMetadata} data to a FITS table at the specified row
    48224845in the current HDU.  If the current HDU is not a table type, this will
    … …  
    48594882\subsubsection{Data Types}
    48604883
    4861 \begin{verbatim}
     4884\begin{datatype}
    48624885typedef enum {
    48634886    PS_TIME_TAI,                    ///< seconds since 1970-01-01T00:00:00Z (Gregorian), SI seconds
    … …  
    48784901    psTimeType       type;          ///< type of time
    48794902} psTime;
    4880 \end{verbatim}
     4903\end{datatype}
    48814904
    48824905\subsubsection{Constructors}
    … …  
    48844907To allocate a new, initialized to zero, \code{psTime}:
    48854908
    4886 \begin{verbatim}
     4909\begin{prototype}
    48874910psTime *psTimeAlloc(psTimeType type);
    4888 \end{verbatim}
     4911\end{prototype}
    48894912
    48904913To allocate a new \code{psTime} set to the current time (in the given system):
    48914914
    4892 \begin{verbatim}
     4915\begin{prototype}
    48934916psTime *psTimeGetNow(psTimeType type);
    4894 \end{verbatim}
     4917\end{prototype}
    48954918
    48964919\subsubsection{Time Conversion}
    … …  
    48984921Converting between the \code{psTime} time systems is done with:
    48994922
    4900 \begin{verbatim}
     4923\begin{prototype}
    49014924psTime *psTimeConvert(psTime *time, psTimeType type);
    4902 \end{verbatim}
     4925\end{prototype}
    49034926
    49044927This function may be used to convert between the various \code{psTimeType} time
    … …  
    49134936positive East of Greenwich) as well:
    49144937
    4915 \begin{verbatim}
     4938\begin{prototype}
    49164939psF64 *psTimeToLMST(psTime *time, psF64 longitude);
    4917 \end{verbatim}
     4940\end{prototype}
    49184941
    49194942The function may accept any of the \code{psTimeType} types with
    … …  
    49264949extract the value of $UT1-UTC$ from the IERS Time Tables:
    49274950
    4928 \begin{verbatim}
     4951\begin{prototype}
    49294952double psTimeGetUT1Delta(const psTime *time, psTimeBulletin bulletin);
    4930 \end{verbatim}
     4953\end{prototype}
    49314954
    49324955The following function provides tidal corrections to UT1-UTC, using
    49334956the Ray model of Simon et al (REF).
    4934 \begin{verbatim}
     4957\begin{prototype}
    49354958psTime *psTime_TideUT1Corr(const psTime *time);
    4936 \end{verbatim}
     4959\end{prototype}
    49374960
    49384961Leap seconds are added to UTC in order to keep it within $0.9s$ of UT1
    … …  
    49414964the absolute number of leap seconds different between two times.
    49424965
    4943 \begin{verbatim}
     4966\begin{prototype}
    49444967long psTimeLeapSecondDelta(const psTime *time1, const psTime *time2);
    4945 \end{verbatim}
     4968\end{prototype}
    49464969
    49474970The following function accepts \code{PS_TIME_UTC} objects and
    … …  
    49494972\code{TRUE} if so.
    49504973
    4951 \begin{verbatim}
     4974\begin{prototype}
    49524975bool psTimeIsLeapSecond(const psTime *utc);
    4953 \end{verbatim}
     4976\end{prototype}
    49544977
    49554978\subsubsection{External Date and Time Formats}
    … …  
    49624985\code{NULL} pointer to be returned.}
    49634986
    4964 \begin{verbatim}
     4987\begin{prototype}
    49654988psF64 psTimeToJD(const psTime *time);
    49664989psF64 psTimeToMJD(const psTime *time);
    49674990char *psTimeToISO(const psTime *time);
    49684991timeval *psTimeToTimeval(const psTime *time);
    4969 \end{verbatim}
     4992\end{prototype}
    49704993
    49714994The \code{psTimeToISO()} function converts \code{PS_TIME_UTC} objects
    … …  
    49785001\code{psTime} type.
    49795002
    4980 \begin{verbatim}
     5003\begin{prototype}
    49815004psTime *psTimeFromJD(psF64 input);
    49825005psTime *psTimeFromMJD(psF64 input);
    … …  
    49855008psTime *psTimeFromUTC(psS64 sec, psU32 nsec, bool leapsecond);
    49865009psTime *psTimeFromTT(psS64 sec, psU32 nsec);
    4987 \end{verbatim}
     5010\end{prototype}
    49885011
    49895012Where \code{psTimeFromUTC()} will validate that it is possible for the input
    … …  
    49935016\subsubsection{Date and Time Math}
    49945017
    4995 \begin{verbatim}
     5018\begin{prototype}
    49965019psTime *psTimeMath(const psTime *time, psF64 delta);
    49975020psF64 psTimeDelta(const psTime *time1, const psTime *time2);
    4998 \end{verbatim}
     5021\end{prototype}
    49995022
    50005023\code{psTimeMath} adds the \code{delta} (in seconds; may be negative) to a
    … …  
    51585181\code{psCube} to represent such an element.
    51595182%
    5160 \begin{verbatim}
     5183\begin{datatype}
    51615184typedef struct {
    51625185    double x;                           ///< x position
    … …  
    51815204    double zErr;                        ///< Error in z
    51825205} psCube;
    5183 \end{verbatim}
     5206\end{datatype}
    51845207
    51855208Three major classes of coordinate transformations are necessary.
    … …  
    52045227
    52055228Constructors for these are straight-forward:
    5206 \begin{verbatim}
     5229\begin{prototype}
    52075230psPlane  *psPlaneAlloc(void);
    52085231psSphere *psSphereAlloc(void);
    52095232psCube   *psCubeAlloc(void);
    5210 \end{verbatim}
     5233\end{prototype}
    52115234Initialization of the structures is not necessary.
    52125235
    … …  
    52265249of these transformations:
    52275250
    5228 \begin{verbatim}
     5251\begin{datatype}
    52295252typedef struct {
    52305253    psDPolynomial2D *x;
    52315254    psDPolynomial2D *y;
    52325255} psPlaneTransform;
    5233 \end{verbatim}
     5256\end{datatype}
    52345257
    52355258The \code{psDPolynomial2D} structures represent polynomials of
    … …  
    52535276lowest two terms are the $x$ and $y$ axis of the target system.  The
    52545277higher two terms may represent color and magnitude terms.
    5255 \begin{verbatim}
     5278\begin{datatype}
    52565279typedef struct {
    52575280    psDPolynomial4D *x;
    52585281    psDPolynomial4D *y;
    52595282} psPlaneDistort;
    5260 \end{verbatim}
     5283\end{datatype}
    52615284
    52625285Like \code{psPlaneTransform}, \code{psPlaneDistort} contains two
    … …  
    52865309dimension.  Both the \code{x} and \code{y} polynomials shall be have
    52875310the same dimensions.
    5288 \begin{verbatim}
     5311\begin{prototype}
    52895312psPlaneTransform *psPlaneTransformAlloc(int n1, int n2);
    52905313psPlaneDistort *psPlaneDistortAlloc(int n1, int n2, int n3, int n4);
    5291 \end{verbatim}
     5314\end{prototype}
    52925315
    52935316We require corresponding functions to apply the transformations to a
    52945317specified coordinate \code{coords}:
    52955318%
    5296 \begin{verbatim}
     5319\begin{prototype}
    52975320psPlane *psPlaneTransformApply(psPlane *out,
    52985321                               const psPlaneTransform *transform,
    … …  
    53025325                             const psPlane *coords,
    53035326                             float mag, float color);
    5304 \end{verbatim}
     5327\end{prototype}
    53055328
    53065329
    53075330The following functions perform operations on transformations:
    53085331
    5309 \begin{verbatim}
     5332\begin{prototype}
    53105333psPlaneTransform *psPlaneTransformInvert(psPlaneTransform *out, const psPlaneTransform *in,
    53115334                                         psRegion region, int nSamples);
    … …  
    53155338bool psPlaneTransformFit(psPlaneTransform *trans, const psArray *source, const psArray *dest,
    53165339                         int nRejIter, float sigmaClip);
    5317 \end{verbatim}
     5340\end{prototype}
    53185341
    53195342\code{psPlaneTransformInvert} shall return the transformation that
    … …  
    53615384transformation with respect to each coordinate.
    53625385
    5363 \begin{verbatim}
     5386\begin{prototype}
    53645387psPlane *psPlaneTransformDeriv(psPlane *out, const psPlaneTransform *transformation, const psPlane *coord);
    5365 \end{verbatim}
     5388\end{prototype}
    53665389
    53675390\code{psPlaneTransformDeriv} shall return the derivatives of the
    … …  
    53745397\code{NULL}.
    53755398
    5376 \begin{verbatim}
     5399\begin{prototype}
    53775400psPixels *psPixelsTransform(psPixels *out, const psPixels *input, const psPlaneTransform *inToOut);
    5378 \end{verbatim}
     5401\end{prototype}
    53795402
    53805403\code{psPixelsTransform} shall generate a list of pixels in the output
    … …  
    54145437way.
    54155438
    5416 \begin{verbatim}
     5439\begin{datatype}
    54175440typedef struct {
    54185441    double q0;
    … …  
    54215444    double q3;
    54225445} psSphereRot;
    5423 \end{verbatim}
     5446\end{datatype}
    54245447
    54255448The constructor is defined as follows:
    5426 \begin{verbatim}
     5449\begin{prototype}
    54275450psSphereRot *psSphereRotAlloc(double alphaP, double deltaP, double phiP);
    5428 \end{verbatim}
     5451\end{prototype}
    54295452where \code{alphaP} and \code{deltaP} define the coordinates in the
    54305453input system of the axis of rotation (the north pole of the output
    … …  
    54365459The \code{psSphereRot} may also be constructed by supplying the
    54375460elements of the quaternion to the following function:
    5438 \begin{verbatim}
     5461\begin{prototype}
    54395462psSphereRot *psSphereRotQuat(double q0, double q1, double q2, double q3);
    5440 \end{verbatim}
     5463\end{prototype}
    54415464This function normalizes the quaternion, so the input elements need
    54425465not be normalized.
    … …  
    54475470if \code{NULL}, is allocated by the function.
    54485471
    5449 \begin{verbatim}
     5472\begin{prototype}
    54505473psSphere *psSphereRotApply(psSphere *out, const psSphereRot *transform, const psSphere *coord);
    5451 \end{verbatim}
     5474\end{prototype}
    54525475
    54535476The following function combines two rotations, to produce a single
    … …  
    54565479allocated if \code{NULL}.
    54575480
    5458 \begin{verbatim}
     5481\begin{prototype}
    54595482psSphereRot *psSphereRotCombine(psSphereRot *out, const psSphereRot *rot1, const psSphereRot *rot2)
    5460 \end{verbatim}
     5483\end{prototype}
    54615484
    54625485The following function changes the given rotation to its inverse:
    54635486
    5464 \begin{verbatim}
     5487\begin{prototype}
    54655488psSphereRot *psSphereRotInvert(psSphereRot *rot)
    5466 \end{verbatim}
     5489\end{prototype}
    54675490
    54685491The 3-vector representation of the angles (\code{psCube}) is needed to
    … …  
    54705493well.  Two utility functions are provided to convert between the
    54715494angular and 3-vector representations:
    5472 \begin{verbatim}
     5495\begin{prototype}
    54735496psSphere *psCubeToSphere(const psCube *cube);
    54745497psCube *psSphereToCube(const psSphere *sphere);
    5475 \end{verbatim}
     5498\end{prototype}
    54765499
    54775500\subsubsection{Offsets}
    … …  
    54885511the offset only.
    54895512
    5490 \begin{verbatim}
     5513\begin{prototype}
    54915514psSphere *psSphereGetOffset(const psSphere *position1,
    54925515                            const psSphere *position2,
    … …  
    54985521                            psSphereOffsetMode mode,
    54995522                            psSphereOffsetUnit unit);
    5500 
     5523\end{prototype}
     5524
     5525\begin{datatype}
    55015526typedef enum {
    55025527    PS_SPHERICAL;                       ///< Offset on a sphere
    … …  
    55105535    PS_RADIAN;                          ///< Radians
    55115536} psSphereOffsetUnit;
    5512 \end{verbatim}
     5537\end{datatype}
    55135538Note that these should propagate the errors appropriately.
    55145539
    … …  
    55205545constructors as well as the above \code{psSphereRotAlloc}.
    55215546%
    5522 \begin{verbatim}
     5547\begin{prototype}
    55235548psSphereRot *psSphereRotICRSToEcliptic(const psTime *time);
    55245549psSphereRot *psSphereRotEclipticToICRS(const psTime *time);
    55255550psSphereRot *psSphereRotICRSToGalactic(void);
    55265551psSphereRot *psSphereRotGalacticToICRS(void);
    5527 \end{verbatim}
     5552\end{prototype}
    55285553
    55295554\subsection{Earth Orientation Calculations}
    … …  
    55815606star, given its \code{actual} position and the velocity vector of the
    55825607observer, represented as a speed and a direction:
    5583 \begin{verbatim}
     5608\begin{prototype}
    55845609psSphere *psAberration(psSphere *apparent, const psSphere *actual, const psSphere *direction, double speed);
    5585 \end{verbatim}
     5610\end{prototype}
    55865611The \code{actual} and \code{apparent} positions are represented as
    55875612\code{psSphere} entries, as is the \code{direction} of motion.  The
    … …  
    55955620The following function calculates the \code{apparent} position of a
    55965621star, given its \code{actual} position and the position of the sun:
    5597 \begin{verbatim}
     5622\begin{prototype}
    55985623psSphere *psGravityDeflection(psSphere *apparent, psSphere *actual, psSphere *sun);
    5599 \end{verbatim}
     5624\end{prototype}
    56005625The \code{actual} and \code{apparent} positions are represented as
    56015626\code{psSphere} entries, as is position of the sun.  If the value of
    … …  
    56055630\paragraph{Parallax}
    56065631
    5607 \begin{verbatim}
     5632\begin{prototype}
    56085633double psEOC_ParallaxFactor(const psSphere *coords, const psTime *time);
    5609 \end{verbatim}
     5634\end{prototype}
    56105635Calculate the parallax factor for the given position and time.
    56115636
    … …  
    56185643representation may be converted to a rotation between the frames.
    56195644
    5620 \begin{verbatim}
     5645\begin{datatype}
    56215646typedef struct {
    56225647  double x;
    … …  
    56245649  double s;
    56255650} psEarthPole;
    5626 \end{verbatim}
     5651\end{datatype}
    56275652
    56285653\paragraph{Precession/Nutation}
    … …  
    56325657IAU2000A precession \& nutation model:
    56335658%
    5634 \begin{verbatim}
     5659\begin{prototype}
    56355660psEarthPole *psEOC_PrecessionModel(const psTime *time)
    5636 \end{verbatim}
     5661\end{prototype}
    56375662%
    56385663The input to this function is the desired \code{time}, which may be
    … …  
    56455670by the IERS, just as it does for UT1 and polar motion.
    56465671
    5647 \begin{verbatim}
     5672\begin{prototype}
    56485673psEarthPole *psEOC_PrecessionCorr(const psTime *time, psTimeBulletin bulletin);
    5649 \end{verbatim}
     5674\end{prototype}
    56505675
    56515676The polar correction is applied to the $X$ and $Y$ elements of the
    56525677rotation to provide higher accuracy.  The spherical rotation term is
    56535678generated by providing the polar coordinate to the following function:
    5654 \begin{verbatim}
     5679\begin{prototype}
    56555680psSphereRot *psSphereRot_CEOtoGCRS(const psEarthPole *pole)
    5656 \end{verbatim}
     5681\end{prototype}
    56575682This function constructs the rotation element as described in the ADD (
    56585683The resulting \code{psSphereRot} may be used to determine the rotation
    … …  
    56635688
    56645689The following routine calculates the rotation of the Earth about the CIP:
    5665 \begin{verbatim}
     5690\begin{prototype}
    56665691psSphereRot *psSphereRot_TEOtoCEO(const psTime *time)
    5667 \end{verbatim}
     5692\end{prototype}
    56685693The IERS code to create the comparable rotation is embedded in
    56695694T2C2000, with the Earth Rotation Angle calculated by ERA2000.
    … …  
    56735698The following function provides interpolated values of the polar
    56745699motion components, $x_p$ and $y_p$, extracted from the IERS tables. 
    5675 \begin{verbatim}
     5700\begin{prototype}
    56765701psEarthPole *psEOC_GetPolarMotion(const psTime *time, psTimeBulletin bulletin);
    5677 \end{verbatim}
     5702\end{prototype}
    56785703
    56795704The following function provides tidal corrections to the polar motion
    56805705components, $x_p$ and $y_p$, using the Ray model of Simon et al (see
    56815706ADD).
    5682 \begin{verbatim}
     5707\begin{prototype}
    56835708psEarthPole *psEOC_PolarTideCorr(const psTime *time);
    5684 \end{verbatim}
     5709\end{prototype}
    56855710
    56865711The following function provides the additional corrections due to nutation
    56875712terms with periods less than or equal to two days, as well as the
    56885713correction to the $s'$ component of the polar motion:
    5689 \begin{verbatim}
     5714\begin{prototype}
    56905715psEarthPole *psEOC_NutationCorr(psTime *time);
    5691 \end{verbatim}
     5716\end{prototype}
    56925717
    56935718The following function converts the polar motion corrections to a
    56945719spherical rotation using the prescription in the ADD:
    5695 \begin{verbatim}
     5720\begin{prototype}
    56965721psSphereRot *psSphereRot_ITRStoTEO(const psEarthPole *motion);
    5697 \end{verbatim}
     5722\end{prototype}
    56985723This function should give identical results to the IERS POM2000
    56995724subroutine.
    … …  
    57055730for either time, it is assumed to have the reference equinox value of
    57065731J2000.
    5707 \begin{verbatim}
     5732\begin{prototype}
    57085733psSphere *psSpherePrecess(const psTime *fromTime, const psTime *toTime, psPrecessMethod mode);
    5709 \end{verbatim}
     5734\end{prototype}
    57105735The mode argument is used to specify the level of detail used in the
    57115736calculation.
    57125737
    5713 \begin{verbatim}
     5738\begin{datatype}
    57145739typedef enum {
    57155740  PS_PRECESS_ROUGH,
    … …  
    57175742  PS_PRECESS_IAU2000A,
    57185743} psPrecessMethod;
    5719 \end{verbatim}
     5744\end{datatype}
    57205745
    57215746\subsection{Atmospheric Effects}
    … …  
    57405765  pre-calculated entries and a separate structure for ATM effect?}
    57415766
    5742 \begin{verbatim}
     5767\begin{datatype}
    57435768typedef struct {
    57445769    const double latitude;              ///< geodetic latitude (radians)
    … …  
    57545779    const double siderealTime;          ///< local apparent sidereal time (radians)
    57555780} psGrommit;
    5756 \end{verbatim}
     5781\end{datatype}
    57575782
    57585783The \code{psGrommit} is calculated from telescope information for the
    57595784particular exposure, \code{exp}:
    5760 \begin{verbatim}
     5785\begin{prototype}
    57615786psGrommit *psGrommitAlloc(const psExposure *exp);
    5762 \end{verbatim}
     5787\end{prototype}
    57635788
    57645789\tbd{these functions probably need to take the ATM structure}
    … …  
    57695794the atmospheric refraction.
    57705795
    5771 \begin{verbatim}
     5796\begin{prototype}
    57725797float psGetAirmass(const psSphere *coord, psTime *lst, float height);
    5773 \end{verbatim}
     5798\end{prototype}
    57745799which returns the airmass for a given position and local sidereal time
    57755800(\code{lst}).
    57765801
    5777 \begin{verbatim}
     5802\begin{prototype}
    57785803float psGetParallactic(const psSphere *coord, double siderealTime);
    5779 \end{verbatim}
     5804\end{prototype}
    57805805which returns the parallactic angle for a given position and sidereal time.
    57815806
    5782 \begin{verbatim}
     5807\begin{prototype}
    57835808float psGetRefraction(float colour,            ///< Colour of object
    57845809                      psPhotSystem colorPlus,  ///< Colour reference
    57855810                      psPhotSystem colorMinus, ///< Colour reference
    57865811                      const psExposure *exp);  ///< Telescope pointing information
    5787 \end{verbatim}
     5812\end{prototype}
    57885813which provides an estimate of the atmospheric refraction, along the parallactic angle.
    57895814
    … …  
    58005825grid.
    58015826
    5802 \begin{verbatim}
     5827\begin{datatype}
    58035828typedef struct {
    58045829    int nX, nY;                         ///< Number of elements in x and y
    … …  
    58075832    double **x, **y;                    ///< The grid of offsets in x and y
    58085833} psFixedPattern;
    5809 \end{verbatim}
     5834\end{datatype}
    58105835
    58115836The constructor for \code{psFixedPattern} shall be:
    5812 \begin{verbatim}
     5837\begin{prototype}
    58135838psFixedPattern *psFixedPatternAlloc(double x0,        double y0,
    58145839                                    double xScale,    double yScale,
    58155840                                    const psImage *x, const psImage *y);
    5816 \end{verbatim}
     5841\end{prototype}
    58175842Here, \code{x0}, \code{y0}, \code{xScale} and \code{yScale} have the
    58185843same meaning as in the \code{psFixedPattern} structure.  Note that the
    … …  
    58385863We specify the following structure \code{psProjection} to define the
    58395864parameters of the projection:
    5840 \begin{verbatim}
     5865\begin{datatype}
    58415866typedef struct {
    58425867    double R, D;                         ///< coordinates of projection center
    … …  
    58445869    psProjectionType type;               ///< projection type
    58455870} psProjection;
    5846 \end{verbatim}
     5871\end{datatype}
    58475872
    58485873The projection type is defined by the following enumerated type \code{psProjectionType}:
    5849 \begin{verbatim}
     5874\begin{datatype}
    58505875typedef enum {                          ///< type of val is:
    58515876    PS_PROJ_TAN,                        ///< Tangent projection
    … …  
    58555880    PS_PROJ_NTYPE                       ///< Number of types; must be last
    58565881} psProjectionType;
    5857 \end{verbatim}
     5882\end{datatype}
    58585883
    58595884The constructor is straight-forward:
    5860 \begin{verbatim}
     5885\begin{prototype}
    58615886psProjection *psProjectionAlloc(double R, double D, double Xs, double Ys, psProjectionType type);
    5862 \end{verbatim}
     5887\end{prototype}
    58635888
    58645889The following functions will project and deproject (respectively)
    58655890spherical coordinates:
    58665891
    5867 \begin{verbatim}
     5892\begin{prototype}
    58685893psPlane  *psProject(const psSphere *coord, const psProjection *projection);
    58695894psSphere *psDeproject(const psPlane *coord, const psProjection *projection);
    5870 \end{verbatim}
     5895\end{prototype}
    58715896
    58725897%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5
    … …  
    58925917a specific camera/detector/filter combination can be associated with
    58935918those components.
    5894 \begin{verbatim}
     5919\begin{datatype}
    58955920typedef struct {
    58965921    const int ID;                       ///< ID number for this photometric system
    … …  
    59005925    const char *detector;               ///< Detector used for photometric system
    59015926} psPhotSystem;
    5902 \end{verbatim}
     5927\end{datatype}
    59035928
    59045929The following structure defines the transformation between two
    59055930photometric systems.
    5906 \begin{verbatim}
     5931\begin{datatype}
    59075932typedef struct {
    59085933    psPhotSystem src;                   ///< Source photometric system
    … …  
    59135938    psPolynomial3D transform;           ///< Transformation from source to destination
    59145939} psPhotTransform;
    5915 \end{verbatim}
     5940\end{datatype}
    59165941
    59175942The transformation between two photometric systems may depend on the
    … …  
    59555980objects, as well as Lunar phase.
    59565981
    5957 \begin{verbatim}
     5982\begin{prototype}
    59585983psSphere *psSunGetPos(psTime *time);
    59595984psTime *psSunGetRise (psTime *twi15, psTime *twi18, const psTime *time);
    … …  
    59685993psTime *psPlanetGetRise (psTime *twi15, psTime *twi18, psTime *time);
    59695994psTime *psPlanetGetSet (psTime *twi15, psTime *twi18, psTime *time);
    5970 \end{verbatim}
     5995\end{prototype}
    59715996
    59725997%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Note: See TracChangeset for help on using the changeset viewer.