Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 533) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 534) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.38 2004-04-27 00:33:18 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.39 2004-04-28 00:27:24 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -1083,5 +1083,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 be invalid. +This type of operation should be invalid and should generate an error. Given that some functions should be able to operate equivalently (or @@ -1115,5 +1115,5 @@ PS_DIMEN_VECTOR, ///< A vector PS_DIMEN_TRANSV, ///< A transposed vector - PS_DIMEN_MATRIX, ///< A matrix + PS_DIMEN_IMAGE, ///< An image (matrix) PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic } psDimen; @@ -1137,11 +1137,11 @@ \end{verbatim} We discuss the application of \code{psType} in more detail in -section~\ref{math}. +section~\ref{arithmetic}. \subsection{Arrays of Simple Types} We require several types of basic one-dimensional arrays: arrays of -values of type \code{int}, \code{float}, \code{double}, \code{complex float}, -and \code{void *}. We have defined structures for these types +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}: @@ -1150,5 +1150,5 @@ typedef struct { psType type; ///< Type of data. Must be first element - int nalloc; ///< Total number of elements available + int nAlloc; ///< Total number of elements available int n; ///< Number of elements in use float *arr; ///< The array data @@ -1157,5 +1157,5 @@ % In this structure, the argument \code{n} is the length of the array -(the number of elements); \code{size} is the number of elements +(the number of elements); \code{nAlloc} is the number of elements allocated ($s \ge n$). The allocated memory is available at \code{arr}. The data type is defined by the first element, @@ -1164,16 +1164,16 @@ % \begin{verbatim} -psFloatArray *psFloatArrayAlloc(int nalloc); -psFloatArray *psFloatArrayRealloc(psFloatArray *myArray, int nalloc); +psFloatArray *psFloatArrayAlloc(int nAlloc); +psFloatArray *psFloatArrayRealloc(psFloatArray *myArray, int nAlloc); void psFloatArrayFree(psFloatArray *restrict myArray); \end{verbatim} % -In these functions, \code{nalloc} is the number of elements to +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. For \code{psFloatArrayRealloc}, if -the value of \code{nalloc} is smaller than the current value of +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 -the extra elements are lost. If \code{nalloc} is larger than the +\code{nAlloc}, the array is adjusted down to match \code{nAlloc}, and +the extra elements are lost. If \code{nAlloc} is larger than the current value of \code{psFloatArray.n}, \code{psFloatArray.n} is left intact. If the value of \code{myArray} is \code{NULL}, then @@ -1185,8 +1185,8 @@ appropriate type. Thus we have: \begin{verbatim} -psIntArray *psIntArrayAlloc(int nalloc); -psFloatArray *psFloatArrayAlloc(int nalloc); -psDoubleArray *psDoubleArrayAlloc(int nalloc); -psComplexArray *psComplexArrayAlloc(int nalloc); +psIntArray *psIntArrayAlloc(int nAlloc); +psFloatArray *psFloatArrayAlloc(int nAlloc); +psDoubleArray *psDoubleArrayAlloc(int nAlloc); +psComplexArray *psComplexArrayAlloc(int nAlloc); \end{verbatim} and so on for the other functions. The collection of structures and @@ -1204,5 +1204,5 @@ typedef struct { psType type; ///< Type of data. Must be first element - int nalloc; ///< Total number of elements available + int nAlloc; ///< Total number of elements available int n; ///< Number of elements in use void **arr; ///< The array data @@ -1213,6 +1213,6 @@ % \begin{verbatim} -psVoidPtrArray *psVoidPtrArrayAlloc(int nalloc); -psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *myArray, int nalloc); +psVoidPtrArray *psVoidPtrArrayAlloc(int nAlloc); +psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *myArray, int nAlloc); void psVoidPtrArrayFree(psVoidPtrArray *restrict myArray, void (*elemFree)(void *)); \end{verbatim} @@ -1509,5 +1509,5 @@ psBitset * psBitsetSet(psBitset *restrict myBits, ///< Input bitset - int bit ///< Bit to set + int bit ///< Bit to set ); \end{verbatim} @@ -1619,8 +1619,8 @@ psStats * psArrayStats(const psFloatArray *restrict myArray, ///< Array to be analysed - const psIntArray *restrict maskArray, ///< Ignore elements where (maskArray & maskVal) != 0 - ///< May be NULL - unsigned int maskVal, ///< Only mask elements with one of these bits set in maskArray - psStats *stats ///< stats structure defines stats to be calculated and how + const psIntArray *restrict maskArray, ///< Ignore elements where (maskArray & maskVal) != 0 + ///< May be NULL + unsigned int maskVal, ///< Only mask elements with one of these bits set in maskArray + psStats *stats ///< stats structure defines stats to be calculated and how ); \end{verbatim} @@ -1637,27 +1637,27 @@ /** generic statistics structure */ typedef struct { - double sampleMean; ///< formal mean of sample - double sampleMedian; ///< formal median of sample - double sampleStdev; ///< standard deviation of sample - double sampleUQ; ///< upper quartile of sample - double sampleLQ; ///< lower quartile of sample - double robustMean; ///< robust mean of array - int robustMeanNvalues; ///< number of measurements used for robust mean - double robustMedian; ///< robust median of array - int robustMedianNvalues; ///< number of measurements used for robust median - double robustMode; ///< Robust mode of array - int robustModeNvalues; ///< Number of measurements used for robust mode - double robustStdev; ///< robust standard deviation of array - double robustUQ; ///< robust upper quartile - double robustLQ; ///< robust lower quartile - double clippedMean; ///< Nsigma clipped mean - int clippedMeanNvalues; ///< number of data points used for clipped mean - double clippedStdev; ///< standard deviation after clipping - double clipSigma; ///< Nsigma used for clipping; user input - int clipIter; ///< Number of clipping iterations; user input - double min; ///< minimum data value in array - double max; ///< maximum data value in array - int nValues; ///< number of data values in array - psStatsOptions options; ///< bitmask of calculated values + double sampleMean; ///< formal mean of sample + double sampleMedian; ///< formal median of sample + double sampleStdev; ///< standard deviation of sample + double sampleUQ; ///< upper quartile of sample + double sampleLQ; ///< lower quartile of sample + double robustMean; ///< robust mean of array + int robustMeanNvalues; ///< number of measurements used for robust mean + double robustMedian; ///< robust median of array + int robustMedianNvalues; ///< number of measurements used for robust median + double robustMode; ///< Robust mode of array + int robustModeNvalues; ///< Number of measurements used for robust mode + double robustStdev; ///< robust standard deviation of array + double robustUQ; ///< robust upper quartile + double robustLQ; ///< robust lower quartile + double clippedMean; ///< Nsigma clipped mean + int clippedMeanNvalues; ///< number of data points used for clipped mean + double clippedStdev; ///< standard deviation after clipping + double clipSigma; ///< Nsigma used for clipping; user input + int clipIter; ///< Number of clipping iterations; user input + double min; ///< minimum data value in array + double max; ///< maximum data value in array + int nValues; ///< number of data values in array + psStatsOptions options; ///< bitmask of calculated values } psStats; \end{verbatim} @@ -1671,6 +1671,6 @@ PS_STAT_SAMPLE_MEDIAN = 0x000002, PS_STAT_SAMPLE_STDEV = 0x000004, - PS_STAT_SAMPLE_UQ = 0x000008, - PS_STAT_SAMPLE_LQ = 0x000010, + PS_STAT_SAMPLE_UQ = 0x000008, + PS_STAT_SAMPLE_LQ = 0x000010, PS_STAT_ROBUST_MEAN = 0x000020, PS_STAT_ROBUST_MEAN_NVALUES = 0x000040, @@ -1680,14 +1680,14 @@ PS_STAT_ROBUST_MODE_NVALUES = 0x000400, PS_STAT_ROBUST_STDEV = 0x000800, - PS_STAT_ROBUST_UQ = 0x001000, - PS_STAT_ROBUST_LQ = 0x002000, + PS_STAT_ROBUST_UQ = 0x001000, + PS_STAT_ROBUST_LQ = 0x002000, PS_STAT_CLIPPED_MEAN = 0x004000, PS_STAT_CLIPPED_MEAN_NVALUES = 0x008000, PS_STAT_CLIPPED_MEAN_NSIGMA = 0x010000, PS_STAT_CLIPPED_STDEV = 0x020000, - PS_STAT_MAX = 0x040000, - PS_STAT_MIN = 0x080000, - PS_STAT_NVALUES = 0x100000 -} psStatsOptions; + PS_STAT_MAX = 0x040000, + PS_STAT_MIN = 0x080000, + PS_STAT_NVALUES = 0x100000 +} psStatsOptions; \end{verbatim} @@ -1697,10 +1697,10 @@ /** Constructor */ psStats * -psStatsAlloc(psStatsOptions options ///< Statistics to measure +psStatsAlloc(psStatsOptions options ///< Statistics to measure ); /** Destructor */ void -psStatsFree(psStats *restrict stats ///< Stats structure to destroy +psStatsFree(psStats *restrict stats ///< Stats structure to destroy ); \end{verbatim} @@ -1764,5 +1764,5 @@ psHistogram * psGetArrayHistogram(psHistogram *restrict myHist, ///< Histogram data - const psFloatArray *restrict myArray ///< Array to analyse + const psFloatArray *restrict myArray ///< Array to analyse ); \end{verbatim} @@ -1772,8 +1772,11 @@ \subsection{Matrix operations and linear algebra} -In addition to the ability to perform image arithmetic (\S\ref{sec:arithmetic}), -we also require the ability to perform basic linear algebra on matrices, in order -to solve equations. We use \code{psImage} as a matrix, since it has the correct -form, and we define the following basic matrix operations: +In addition to the ability to perform image arithmetic +(\S\ref{sec:arithmetic}), we also require the ability to perform basic +linear algebra on matrices, in order to solve equations. We use +\code{psImage} as a matrix, since it has the correct form; similarly, +we define a vector, \code{psVector} to be an array of floating-point +numbers, \code{psFloatArray}. We define the following basic matrix +operations: \begin{itemize} \item $LU$ Decompose a matrix, and solve for $x$ in $Ax = b$; @@ -1789,14 +1792,14 @@ /** LU Decomposition of a matrix */ psImage * -psMatrixLUD(psImage *out, ///< Matrix to return, or NULL - psImage *myMatrix ///< Matrix to decompose - ); +psMatrixLUD(psImage *out, ///< Matrix to return, or NULL + psImage *myMatrix ///< Matrix to decompose + ); /** LU Solution. Solves for and returns x in the equation Ax = b */ psVector * -psMatrixLUSolve(psVector *out, ///< Vector to return, or NULL - const psImage *luMatrix, ///< LU-decomposed matrix - const psVector *rhsVector ///< right-hand-side of the equation - ); +psMatrixLUSolve(psVector *out, ///< Vector to return, or NULL + const psImage *luMatrix, ///< LU-decomposed matrix + const psVector *rhsVector ///< right-hand-side of the equation + ); \end{verbatim} @@ -1810,7 +1813,7 @@ \begin{verbatim} /** Invert matrix. Not using restrict, to allow inversion to be done in-place */ -psMatrix * -psMatrixInvert(psMatrix *out, ///< Matrix to return, or NULL - const psMatrix *myMatrix, ///< Matrix to be inverted +psImage * +psMatrixInvert(psImage *out, ///< Matrix to return, or NULL + const psImage *myMatrix, ///< Matrix to be inverted float *restrict determinant ///< Determinant to return, or NULL ); @@ -1827,5 +1830,5 @@ /** Matrix determinant */ float -psMatrixDeterminant(const psMatrix *restrict myMatrix //!< Matrix to get determinant for +psMatrixDeterminant(const psImage *restrict myMatrix //!< Matrix to get determinant for ); \end{verbatim} @@ -1842,9 +1845,9 @@ \begin{verbatim} /** Matrix operations */ -psMatrix * -psMatrixOp(psMatrix *out, ///< Matrix to return, or NULL - const psMatrix *matrix1, ///< Matrix 1 +psImage * +psMatrixOp(psImage *out, ///< Matrix to return, or NULL + const psImage *matrix1, ///< Matrix 1 const char *op, ///< Operation to perform: "+", "-", "*" - const psMatrix *matrix2 ///< Matrix 2 + const psImage *matrix2 ///< Matrix 2 ); \end{verbatim} @@ -1855,7 +1858,7 @@ \begin{verbatim} /** Transpose Matrix */ -psMatrix * -psMatrixTranspose(psMatrix *out, ///< Matrix to return, or NULL - const psMatrix *myMatrix ///< Matrix to transpose +psImage * +psMatrixTranspose(psImage *out, ///< Matrix to return, or NULL + const psImage *myMatrix ///< Matrix to transpose ); \end{verbatim} @@ -1869,6 +1872,6 @@ /** Convert matrix to vector. Intended for a 1-d matrix. */ psVector * -psMatrixToVector(psVector *out, ///< Vector to return, or NULL - psImage *myMatrix ///< Matrix to convert +psMatrixToVector(psVector *out, ///< Vector to return, or NULL + psImage *myMatrix ///< Matrix to convert ); @@ -1895,8 +1898,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: a 2D array using the [nx*y + x] stuff - 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: a 2D array using the [nx*y + x] stuff + void *fourier; ///< Data in fourier space; implementation dependent } psFFT; \end{verbatim} @@ -1944,11 +1947,11 @@ /** Forward FFT: from real to fourier space */ psFFT * -psFFTForward(psFFT *fft ///< FFT to apply (input and output) - ); +psFFTForward(psFFT *fft ///< FFT to apply (input and output) + ); /** Reverse FFT: from fourier to real space */ psFFT * -psFFTReverse(psFFT *fft ///< FFT to apply (input and output) - ); +psFFTReverse(psFFT *fft ///< FFT to apply (input and output) + ); \end{verbatim} @@ -1997,7 +2000,7 @@ /** Calculate FFT of the convolution. Straight multiplication of the FFTs */ psFFT * -psFFTConvolve(psFFT *out, ///< Output FFT (or NULL) - const psFFT *fft1, const psFFT *fft2 ///< FFTs to multiply - ); +psFFTConvolve(psFFT *out, ///< Output FFT (or NULL) + const psFFT *fft1, const psFFT *fft2 ///< FFTs to multiply + ); \end{verbatim} @@ -2008,6 +2011,6 @@ /** Calculate power spectrum */ psFloatArray * -psFFTPowerSpec(psFFT *fft ///< FFT to use (input and output) - ); +psFFTPowerSpec(psFFT *fft ///< FFT to use (input and output) + ); \end{verbatim} @@ -2139,7 +2142,7 @@ psFloatArray * psMinimize(float (*myFunction)(const psFloatArray *restrict), ///< Function to minimize - psFloatArray *restrict initialGuess, ///< Initial guess - psIntArray *restrict paramMask //!< 1 = fit for parameter, 0 = hold parameter constant - ); + psFloatArray *restrict initialGuess, ///< Initial guess + psIntArray *restrict paramMask //!< 1 = fit for parameter, 0 = hold parameter constant + ); \end{verbatim} @@ -2154,10 +2157,10 @@ psFloatArray * psMinimizeChi2(float (*evalModel)(const psFloatArray *restrict, - const psFloatArray *restrict), ///< Model to fit; (domain and params) - const psFloatArray *restrict domain, ///< The domain values for the corresponding measurements - const psFloatArray *restrict data, ///< Data to fit - const psFloatArray *restrict errors, ///< Errors in the data - psFloatArray *restrict initialGuess, ///< Initial guess - const psIntArray *restrict paramMask ///< 1 = fit for parameter, 0 = hold parameter constant + const psFloatArray *restrict), ///< Model to fit; (domain and params) + const psFloatArray *restrict domain, ///< The domain values for the corresponding measurements + const psFloatArray *restrict data, ///< Data to fit + const psFloatArray *restrict errors, ///< Errors in the data + psFloatArray *restrict initialGuess, ///< Initial guess + const psIntArray *restrict paramMask ///< 1 = fit for parameter, 0 = hold parameter constant ); \end{verbatim} @@ -2175,7 +2178,7 @@ psPolynomial1D * psGetArrayPolynomial(psPolynomial1D myPoly, ///< Polynomial to fit - const psFloatArray *restrict x, ///< Ordinates (or NULL to just use the indices) - const psFloatArray *restrict y, ///< Coordinates - const psFloatArray *restrict yErr ///< Errors in coordinates, or NULL + const psFloatArray *restrict x, ///< Ordinates (or NULL to just use the indices) + const psFloatArray *restrict y, ///< Coordinates + const psFloatArray *restrict yErr ///< Errors in coordinates, or NULL ); \end{verbatim} @@ -2203,18 +2206,18 @@ int x0, y0; ///< data region relative to parent union { - psF32 **rows; ///< == rows_f32 - psS8 **rows_s8; ///< pointers to psS8 data - psS16 **rows_s16; ///< pointers to psS16 data - psS32 **rows_s32; ///< pointers to psS32 data - psU8 **rows_u8; ///< pointers to psU8 data - psU16 **rows_u16; ///< pointers to psU16 data - psU32 **rows_u32; ///< pointers to psU32 data - psF32 **rows_f32; ///< pointers to psF32 data - psF64 **rows_f64; ///< pointers to psF64 data - psComplex **rows_complex; ///< pointers to psComplex data + float **rows; ///< Pointers to floating-point data (default) + short int **rows_si; ///< Pointers to short-integer data + int **rows_i; ///< Pointers to integer data + long int **rows_li; ///< Pointers to long-integer data + unsigned short int **rows_usi; ///< Pointers to unsigned-short-integer data + unsigned int **rows_ui; ///< Pointers to unsigned-integer data + unsigned long int **rows_uli; ///< Pointers to unsigned-long-integer data + float **rows_f; ///< Pointers to floating-point data + double **rows_d; ///< Pointers to double-precision data + complex float **rows_complex; ///< Pointers to complex floating-point data } rows; - psImage *parent; ///< parent, if a subimage + struct psImage *parent; ///< parent, if a subimage int Nchildren; ///< number of subimages - psImage *children; ///< children of this region; array of Nchildren pointers + struct psImage *children; ///< children of this region; array of Nchildren pointers } psImage; \end{verbatim} @@ -2223,15 +2226,16 @@ pixels. The size of this array is given by the elements \code{(nx, ny)}. The data type of the pixel is defined by the \code{psType type} -entry (see \ref{TBD}). (n.b. that for FITS images, these values are -restricted to the datatypes equivalent to the valid BITPIX values 8, -16, 32, -32, -64). The image represented in the data structure may -represent a subset of the pixels in a complete array, in which case -the image is considered to be the child of that parent array. The -offset of the \code{(0,0)} pixel in this array relative to the parent -array is given by the elements \code{(x0,y0)}. The structure may -include references to subrasters (\code{children, Nchildren}) and/or -to a containing array (\code{parent}). Unless this is image is a -child of another image (represents a subset of the pixels of another -image), the image data is allocated in a contiguous block. +entry (see \ref{arithmetic}). (n.b. that for FITS images, these +values are restricted to the datatypes equivalent to the valid BITPIX +values 8, 16, 32, -32, -64). The image represented in the data +structure may represent a subset of the pixels in a complete array, in +which case the image is considered to be the child of that parent +array. The offset of the \code{(0,0)} pixel in this array relative to +the parent array is given by the elements \code{(x0,y0)}. The +structure may include references to subrasters (\code{children, +Nchildren}) and/or to a containing array (\code{parent}). Unless this +is image is a child of another image (represents a subset of the +pixels of another image), the image data is allocated in a contiguous +block. We require a variety of functions to manipulate these image @@ -2511,6 +2515,7 @@ expected that the implementation of these functions will employ pre-processor macros to perform the onerous task of creating the -loops. Also note that \code{psVectors} is equivalent to -\code{psFloatArray}. +loops. Also note that \code{psVector} is equivalent to +\code{psFloatArray}. An attempt to perform an arithmetic operation on +an object of dimension \code{PS_DIMEN_OTHER} should produce an error. Binary operations between an image and a vector have a potential @@ -2932,11 +2937,11 @@ /// Add item to the end of the metadata. Combines psMetadataItemAlloc and psMetadataAppendItem psMetadataItem *psMetadataAppend(psMetadata *restrict md, ///< Metadata to add to - int typeFlags ///< type of this piece of metadata + flags - const void *val, ///< value of new item N.b. a pointer even if the item - ///< is of type e.g. int - const char *comment, ///< comment associated with item - const char *name, ///< name of new item of metadata (may be in sprintf - ///< format) - ... ///< possible arguments for name format + int typeFlags ///< type of this piece of metadata + flags + const void *val, ///< value of new item N.b. a pointer even if the item + ///< is of type e.g. int + const char *comment, ///< comment associated with item + const char *name, ///< name of new item of metadata (may be in sprintf + ///< format) + ... ///< possible arguments for name format ); \end{verbatim} @@ -3346,5 +3351,5 @@ typedef struct { int x0, y0; ///< Offset from the lower-left corner - int nx, ny; ///< Image binning + int nx, ny; ///< Image binning psImage *image; ///< imaging area of cell psDlist *objects; ///< objects derived from cell @@ -3444,5 +3449,5 @@ psChip *chips; ///< Chips in the Focal Plane Array - psMetadata *md; ///< FPA-level metadata + psMetadata *md; ///< FPA-level metadata psDistortion *TPtoFP; ///< Transformation term from psDistortion *FPtoTP; ///< Transformation term from