Changeset 348
- Timestamp:
- Mar 31, 2004, 6:40:36 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/pslib/psLibSDRS.tex (modified) (39 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/pslib/psLibSDRS.tex
r347 r348 1 %%% $Id: psLibSDRS.tex,v 1.2 0 2004-04-01 04:40:14 eugene Exp $1 %%% $Id: psLibSDRS.tex,v 1.21 2004-04-01 04:40:36 price Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 387 387 \end{verbatim} 388 388 % 389 The corresponding callback have the following form:389 The corresponding callbacks have the following form: 390 390 % 391 391 \begin{verbatim} … … 402 402 \code{psMemAllocateCBSet} and \code{psMemFreeCBSet} are used to 403 403 increment the values of \code{p_psMemAllocateID} and 404 \code{p_psMemFreeID} respectively. For example, the return value404 \code{p_psMemFreeID} respectively. For example, a return value of 405 405 \code{0} implies that the value is unchanged; if the value is \code{2} 406 406 the callback will be called again when the memory ID counter has 407 407 increased by two. This functionality may be useful to check, for 408 example, every 100th block allocated. The function, \code{long 409 psMemGetId(void);} returns the next identification number to be 410 assigned to a memory block. This function can be used to guide the 411 choice of ID set withthe functions above.408 example, every 100th block allocated. The function, \code{long psMemGetId(void);} 409 returns the next identification number to be assigned to a memory 410 block. This function can be used to guide the choice of ID set with 411 the functions above. 412 412 413 413 \subsubsection{Memory Tracing and Corruption Checks} … … 438 438 or the corresponding memory reference will be lost. 439 439 440 If the argument \code{fd} is non \code{NULL}, a one-line summary440 If the argument \code{fd} is non-\code{NULL}, a one-line summary 441 441 of each block that has been allocated but not freed is written to that 442 442 file descriptor. … … 484 484 be in the valid range and should correspond to the address of the 485 485 \code{psMemBlock}). For an example implementation of the 486 \code{refCounter} facilities, see the discussion of \code{psDlist} 486 \code{refCounter} facilities, see the discussion of \code{psDlist}. 487 487 488 488 \tbd{REF}. … … 495 495 code); the latter means information about the processing that must be 496 496 collected and saved, even in the production system. We envision that 497 we will make extensive use of \code{psTrace} throughout the \PS{}497 extensive use will be made of \code{psTrace} throughout the \PS{} 498 498 code. 499 499 … … 520 520 lowest-level step-by-step messages would be printed. 521 521 522 The PSLib tracing facility provides the above functionality along with523 the ability to assign different trace levels to different types of 524 messages. Each trace message when placed in the code is assigned to 525 be part of a specific tracing 'facility', defined in more detail 526 below. The trace level for that specific message is also set when the 527 message is placed. Each facility may have its trace level set 528 independently. Thus, it is possible to request detailed trace output 529 for one facility while minimizing the verbosity of the trace output 530 from the rest of the program. 522 The PSLib tracing facility will provide the above functionality, along 523 with the ability to assign different trace levels to messages from 524 different software components. Each trace message when placed in the 525 code is assigned to be part of a specific tracing 'facility', defined 526 in more detail below. The trace level for that specific message is 527 also set when the message is placed. Each facility may have its trace 528 level set independently. Thus, it is possible to request detailed 529 trace output for one facility while minimizing the verbosity of the 530 trace output from the rest of the program. 531 531 532 532 The trace facilities consist of a hierarchy of names. A trace … … 536 536 would be \code{'.A'}, followed by \code{.A.B}, and so on. The 537 537 relationship is seen in two ways. First, a facility inherits the 538 trace level of its parent unless specified. Second, the hierarchy is539 used to format the listing of the trace facilities. The first of 540 these rules provides a mechanism to define the default trace levels 541 for any facility even if it has not been registered explicitly since 542 all named facilities are implicitly children of the top level facility 543 (\code{.}). The second rule is simply an organizational technique to 544 make the listing of facility information clear.538 trace level of its parent unless explicitly specified. Second, the 539 hierarchy is used to format the listing of the trace facilities. The 540 first of these rules provides a mechanism to define the default trace 541 levels for any facility even if it has not been registered explicitly 542 since all named facilities are implicitly children of the top level 543 facility (\code{.}). The second rule is simply an organizational 544 technique to make the listing of facility information clear. 545 545 546 546 The API to place a trace message in the code, and simultaneously set … … 567 567 where \code{level} specifies the current trace level for the facility 568 568 named by \code{facil}. The currently defined trace level for a given 569 facility isdetermined by the function:569 facility may be determined by the function: 570 570 % 571 571 \begin{verbatim} … … 577 577 \code{psTrace}) shall be printed if and only if 578 578 \code{psGetTraceLevel(facil)} returns a value greater than or equal to 579 the value of \code{myLevel} for that message. 580 581 PSLib includes a utility function for examining the current tracing 582 levels of all facilities: \code{void psPrintTraceLevels(void);}. This 583 function will print the hierarchy of trace facilities along with the 584 current trace level for each facility. For example, a particular 579 the value of \code{myLevel} for that message. That is, a larger 580 number for the trace level corresponds to lower-level statements, and 581 hence is more verbose. 582 583 PSLib will include a utility function for examining the current 584 tracing levels of all facilities: \code{void psPrintTraceLevels(void);}. 585 This function will print the hierarchy of trace facilities along with 586 the current trace level for each facility. For example, a particular 585 587 program may have a few facilities defined, along with their trace 586 588 levels. A call to \code{psPrintTraceLevels} may produce a listing … … 612 614 % 613 615 \begin{verbatim} 614 ERROR: flat-field image foo.fits is invalid (printed)615 doing the divide (printed)616 got an invalid pixel value (NaN) at 500,20 (printed)617 divide is done (printed)616 ERROR: flat-field image foo.fits is invalid 617 doing the divide 618 got an invalid pixel value (NaN) at 500,20 619 divide is done 618 620 \end{verbatim} 619 621 % … … 630 632 % 631 633 632 The tracing facility should be made available, or not, on compilation.633 If the C pre-processor macro \code{PS_NO_TRACE} is defined, all trace 634 code shall be replaced by empty space so that none of the code is 635 compiled. This can be implemented via macro front-ends to private 636 versions of the user APIs. In addition, a function \code{void 637 psTraceReset(void)} will set all trace levels to 0.634 The availability of the tracing facility at run-time, shall be decided 635 at compilation: If the C pre-processor macro \code{PS_NO_TRACE} is 636 defined, all trace code shall be replaced by empty space so that none 637 of the code is compiled. This can be implemented via macro front-ends 638 to private versions of the user APIs. In addition, a function 639 \code{void psTraceReset(void)} will set all trace levels to 0. 638 640 639 641 \tbd{ability to send trace messages to output locations other than stdout?} … … 686 688 \end{verbatim} 687 689 % 688 A specific message invoked with \code{psLogMsg} is only printed if its 689 value of \code{myLevel} is less than the current value set by 690 \code{psSetLogLevel}. 690 This function returns the previous log level. A specific message 691 invoked with \code{psLogMsg} is only printed if its value of 692 \code{myLevel} is less than the current value set by 693 \code{psSetLogLevel}. 691 694 692 695 Log messages are sent to the destination most recently set using: … … 715 718 \end{verbatim} 716 719 where \code{YYYY}, \code{MM}, \code{DD}, \code{hh}, \code{mm}, and 717 \code{ss} are the year, month (Jan ==1), day of the month, hours720 \code{ss} are the year, month (Jan is 01), day of the month, hours 718 721 (0--23), minutes, and seconds when the log message was received. Note 719 722 that the timestamp is in ISO order, and that the timezone is GMT 720 723 (hence the \code{Z}). The \code{hostname} is returned by 721 \code{gethostname}, \code{L} is a letter associated with the level724 \code{gethostname}, \code{L} is a character associated with the level 722 725 (\code{A}, \code{E}, \code{W}, and \code{I} for \code{PS_LOG_ABORT}, 723 726 \code{PS_LOG_ERROR}, \code{PS_LOG_WARN}, and \code{PS_LOG_INFO} … … 733 736 % 734 737 The possible order of the format entries is fixed and not determined 735 by the order of the letters . Selecting an output format with fewer736 than the complete set of 5 entries simply removes those entries from 737 the output messages.738 by the order of the letters used in \code{psSetLogFormat}. Selecting 739 an output format with fewer than the complete set of 5 entries simply 740 removes those entries from the output messages. 738 741 739 742 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% … … 741 744 \subsection{Miscellaneous Utilities} 742 745 743 We require a several very low-functions. Two functions provide746 We require several very low-level functions. Two functions provide 744 747 conveniences tied to the logging facilities: 745 748 % … … 764 767 % 765 768 The first function simply converts the argument to a string 766 \tbd{explanation of usage and rational ?}. The second function,769 \tbd{explanation of usage and rationale?}. The second function, 767 770 \code{psStringCopy}, shall allocate a sufficient memory block and 768 771 return a copy of the input string. Similarly, \code{psStringNCopy} … … 812 815 example, if $x$ were a vector of 100 elements, but $y$ were a vector 813 816 of 1000 elements, the meaning of the operation $x + y$ is unclear. 814 This type of operation should probablybe invalid.817 This type of operation should be invalid. 815 818 816 819 Given that some functions should be able to operate equivalently (or … … 826 829 structure \code{psType}. 827 830 828 Each of these equivalent data type is defined by a structure in which831 Each of these equivalent data types is defined by a structure in which 829 832 the first element is always of type \code{psType}. This element 830 833 defines both the dimensions of the array and the data type of each … … 832 835 \begin{verbatim} 833 836 typedef struct { 834 psDimen dimen; 835 psElemType type; 837 psDimen dimen; ///< The dimensionality 838 psElemType type; ///< The type 836 839 } psType; 837 \ begin{end}840 \end{verbatim} 838 841 where \code{psDimen dimen} defines the dimensionality of the data and 839 842 \code{psElemType type} defines the data type of each element. These … … 841 844 \begin{verbatim} 842 845 typedef enum { 843 PS_DIMEN_SCALAR, 844 PS_DIMEN_VECTOR, 845 PS_DIMEN_TRANSV, 846 PS_DIMEN_MATRIX, 847 PS_DIMEN_OTHER 846 PS_DIMEN_SCALAR, ///< Scalar 847 PS_DIMEN_VECTOR, ///< A vector 848 PS_DIMEN_TRANSV, ///< A transposed vector 849 PS_DIMEN_MATRIX, ///< A matrix 850 PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic 848 851 } psDimen; 849 852 \end{verbatim} … … 851 854 \begin{verbatim} 852 855 typedef enum { 853 PS_TYPE_CHAR, 854 PS_TYPE_SHORT, 855 PS_TYPE_INT, 856 PS_TYPE_LONG, 857 PS_TYPE_UCHAR, 858 PS_TYPE_USHORT, 859 PS_TYPE_UINT, 860 PS_TYPE_ULONG, 861 PS_TYPE_FLOAT, 862 PS_TYPE_DOUBLE, 863 PS_TYPE_COMPLEX, 864 PS_TYPE_OTHER, 856 PS_TYPE_CHAR, ///< Character 857 PS_TYPE_SHORT, ///< Short integer 858 PS_TYPE_INT, ///< Integer 859 PS_TYPE_LONG, ///< Long integer 860 PS_TYPE_UCHAR, ///< Unsigned character 861 PS_TYPE_USHORT, ///< Unsigned short integer 862 PS_TYPE_UINT, ///< Unsigned integer 863 PS_TYPE_ULONG, ///< Unsigned long integer 864 PS_TYPE_FLOAT, ///< Floating point 865 PS_TYPE_DOUBLE, ///< Double-precision floating point 866 PS_TYPE_COMPLEX, ///< Complex numbers consisting of floating point 867 PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic 865 868 } psElemType; 866 869 \end{verbatim} … … 871 874 872 875 We require several types of basic one-dimensional arrays: arrays of 873 values of type \code{int}, \code{float}, \code{double}, 874 \code{complex}, and \code{void *}. We have defined structures for 875 these types which are all equivalent. We illustrate them with the 876 example of\code{psFloatArray}:876 values of type \code{int}, \code{float}, \code{double}, \code{complex float}, 877 and \code{void *}. We have defined structures for these types 878 which are all equivalent. We illustrate them with the example of 879 \code{psFloatArray}: 877 880 % 878 881 \begin{verbatim} 879 882 typedef struct { 880 psType type; 881 int nalloc; 882 int n; 883 float *arr; 883 psType type; ///< Type of data. Must be first element 884 int nalloc; ///< Total number of elements available 885 int n; ///< Number of elements in use 886 float *arr; ///< The array data 884 887 } psFloatArray; 885 888 \end{verbatim} … … 889 892 allocated ($s \ge n$). The allocated memory is available at 890 893 \code{arr}. The data type is defined by the first element, 891 \code{psType}. The structure is associated with a constructor and a destructor: 894 \code{psType}. The structure is associated with a constructor and a 895 destructor: 892 896 % 893 897 \begin{verbatim} … … 899 903 In these functions, \code{nalloc} is the number of elements to 900 904 allocate. For \code{psFloatArrayAlloc}, the value of 901 \code{psFloatArray.n} is set to 0 and the allocated arrays are 902 initialized to 0.0. For \code{psFloatArrayRealloc}, if the value of 903 \code{nalloc} is smaller than the current value of 905 \code{psFloatArray.n} is set to 0. For \code{psFloatArrayRealloc}, if 906 the value of \code{nalloc} is smaller than the current value of 904 907 \code{psFloatArray.n}, then \code{psFloatArray.n} is set to 905 908 \code{nalloc}, the array is adjusted down to match \code{nalloc}, and … … 927 930 require an array of pointers of type \code{void}, with which we can 928 931 carry around a collection of data of an arbitrary type which is more 929 complicated than the simple numeric types above. The structure is a follows: 932 complicated than the simple numeric types above. The structure is as 933 follows: 930 934 % 931 935 \begin{verbatim} 932 936 typedef struct { 933 psType type; 934 int nalloc; 935 int n; 936 void **arr; 937 psType type; ///< Type of data. Must be first element 938 int nalloc; ///< Total number of elements available 939 int n; ///< Number of elements in use 940 void **arr; ///< The array data 937 941 } psVoidPtrArray; 938 942 \end{verbatim} … … 1102 1106 \begin{verbatim} 1103 1107 typedef struct { 1104 int nbucket; 1105 psHashBucket **buckets; 1108 int nbucket; // number of buckets 1109 psHashBucket **buckets; // the buckets themselves 1106 1110 } psHash; 1107 1111 \end{verbatim} … … 1113 1117 \begin{verbatim} 1114 1118 typedef struct psHashBucket { 1115 char *key; 1116 void *data; 1117 struct psHashBucket *next; 1119 char *key; // key for this item of data 1120 void *data; // the data itself 1121 struct psHashBucket *next; // list of other possible keys 1118 1122 } psHashBucket; 1119 1123 \end{verbatim} … … 1491 1495 /** Convert vector to matrix. */ 1492 1496 psImage * 1493 psVectorToMatrix(psImage *out, 1494 psVector *myVector//!< Vector to convert1497 psVectorToMatrix(psImage *out, //!< Matrix to return, or NULL 1498 psVector *myVector //!< Vector to convert 1495 1499 ); 1496 1500 \end{verbatim} … … 1515 1519 /** Fast Fourier Transform */ 1516 1520 typedef struct { 1517 p_psFFTDetails *details; 1518 int nx, ny; 1519 float **real; 1520 void *fourier; 1521 p_psFFTDetails *details; //!< Details on FFT implementation (private) 1522 int nx, ny; //!< Size in x and y 1523 float **real; //!< Data in real space 1524 void *fourier; //!< Data in fourier space; implementation dependent 1521 1525 } psFFT; 1522 1526 \end{verbatim} … … 1537 1541 /** Constructor */ 1538 1542 psFFT * 1539 psFFTAlloc(psImage *image 1540 1543 psFFTAlloc(psImage *image //!< Image to transform 1544 ); 1541 1545 1542 1546 /** Constructor for 1D case */ 1543 1547 psFFT * 1544 psFFTAlloc1D(const psFloatArray *arr 1545 1548 psFFTAlloc1D(const psFloatArray *arr //!< Array to transform 1549 ); 1546 1550 1547 1551 /** Destructor. Returns the data in the real space as an image. */ 1548 1552 psImage * 1549 psFFTFree(psImage *out, 1550 psFFT *restrict fft//!< FFT to destroy1551 1553 psFFTFree(psImage *out, //!< Image to write the data to, or NULL 1554 psFFT *restrict fft //!< FFT to destroy 1555 ); 1552 1556 \end{verbatim} 1553 1557 … … 1557 1561 /** Forward FFT: from real to fourier space */ 1558 1562 psFFT * 1559 psFFTForwardTransform(psFFT *fft 1560 1563 psFFTForwardTransform(psFFT *fft //!< FFT to apply 1564 ); 1561 1565 1562 1566 /** Reverse FFT: from fourier to real space */ 1563 1567 psFFT * 1564 psFFTReverseTransform(psFFT *fft 1565 1568 psFFTReverseTransform(psFFT *fft //!< FFT to apply 1569 ); 1566 1570 \end{verbatim} 1567 1571 … … 1572 1576 /** Apply filter function in fourier space */ 1573 1577 psFFT * 1574 psFFTFilter(psFFT *fft, 1575 float (*filterFunc)(int kx, int ky)//!< External filter function1576 1578 psFFTFilter(psFFT *fft, //!< FFT to use (input and output) 1579 float (*filterFunc)(int kx, int ky) //!< External filter function 1580 ); 1577 1581 1578 1582 /** Apply complex filter function */ 1579 1583 psFFT * 1580 psFFTFilterComplex(psFFT *fft, 1581 1582 1583 1584 psFFTFilterComplex(psFFT *fft, //!< FFT to use (input and output) 1585 float (*realFilterFunc)(int kx, int ky), //!< External filter function, real part 1586 float (*imagFilterFunc)(int kx, int ky) //!< External filter function, imaginary part 1587 ); 1584 1588 \end{verbatim} 1585 1589 … … 1590 1594 /** Calculate cross-correlation function */ 1591 1595 psFFT * 1592 psFFTCrossCorrelate(psFFT *out 1593 1594 1596 psFFTCrossCorrelate(psFFT *out //!< Output FFT (or NULL) 1597 psFFT *fft1, psFFT *fft2 //!< FFTs to use in cross-correlation 1598 ); 1595 1599 \end{verbatim} 1596 1600 … … 1600 1604 /** Calculate power spectrum */ 1601 1605 psFFT * 1602 psFFTPowerSpec(psFFT *fft 1603 1606 psFFTPowerSpec(psFFT *fft //!< FFT to use (input and output) 1607 ); 1604 1608 \end{verbatim} 1605 1609 … … 1609 1613 /** Multiply two Fourier transforms, as for convolution */ 1610 1614 psFFT * 1611 psFFTMultiplyFT(psFFT *out, 1612 1613 1615 psFFTMultiplyFT(psFFT *out, //!< Output FFT (or NULL) 1616 const psFFT *fft1, const psFFT *fft2 //!< FFTs to multiply 1617 ); 1614 1618 \end{verbatim} 1615 1619 … … 1620 1624 /* Convert the real data in the FFT struct to an image again */ 1621 1625 psImage * 1622 psFFTGetImage(psImage *out, 1623 const psFFT *fft//!< FFT to get image from1624 1626 psFFTGetImage(psImage *out, //!< Image to write to (or NULL) 1627 const psFFT *fft //!< FFT to get image from 1628 ); 1625 1629 1626 1630 /** Convert the Fourier transform data in the FFT struct to an image of complex numbers */ 1627 1631 psImage * 1628 psFFTGetFT(psImage *out, 1629 const psFFT *fft//!< FFT to get Fourier transform from1630 1632 psFFTGetFT(psImage *out, //!< Image to write to (or NULL) 1633 const psFFT *fft //!< FFT to get Fourier transform from 1634 ); 1631 1635 \end{verbatim} 1632 1636 … … 2239 2243 /** The type of a data type */ 2240 2244 typedef struct { 2241 psElemType type; 2242 psDimen dimen; 2245 psElemType type; ///< The type 2246 psDimen dimen; ///< The dimensionality 2243 2247 } psType; 2244 2248 2245 2249 /** Types of the elements of vectors, images, etc. */ 2246 2250 typedef enum { 2247 PS_TYPE_CHAR, 2248 PS_TYPE_SHORT, 2249 PS_TYPE_INT, 2250 PS_TYPE_LONG, 2251 PS_TYPE_UCHAR, 2252 PS_TYPE_USHORT, 2253 PS_TYPE_UINT, 2254 PS_TYPE_ULONG, 2255 PS_TYPE_FLOAT, 2256 PS_TYPE_DOUBLE, 2257 PS_TYPE_COMPLEX, 2258 PS_TYPE_OTHER, 2251 PS_TYPE_CHAR, ///< Character 2252 PS_TYPE_SHORT, ///< Short integer 2253 PS_TYPE_INT, ///< Integer 2254 PS_TYPE_LONG, ///< Long integer 2255 PS_TYPE_UCHAR, ///< Unsigned character 2256 PS_TYPE_USHORT, ///< Unsigned short integer 2257 PS_TYPE_UINT, ///< Unsigned integer 2258 PS_TYPE_ULONG, ///< Unsigned long integer 2259 PS_TYPE_FLOAT, ///< Floating point 2260 PS_TYPE_DOUBLE, ///< Double-precision floating point 2261 PS_TYPE_COMPLEX, ///< Complex numbers consisting of floating point 2262 PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic 2259 2263 } psElemType; 2260 2264 2261 2265 /** Dimensions of a data type */ 2262 2266 typedef enum { 2263 PS_DIMEN_SCALAR, 2264 PS_DIMEN_VECTOR, 2265 PS_DIMEN_TRANSV, 2266 PS_DIMEN_IMAGE, 2267 PS_DIMEN_OTHER 2267 PS_DIMEN_SCALAR, ///< Scalar 2268 PS_DIMEN_VECTOR, ///< A vector 2269 PS_DIMEN_TRANSV, ///< A transposed vector 2270 PS_DIMEN_IMAGE, ///< An image 2271 PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic 2268 2272 } psDimen; 2269 2273 \end{verbatim} … … 2282 2286 /** Transpose a vector. Changes the type to a PS_DIMEN_TRANSV */ 2283 2287 psVector *psVectorTranspose(psVector *out, //!< Output vector, or NULL 2284 2288 psVector *myVector //!< Vector to be transposed 2285 2289 ); 2286 2290 \end{verbatim}
Note:
See TracChangeset
for help on using the changeset viewer.
