Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 4020) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 4021) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.231 2005-05-20 00:43:57 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.232 2005-05-24 23:44:45 jhoblitt Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -195,7 +195,7 @@ as determined from CVS tags. -\begin{verbatim} +\begin{prototype} const char *psLibVersion(void); -\end{verbatim} +\end{prototype} \subsection{Initialization} @@ -211,7 +211,7 @@ The prototype is: -\begin{verbatim} +\begin{prototype} void psLibInit(const char *timeConfig); -\end{verbatim} +\end{prototype} \code{timeConfig} specifies the filename of the configuration file @@ -220,7 +220,7 @@ \subsection{Finalization} -\begin{verbatim} +\begin{prototype} void psFinalize(void); -\end{verbatim} +\end{prototype} \code{psLibFinalize} shall free memory that was allocated by @@ -327,6 +327,6 @@ follows: % -\filbreak -\begin{verbatim} +%\filbreak +\begin{datatype} typedef struct { const void* startblock; ///< initialised to p_psMEMMAGIC @@ -347,5 +347,5 @@ typedef unsigned long psMemoryId; typedef unsigned long psReferenceCount; -\end{verbatim} +\end{datatype} % The PSLib memory management system must maintain the collection of @@ -421,9 +421,9 @@ blocks: % -\begin{verbatim} +\begin{prototype} void *psAlloc(size_t size); void *psRealloc(void *ptr, size_t size); void *psFree(void *ptr); -\end{verbatim} +\end{prototype} % From the user's perspective, the functions \code{psAlloc}, @@ -433,9 +433,9 @@ preprocessor macros which call the following private functions: % -\begin{verbatim} +\begin{prototype} void *p_psAlloc(size_t size, const char *file, int line); void *p_psRealloc(void *ptr, size_t size, const char *file, int line); void p_psFree(void *ptr, const char *file, int line); -\end{verbatim} +\end{prototype} % In these function calls, \code{size} is the number of bytes required @@ -480,8 +480,8 @@ usually insufficient. -\begin{verbatim} +\begin{prototype} void psMemSetDeallocator(void* ptr, psFreeFcn freeFcn); psFreeFcn psMemGetDeallocator(void* ptr); -\end{verbatim} +\end{prototype} A free function handles any deallocation procedures of an object @@ -551,8 +551,11 @@ following form: % -\begin{verbatim} +\begin{datatype} typedef void (*psMemExhaustedCallback)(size_t size); +\end{datatype} + +\begin{prototype} psMemExhaustedCallback psMemExhaustedCallbackSet(psMemExhaustedCallback func); -\end{verbatim} +\end{prototype} % The callback function is called with the attempted size and is @@ -569,8 +572,11 @@ has the following form: % -\begin{verbatim} +\begin{datatype} typedef void (*psMemProblemCallback)(psMemBlock *ptr, char *file, int lineno); +\end{datatype} + +\begin{prototype} psMemProblemCallback psMemProblemCallbackSet(psMemProblemCallback func); -\end{verbatim} +\end{prototype} % This callback may be used to report the error and other status @@ -595,18 +601,27 @@ following two functions: % -\begin{verbatim} +\begin{prototype} psMemoryId psMemAllocateCallbackSetID(psMemoryId id); psMemoryId psMemFreeCallbackSetID(psMemoryId id); -\end{verbatim} +\end{prototype} % The corresponding callbacks have the following form: % -\begin{verbatim} +\begin{datatype} typedef psMemoryId (*psMemAllocateCallback)(const psMemBlock *ptr); +\end{datatype} + +\begin{prototype} psMemAllocateCallback psMemAllocateCallbackSet(psMemAllocateCallback func); +\end{prototype} + +\begin{datatype} typedef psMemoryId (*psMemFreeCallback)(const psMemBlock *ptr); +\end{datatype} + +\begin{prototype} psMemFreeCallback psMemFreeCallbackSet(psMemFreeCallback func); psMemoryId psMemGetId(void); -\end{verbatim} +\end{prototype} % The callback functions are called with a pointer to the corresponding @@ -633,8 +648,8 @@ this part of the memory API are shown below. % -\begin{verbatim} +\begin{prototype} int psMemCheckLeaks(psMemoryId id0, psMemBlock ***array, FILE *fd, bool persistence); int psMemCheckCorruption(bool abort_on_error); -\end{verbatim} +\end{prototype} % The routine \code{psMemCheckLeaks} may be used to check for memory @@ -687,9 +702,9 @@ APIs are: % -\begin{verbatim} +\begin{prototype} psReferenceCount psMemGetRefCounter(const void *vptr); void *psMemIncrRefCounter(const void *vptr); void *psMemDecrRefCounter(void *vptr); -\end{verbatim} +\end{prototype} % The functions all take a pointer to the start of a user block of @@ -812,7 +827,7 @@ its trace level and facility, is: % -\begin{verbatim} +\begin{prototype} void psTrace(const char *facil, int myLevel,...); -\end{verbatim} +\end{prototype} % where the last argument is a printf-style formatting code and possible @@ -826,7 +841,7 @@ following function: % -\begin{verbatim} +\begin{prototype} int psTraceSetLevel(const char *facil, int level); -\end{verbatim} +\end{prototype} % where \code{level} specifies the current trace level for the facility @@ -834,7 +849,7 @@ facility may be determined by the function: % -\begin{verbatim} +\begin{prototype} int psTraceGetLevel(const char *facil); -\end{verbatim} +\end{prototype} % which returns the trace level of the named facility following the @@ -849,7 +864,7 @@ levels of all facilities: % -\begin{verbatim} +\begin{prototype} void psTracePrintLevels(void); -\end{verbatim}. +\end{prototype} % This function prints the hierarchy of trace facilities along with the @@ -914,7 +929,7 @@ The trace may optionally be written to a file on specifying a filename with \code{psTraceSetDestination}: -\begin{verbatim} +\begin{prototype} void psTraceSetDestination(FILE *fp); -\end{verbatim} +\end{prototype} If the \code{fp} is \code{NULL}, then the trace is sent to standard output, otherwise it is sent to the specified file pointer. @@ -940,8 +955,8 @@ A log message is placed in the code with the command: % -\begin{verbatim} +\begin{prototype} void psLogMsg(const char *name, int myLevel, const char *fmt, ...); void psLogMsgV(const char *name, int myLevel, const char *fmt, va_list ap); -\end{verbatim} +\end{prototype} where \code{name} is a word to describe the source of the message, \code{myLevel} is the severity level of this message, and \code{fmt} @@ -954,7 +969,7 @@ the first 4 levels are associated with symbolic names: % -\begin{verbatim} +\begin{datatype} enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO }; -\end{verbatim} +\end{datatype} % @@ -962,7 +977,7 @@ above which log messages are ignored, using the function: % -\begin{verbatim} +\begin{prototype} int psLogSetLevel(int level); -\end{verbatim} +\end{prototype} % This function returns the previous log level. A specific message @@ -974,7 +989,7 @@ Log messages are sent to the destination most recently set using: % -\begin{verbatim} +\begin{prototype} bool psLogSetDestination(const char *dest); -\end{verbatim} +\end{prototype} % The destination string consists of a URL in the form @@ -990,7 +1005,7 @@ The output format is controlled with the function: % -\begin{verbatim} +\begin{prototype} bool psLogSetFormat(const char *fmt); -\end{verbatim} +\end{prototype} % which expects a string consisting of the letters \code{H} (host), @@ -1043,9 +1058,11 @@ \code{psError} prints an error message and doesn't abort, but instead returns the error code. -\begin{verbatim} +\begin{prototype} psErrorCode p_psError(const char *file, int lineno, const char *func, psErrorCode code, bool new, const char *fmt, ...); +\end{prototype} +\begin{datatype} #define psError(code, new, fmt, ...) psError(__FILE__, __LINE__, __func__, code, new, fmt, __VA_ARGS__) -\end{verbatim} +\end{datatype} \code{psError} is a macro definition that allows the filename, line @@ -1066,5 +1083,5 @@ The errors on the error stack are defined as the following: -\begin{verbatim} +\begin{datatype} typedef struct { char *name; ///< category of code that caused the error @@ -1072,5 +1089,5 @@ char *msg; ///< the message associated with the error } psErr; -\end{verbatim} +\end{datatype} The last error reported is available from \code{psErrorLast}; if no @@ -1081,10 +1098,10 @@ The error stack may be completely cleared with \code{psErrorClear}. % -\begin{verbatim} +\begin{prototype} unsigned int psErrorGetStackSize(void); const psErr *psErrorGet(int which); const psErr *psErrorLast(void); void psErrorClear(void); -\end{verbatim} +\end{prototype} \code{psErrorGetStackSize} shall return the number of errors on the @@ -1099,8 +1116,8 @@ \code{psErrorStackPrintV} must not invoke \code{va_end}. % -\begin{verbatim} +\begin{prototype} void psErrorStackPrint(FILE *fd, const char *fmt, ...); void psErrorStackPrintV(FILE *fd, const char *fmt, va_list va); -\end{verbatim} +\end{prototype} Any \code{errorCode}s less then or equal to \code{PS_ERR_BASE} (see @@ -1111,7 +1128,7 @@ The routine \code{psErrorCodeString} returns the string associated with an error code: -\begin{verbatim} +\begin{prototype} const char *psErrorCodeString(psErrorCode code); -\end{verbatim} +\end{prototype} \subsubsection{Error Codes} @@ -1128,14 +1145,14 @@ error codes and associated message strings. An array of error codes may be registered with the PSLib error handler using the function: -\begin{verbatim} +\begin{prototype} void psErrorRegister(const psErrorDescription *errors, int nerror); -\end{verbatim} +\end{prototype} where the errors are represented internally as follows: -\begin{verbatim} +\begin{datatype} typedef struct { psErrorCode code; ///< An error code const char *descrip; ///< the associated description } psErrorDescription; -\end{verbatim} +\end{datatype} PSLib internal errors must be registered with the function \code{psErrorRegister}, which should be called as part of the @@ -1179,5 +1196,5 @@ enumerated type \code{psErrorCode} with elements \code{PS_ERR_NAME} and values as specified in \file{psErrorCodes.dat}, e.g. -\begin{verbatim} +\begin{datatype} #if !defined(PS_ERROR_CODES_H) #define PS_ERROR_CODES_H @@ -1193,5 +1210,5 @@ } psErrorCode; #endif -\end{verbatim} +\end{datatype} Any \code{errorCode}s less then or equal to \code{PS_ERR_BASE} must be @@ -1208,7 +1225,7 @@ \code{PS_LOG_ABORT}, and then call \code{abort}. -\begin{verbatim} +\begin{prototype} void psAbort(const char *name, const char *fmt,...); -\end{verbatim} +\end{prototype} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1260,14 +1277,14 @@ Supported data types must be defined by a structure in which the first element is always of type \code{psType}: -\begin{verbatim} +\begin{datatype} typedef struct { psDimen dimen; ///< The dimensionality psElemType type; ///< The type } psType; -\end{verbatim} +\end{datatype} where \code{psDimen dimen} defines the dimensionality of the data and \code{psElemType type} defines the data type of each element. These two variable types are defined as: -\begin{verbatim} +\begin{datatype} typedef enum { PS_DIMEN_SCALAR, ///< Scalar @@ -1277,7 +1294,7 @@ PS_DIMEN_OTHER ///< Not supported for arithmetic } psDimen; -\end{verbatim} +\end{datatype} and -\begin{verbatim} +\begin{datatype} typedef enum { PS_TYPE_S8, ///< Character @@ -1295,5 +1312,5 @@ PS_TYPE_BOOL ///< Boolean value } psElemType; -\end{verbatim} +\end{datatype} We discuss the application of \code{psType} in more detail in section~\ref{sec:arithmetic}. @@ -1305,5 +1322,5 @@ which interpret the data type from the structure when deciding how to perform an operation. The basic scalar structure is: -\begin{verbatim} +\begin{datatype} typedef struct { psType type; ///< data type information @@ -1319,11 +1336,11 @@ } data; } psScalar; -\end{verbatim} +\end{datatype} In addition, we specify two functions for working with \code{psScalar} data: -\begin{verbatim} +\begin{prototype} psScalar *psScalarAlloc(psC64 value, psElemType dataType); psScalar *psScalarCopy(const psScalar *value); -\end{verbatim} +\end{prototype} The first creates a \code{psType}-ed structure from a constant value, casting it as appropriate based on the \code{dataType}. The second @@ -1340,5 +1357,5 @@ single structure, \code{psVector} to represent these concepts: % -\begin{verbatim} +\begin{datatype} typedef struct { psType type; ///< vector data type and dimension @@ -1360,5 +1377,5 @@ } data; } psVector; -\end{verbatim} +\end{datatype} % In this structure, the argument \code{n} is the length of the array @@ -1372,9 +1389,9 @@ associated with a constructor and reallocator: % -\begin{verbatim} +\begin{prototype} psVector *psVectorAlloc(int nalloc, psElemType type); psVector *psVectorRealloc(psVector *vector, int nalloc); psVector *psVectorRecycle(psVector *vector, int nalloc, psElemType type); -\end{verbatim} +\end{prototype} % In these functions, \code{nalloc} is the number of elements to @@ -1396,7 +1413,7 @@ shall be allocated and returned. -\begin{verbatim} +\begin{prototype} psVector *psVectorExtend(psVector *vector, int delta, int nExtend); -\end{verbatim} +\end{prototype} This function increments \code{psVector.n}, the number of elements in @@ -1408,5 +1425,5 @@ Here is an example of how \code{psVectorExtend} is used to automatically increment the vector length. -\begin{verbatim} +\begin{datatype} // create data vector psVector *y = psVectorAlloc (100); @@ -1419,5 +1436,5 @@ // increments n by 1, extends length if needed by 100 } -\end{verbatim} +\end{datatype} Note that the specification that the allocation always be greater than the number of elements by twice the number of new elements implies @@ -1425,7 +1442,7 @@ elements, as in this example. -\begin{verbatim} +\begin{prototype} psVector *psVectorCopy(psVector *output, const psVector *input, psElemType type); -\end{verbatim} +\end{prototype} \code{psVectorCopy} shall copy the elements in the \code{input} vector @@ -1441,5 +1458,5 @@ value. We require a basic image data type: -\begin{verbatim} +\begin{datatype} typedef struct psImage { psType type; ///< image data type and dimension @@ -1463,5 +1480,5 @@ psArray *children; ///< children of this region } psImage; -\end{verbatim} +\end{datatype} This structure represents an image consisting of a 2-D array of @@ -1485,8 +1502,8 @@ psS16, psU8, psU16, psF32, psF64, psC32, psC64}. -\begin{verbatim} +\begin{prototype} psImage *psImageAlloc (int width, int height, psElemType type); psImage* psImageRecycle(psImage* old, int numCols, int numRows, const psElemType type); -\end{verbatim} +\end{prototype} \code{psImageAlloc} shall create an image of a specified \code{width}, \code{height}, and data @@ -1501,7 +1518,7 @@ shall be allocated and returned. -\begin{verbatim} +\begin{prototype} int psImageFreeChildren(psImage* image); -\end{verbatim} +\end{prototype} \code{psImageFreeChildren} shall free all child images of the given @@ -1515,9 +1532,9 @@ data type testing may be safely performed. -\begin{verbatim} +\begin{datatype} typedef struct { psType type; ///< data type information } psMath; -\end{verbatim} +\end{datatype} \subsection{Simple Arrays} @@ -1526,5 +1543,5 @@ define \code{psArray} to carry such a collection: % -\begin{verbatim} +\begin{datatype} typedef struct { const int n; ///< size of array @@ -1532,5 +1549,5 @@ void **data; ///< pointer to data block } psArray; -\end{verbatim} +\end{datatype} % In this structure, the argument \code{n} is the length of the array @@ -1540,8 +1557,8 @@ destructor: % -\begin{verbatim} +\begin{prototype} psArray *psArrayAlloc(int nalloc); psArray *psArrayRealloc(const psArray *array, int nalloc); -\end{verbatim} +\end{prototype} % In these functions, \code{nalloc} is the number of elements to @@ -1558,7 +1575,7 @@ error. -\begin{verbatim} +\begin{prototype} psArray *psArrayAdd(psArray *array, int delta, const void *value); -\end{verbatim} +\end{prototype} This function adds a value to the end of an array. If the current @@ -1568,7 +1585,7 @@ value is less than 1, 10 shall be used). -\begin{verbatim} +\begin{prototype} psBool psArrayRemove(psArray *array, const psPtr value); -\end{verbatim} +\end{prototype} This function removes all entries of \code{value} in the \code{array}, @@ -1577,8 +1594,8 @@ \code{FALSE}. -\begin{verbatim} +\begin{prototype} psBool psArraySet(psArray* in, psU32 position, const void* value); void* psArrayGet(const psArray* in, psU32 position); -\end{verbatim} +\end{prototype} These accessor functions are provided as a convenience to the user. @@ -1588,7 +1605,7 @@ specified \code{position}. -\begin{verbatim} +\begin{prototype} psArray *psArraySort(psArray *array, int (*compare)(const void **a, const void **b) ); -\end{verbatim} +\end{prototype} An array may be sorted using \code{psArraySort}, which requires the specification of a comparison function to specify how the objects on @@ -1602,5 +1619,5 @@ \PS{} shall support doubly linked lists through a type \code{psList}: % -\begin{verbatim} +\begin{datatype} typedef struct { unsigned int size; ///< number of elements on list @@ -1610,5 +1627,5 @@ pthread_mutex_t lock; ///< mutex to lock a node during changes } psList; -\end{verbatim} +\end{datatype} % The type \code{psList} represents the container of the list. It has a @@ -1621,5 +1638,5 @@ The elements of the list are defined by the type \code{psListElem}: % -\begin{verbatim} +\begin{datatype} typedef struct psListElem { struct psListElem *prev; ///< previous link in list @@ -1627,5 +1644,5 @@ void *data; ///< real data item } psListElem; -\end{verbatim} +\end{datatype} % which includes a pointer to the next element in the list @@ -1634,7 +1651,7 @@ element. The following supporting functions are required: -\begin{verbatim} +\begin{prototype} psList *psListAlloc(const void *data); -\end{verbatim} +\end{prototype} Create a list. This function may take a pointer to a data item, or it may take \code{NULL}. The allocator creates both the \code{psList} @@ -1656,5 +1673,5 @@ Iteration on the list shall be achieved by means of a list iterator type: -\begin{verbatim} +\begin{datatype} typedef struct { psList *list; ///< List iterator works on @@ -1664,5 +1681,5 @@ bool mutable; ///< Is it permissible to modify the list? } psListIterator; -\end{verbatim} +\end{datatype} The \code{psListIterator} keeps track of which list element the iterator \code{cursor} is currently pointing at. \code{index} is the @@ -1678,7 +1695,7 @@ The corresponding constructor shall be: -\begin{verbatim} +\begin{prototype} psListIterator *psListIteratorAlloc(const psList *list, int location, bool mutable); -\end{verbatim} +\end{prototype} Here, \code{list} is the \code{psList} on which the iterator will iterate, and \code{location} is the initial starting point, and may be @@ -1696,7 +1713,7 @@ A list \code{iterator} shall be set to a specific \code{location} on the list upon calling \code{psListIteratorSet}: -\begin{verbatim} +\begin{prototype} bool psListIteratorSet(psListIterator *iterator, int location); -\end{verbatim} +\end{prototype} Again, the \code{location} may be a numerical index or it may be one of the special values: \code{PS_LIST_HEAD} or \code{PS_LIST_TAIL}, @@ -1706,9 +1723,9 @@ otherwise. -\begin{verbatim} +\begin{prototype} bool psListAdd(psList *list, int location, const void *data); bool psListAddAfter(psListIterator *iterator, const void *data); bool psListAddBefore(psListIterator *iterator, const void *data); -\end{verbatim} +\end{prototype} the first function, \code{psListAdd}, adds an entry to the \code{list} and returns a boolean giving the success or failure of the @@ -1724,9 +1741,9 @@ cursor position of the \code{iterator}. -\begin{verbatim} +\begin{prototype} void *psListGet(psList *list, int location); void *psListGetAndIncrement(psListIterator *iterator); void *psListGetAndDecrement(psListIterator *iterator); -\end{verbatim} +\end{prototype} A data item may be retrieved from the list with these functions. The first function, \code{psListGet} simply returns the value specified by @@ -1754,8 +1771,8 @@ longer off the end of the list. -\begin{verbatim} +\begin{prototype} bool psListRemove(psList *list, int location) bool psListRemoveData(psList *list, const void *data); -\end{verbatim} +\end{prototype} A data item may be removed from the list with these functions. For \code{psListRemove}, the value of \code{location} may be the numerical @@ -1773,8 +1790,8 @@ \code{false}. -\begin{verbatim} +\begin{prototype} psArray *psListToArray(const psList *list); psList *psArrayToList(const psArray *array); -\end{verbatim} +\end{prototype} These two functions are available to convert between the \code{psList} and \code{psArray} containers. These functions do not @@ -1782,7 +1799,7 @@ increment the reference counter for each of the elements. -\begin{verbatim} +\begin{prototype} psList *psListSort(psList *list, int (*compare)(const void **a, const void **b) ); -\end{verbatim} +\end{prototype} A list may be sorted using \code{psListSort}, which requires the specification of a comparison function to specify how the objects on @@ -1814,10 +1831,10 @@ table at any one time.} % -\begin{verbatim} +\begin{datatype} typedef struct { int nbucket; ///< number of buckets psHashBucket **buckets; ///< the buckets themselves } psHash; -\end{verbatim} +\end{datatype} % where \code{nbucket} is the number of buckets defined for the hash @@ -1825,5 +1842,5 @@ individual buckets, each of which is defined by: % -\begin{verbatim} +\begin{datatype} typedef struct psHashBucket { char *key; ///< key for this item of data @@ -1831,5 +1848,5 @@ struct psHashBucket *next; ///< list of other possible keys } psHashBucket; -\end{verbatim} +\end{datatype} where each bucket contains the value of the \code{key}, a pointer to the \code{data}, and a pointer to the \code{next} list entry in the @@ -1837,7 +1854,7 @@ A hash table is created with the following function: -\begin{verbatim} +\begin{prototype} psHash *psHashAlloc(int nbuckets); -\end{verbatim} +\end{prototype} which allocates the space for the hash table, creating and initializing \code{nbuckets} hash buckets. @@ -1846,7 +1863,7 @@ A data item may be added to the hash table with the function: -\begin{verbatim} +\begin{prototype} bool psHashAdd(psHash *table, const char *key, const void *data); -\end{verbatim} +\end{prototype} In this function, the value of the string \code{key} is used to construct the hash value, find the appropriate bucket set, and add the @@ -1857,26 +1874,26 @@ The data associated with a given key may be found with the function: -\begin{verbatim} +\begin{prototype} void *psHashLookup(const psHash *table, const char *key); -\end{verbatim} +\end{prototype} which returns the data value pointed to by the element associated with \code{key}, or the value \code{NULL} if no match is found. Similarly, a specific key may be removed (deleted) with the function: -\begin{verbatim} +\begin{prototype} bool psHashRemove(psHash *table, const char *key); -\end{verbatim} +\end{prototype} The function returns a value of \code{true} if the operation was successfull, and \code{false} otherwise. The function -\begin{verbatim} +\begin{prototype} psList *psHashKeyList(const psHash *table); -\end{verbatim} +\end{prototype} returns the complete list of defined keys associated with the \code{psHash} table as a linked list. -\begin{verbatim} +\begin{prototype} psArray *psHashToArray(const psHash *hash); -\end{verbatim} +\end{prototype} This function places the data in a \code{psHash} into a \code{psArray} container. This function does not free the elements or destroy the @@ -1896,7 +1913,7 @@ generally useful, and so we specify a separate function that may be called independently: -\begin{verbatim} +\begin{prototype} psArray *psVectorsReadFromFile(const char *filename, const char *format); -\end{verbatim} +\end{prototype} \code{psVectorsReadFromFile} shall return an array of \code{psVector}s, read from the specified \code{filename}. The file @@ -1911,6 +1928,5 @@ is to be skipped. - -\begin{verbatim} +\begin{datatype} typedef struct { const char *filename; ///< File from which data is to be read @@ -1921,5 +1937,5 @@ const psF64 validFrom, validTo; ///< Range of validity } psLookupTable; -\end{verbatim} +\end{datatype} \code{filename} shall specify the file from which the lookup table @@ -1938,10 +1954,10 @@ The constructor shall be: -\begin{verbatim} +\begin{prototype} psLookupTable *psLookupTableAlloc(const char *filename, ///< File from which to read const char *format ///< scanf-like format string int indexCol ///< Column of the index vector (starting at zero) ); -\end{verbatim} +\end{prototype} This function shall allocate a \code{psLookupTable}, and set the appropriate values, but it shall not read the lookup table. This is @@ -1951,10 +1967,10 @@ The destructor shall free all the components. -\begin{verbatim} +\begin{prototype} psLookupTable *psLookupTableImport(psLookupTable *table, ///< Lookup table into which to import const psArray *vectors, ///< Array of vectors int indexCol ///< Index of the index vector in the array of vectors ); -\end{verbatim} +\end{prototype} \code{psLookupTableImport} shall import an array of vectors into a \code{table}. If \code{table} is \code{NULL}, a new @@ -1971,7 +1987,7 @@ function returning. -\begin{verbatim} +\begin{prototype} int psLookupTableRead(psLookupTable *table); -\end{verbatim} +\end{prototype} \code{psLookupTableRead} combines \code{psVectorsReadFromFile} and \code{psLookupTableImport} to read the appropriate file and import the @@ -1983,8 +1999,8 @@ Interpolation on a lookup table is performed by the following functions: -\begin{verbatim} +\begin{prototype} psF64 psLookupTableInterpolate(const psLookupTable *table, psF64 index, int column, psLookupStatusType *status); psVector *psLookupTableInterpolateAll(const psLookupTable *table, psF64 index, psVector *stats); -\end{verbatim} +\end{prototype} Both functions shall interpolate the \code{table} at the provided \code{index}. For \code{psLookupTableInterpolate}, only the value in @@ -2029,15 +2045,15 @@ \code{ceil(n/8)} bytes must be allocated. The bitset structure is define by: -\begin{verbatim} +\begin{datatype} typedef struct { int n; ///< Number of chars that form the bitset char *bits; ///< The bits } psBitSet; -\end{verbatim} +\end{datatype} We also require the corresponding constructor and destructor: -\begin{verbatim} +\begin{prototype} psBitSet *psBitSetAlloc(int n); -\end{verbatim} +\end{prototype} where \code{n} is the requested number of bits. @@ -2051,5 +2067,5 @@ The corresponding APIs are defined below: -\begin{verbatim} +\begin{prototype} psBitSet *psBitSetSet(psBitSet *myBits, int bit); psBitSet* psBitSetClear(psBitSet* inBits, int bit); @@ -2058,5 +2074,5 @@ bool psBitSetTest(const psBitSet *checkBits, int bit); char *psBitSetToString(const pBitSet* bits); -\end{verbatim} +\end{prototype} \code{psBitSetSet} sets the specified \code{bit} in the @@ -2095,7 +2111,7 @@ psF64}. The input and output vectors must have the same type. -\begin{verbatim} +\begin{prototype} psVector *psVectorSort(psVector *out, const psVector *in); -\end{verbatim} +\end{prototype} We also require the ability to sort one vector based on another. For @@ -2109,7 +2125,7 @@ input types \code{psS8, psU16, psF32, psF64}. -\begin{verbatim} +\begin{prototype} psVector *psVectorSortIndex(psVector *out; const psVector *in); -\end{verbatim} +\end{prototype} The sorted vectors may be accessed in the following manner: @@ -2153,5 +2169,5 @@ function: -\begin{verbatim} +\begin{prototype} psStats *psVectorStats(psStats *stats, const psVector *in, @@ -2160,5 +2176,5 @@ unsigned int maskVal ); -\end{verbatim} +\end{prototype} % This function takes the input data in \code{in} (with optional @@ -2192,5 +2208,5 @@ desired statistical quantities: -\begin{verbatim} +\begin{datatype} /** generic statistics structure */ typedef struct { @@ -2218,9 +2234,9 @@ psStatsOptions options; ///< bitmask of calculated values } psStats; -\end{verbatim} +\end{datatype} where \code{psStatsOptions} is defined with entries to turn on the calculation of each of the statistics: -\begin{verbatim} +\begin{datatype} /** statistics which may be calculated */ typedef enum { @@ -2241,11 +2257,11 @@ PS_STAT_USE_BINSIZE = 0x004000 } psStatsOptions; -\end{verbatim} +\end{datatype} A constructor is also required: % -\begin{verbatim} +\begin{prototype} psStats *psStatsAlloc(psStatsOptions options); -\end{verbatim} +\end{prototype} \subsubsection{Histograms} @@ -2255,5 +2271,5 @@ upper and lower bounds for each of the bins. We define the following data structure to represent a histogram: -\begin{verbatim} +\begin{datatype} typedef struct { const psVector *bounds; ///< Bounds for the bins @@ -2262,5 +2278,5 @@ bool uniform; ///< Is it a uniform distribution? } psHistogram; -\end{verbatim} +\end{datatype} In this structure, the vector \code{bounds} specifies the boundaries of the histogram bins, and must of type \code{psF32}, while @@ -2277,7 +2293,7 @@ with the size of the bins. -\begin{verbatim} +\begin{prototype} psHistogram *psHistogramAlloc(float lower, float upper, int n); -\end{verbatim} +\end{prototype} where \code{lower} specifies the lower bound of the histogram range, \code{upper} specified the upper bound of the histogram range, and @@ -2287,7 +2303,7 @@ A histogram with a more flexible bin set may be constructed with the following constructor: -\begin{verbatim} +\begin{prototype} psHistogram *psHistogramAllocGeneric(const psVector *bounds); -\end{verbatim} +\end{prototype} where the \code{psVector *bounds} (of type \code{psF32}) is defined by the user to specify the boundaries of the histogram bins. This @@ -2297,5 +2313,5 @@ vector (\code{values}), and optionally the \code{errors} in the input values. It alters and returns the histogram \code{out} structure. -\begin{verbatim} +\begin{prototype} psHistogram *psVectorHistogram(psHistogram *out, const psVector *values, @@ -2303,5 +2319,5 @@ const psVector *mask, unsigned int maskVal); -\end{verbatim} +\end{prototype} The \code{values} vector may be of types \code{psU8, psU16, psF32, psF64}, with the \code{errors} vector of the corresponding type. @@ -2330,5 +2346,5 @@ This leads us to define the following polynomial types: -\begin{verbatim} +\begin{datatype} /** One-dimensional polynomial */ typedef struct { @@ -2339,7 +2355,7 @@ char *mask; ///< Coefficient mask } psPolynomial1D; -\end{verbatim} - -\begin{verbatim} +\end{datatype} + +\begin{datatype} /** Two-dimensional polynomial */ typedef struct { @@ -2350,5 +2366,5 @@ char **mask; ///< Coefficients mask } psPolynomial2D; -\end{verbatim} +\end{datatype} etc., up to four dimensions. \code{psPolynomialType} is an @@ -2356,14 +2372,14 @@ or Chebyshev: -\begin{verbatim} +\begin{datatype} typedef enum { PS_POLYNOMIAL_ORD, ///< Ordinary polynomial PS_POLYNOMIAL_CHEB ///< Chebyshev polynomial } psPolynomialType; -\end{verbatim} +\end{datatype} We also define double-precision versions of the polynomials: -\begin{verbatim} +\begin{datatype} /** Double-precision one-dimensional polynomial */ typedef struct { @@ -2374,7 +2390,7 @@ char *mask; ///< Coefficient mask } psDPolynomial1D; -\end{verbatim} - -\begin{verbatim} +\end{datatype} + +\begin{datatype} /** Double-precision two-dimensional polynomial */ typedef struct { @@ -2385,5 +2401,5 @@ char **mask; ///< Coefficients mask } psDPolynomial2D; -\end{verbatim} +\end{datatype} etc. In what follows, we only show the version for double-precision @@ -2392,7 +2408,7 @@ The constructor is: -\begin{verbatim} +\begin{prototype} psDPolynomial2D *psDPolynomial2DAlloc(int nX, int nY, psPolynomialType type); -\end{verbatim} +\end{prototype} where \code{nX} and \code{nY} are the number of terms in x and y respectively. The coefficients, errors and masks are set initially to @@ -2400,12 +2416,12 @@ To evaluate the polynomials at specific coordinates, we define: -\begin{verbatim} +\begin{prototype} double psDPolynomial2DEval(const psDPolynomial2D *myPoly, double x, double y); -\end{verbatim} +\end{prototype} In the event that several evaluations are required, we also define: -\begin{verbatim} +\begin{prototype} psVector *psDPolynomial2DEvalVector(const psDPolynomial2D *myPoly, const psVector *x, const psVector *y); -\end{verbatim} +\end{prototype} If the \code{x} and \code{y} vectors do not match the precision of the polynomial, the function shall generate a warning, and convert the @@ -2425,5 +2441,5 @@ incorporated into PSLib: -\begin{verbatim} +\begin{datatype} typedef struct { int n; ///< Number of spline pieces @@ -2431,5 +2447,5 @@ psVector *knots; ///< The boundaries between each spline piece. Size is n+1. } psSpline1D; -\end{verbatim} +\end{datatype} The \code{psSpline1D} structure consists of an array of \code{n} @@ -2444,8 +2460,8 @@ Of course, we require the appropriate constructors and destructor: -\begin{verbatim} +\begin{prototype} psSpline1D *psSpline1DAlloc(int n, int order, float min, float max); psSpline1D *psSpline1DAllocGeneric(const psVector *bounds, int order); -\end{verbatim} +\end{prototype} \code{psSpline1DAlloc} shall allocate and return a \code{psSpline1D}, @@ -2469,8 +2485,8 @@ for an input vector of ordinates. -\begin{verbatim} +\begin{prototype} float psSpline1DEval(const psSpline1D *spline, float x); psVector *psSpline1DEvalVector(const psSpline1D *spline, const psVector *x); -\end{verbatim} +\end{prototype} \subsubsection{Gaussians} @@ -2481,7 +2497,7 @@ The Gaussian evaluation is provide by: -\begin{verbatim} +\begin{prototype} float psGaussian(float x, float mean, float sigma, bool normal); -\end{verbatim} +\end{prototype} which evaluates a Gaussian with the given \code{mean} and \code{sigma} at the given coordinate \code{x}. If \code{normal} is true, the @@ -2517,5 +2533,5 @@ (\code{lastDelta}). -\begin{verbatim} +\begin{datatype} typedef struct { const int maxIter; ///< Maximum number of iterations @@ -2525,10 +2541,10 @@ float lastDelta; ///< Last change before quitting } psMinimization; -\end{verbatim} +\end{datatype} The corresponding allocator is: -\begin{verbatim} +\begin{prototype} psMinimization *psMinimizationAlloc(int maxIter, float tol); -\end{verbatim} +\end{prototype} \subsubsection{Levenberg-Marquardt} @@ -2539,7 +2555,7 @@ parameters and coordinate vectors, along with the derivatives of the function with respect to each of the parameters, \code{deriv}: -\begin{verbatim} +\begin{datatype} typedef float (*psMinimizeLMChi2Func)(psVector *deriv, const psVector *params, const psVector *x); -\end{verbatim} +\end{datatype} Then \code{psMinimizeLMChi2} shall fit the specified function, @@ -2547,9 +2563,9 @@ Levenberg-Marquardt method: -\begin{verbatim} +\begin{prototype} bool psMinimizeLMChi2(psMinimization *min, psImage *covar, psVector *params, const psVector *paramMask, const psArray *x, const psVector *y, const psVector *yErr, psMinimizeLMChi2Func func); -\end{verbatim} +\end{prototype} The function shall return \code{false} in the event that there was an @@ -2594,8 +2610,8 @@ %% minimization, used for the purpose of performing $\chi^2$ fitting: -%% \begin{verbatim} +%% \begin{prototype} %% psMinimizeLMChi2Func psMinimizeLMChi2Gauss1D; %% psMinimizeLMChi2Func psMinimizeLMChi2Gauss2D; -%% \end{verbatim} +%% \end{prototype} %% \code{psMinimizeChi2LMGauss1D} shall take as \code{params}, the @@ -2620,15 +2636,15 @@ the parameters and coordinate vectors, but now the derivatives are not known: -\begin{verbatim} +\begin{datatype} typedef float (*psMinimizePowellFunc)(const psVector *params, const psArray *coords); -\end{verbatim} +\end{datatype} Then \code{psMinimizePowell} shall minimize the specified function, \code{func}, using the Powell method: -\begin{verbatim} +\begin{prototype} bool psMinimizePowell(psMinimization *min, psVector *params, const psVector *paramMask, const psArray *coords, psMinimizePowellFunc func); -\end{verbatim} +\end{prototype} The inputs and general behavior of this function is the same as for @@ -2641,11 +2657,13 @@ general functions to data. -\begin{verbatim} +\begin{datatype} typedef psVector* (*psMinimizeChi2PowellFunc)(const psVector *params, const psArray *coords); - +\end{datatype} + +\begin{prototype} bool psMinimizeChi2Powell(psMinimization *min, psVector *params, const psVector *paramMask, const psArray *coords, const psVector *value, const psVector *error, psMinimizeChi2PowellFunc model); -\end{verbatim} +\end{prototype} The inputs and general behavior of \code{psMinimizeChi2Powell} is @@ -2672,8 +2690,8 @@ \subsubsection{Analytical fits} -\begin{verbatim} +\begin{prototype} psPolynomial1D *psVectorFitPolynomial1D(psPolynomial1D *myPoly, const psVector *x, const psVector *y, const psVector *yErr); -\end{verbatim} +\end{prototype} \code{psVectorFitPolynomial1d} returns the polynomial that best fits the observations. The input parameters are a polynomial that specifies @@ -2686,7 +2704,7 @@ function must be valid only for types \code{psF32}, \code{psF64}. -\begin{verbatim} +\begin{prototype} psSpline1D *psVectorFitSpline1D(const psVector *x, const psVector *y, int nKnots); -\end{verbatim} +\end{prototype} \code{psVectorFitSpline1D} shall return the spline that best fits the given combination of ordinates (\code{x}) and coordinates (\code{y}). @@ -2710,5 +2728,5 @@ In many places, we need to refer to a rectangular area. We define a structure to represent a rectangle: -\begin{verbatim} +\begin{datatype} typedef struct { float x0; @@ -2717,5 +2735,5 @@ float y1; } psRegion; -\end{verbatim} +\end{datatype} This structure is used in psLib as an abbreviation for the four floats, and is defined statically. Functions which accept or return a @@ -2731,9 +2749,9 @@ \code{psRegion} to the corresponding IRAF description. -\begin{verbatim} +\begin{prototype} psRegion psRegionSet(float x0, float x1, float y0, float y1); psRegion psRegionFromString(const char *region); char *psRegionToString(const psRegion region); -\end{verbatim} +\end{prototype} All functions which use a psRegion must interpret the definition of @@ -2748,7 +2766,7 @@ \subsubsection{Image Structure Manipulation} -\begin{verbatim} +\begin{prototype} psImage *psImageSubset(psImage *image, psRegion region); -\end{verbatim} +\end{prototype} Define a subimage of the specified area of the given image. This function must raise an error if the requested subset area lies outside @@ -2766,7 +2784,7 @@ \code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. -\begin{verbatim} +\begin{prototype} psImage *psImageCopy(psImage *output, const psImage *input, psElemType type); -\end{verbatim} +\end{prototype} Create a copy of the specified image, converting the type in the process. If the output target pointer is not \code{NULL}, place the @@ -2778,7 +2796,7 @@ \code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. -\begin{verbatim} +\begin{prototype} psImage *psImageTrim(psImage *image, psRegion region); -\end{verbatim} +\end{prototype} Trim the specified \code{image} in-place, which involves shuffling the pixels around in memory. The region to be kept is defined by the @@ -2797,5 +2815,5 @@ \subsubsection{Image Pixel Extractions} -\begin{verbatim} +\begin{datatype} typedef enum { PS_CUT_X_POS, ///< Cut in positive x direction @@ -2804,5 +2822,7 @@ PS_CUT_Y_NEG ///< Cut in negative y direction } psImageCutDirection; - +\end{datatype} + +\begin{prototype} psVector *psImageSlice(psVector *out, psVector *coords, @@ -2813,5 +2833,5 @@ psImageCutDirection direction, const psStats *stats); -\end{verbatim} +\end{prototype} Extract pixels from rectilinear region to a vector (array of floats). The output vector contains either \code{region.x1-region.x0} or @@ -2839,5 +2859,5 @@ \code{psF32}, \code{psF64}. -\begin{verbatim} +\begin{prototype} psVector *psImageCut(psVector *out, psVector *coords, @@ -2848,5 +2868,5 @@ unsigned int nSamples, psImageInterpolateMode mode); -\end{verbatim} +\end{prototype} Extract pixels along a line segment, \code{(region.x0,region.y0)} to \code{(region.x1,region.y1)}, on the image to a vector of the same @@ -2860,5 +2880,5 @@ \code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}. -\begin{verbatim} +\begin{prototype} psVector *psImageRadialCut(psVector *out, const psImage *input, @@ -2869,5 +2889,5 @@ const psVector *radii, const psStats *stats); -\end{verbatim} +\end{prototype} Extract radial region data to a vector. A vector is constructed where each vector elements is derived from the statistics of the pixels @@ -2889,5 +2909,5 @@ specification of the interpolation scheme to be used. This information is carried by the following enum: -\begin{verbatim} +\begin{datatype} typedef enum { PS_INTERPOLATE_FLAT, @@ -2901,5 +2921,5 @@ PS_INTERPOLATE_LANCZOS4_VARIANCE } psImageInterpolateMode mode; -\end{verbatim} +\end{datatype} The first five are fairly straightforward. The last four, however, @@ -2912,10 +2932,10 @@ the noise (adding in quadrature). -\begin{verbatim} +\begin{prototype} psImage *psImageRebin(psImage *out, const psImage *in, const psImage *mask, unsigned int maskVal, int scale, const psStats *stats); -\end{verbatim} +\end{prototype} Rebin image to new scale. A new image is constructed in which the dimensions are reduced by a factor of \code{1 / scale}. The @@ -2935,8 +2955,8 @@ \code{psU16}, \code{psF32} and \code{psF64}. -\begin{verbatim} +\begin{prototype} psImage *psImageResample(psImage *out, const psImage *in, int scale, psImageInterpolateMode mode); -\end{verbatim} +\end{prototype} Resample image to new scale. A new image is constructed in which the dimensions are increased by a factor of \code{scale}. The @@ -2946,8 +2966,8 @@ pixels using the specified interpolation method (\code{mode}). -\begin{verbatim} +\begin{prototype} psImage *psImageRotate(psImage *out, const psImage *input, float angle, psC64 exposed, psImageInterpolateMode mode); -\end{verbatim} +\end{prototype} Rotate the input image by given angle, specified in radians. The output image must contain all of the pixels from the input image in @@ -2960,8 +2980,8 @@ \code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. -\begin{verbatim} +\begin{prototype} psImage *psImageShift(psImage *out, const psImage *input, float dx, float dy, psC64 exposed, psImageInterpolateMode mode); -\end{verbatim} +\end{prototype} Shift image by an arbitrary number of pixels (\code{dx,dy}) in either direction. If the shift values are fractional, the output pixel @@ -2974,7 +2994,7 @@ \code{psF64}, \code{psC32}, \code{psC64}. -\begin{verbatim} +\begin{prototype} psImage *psImageRoll(psImage *out, const psImage *input, int dx, int dy); -\end{verbatim} +\end{prototype} Roll image by an integer number of pixels (\code{dx,dy}) in either direction. The output image is the same dimensions as the input @@ -2984,5 +3004,5 @@ \code{psC32}, \code{psC64}. -\begin{verbatim} +\begin{prototype} psImage *psImageTransform(psImage *output, psArray **blankPixels, @@ -2995,5 +3015,5 @@ psImageInterpolateMode mode, double exposedValue); -\end{verbatim} +\end{prototype} Transform the \code{input} image according the supplied transformation. The size of the transformed image is defined by the @@ -3027,10 +3047,10 @@ \subsubsection{Image Statistical Functions} -\begin{verbatim} +\begin{prototype} psStats *psImageStats(psStats *stats, const psImage *in, const psImage *mask, unsigned int maskVal); -\end{verbatim} +\end{prototype} Determine statistics for image (or subimage). The statistics to be determined are specified by \code{stats}. The \code{mask} allows @@ -3040,10 +3060,10 @@ \code{psF64}. -\begin{verbatim} +\begin{prototype} psHistogram *psImageHistogram(psHistogram *out, const psImage *in, const psImage *mask, unsigned int maskVal); -\end{verbatim} +\end{prototype} Construct a histogram from an image (or subimage). The histogram to generate is specified by \code{psHistogram hist} (see @@ -3054,7 +3074,7 @@ \code{psF64}. -\begin{verbatim} +\begin{prototype} psPolynomial2D *psImageFitPolynomial(psPolynomial2D *coeffs, const psImage *input); -\end{verbatim} +\end{prototype} Fit a 2-D Chebychev polynomial surface to an image. The input structure \code{coeffs} contains the desired order and terms of @@ -3062,7 +3082,7 @@ following types: \code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}. -\begin{verbatim} +\begin{prototype} psImage *psImageEvalPolynomial(psImage *input, const psPolynomial2D *coeffs); -\end{verbatim} +\end{prototype} Evaluate a 2-D polynomial surface for the image pixels. Given the input polynomial coefficients, set the image pixel values on the basis @@ -3070,9 +3090,9 @@ following types: \code{psS8}, \code{psU16}, \code{psF32}, \code{psF64}. -\begin{verbatim} +\begin{prototype} psC64 psImagePixelInterpolate(const psImage *input, float x, float y, const psImage *mask, unsigned int maskVal, psC64 unexposedValue, psImageInterpolateMode mode); -\end{verbatim} +\end{prototype} Perform interpolation of image pixel values to the given fractional coordinate \code{x,y}. The function returns the interpolated value of @@ -3087,7 +3107,7 @@ \subsubsection{Image Pixel Manipulations} -\begin{verbatim} +\begin{prototype} int psImageClip(psImage *input, double min, double vmin, double max, double vmax); -\end{verbatim} +\end{prototype} Clip image values outside of range to given values. All pixels with values \code{< min} are set to the value \code{vmin}. All pixels with @@ -3106,8 +3126,8 @@ 0.0 for the imaginary component. -\begin{verbatim} +\begin{prototype} int psImageClipComplexRegion(psImage *input, complex double min, complex double vmin, complex double max, complex double vmax); -\end{verbatim} +\end{prototype} Clip image values outside of range to given values. All pixels with values \code{< min} are set to the value \code{vmin}. All pixels with @@ -3124,7 +3144,7 @@ \code{min} or \code{max} to be out of range. -\begin{verbatim} +\begin{prototype} int psImageClipNaN(psImage *input, float value); -\end{verbatim} +\end{prototype} Clip \code{NaN} image pixels to given value. Pixels with \code{NaN}, \code{+Inf} or \code{-Inf} values are set to the specified value. @@ -3135,8 +3155,8 @@ set to the specified value. -\begin{verbatim} +\begin{prototype} int psImageOverlaySection(psImage *image, const psImage *overlay, int x0, int y0, const char *op); -\end{verbatim} +\end{prototype} Overlay subregion of image with another image. Replace the pixels in the \code{image} which correspond to the pixels in \code{overlay} with @@ -3154,8 +3174,8 @@ \subsubsection{Mask operations} -\begin{verbatim} +\begin{prototype} psImage *psImageGrowMask(psImage *out, const psImage *in, unsigned int maskVal, unsigned int growSize, unsigned int growValue); -\end{verbatim} +\end{prototype} \code{psImageGrowMask} grows specified values on the input mask image, @@ -3184,5 +3204,5 @@ through an entire mask image checking each pixel. -\begin{verbatim} +\begin{datatype} typedef struct { int x; // x coordinate @@ -3195,10 +3215,10 @@ psPixelCoord *data; // The pixel coordinates } psPixels; -\end{verbatim} - -\begin{verbatim} +\end{datatype} + +\begin{prototype} psPixels *psPixelsAlloc(int nalloc); psPixels *psPixelsRealloc(psPixels *pixels, int nalloc); -\end{verbatim} +\end{prototype} \code{psPixelsAlloc} and \code{psPixelsRealloc} provide dynamic @@ -3206,8 +3226,8 @@ by \code{psVectorAlloc} and \code{psVectorRealloc}. -\begin{verbatim} +\begin{prototype} psImage *psPixelsToMask(psImage *out, const psPixels *pixels, const psRegion region, unsigned int maskVal); psPixels *psPixelsFromMask(psPixels *out, const psImage *mask, unsigned int maskVal); -\end{verbatim} +\end{prototype} \code{psPixelsToMask} shall return an image of type U8 with the @@ -3228,8 +3248,8 @@ \code{NULL}. -\begin{verbatim} +\begin{prototype} psPixels *psPixelsCopy(psPixels *out, const psPixels *pixels); psPixels *psPixelsConcatenate(psPixels *out, const psPixels *pixels); -\end{verbatim} +\end{prototype} \code{psPixelsCopy} shall copy the contents of \code{pixels} to the @@ -3259,8 +3279,8 @@ specify two generic APIs for the binary and unary operations. -\begin{verbatim} +\begin{prototype} psType *psBinaryOp(void *out, const void *in1, const char *op, const void *in2); psType *psUnaryOp(void *out, const void *in, const char *op); -\end{verbatim} +\end{prototype} These functions determine the type of the operands on the basis of their \code{psType} elements, which always are the first elements. @@ -3359,8 +3379,8 @@ In the event of an error, the matrix functions shall return \code{NULL}. -\begin{verbatim} +\begin{prototype} psImage *psMatrixLUD(psImage *out, psVector **perm, const psImage *in); psVector *psMatrixLUSolve(psVector *out, const psImage *LU, const psVector *RHS, const psVector *perm); -\end{verbatim} +\end{prototype} The above functions decompose a matrix, \code{in}, into its $LU$ representation (\code{psMatrixLUD}, which returns the decomposed @@ -3378,7 +3398,7 @@ \code{NULL} on calling \code{psMatrixLUD}. -\begin{verbatim} +\begin{prototype} psImage *psMatrixInvert(psImage *out, const psImage *in, float *determinant); -\end{verbatim} +\end{prototype} \code{psMatrixInvert} returns the inverse of the specified matrix (\code{in}), along with the \code{determinant}, if the \code{float} @@ -3390,27 +3410,27 @@ the specified matrix, \code{in}. This function is specified for data types \code{psF32, psF64}. -\begin{verbatim} +\begin{prototype} float psMatrixDeterminant(const psImage *in); -\end{verbatim} +\end{prototype} Matrix multiplication is supported through \code{psMatrixMultiply}. This function is specified for data types \code{psF32, psF64}. -\begin{verbatim} +\begin{prototype} psImage *psMatrixMultiply(psImage *out, const psImage *in1, const psImage *in2); -\end{verbatim} +\end{prototype} The transpose of an input matrix, \code{in}, is returned by \code{psMatrixTranspose}, optionally into the provided matrix \code{out}. This function is specified for data types \code{psF32,psF64}. -\begin{verbatim} +\begin{prototype} psImage *psMatrixTranspose(psImage *out, const psImage *in); -\end{verbatim} +\end{prototype} Eigenvectors of a matrix are calculated by \code{psMatrixEigenvectors}. This function is specified for data types \code{psF32, psF64}. Input and output data types should match. -\begin{verbatim} +\begin{prototype} psImage *psMatrixEigenvectors(psImage *out, const psImage *in); -\end{verbatim} +\end{prototype} \tbd{Should this return an array of vectors? Specified here as currently implemented by MHPCC.} @@ -3422,8 +3442,8 @@ for data types \code{psF32, psF64}. Input and output data types should match. -\begin{verbatim} +\begin{prototype} psVector *psMatrixToVector(psVector *out, const psImage *in); psImage *psVectorToMatrix(psImage *out, const psVector *in); -\end{verbatim} +\end{prototype} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3436,5 +3456,5 @@ library. We define the following APIs to support FFT operations on vectors: -\begin{verbatim} +\begin{prototype} psVector *psVectorFFT(psVector *out, const psVector *in, psFFTFlags direction); psVector *psVectorReal(psVector *out, const psVector *in); @@ -3443,5 +3463,5 @@ psVector *psVectorConjugate(psVector *out, const psVector *in); psVector *psVectorPowerSpectrum(psVector *out, const psVector *in); -\end{verbatim} +\end{prototype} The forward and reverse FFT is calculated using \code{psVectorFFT}, @@ -3471,5 +3491,5 @@ by an enumerated type, \code{psFFTFlags}: -\begin{verbatim} +\begin{datatype} /** Specify direction of FFT, and if the result is real or not */ typedef enum { @@ -3480,5 +3500,5 @@ ///< parameter should appear as PS_FFT_REVERSE+PS_FFT_REAL_RESULT. } psFFTFlags; -\end{verbatim} +\end{datatype} The entry \code{PS_FFT_REAL_RESULT} means that the output of an @@ -3496,5 +3516,5 @@ In analogy with the vector FFT operations, we also define matching image operations as follows: -\begin{verbatim} +\begin{prototype} psImage *psImageFFT(psImage *out, const psImage *image, psFFTFlags direction); psImage *psImageReal(psImage *out, const psImage *in); @@ -3503,5 +3523,5 @@ psImage *psImageConjugate(psImage *out, const psImage *in); psImage *psImagePowerSpectrum(psImage *out, const psImage *in); -\end{verbatim} +\end{prototype} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3528,5 +3548,5 @@ \code{psImage} operations. We define a \code{psKernel}: -\begin{verbatim} +\begin{datatype} /** A convolution kernel */ typedef struct { @@ -3537,5 +3557,5 @@ float **p_kernelRows; ///< Pointer to the rows of the kernel data } psKernel; -\end{verbatim} +\end{datatype} The kernel data is carried primarily by the \code{data} member which @@ -3557,7 +3577,7 @@ Of course, we require the appropriate constructor: -\begin{verbatim} +\begin{prototype} psKernel *psKernelAlloc(int xMin, int xMax, int yMin, int yMax); -\end{verbatim} +\end{prototype} \code{psKernelAlloc} shall allocate a kernel. In the event that one @@ -3571,8 +3591,8 @@ guiding), \code{psKernelGenerate} shall return the appropriate kernel. The API shall be the following: -\begin{verbatim} +\begin{prototype} psKernel *psKernelGenerate(const psVector *tShifts, const psVector *xShifts, const psVector *yShifts, bool relative); -\end{verbatim} +\end{prototype} The vectors \code{xShifts} and \code{yShifts}, which are a list of @@ -3595,7 +3615,7 @@ \code{in}, with the kernel, \code{kernel} and return the convolved image, \code{out}. The API shall be the following: -\begin{verbatim} +\begin{prototype} psImage *psImageConvolve(psImage *out, const psImage *in, const psKernel *kernel, bool direct); -\end{verbatim} +\end{prototype} Two methods shall be available for the convolution: if \code{direct} @@ -3625,5 +3645,5 @@ expansion in the future, depending upon user requirements. -\begin{verbatim} +\begin{datatype} typedef enum { PS_RANDOM_TAUS ///< A maximally equidistributed combined Tausworthe generator @@ -3634,5 +3654,5 @@ gsl_rng *gsl; ///< The RNG itself } psRandom; -\end{verbatim} +\end{datatype} We require the ability to seed the random number generator (RNG) with @@ -3640,8 +3660,8 @@ may be reproduced. -\begin{verbatim} +\begin{prototype} psRandom *psRandomAlloc(psRandomType type, unsigned long seed); void psRandomReset(psRandom *rand, unsigned long seed); -\end{verbatim} +\end{prototype} \code{psRandomAlloc} shall construct a new instance of \code{psRandom} @@ -3653,9 +3673,9 @@ \code{psLogMsg} with a level of \code{PS_LOG_INFO}. -\begin{verbatim} +\begin{prototype} double psRandomUniform(const psRandom *r); double psRandomGaussian(const psRandom *r); double psRandomPoisson(const psRandom *r, double mean); -\end{verbatim} +\end{prototype} \code{psRandomUniform} shall return random numbers uniformly @@ -3785,5 +3805,5 @@ We define an item of metadata with the following structure: \filbreak -\begin{verbatim} +\begin{datatype} typedef struct { const psS32 id; ///< unique ID for this item @@ -3800,5 +3820,5 @@ char *comment; ///< optional comment ("", not NULL) } psMetadataItem; -\end{verbatim} +\end{datatype} The \code{id} is a unique identifier for this item of metadata; @@ -3814,5 +3834,5 @@ % \filbreak -\begin{verbatim} +\begin{datatype} typedef enum { ///< type of item.data is: PS_META_S32 = PS_TYPE_S32, ///< psS32 primitive data. @@ -3834,5 +3854,5 @@ PS_META_MULTI ///< Used internally, do not create a metadata item of this type. } psMetadataType; -\end{verbatim} +\end{datatype} The macro \code{PS_META_IS_PRIMITIVE(psMetadataType.type)} returns true if the type is one of the primitive data types (S32, F64, etc). @@ -3841,10 +3861,10 @@ A collection of metadata is represented by the \code{psMetadata} structure: -\begin{verbatim} +\begin{datatype} typedef struct { psList *list; ///< list of psMetadataItem psHash *table; ///< hash table of the same metadata } psMetadata; -\end{verbatim} +\end{datatype} The type \code{psMetadata} is a container class for metadata. Note that there are in fact \emph{two} representations of the metadata @@ -3873,5 +3893,5 @@ As a convenience to the user, the following type-specific functions are also defined: -\begin{verbatim} +\begin{prototype} psMetadataItem* psMetadataItemAllocStr(const char* name, const char* comment, const char* value); psMetadataItem* psMetadataItemAllocF32(const char* name, const char* comment, psF32 value); @@ -3879,11 +3899,11 @@ psMetadataItem* psMetadataItemAllocS32(const char* name, const char* comment, psS32 value); psMetadataItem* psMetadataItemAllocBool(const char* name, const char* comment, psBool value); -\end{verbatim} +\end{prototype} \subsubsection{Metadata APIs} -\begin{verbatim} +\begin{prototype} psMetadata *psMetadataAlloc(void); -\end{verbatim} +\end{prototype} The constructor for the collection of metadata, \code{psMetadata}, @@ -3892,8 +3912,8 @@ free each of the \code{psMetadataItem}s. -\begin{verbatim} +\begin{prototype} psMetadataItem *psMetadataItemAlloc(const char *name, psMetadataType type, const char *comment, ...); psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type, const char *comment, va_list list); -\end{verbatim} +\end{prototype} The allocator for \code{psMetadataItem} returns a full @@ -3911,10 +3931,10 @@ in the function. -\begin{verbatim} +\begin{prototype} bool psMetadataAddItem(psMetadata *md, const psMetadataItem *item, int location, int mode); bool psMetadataAdd(psMetadata *md, int location, const char *name, int format, const char *comment, ...); bool psMetadataAddV(psMetadata *md, int location, const char *name, int format, const char *comment, va_list list); -\end{verbatim} +\end{prototype} Items may be added to the metadata in one of two ways --- firstly, an @@ -3939,5 +3959,5 @@ % -\begin{verbatim} +\begin{datatype} typedef enum { ///< option flags for psMetadata functions PS_META_DEFAULT, ///< default behavior (0x0000) for use in mode above @@ -3945,5 +3965,5 @@ PS_META_DUPLICATE_OK, ///< allow entry to be replaced } psMetadataFlags; -\end{verbatim} +\end{datatype} The functions above take option flags which modify the behavior when @@ -4021,5 +4041,5 @@ As a convenience to the user, the following type-specific functions are specified: -\begin{verbatim} +\begin{prototype} psBool psMetadataAddS32(psMetadata* md, psS32 location, const char* name, const char* comment, psS32 value); psBool psMetadataAddF32(psMetadata* md, psS32 location, const char* name, const char* comment, psF32 value); @@ -4041,5 +4061,5 @@ psBool psMetadataAddMetadata(psMetadata* md, psS32 location, const char* name, const char* comment, const psMetadata* value); -\end{verbatim} +\end{prototype} @@ -4054,13 +4074,13 @@ returned. % -\begin{verbatim} +\begin{prototype} bool psMetadataRemove(psMetadata *md, int location, const char *key); -\end{verbatim} +\end{prototype} Items may be found within the metadata by providing a key. In the event that the key is non-unique, the first item is returned. -\begin{verbatim} +\begin{prototype} psMetadataItem *psMetadataLookup(const psMetadata *md, const char *key); -\end{verbatim} +\end{prototype} Several utility functions are provided for simple cases. These @@ -4069,27 +4089,27 @@ found. If the pointer value of \code{status} is not \code{NULL}, it is set to reflect the success or failure of the lookup. -\begin{verbatim} +\begin{prototype} void *psMetadataLookupPtr(bool *status, const psMetadata *md, const char *key); psS32 psMetadataLookupS32(bool *status, const psMetadata *md, const char *key); psF32 psMetadataLookupF32(bool *status, const psMetadata *md, const char *key); psF64 psMetadataLookupF64(bool *status, const psMetadata *md, const char *key); -\end{verbatim} +\end{prototype} Items may be retrieved from the metadata by their entry position. The value of which specifies the desired entry in the fashion of \code{psList}. -\begin{verbatim} +\begin{prototype} psMetadataItem *psMetadataGet(const psMetadata *md, int location); -\end{verbatim} +\end{prototype} The metadata list component may be iterated over by using a \code{psMetadataIterator} in a fashion equivalent to the \code{psListIterator}: -\begin{verbatim} +\begin{datatype} typedef struct { psListIterator* iter; ///< iterator for the psMetadata's psList regex_t* regex; ///< the subsetting regular expression } psMetadataIterator; -\end{verbatim} +\end{datatype} The iterator may be set to a location in the \code{psMetadata} list, @@ -4104,10 +4124,10 @@ defined by \code{location}, which follows the conventions of the \code{psList} iterators. -\begin{verbatim} +\begin{prototype} psMetadataIterator *psMetadataIteratorAlloc(psMetadata *md, int location, const char *regex); bool psMetadataIteratorSet(psMetadataIterator *iterator, int location); psMetadataItem *psMetadataGetAndIncrement(psMetadataIterator *iterator); psMetadataItem *psMetadataGetAndDecrement(psMetadataIterator *iterator); -\end{verbatim} +\end{prototype} Metadata items may be printed to an open file descriptor based on a @@ -4119,7 +4139,7 @@ for a string (\%s type of command). If the metadata type is any other data type, printing is not allowed. -\begin{verbatim} +\begin{prototype} bool psMetadataItemPrint(FILE *fd, const char *format, const psMetadataItem *md); -\end{verbatim} +\end{prototype} \subsubsection{Configuration files} @@ -4131,7 +4151,7 @@ function \code{psMetadataConfigParse}, as described below. -\begin{verbatim} +\begin{prototype} psMetadata *psMetadataConfigParse(psMetadata *md, int *nFail, const char *filename, bool overwrite); -\end{verbatim} +\end{prototype} Given a metadata container, \code{md}, and the name of a configuration @@ -4150,8 +4170,8 @@ configuration. -\begin{verbatim} +\begin{prototype} char *psMetadataConfigFormat(psMetadata *md); bool psMetadataConfigWrite(psMetadata *md, const char *filename); -\end{verbatim} +\end{prototype} The \code{psMetadataConfigFormat} function converts a \code{psMetadata} @@ -4365,30 +4385,33 @@ document in memory. We wrap the \code{libxml2} version of an XML document pointer for now: -\begin{verbatim} +\begin{datatype} typedef xmlDocPtr psXMLDoc; +\end{datatype} + +\begin{prototype} void psXMLDocFree(psXMLDoc *doc); -\end{verbatim} +\end{prototype} The next pair of functions convert a \code{psMetadata} data structure to a complete \code{psXMLDoc} (in memory) and vice versa: -\begin{verbatim} +\begin{prototype} psXMLDoc *psMetadataToXMLDoc(const psMetadata *metadata); psMetadata *psXMLDocToMetadata(const psXMLDoc *doc); -\end{verbatim} +\end{prototype} The next pair of functions loads the data in a named file into a complete \code{psXMLDoc} (in memory) and write out the \code{psXMLDoc} to a named file: -\begin{verbatim} +\begin{prototype} psXMLDoc *psXMLParseFile(const char *filename); int psXMLDocToFile(const psXMLDoc *doc, const char *filename); -\end{verbatim} +\end{prototype} The next pair of functions accepts a block of memory and parses it into a complete \code{psXMLDoc} (also in memory), and vice versa: -\begin{verbatim} +\begin{prototype} psXMLDoc *psXMLParseMemory(const char *buffer, const int size); int psXMLDocToMemory(const psXMLDoc *doc, char *buffer); -\end{verbatim} +\end{prototype} The next pair of functions read from and write to a file descriptor. @@ -4396,8 +4419,8 @@ (also in memory), the second writes the \code{psXMLDoc} to the file descriptor: -\begin{verbatim} +\begin{prototype} psXMLDoc *psXMLParseFD(int fd); int psXMLDocToFD(const psXMLDoc *doc, int fd); -\end{verbatim} +\end{prototype} \subsection{Database Functions} @@ -4428,13 +4451,13 @@ database connection: -\begin{verbatim} +\begin{datatype} typedef struct { MYSQL *mysql; } psDB; -\end{verbatim} +\end{datatype} The following collection of functions provides basic database functionality: -\begin{verbatim} +\begin{prototype} // wraps mysql_init() & mysql_real_connect() psDB *psDBInit(const char *host, const char *user, const char *passwd, const char *dbname); @@ -4451,5 +4474,5 @@ // wraps mysql_drop_db() bool psDBDrop(psDB *dbh, const char *dbname); -\end{verbatim} +\end{prototype} For MySQL support, \code{psDBInit()} wraps \code{mysql_init()} and @@ -4476,7 +4499,7 @@ table and as part of the query restrictions. -\begin{verbatim} +\begin{prototype} bool psDBCreateTable(psDB *dbh, const char *tableName, const psMetadata *md); -\end{verbatim} +\end{prototype} This function generates and executes the SQL needed to create a table @@ -4503,13 +4526,13 @@ whitespace. The \code{comment} field is otherwise ignored. -\begin{verbatim} +\begin{prototype} bool psDBDropTable(psDB *dbh, const char *tableName); -\end{verbatim} +\end{prototype} This function deletes the specified table. -\begin{verbatim} +\begin{prototype} bool p_psDBRunQuery(psDB *dbh, const char *query); -\end{verbatim} +\end{prototype} This function will execute a string as a raw SQL query. No additional @@ -4517,8 +4540,8 @@ dialect is provided. -\begin{verbatim} +\begin{prototype} psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, const psU64 limit); psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, psMetadataType type, const psU64 limit); -\end{verbatim} +\end{prototype} These functions generates and executes the SQL needed to select an entire @@ -4529,7 +4552,7 @@ (NULL) if the requested field is not a numerical type. -\begin{verbatim} +\begin{prototype} psArray *psDBSelectRows(psDB *dbh, const char *tableName, psMetadata *where, const psU64 limit); -\end{verbatim} +\end{prototype} This function returns rows from the specified table which match @@ -4542,7 +4565,7 @@ \code{psArray} of \code{psMetadata} values, one per row. -\begin{verbatim} +\begin{prototype} bool psDBInsertOneRow(psDB *dbh, const char *tableName, const psMetadata *row); -\end{verbatim} +\end{prototype} Insert the data from \code{row} into \code{tableName}. It should be noted in @@ -4550,20 +4573,20 @@ in \code{tablename}, the insert will fail. -\begin{verbatim} +\begin{prototype} bool psDBInsertRows(psDB *dbh, const char *tableName, const psArray *rowSet); -\end{verbatim} +\end{prototype} Similar to \code{psDBInsertOneRow()}, this function inserts many rows at once and is atomic for the complete set of rows. -\begin{verbatim} +\begin{prototype} psArray *psDBDumpRows(psDB *dbh, const char *tableName); -\end{verbatim} +\end{prototype} Fetch all rows as an psArray of psMetadata. -\begin{verbatim} +\begin{prototype} psMetadata *psDBDumpCols(psDB *dbh, const char *tableName); -\end{verbatim} +\end{prototype} Fetch all columns, as either a psVector or a psArray depending on whether or not @@ -4571,7 +4594,7 @@ psMetadataItem.name contains the column's name. -\begin{verbatim} +\begin{prototype} psS64 psDBUpdateRows(psDB *dbh, const char *tableName, const psMetadata *where, const psMetadata *values); -\end{verbatim} +\end{prototype} Update the columns contained in \code{values} in the row(s) that have a field @@ -4582,7 +4605,7 @@ an additional constraint. e.g. ``where foo = x and where bar = y'' -\begin{verbatim} +\begin{prototype} psS64 psDBDeleteRows(psDB *dbh, const char *tableName, const psMetadata *where); -\end{verbatim} +\end{prototype} Delete the rows that are matched by \code{where} using the same semantics for @@ -4603,9 +4626,9 @@ be the most basic versions. -\begin{verbatim} +\begin{datatype} typedef struct { fitsfile fd; } psFits; -\end{verbatim} +\end{datatype} We begin by defining a datatype to wrap the CFITSIO \code{fitsfile} structure. This is necessary to allow repeated access to the data in @@ -4614,13 +4637,13 @@ \subsubsection{FITS File Manipulations} -\begin{verbatim} +\begin{prototype} psFits *psFitsAlloc(const char *filename); -\end{verbatim} +\end{prototype} Opens a FITS file at positions the pointer to the PHU. -\begin{verbatim} +\begin{prototype} bool psFitsMoveExtName(psFits *fits, const char *extname); -\end{verbatim} +\end{prototype} Positions the pointer to the beginning of the specified @@ -4628,7 +4651,7 @@ shall fail. -\begin{verbatim} +\begin{prototype} bool psFitsMoveExtNum(psFits* fits, int extnum, bool relative); -\end{verbatim} +\end{prototype} Moves the pointer to the beginning of the specified HDU number. If @@ -4637,26 +4660,26 @@ extended data segments start at number 1. -\begin{verbatim} +\begin{prototype} int psFitsGetExtNum(psFits* fits); -\end{verbatim} +\end{prototype} Returns the current HDU number (i.e., file position). -\begin{verbatim} +\begin{prototype} int psFitsGetSize(psFits* fits); -\end{verbatim} +\end{prototype} Returns the number of HDUs in the file. -\begin{verbatim} +\begin{prototype} psFitsType psFitsGetExtType(psFits* fits); -\end{verbatim} +\end{prototype} Gets the current HDU's type (table or image). -\begin{verbatim} +\begin{prototype} char *psFitsGetExtName(psFits* fits); bool psFitsSetExtName(psFits* fits, const char* name); -\end{verbatim} +\end{prototype} \code{psFitsGetExtName} shall return the name of the current extension @@ -4668,14 +4691,14 @@ \subsubsection{FITS Header I/O Functions} -\begin{verbatim} +\begin{prototype} psMetadata *psFitsReadHeader(psMetadata *out, psFits *fits); -\end{verbatim} +\end{prototype} Read header data into a \code{psMetadata} structure. The data is read from the current HDU pointed at by the \code{psFits *fits} entry. If \code{out} is \code{NULL}, a new psMetadata is created. -\begin{verbatim} +\begin{prototype} psMetadata *psFitsReadHeaderSet (psFits *fits); -\end{verbatim} +\end{prototype} Load a complete set of headers from the \code{psFits} file pointer. This function loads the headers from all extensions into a @@ -4688,7 +4711,7 @@ called. -\begin{verbatim} +\begin{prototype} bool psFitsWriteHeader(psMetadata *output, psFits *fits); -\end{verbatim} +\end{prototype} Write metadata into the header of a FITS image file. The header is written at the current HDU. @@ -4696,7 +4719,7 @@ \subsubsection{FITS Image I/O Functions} -\begin{verbatim} +\begin{prototype} psImage *psFitsReadImage(psImage *output, psFits *fits, psRegion region, int z); -\end{verbatim} +\end{prototype} Read an image or subimage from the \code{psFits} file pointer. This function is a wrapper to the CFITSIO library function. The input @@ -4715,7 +4738,7 @@ type as needed with \code{psImageCopy}. -\begin{verbatim} +\begin{prototype} bool psFitsUpdateImage(psFits *fits, const psImage *input, psRegion region, int z); -\end{verbatim} +\end{prototype} Write an image section to the open \code{psFits} file pointer. This operation may write a portion of an image over the existing bytes of @@ -4732,7 +4755,7 @@ successful operation and 1 for an error. -\begin{verbatim} +\begin{prototype} bool psFitsWriteImage(psFits *fits, const psMetadata *header, const psImage *input, int depth); -\end{verbatim} +\end{prototype} Create a new image based on the dimensions specified for the image and the requested depth. The header and image data segments are written @@ -4746,7 +4769,7 @@ \subsubsection{FITS Table I/O Functions} -\begin{verbatim} +\begin{prototype} psMetadata *psFitsReadTableRow (psFits *fits, int row); -\end{verbatim} +\end{prototype} This function reads a single row of the table in the extension pointed at by the \code{psFits} file pointer. The row number to be read is @@ -4760,7 +4783,7 @@ the file pointer location, for that matter).} -\begin{verbatim} +\begin{prototype} void *psFitsReadTableRowRaw (int *nBytes, psFits *fits, int row); -\end{verbatim} +\end{prototype} This function reads a single row of the table in the extension pointed at by the \code{psFits} file pointer. The row number to be read is @@ -4773,7 +4796,7 @@ somewhere (and the file pointer location, for that matter).} -\begin{verbatim} +\begin{prototype} psArray *psFitsReadTableColumn (psFits *fits, const char *colname); -\end{verbatim} +\end{prototype} This function reads a single column of the table in the extension pointed at by the \code{psFits} file pointer. The column is specified @@ -4782,7 +4805,7 @@ column per array element. -\begin{verbatim} +\begin{prototype} psVector *psFitsReadTableColumnNum (psFits *fits, const char *colname); -\end{verbatim} +\end{prototype} This function reads a single column of the table in the extension pointed at by the \code{psFits} file pointer. The column is specified @@ -4792,7 +4815,7 @@ per array element. -\begin{verbatim} +\begin{prototype} psArray *psFitsReadTableRaw (int *nBytes, psFits *fits); -\end{verbatim} +\end{prototype} This function reads the entire data block from a table into the a \code{psArray}, with one element of the array per row. The number of @@ -4801,7 +4824,7 @@ description of the table data in the table header. -\begin{verbatim} +\begin{prototype} psArray *psFitsReadTable (psFits *fits); -\end{verbatim} +\end{prototype} This function reads the entire data block from a table into the a \code{psArray}, with one element of the array per row. Each row is @@ -4809,14 +4832,14 @@ \code{psFitsReadTableRow}. -\begin{verbatim} +\begin{prototype} bool psFitsWriteTable(psFits* fits, const psMetadata *header, const psArray* table); -\end{verbatim} +\end{prototype} Accepts a \code{psArray} of \code{psMetadata} and writes it to the current HDU. If the current HDU is not a table type, this will fail and return FALSE. -\begin{verbatim} +\begin{prototype} bool psFitsUpdateTable(psFits* fits, const psMetadata* data, int row); -\end{verbatim} +\end{prototype} Writes the \code{psMetadata} data to a FITS table at the specified row in the current HDU. If the current HDU is not a table type, this will @@ -4859,5 +4882,5 @@ \subsubsection{Data Types} -\begin{verbatim} +\begin{datatype} typedef enum { PS_TIME_TAI, ///< seconds since 1970-01-01T00:00:00Z (Gregorian), SI seconds @@ -4878,5 +4901,5 @@ psTimeType type; ///< type of time } psTime; -\end{verbatim} +\end{datatype} \subsubsection{Constructors} @@ -4884,13 +4907,13 @@ To allocate a new, initialized to zero, \code{psTime}: -\begin{verbatim} +\begin{prototype} psTime *psTimeAlloc(psTimeType type); -\end{verbatim} +\end{prototype} To allocate a new \code{psTime} set to the current time (in the given system): -\begin{verbatim} +\begin{prototype} psTime *psTimeGetNow(psTimeType type); -\end{verbatim} +\end{prototype} \subsubsection{Time Conversion} @@ -4898,7 +4921,7 @@ Converting between the \code{psTime} time systems is done with: -\begin{verbatim} +\begin{prototype} psTime *psTimeConvert(psTime *time, psTimeType type); -\end{verbatim} +\end{prototype} This function may be used to convert between the various \code{psTimeType} time @@ -4913,7 +4936,7 @@ positive East of Greenwich) as well: -\begin{verbatim} +\begin{prototype} psF64 *psTimeToLMST(psTime *time, psF64 longitude); -\end{verbatim} +\end{prototype} The function may accept any of the \code{psTimeType} types with @@ -4926,13 +4949,13 @@ extract the value of $UT1-UTC$ from the IERS Time Tables: -\begin{verbatim} +\begin{prototype} double psTimeGetUT1Delta(const psTime *time, psTimeBulletin bulletin); -\end{verbatim} +\end{prototype} The following function provides tidal corrections to UT1-UTC, using the Ray model of Simon et al (REF). -\begin{verbatim} +\begin{prototype} psTime *psTime_TideUT1Corr(const psTime *time); -\end{verbatim} +\end{prototype} Leap seconds are added to UTC in order to keep it within $0.9s$ of UT1 @@ -4941,7 +4964,7 @@ the absolute number of leap seconds different between two times. -\begin{verbatim} +\begin{prototype} long psTimeLeapSecondDelta(const psTime *time1, const psTime *time2); -\end{verbatim} +\end{prototype} The following function accepts \code{PS_TIME_UTC} objects and @@ -4949,7 +4972,7 @@ \code{TRUE} if so. -\begin{verbatim} +\begin{prototype} bool psTimeIsLeapSecond(const psTime *utc); -\end{verbatim} +\end{prototype} \subsubsection{External Date and Time Formats} @@ -4962,10 +4985,10 @@ \code{NULL} pointer to be returned.} -\begin{verbatim} +\begin{prototype} psF64 psTimeToJD(const psTime *time); psF64 psTimeToMJD(const psTime *time); char *psTimeToISO(const psTime *time); timeval *psTimeToTimeval(const psTime *time); -\end{verbatim} +\end{prototype} The \code{psTimeToISO()} function converts \code{PS_TIME_UTC} objects @@ -4978,5 +5001,5 @@ \code{psTime} type. -\begin{verbatim} +\begin{prototype} psTime *psTimeFromJD(psF64 input); psTime *psTimeFromMJD(psF64 input); @@ -4985,5 +5008,5 @@ psTime *psTimeFromUTC(psS64 sec, psU32 nsec, bool leapsecond); psTime *psTimeFromTT(psS64 sec, psU32 nsec); -\end{verbatim} +\end{prototype} Where \code{psTimeFromUTC()} will validate that it is possible for the input @@ -4993,8 +5016,8 @@ \subsubsection{Date and Time Math} -\begin{verbatim} +\begin{prototype} psTime *psTimeMath(const psTime *time, psF64 delta); psF64 psTimeDelta(const psTime *time1, const psTime *time2); -\end{verbatim} +\end{prototype} \code{psTimeMath} adds the \code{delta} (in seconds; may be negative) to a @@ -5158,5 +5181,5 @@ \code{psCube} to represent such an element. % -\begin{verbatim} +\begin{datatype} typedef struct { double x; ///< x position @@ -5181,5 +5204,5 @@ double zErr; ///< Error in z } psCube; -\end{verbatim} +\end{datatype} Three major classes of coordinate transformations are necessary. @@ -5204,9 +5227,9 @@ Constructors for these are straight-forward: -\begin{verbatim} +\begin{prototype} psPlane *psPlaneAlloc(void); psSphere *psSphereAlloc(void); psCube *psCubeAlloc(void); -\end{verbatim} +\end{prototype} Initialization of the structures is not necessary. @@ -5226,10 +5249,10 @@ of these transformations: -\begin{verbatim} +\begin{datatype} typedef struct { psDPolynomial2D *x; psDPolynomial2D *y; } psPlaneTransform; -\end{verbatim} +\end{datatype} The \code{psDPolynomial2D} structures represent polynomials of @@ -5253,10 +5276,10 @@ lowest two terms are the $x$ and $y$ axis of the target system. The higher two terms may represent color and magnitude terms. -\begin{verbatim} +\begin{datatype} typedef struct { psDPolynomial4D *x; psDPolynomial4D *y; } psPlaneDistort; -\end{verbatim} +\end{datatype} Like \code{psPlaneTransform}, \code{psPlaneDistort} contains two @@ -5286,13 +5309,13 @@ dimension. Both the \code{x} and \code{y} polynomials shall be have the same dimensions. -\begin{verbatim} +\begin{prototype} psPlaneTransform *psPlaneTransformAlloc(int n1, int n2); psPlaneDistort *psPlaneDistortAlloc(int n1, int n2, int n3, int n4); -\end{verbatim} +\end{prototype} We require corresponding functions to apply the transformations to a specified coordinate \code{coords}: % -\begin{verbatim} +\begin{prototype} psPlane *psPlaneTransformApply(psPlane *out, const psPlaneTransform *transform, @@ -5302,10 +5325,10 @@ const psPlane *coords, float mag, float color); -\end{verbatim} +\end{prototype} The following functions perform operations on transformations: -\begin{verbatim} +\begin{prototype} psPlaneTransform *psPlaneTransformInvert(psPlaneTransform *out, const psPlaneTransform *in, psRegion region, int nSamples); @@ -5315,5 +5338,5 @@ bool psPlaneTransformFit(psPlaneTransform *trans, const psArray *source, const psArray *dest, int nRejIter, float sigmaClip); -\end{verbatim} +\end{prototype} \code{psPlaneTransformInvert} shall return the transformation that @@ -5361,7 +5384,7 @@ transformation with respect to each coordinate. -\begin{verbatim} +\begin{prototype} psPlane *psPlaneTransformDeriv(psPlane *out, const psPlaneTransform *transformation, const psPlane *coord); -\end{verbatim} +\end{prototype} \code{psPlaneTransformDeriv} shall return the derivatives of the @@ -5374,7 +5397,7 @@ \code{NULL}. -\begin{verbatim} +\begin{prototype} psPixels *psPixelsTransform(psPixels *out, const psPixels *input, const psPlaneTransform *inToOut); -\end{verbatim} +\end{prototype} \code{psPixelsTransform} shall generate a list of pixels in the output @@ -5414,5 +5437,5 @@ way. -\begin{verbatim} +\begin{datatype} typedef struct { double q0; @@ -5421,10 +5444,10 @@ double q3; } psSphereRot; -\end{verbatim} +\end{datatype} The constructor is defined as follows: -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRotAlloc(double alphaP, double deltaP, double phiP); -\end{verbatim} +\end{prototype} where \code{alphaP} and \code{deltaP} define the coordinates in the input system of the axis of rotation (the north pole of the output @@ -5436,7 +5459,7 @@ The \code{psSphereRot} may also be constructed by supplying the elements of the quaternion to the following function: -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRotQuat(double q0, double q1, double q2, double q3); -\end{verbatim} +\end{prototype} This function normalizes the quaternion, so the input elements need not be normalized. @@ -5447,7 +5470,7 @@ if \code{NULL}, is allocated by the function. -\begin{verbatim} +\begin{prototype} psSphere *psSphereRotApply(psSphere *out, const psSphereRot *transform, const psSphere *coord); -\end{verbatim} +\end{prototype} The following function combines two rotations, to produce a single @@ -5456,13 +5479,13 @@ allocated if \code{NULL}. -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRotCombine(psSphereRot *out, const psSphereRot *rot1, const psSphereRot *rot2) -\end{verbatim} +\end{prototype} The following function changes the given rotation to its inverse: -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRotInvert(psSphereRot *rot) -\end{verbatim} +\end{prototype} The 3-vector representation of the angles (\code{psCube}) is needed to @@ -5470,8 +5493,8 @@ well. Two utility functions are provided to convert between the angular and 3-vector representations: -\begin{verbatim} +\begin{prototype} psSphere *psCubeToSphere(const psCube *cube); psCube *psSphereToCube(const psSphere *sphere); -\end{verbatim} +\end{prototype} \subsubsection{Offsets} @@ -5488,5 +5511,5 @@ the offset only. -\begin{verbatim} +\begin{prototype} psSphere *psSphereGetOffset(const psSphere *position1, const psSphere *position2, @@ -5498,5 +5521,7 @@ psSphereOffsetMode mode, psSphereOffsetUnit unit); - +\end{prototype} + +\begin{datatype} typedef enum { PS_SPHERICAL; ///< Offset on a sphere @@ -5510,5 +5535,5 @@ PS_RADIAN; ///< Radians } psSphereOffsetUnit; -\end{verbatim} +\end{datatype} Note that these should propagate the errors appropriately. @@ -5520,10 +5545,10 @@ constructors as well as the above \code{psSphereRotAlloc}. % -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRotICRSToEcliptic(const psTime *time); psSphereRot *psSphereRotEclipticToICRS(const psTime *time); psSphereRot *psSphereRotICRSToGalactic(void); psSphereRot *psSphereRotGalacticToICRS(void); -\end{verbatim} +\end{prototype} \subsection{Earth Orientation Calculations} @@ -5581,7 +5606,7 @@ star, given its \code{actual} position and the velocity vector of the observer, represented as a speed and a direction: -\begin{verbatim} +\begin{prototype} psSphere *psAberration(psSphere *apparent, const psSphere *actual, const psSphere *direction, double speed); -\end{verbatim} +\end{prototype} The \code{actual} and \code{apparent} positions are represented as \code{psSphere} entries, as is the \code{direction} of motion. The @@ -5595,7 +5620,7 @@ The following function calculates the \code{apparent} position of a star, given its \code{actual} position and the position of the sun: -\begin{verbatim} +\begin{prototype} psSphere *psGravityDeflection(psSphere *apparent, psSphere *actual, psSphere *sun); -\end{verbatim} +\end{prototype} The \code{actual} and \code{apparent} positions are represented as \code{psSphere} entries, as is position of the sun. If the value of @@ -5605,7 +5630,7 @@ \paragraph{Parallax} -\begin{verbatim} +\begin{prototype} double psEOC_ParallaxFactor(const psSphere *coords, const psTime *time); -\end{verbatim} +\end{prototype} Calculate the parallax factor for the given position and time. @@ -5618,5 +5643,5 @@ representation may be converted to a rotation between the frames. -\begin{verbatim} +\begin{datatype} typedef struct { double x; @@ -5624,5 +5649,5 @@ double s; } psEarthPole; -\end{verbatim} +\end{datatype} \paragraph{Precession/Nutation} @@ -5632,7 +5657,7 @@ IAU2000A precession \& nutation model: % -\begin{verbatim} +\begin{prototype} psEarthPole *psEOC_PrecessionModel(const psTime *time) -\end{verbatim} +\end{prototype} % The input to this function is the desired \code{time}, which may be @@ -5645,14 +5670,14 @@ by the IERS, just as it does for UT1 and polar motion. -\begin{verbatim} +\begin{prototype} psEarthPole *psEOC_PrecessionCorr(const psTime *time, psTimeBulletin bulletin); -\end{verbatim} +\end{prototype} The polar correction is applied to the $X$ and $Y$ elements of the rotation to provide higher accuracy. The spherical rotation term is generated by providing the polar coordinate to the following function: -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRot_CEOtoGCRS(const psEarthPole *pole) -\end{verbatim} +\end{prototype} This function constructs the rotation element as described in the ADD ( The resulting \code{psSphereRot} may be used to determine the rotation @@ -5663,7 +5688,7 @@ The following routine calculates the rotation of the Earth about the CIP: -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRot_TEOtoCEO(const psTime *time) -\end{verbatim} +\end{prototype} The IERS code to create the comparable rotation is embedded in T2C2000, with the Earth Rotation Angle calculated by ERA2000. @@ -5673,27 +5698,27 @@ The following function provides interpolated values of the polar motion components, $x_p$ and $y_p$, extracted from the IERS tables. -\begin{verbatim} +\begin{prototype} psEarthPole *psEOC_GetPolarMotion(const psTime *time, psTimeBulletin bulletin); -\end{verbatim} +\end{prototype} The following function provides tidal corrections to the polar motion components, $x_p$ and $y_p$, using the Ray model of Simon et al (see ADD). -\begin{verbatim} +\begin{prototype} psEarthPole *psEOC_PolarTideCorr(const psTime *time); -\end{verbatim} +\end{prototype} The following function provides the additional corrections due to nutation terms with periods less than or equal to two days, as well as the correction to the $s'$ component of the polar motion: -\begin{verbatim} +\begin{prototype} psEarthPole *psEOC_NutationCorr(psTime *time); -\end{verbatim} +\end{prototype} The following function converts the polar motion corrections to a spherical rotation using the prescription in the ADD: -\begin{verbatim} +\begin{prototype} psSphereRot *psSphereRot_ITRStoTEO(const psEarthPole *motion); -\end{verbatim} +\end{prototype} This function should give identical results to the IERS POM2000 subroutine. @@ -5705,11 +5730,11 @@ for either time, it is assumed to have the reference equinox value of J2000. -\begin{verbatim} +\begin{prototype} psSphere *psSpherePrecess(const psTime *fromTime, const psTime *toTime, psPrecessMethod mode); -\end{verbatim} +\end{prototype} The mode argument is used to specify the level of detail used in the calculation. -\begin{verbatim} +\begin{datatype} typedef enum { PS_PRECESS_ROUGH, @@ -5717,5 +5742,5 @@ PS_PRECESS_IAU2000A, } psPrecessMethod; -\end{verbatim} +\end{datatype} \subsection{Atmospheric Effects} @@ -5740,5 +5765,5 @@ pre-calculated entries and a separate structure for ATM effect?} -\begin{verbatim} +\begin{datatype} typedef struct { const double latitude; ///< geodetic latitude (radians) @@ -5754,11 +5779,11 @@ const double siderealTime; ///< local apparent sidereal time (radians) } psGrommit; -\end{verbatim} +\end{datatype} The \code{psGrommit} is calculated from telescope information for the particular exposure, \code{exp}: -\begin{verbatim} +\begin{prototype} psGrommit *psGrommitAlloc(const psExposure *exp); -\end{verbatim} +\end{prototype} \tbd{these functions probably need to take the ATM structure} @@ -5769,21 +5794,21 @@ the atmospheric refraction. -\begin{verbatim} +\begin{prototype} float psGetAirmass(const psSphere *coord, psTime *lst, float height); -\end{verbatim} +\end{prototype} which returns the airmass for a given position and local sidereal time (\code{lst}). -\begin{verbatim} +\begin{prototype} float psGetParallactic(const psSphere *coord, double siderealTime); -\end{verbatim} +\end{prototype} which returns the parallactic angle for a given position and sidereal time. -\begin{verbatim} +\begin{prototype} float psGetRefraction(float colour, ///< Colour of object psPhotSystem colorPlus, ///< Colour reference psPhotSystem colorMinus, ///< Colour reference const psExposure *exp); ///< Telescope pointing information -\end{verbatim} +\end{prototype} which provides an estimate of the atmospheric refraction, along the parallactic angle. @@ -5800,5 +5825,5 @@ grid. -\begin{verbatim} +\begin{datatype} typedef struct { int nX, nY; ///< Number of elements in x and y @@ -5807,12 +5832,12 @@ double **x, **y; ///< The grid of offsets in x and y } psFixedPattern; -\end{verbatim} +\end{datatype} The constructor for \code{psFixedPattern} shall be: -\begin{verbatim} +\begin{prototype} psFixedPattern *psFixedPatternAlloc(double x0, double y0, double xScale, double yScale, const psImage *x, const psImage *y); -\end{verbatim} +\end{prototype} Here, \code{x0}, \code{y0}, \code{xScale} and \code{yScale} have the same meaning as in the \code{psFixedPattern} structure. Note that the @@ -5838,5 +5863,5 @@ We specify the following structure \code{psProjection} to define the parameters of the projection: -\begin{verbatim} +\begin{datatype} typedef struct { double R, D; ///< coordinates of projection center @@ -5844,8 +5869,8 @@ psProjectionType type; ///< projection type } psProjection; -\end{verbatim} +\end{datatype} The projection type is defined by the following enumerated type \code{psProjectionType}: -\begin{verbatim} +\begin{datatype} typedef enum { ///< type of val is: PS_PROJ_TAN, ///< Tangent projection @@ -5855,18 +5880,18 @@ PS_PROJ_NTYPE ///< Number of types; must be last } psProjectionType; -\end{verbatim} +\end{datatype} The constructor is straight-forward: -\begin{verbatim} +\begin{prototype} psProjection *psProjectionAlloc(double R, double D, double Xs, double Ys, psProjectionType type); -\end{verbatim} +\end{prototype} The following functions will project and deproject (respectively) spherical coordinates: -\begin{verbatim} +\begin{prototype} psPlane *psProject(const psSphere *coord, const psProjection *projection); psSphere *psDeproject(const psPlane *coord, const psProjection *projection); -\end{verbatim} +\end{prototype} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5 @@ -5892,5 +5917,5 @@ a specific camera/detector/filter combination can be associated with those components. -\begin{verbatim} +\begin{datatype} typedef struct { const int ID; ///< ID number for this photometric system @@ -5900,9 +5925,9 @@ const char *detector; ///< Detector used for photometric system } psPhotSystem; -\end{verbatim} +\end{datatype} The following structure defines the transformation between two photometric systems. -\begin{verbatim} +\begin{datatype} typedef struct { psPhotSystem src; ///< Source photometric system @@ -5913,5 +5938,5 @@ psPolynomial3D transform; ///< Transformation from source to destination } psPhotTransform; -\end{verbatim} +\end{datatype} The transformation between two photometric systems may depend on the @@ -5955,5 +5980,5 @@ objects, as well as Lunar phase. -\begin{verbatim} +\begin{prototype} psSphere *psSunGetPos(psTime *time); psTime *psSunGetRise (psTime *twi15, psTime *twi18, const psTime *time); @@ -5968,5 +5993,5 @@ psTime *psPlanetGetRise (psTime *twi15, psTime *twi18, psTime *time); psTime *psPlanetGetSet (psTime *twi15, psTime *twi18, psTime *time); -\end{verbatim} +\end{prototype} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%