Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 347) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 348) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.20 2004-04-01 04:40:14 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.21 2004-04-01 04:40:36 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -387,5 +387,5 @@ \end{verbatim} % -The corresponding callback have the following form: +The corresponding callbacks have the following form: % \begin{verbatim} @@ -402,12 +402,12 @@ \code{psMemAllocateCBSet} and \code{psMemFreeCBSet} are used to increment the values of \code{p_psMemAllocateID} and -\code{p_psMemFreeID} respectively. For example, the return value +\code{p_psMemFreeID} respectively. For example, a return value of \code{0} implies that the value is unchanged; if the value is \code{2} the callback will be called again when the memory ID counter has increased by two. This functionality may be useful to check, for -example, every 100th block allocated. The function, \code{long -psMemGetId(void);} returns the next identification number to be -assigned to a memory block. This function can be used to guide the -choice of ID set with the functions above. +example, every 100th block allocated. The function, \code{long psMemGetId(void);} +returns the next identification number to be assigned to a memory +block. This function can be used to guide the choice of ID set with +the functions above. \subsubsection{Memory Tracing and Corruption Checks} @@ -438,5 +438,5 @@ or the corresponding memory reference will be lost. -If the argument \code{fd} is non\code{NULL}, a one-line summary +If the argument \code{fd} is non-\code{NULL}, a one-line summary of each block that has been allocated but not freed is written to that file descriptor. @@ -484,5 +484,5 @@ be in the valid range and should correspond to the address of the \code{psMemBlock}). For an example implementation of the -\code{refCounter} facilities, see the discussion of \code{psDlist} +\code{refCounter} facilities, see the discussion of \code{psDlist}. \tbd{REF}. @@ -495,5 +495,5 @@ code); the latter means information about the processing that must be collected and saved, even in the production system. We envision that -we will make extensive use of \code{psTrace} throughout the \PS{} +extensive use will be made of \code{psTrace} throughout the \PS{} code. @@ -520,13 +520,13 @@ lowest-level step-by-step messages would be printed. -The PSLib tracing facility provides the above functionality along with -the ability to assign different trace levels to different types of -messages. Each trace message when placed in the code is assigned to -be part of a specific tracing 'facility', defined in more detail -below. The trace level for that specific message is also set when the -message is placed. Each facility may have its trace level set -independently. Thus, it is possible to request detailed trace output -for one facility while minimizing the verbosity of the trace output -from the rest of the program. +The PSLib tracing facility will provide the above functionality, along +with the ability to assign different trace levels to messages from +different software components. Each trace message when placed in the +code is assigned to be part of a specific tracing 'facility', defined +in more detail below. The trace level for that specific message is +also set when the message is placed. Each facility may have its trace +level set independently. Thus, it is possible to request detailed +trace output for one facility while minimizing the verbosity of the +trace output from the rest of the program. The trace facilities consist of a hierarchy of names. A trace @@ -536,11 +536,11 @@ would be \code{'.A'}, followed by \code{.A.B}, and so on. The relationship is seen in two ways. First, a facility inherits the -trace level of its parent unless specified. Second, the hierarchy is -used to format the listing of the trace facilities. The first of -these rules provides a mechanism to define the default trace levels -for any facility even if it has not been registered explicitly since -all named facilities are implicitly children of the top level facility -(\code{.}). The second rule is simply an organizational technique to -make the listing of facility information clear. +trace level of its parent unless explicitly specified. Second, the +hierarchy is used to format the listing of the trace facilities. The +first of these rules provides a mechanism to define the default trace +levels for any facility even if it has not been registered explicitly +since all named facilities are implicitly children of the top level +facility (\code{.}). The second rule is simply an organizational +technique to make the listing of facility information clear. The API to place a trace message in the code, and simultaneously set @@ -567,5 +567,5 @@ where \code{level} specifies the current trace level for the facility named by \code{facil}. The currently defined trace level for a given -facility is determined by the function: +facility may be determined by the function: % \begin{verbatim} @@ -577,10 +577,12 @@ \code{psTrace}) shall be printed if and only if \code{psGetTraceLevel(facil)} returns a value greater than or equal to -the value of \code{myLevel} for that message. - -PSLib includes a utility function for examining the current tracing -levels of all facilities: \code{void psPrintTraceLevels(void);}. This -function will print the hierarchy of trace facilities along with the -current trace level for each facility. For example, a particular +the value of \code{myLevel} for that message. That is, a larger +number for the trace level corresponds to lower-level statements, and +hence is more verbose. + +PSLib will include a utility function for examining the current +tracing levels of all facilities: \code{void psPrintTraceLevels(void);}. +This function will print the hierarchy of trace facilities along with +the current trace level for each facility. For example, a particular program may have a few facilities defined, along with their trace levels. A call to \code{psPrintTraceLevels} may produce a listing @@ -612,8 +614,8 @@ % \begin{verbatim} -ERROR: flat-field image foo.fits is invalid (printed) -doing the divide (printed) -got an invalid pixel value (NaN) at 500,20 (printed) -divide is done (printed) +ERROR: flat-field image foo.fits is invalid +doing the divide +got an invalid pixel value (NaN) at 500,20 +divide is done \end{verbatim} % @@ -630,10 +632,10 @@ % -The tracing facility should be made available, or not, on compilation. -If the C pre-processor macro \code{PS_NO_TRACE} is defined, all trace -code shall be replaced by empty space so that none of the code is -compiled. This can be implemented via macro front-ends to private -versions of the user APIs. In addition, a function \code{void -psTraceReset(void)} will set all trace levels to 0. +The availability of the tracing facility at run-time, shall be decided +at compilation: If the C pre-processor macro \code{PS_NO_TRACE} is +defined, all trace code shall be replaced by empty space so that none +of the code is compiled. This can be implemented via macro front-ends +to private versions of the user APIs. In addition, a function +\code{void psTraceReset(void)} will set all trace levels to 0. \tbd{ability to send trace messages to output locations other than stdout?} @@ -686,7 +688,8 @@ \end{verbatim} % -A specific message invoked with \code{psLogMsg} is only printed if its -value of \code{myLevel} is less than the current value set by -\code{psSetLogLevel}. +This function returns the previous log level. A specific message +invoked with \code{psLogMsg} is only printed if its value of +\code{myLevel} is less than the current value set by +\code{psSetLogLevel}. Log messages are sent to the destination most recently set using: @@ -715,9 +718,9 @@ \end{verbatim} where \code{YYYY}, \code{MM}, \code{DD}, \code{hh}, \code{mm}, and -\code{ss} are the year, month (Jan == 1), day of the month, hours +\code{ss} are the year, month (Jan is 01), day of the month, hours (0--23), minutes, and seconds when the log message was received. Note that the timestamp is in ISO order, and that the timezone is GMT (hence the \code{Z}). The \code{hostname} is returned by -\code{gethostname}, \code{L} is a letter associated with the level +\code{gethostname}, \code{L} is a character associated with the level (\code{A}, \code{E}, \code{W}, and \code{I} for \code{PS_LOG_ABORT}, \code{PS_LOG_ERROR}, \code{PS_LOG_WARN}, and \code{PS_LOG_INFO} @@ -733,7 +736,7 @@ % The possible order of the format entries is fixed and not determined -by the order of the letters. Selecting an output format with fewer -than the complete set of 5 entries simply removes those entries from -the output messages. +by the order of the letters used in \code{psSetLogFormat}. Selecting +an output format with fewer than the complete set of 5 entries simply +removes those entries from the output messages. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -741,5 +744,5 @@ \subsection{Miscellaneous Utilities} -We require a several very low-functions. Two functions provide +We require several very low-level functions. Two functions provide conveniences tied to the logging facilities: % @@ -764,5 +767,5 @@ % The first function simply converts the argument to a string -\tbd{explanation of usage and rational?}. The second function, +\tbd{explanation of usage and rationale?}. The second function, \code{psStringCopy}, shall allocate a sufficient memory block and return a copy of the input string. Similarly, \code{psStringNCopy} @@ -812,5 +815,5 @@ example, if $x$ were a vector of 100 elements, but $y$ were a vector of 1000 elements, the meaning of the operation $x + y$ is unclear. -This type of operation should probably be invalid. +This type of operation should be invalid. Given that some functions should be able to operate equivalently (or @@ -826,5 +829,5 @@ structure \code{psType}. -Each of these equivalent data type is defined by a structure in which +Each of these equivalent data types is defined by a structure in which the first element is always of type \code{psType}. This element defines both the dimensions of the array and the data type of each @@ -832,8 +835,8 @@ \begin{verbatim} typedef struct { - psDimen dimen; ///< The dimensionality - psElemType type; ///< The type + psDimen dimen; ///< The dimensionality + psElemType type; ///< The type } psType; -\begin{end} +\end{verbatim} where \code{psDimen dimen} defines the dimensionality of the data and \code{psElemType type} defines the data type of each element. These @@ -841,9 +844,9 @@ \begin{verbatim} typedef enum { - PS_DIMEN_SCALAR, ///< Scalar - PS_DIMEN_VECTOR, ///< A vector - PS_DIMEN_TRANSV, ///< A transposed vector - PS_DIMEN_MATRIX, ///< A matrix - PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic + PS_DIMEN_SCALAR, ///< Scalar + PS_DIMEN_VECTOR, ///< A vector + PS_DIMEN_TRANSV, ///< A transposed vector + PS_DIMEN_MATRIX, ///< A matrix + PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic } psDimen; \end{verbatim} @@ -851,16 +854,16 @@ \begin{verbatim} typedef enum { - PS_TYPE_CHAR, ///< Character - PS_TYPE_SHORT, ///< Short integer - PS_TYPE_INT, ///< Integer - PS_TYPE_LONG, ///< Long integer - PS_TYPE_UCHAR, ///< Unsigned character - PS_TYPE_USHORT, ///< Unsigned short integer - PS_TYPE_UINT, ///< Unsigned integer - PS_TYPE_ULONG, ///< Unsigned long integer - PS_TYPE_FLOAT, ///< Floating point - PS_TYPE_DOUBLE, ///< Double-precision floating point - PS_TYPE_COMPLEX, ///< Complex numbers consisting of floating point - PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic + PS_TYPE_CHAR, ///< Character + PS_TYPE_SHORT, ///< Short integer + PS_TYPE_INT, ///< Integer + PS_TYPE_LONG, ///< Long integer + PS_TYPE_UCHAR, ///< Unsigned character + PS_TYPE_USHORT, ///< Unsigned short integer + PS_TYPE_UINT, ///< Unsigned integer + PS_TYPE_ULONG, ///< Unsigned long integer + PS_TYPE_FLOAT, ///< Floating point + PS_TYPE_DOUBLE, ///< Double-precision floating point + PS_TYPE_COMPLEX, ///< Complex numbers consisting of floating point + PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic } psElemType; \end{verbatim} @@ -871,15 +874,15 @@ We require several types of basic one-dimensional arrays: arrays of -values of type \code{int}, \code{float}, \code{double}, -\code{complex}, and \code{void *}. We have defined structures for -these types which are all equivalent. We illustrate them with the -example of \code{psFloatArray}: +values of type \code{int}, \code{float}, \code{double}, \code{complex float}, +and \code{void *}. We have defined structures for these types +which are all equivalent. We illustrate them with the example of +\code{psFloatArray}: % \begin{verbatim} typedef struct { - psType type; ///< Type of data. Must be first element - int nalloc; ///< Total number of elements available - int n; ///< Number of elements in use - float *arr; ///< The array data + psType type; ///< Type of data. Must be first element + int nalloc; ///< Total number of elements available + int n; ///< Number of elements in use + float *arr; ///< The array data } psFloatArray; \end{verbatim} @@ -889,5 +892,6 @@ allocated ($s \ge n$). The allocated memory is available at \code{arr}. The data type is defined by the first element, -\code{psType}. The structure is associated with a constructor and a destructor: +\code{psType}. The structure is associated with a constructor and a +destructor: % \begin{verbatim} @@ -899,7 +903,6 @@ In these functions, \code{nalloc} is the number of elements to allocate. For \code{psFloatArrayAlloc}, the value of -\code{psFloatArray.n} is set to 0 and the allocated arrays are -initialized to 0.0. For \code{psFloatArrayRealloc}, if the value of -\code{nalloc} is smaller than the current value of +\code{psFloatArray.n} is set to 0. For \code{psFloatArrayRealloc}, if +the value of \code{nalloc} is smaller than the current value of \code{psFloatArray.n}, then \code{psFloatArray.n} is set to \code{nalloc}, the array is adjusted down to match \code{nalloc}, and @@ -927,12 +930,13 @@ require an array of pointers of type \code{void}, with which we can carry around a collection of data of an arbitrary type which is more -complicated than the simple numeric types above. The structure is a follows: +complicated than the simple numeric types above. The structure is as +follows: % \begin{verbatim} typedef struct { - psType type; ///< Type of data. Must be first element - int nalloc; ///< Total number of elements available - int n; ///< Number of elements in use - void **arr; ///< The array data + psType type; ///< Type of data. Must be first element + int nalloc; ///< Total number of elements available + int n; ///< Number of elements in use + void **arr; ///< The array data } psVoidPtrArray; \end{verbatim} @@ -1102,6 +1106,6 @@ \begin{verbatim} typedef struct { - int nbucket; // number of buckets - psHashBucket **buckets; // the buckets themselves + int nbucket; // number of buckets + psHashBucket **buckets; // the buckets themselves } psHash; \end{verbatim} @@ -1113,7 +1117,7 @@ \begin{verbatim} typedef struct psHashBucket { - char *key; // key for this item of data - void *data; // the data itself - struct psHashBucket *next; // list of other possible keys + char *key; // key for this item of data + void *data; // the data itself + struct psHashBucket *next; // list of other possible keys } psHashBucket; \end{verbatim} @@ -1491,6 +1495,6 @@ /** Convert vector to matrix. */ psImage * -psVectorToMatrix(psImage *out, //!< Matrix to return, or NULL - psVector *myVector //!< Vector to convert +psVectorToMatrix(psImage *out, //!< Matrix to return, or NULL + psVector *myVector //!< Vector to convert ); \end{verbatim} @@ -1515,8 +1519,8 @@ /** Fast Fourier Transform */ typedef struct { - p_psFFTDetails *details; //!< Details on FFT implementation (private) - int nx, ny; //!< Size in x and y - float **real; //!< Data in real space - void *fourier; //!< Data in fourier space; implementation dependent + p_psFFTDetails *details; //!< Details on FFT implementation (private) + int nx, ny; //!< Size in x and y + float **real; //!< Data in real space + void *fourier; //!< Data in fourier space; implementation dependent } psFFT; \end{verbatim} @@ -1537,17 +1541,17 @@ /** Constructor */ psFFT * -psFFTAlloc(psImage *image //!< Image to transform - ); +psFFTAlloc(psImage *image //!< Image to transform + ); /** Constructor for 1D case */ psFFT * -psFFTAlloc1D(const psFloatArray *arr //!< Array to transform - ); +psFFTAlloc1D(const psFloatArray *arr //!< Array to transform + ); /** Destructor. Returns the data in the real space as an image. */ psImage * -psFFTFree(psImage *out, //!< Image to write the data to, or NULL - psFFT *restrict fft //!< FFT to destroy - ); +psFFTFree(psImage *out, //!< Image to write the data to, or NULL + psFFT *restrict fft //!< FFT to destroy + ); \end{verbatim} @@ -1557,11 +1561,11 @@ /** Forward FFT: from real to fourier space */ psFFT * -psFFTForwardTransform(psFFT *fft //!< FFT to apply - ); +psFFTForwardTransform(psFFT *fft //!< FFT to apply + ); /** Reverse FFT: from fourier to real space */ psFFT * -psFFTReverseTransform(psFFT *fft //!< FFT to apply - ); +psFFTReverseTransform(psFFT *fft //!< FFT to apply + ); \end{verbatim} @@ -1572,14 +1576,14 @@ /** Apply filter function in fourier space */ psFFT * -psFFTFilter(psFFT *fft, //!< FFT to use (input and output) - float (*filterFunc)(int kx, int ky) //!< External filter function - ); +psFFTFilter(psFFT *fft, //!< FFT to use (input and output) + float (*filterFunc)(int kx, int ky) //!< External filter function + ); /** Apply complex filter function */ psFFT * -psFFTFilterComplex(psFFT *fft, //!< FFT to use (input and output) - float (*realFilterFunc)(int kx, int ky), //!< External filter function, real part - float (*imagFilterFunc)(int kx, int ky) //!< External filter function, imaginary part - ); +psFFTFilterComplex(psFFT *fft, //!< FFT to use (input and output) + float (*realFilterFunc)(int kx, int ky), //!< External filter function, real part + float (*imagFilterFunc)(int kx, int ky) //!< External filter function, imaginary part + ); \end{verbatim} @@ -1590,7 +1594,7 @@ /** Calculate cross-correlation function */ psFFT * -psFFTCrossCorrelate(psFFT *out //!< Output FFT (or NULL) - psFFT *fft1, psFFT *fft2 //!< FFTs to use in cross-correlation - ); +psFFTCrossCorrelate(psFFT *out //!< Output FFT (or NULL) + psFFT *fft1, psFFT *fft2 //!< FFTs to use in cross-correlation + ); \end{verbatim} @@ -1600,6 +1604,6 @@ /** Calculate power spectrum */ psFFT * -psFFTPowerSpec(psFFT *fft //!< FFT to use (input and output) - ); +psFFTPowerSpec(psFFT *fft //!< FFT to use (input and output) + ); \end{verbatim} @@ -1609,7 +1613,7 @@ /** Multiply two Fourier transforms, as for convolution */ psFFT * -psFFTMultiplyFT(psFFT *out, //!< Output FFT (or NULL) - const psFFT *fft1, const psFFT *fft2 //!< FFTs to multiply - ); +psFFTMultiplyFT(psFFT *out, //!< Output FFT (or NULL) + const psFFT *fft1, const psFFT *fft2 //!< FFTs to multiply + ); \end{verbatim} @@ -1620,13 +1624,13 @@ /* Convert the real data in the FFT struct to an image again */ psImage * -psFFTGetImage(psImage *out, //!< Image to write to (or NULL) - const psFFT *fft //!< FFT to get image from - ); +psFFTGetImage(psImage *out, //!< Image to write to (or NULL) + const psFFT *fft //!< FFT to get image from + ); /** Convert the Fourier transform data in the FFT struct to an image of complex numbers */ psImage * -psFFTGetFT(psImage *out, //!< Image to write to (or NULL) - const psFFT *fft //!< FFT to get Fourier transform from - ); +psFFTGetFT(psImage *out, //!< Image to write to (or NULL) + const psFFT *fft //!< FFT to get Fourier transform from + ); \end{verbatim} @@ -2239,31 +2243,31 @@ /** The type of a data type */ typedef struct { - psElemType type; ///< The type - psDimen dimen; ///< The dimensionality + psElemType type; ///< The type + psDimen dimen; ///< The dimensionality } psType; /** Types of the elements of vectors, images, etc. */ typedef enum { - PS_TYPE_CHAR, ///< Character - PS_TYPE_SHORT, ///< Short integer - PS_TYPE_INT, ///< Integer - PS_TYPE_LONG, ///< Long integer - PS_TYPE_UCHAR, ///< Unsigned character - PS_TYPE_USHORT, ///< Unsigned short integer - PS_TYPE_UINT, ///< Unsigned integer - PS_TYPE_ULONG, ///< Unsigned long integer - PS_TYPE_FLOAT, ///< Floating point - PS_TYPE_DOUBLE, ///< Double-precision floating point - PS_TYPE_COMPLEX, ///< Complex numbers consisting of floating point - PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic + PS_TYPE_CHAR, ///< Character + PS_TYPE_SHORT, ///< Short integer + PS_TYPE_INT, ///< Integer + PS_TYPE_LONG, ///< Long integer + PS_TYPE_UCHAR, ///< Unsigned character + PS_TYPE_USHORT, ///< Unsigned short integer + PS_TYPE_UINT, ///< Unsigned integer + PS_TYPE_ULONG, ///< Unsigned long integer + PS_TYPE_FLOAT, ///< Floating point + PS_TYPE_DOUBLE, ///< Double-precision floating point + PS_TYPE_COMPLEX, ///< Complex numbers consisting of floating point + PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic } psElemType; /** Dimensions of a data type */ typedef enum { - PS_DIMEN_SCALAR, ///< Scalar - PS_DIMEN_VECTOR, ///< A vector - PS_DIMEN_TRANSV, ///< A transposed vector - PS_DIMEN_IMAGE, ///< An image - PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic + PS_DIMEN_SCALAR, ///< Scalar + PS_DIMEN_VECTOR, ///< A vector + PS_DIMEN_TRANSV, ///< A transposed vector + PS_DIMEN_IMAGE, ///< An image + PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic } psDimen; \end{verbatim} @@ -2282,5 +2286,5 @@ /** Transpose a vector. Changes the type to a PS_DIMEN_TRANSV */ psVector *psVectorTranspose(psVector *out, //!< Output vector, or NULL - psVector *myVector //!< Vector to be transposed + psVector *myVector //!< Vector to be transposed ); \end{verbatim}