Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 276) +++ trunk/doc/pslib/psLibSDRS.tex (revision 284) @@ -10,5 +10,5 @@ \organization{Institute for Astronomy} \version{DR} -\docnumber{PSDC-xxx-xxx} +\docnumber{PSDC-430-007} % note the use of the docnumber & version number: % the complete PSDC document number is given by @@ -24,5 +24,5 @@ \RevisionsStart % version Date Description -\theversion & 2003 Mar 11 & Hacking \\ +\theversion & 2003 Mar 11-- & Draft \\ \RevisionsEnd @@ -38,7 +38,7 @@ %a regular \code{\label}, but defines the hyperlink too). -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{\PS{} Library (PSLib)} @@ -58,10 +58,10 @@ \end{itemize} -Below we sketch out approximately 120 APIs which specify the required +Below we sketch out approximately 200~APIs which specify the required capabilities. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{System Utilities} @@ -73,6 +73,6 @@ The \PS{} software system will need a level of memory management -placed between the operating system (malloc/free) and the high level -routines (e.g. \code{psMetaDataAlloc}). +placed between the operating system (\code{malloc}/\code{free}) and +the high level routines (e.g.\ \code{psMetaDataAlloc}). This layer is in addition to the possibility that specific heavily @@ -80,5 +80,5 @@ but as we have specified that all user-level objects be allocated via \code{typeAlloc/typeFree} functions, we will easily be able to -implement such functionality without impacting on the facilities +implement such functionality without impacting the facilities described here. @@ -103,8 +103,8 @@ \item - We need to provide a mechanism for tracking and fixing memory - leaks. While it is possible to do this by linking with external - libraries (\tbd{reference}), it is convenient to do so within the - \PS{} framework. + We need to provide a mechanism for tracking and fixing memory leaks. + While it is possible to do this by linking with external libraries + (e.g.\ Electric Fence, \href{gnu.org}), it is convenient to do so + within the \PS{} framework. \item @@ -126,9 +126,9 @@ The previous section laid out a number of desiderata for a memory management system. Rather than implement our own heap-manager at this -stage of the project, I propose that we put in place a sufficient -set of data structures and APIs, but initially implement only -a simple subset (e.g. that we not implement a multi-bucket memory -manager that takes in 100Mb chunks from the system and performs -sophisticated defragmentation and garbage collection). +stage of the project, we propose to put in place a sufficient set of +data structures and APIs, but initially implement only a simple subset +(e.g.\ that we not implement a multi-bucket memory manager that takes +in 100Mb chunks from the system and performs sophisticated +defragmentation and garbage collection). Subject to agreement with the IfA, some of the functions proposed @@ -184,13 +184,13 @@ The types and function prototypes for the part of the memory API concerned with allocating and freeing memory are given in table -\ref{tabUsageAPI}). +\ref{tabUsageAPI}. N.b. \begin{itemize} \item - The functions \code{psAlloc}, \code{psRealloc}, and - \code{psFree} are defined, and are required to be equivalent to - \code{p_psAlloc}, \code{p_psRealloc}, and \code{p_psFree} - with the final two arguments \code{"(unknown)"} and \code{0}. + The functions \code{psAlloc}, \code{psRealloc}, and \code{psFree} + are defined, and are required to be equivalent to \code{p_psAlloc}, + \code{p_psRealloc}, and \code{p_psFree} with the final two arguments + \code{__FILE__} and \code{__LINE__}. In the descriptions that follow, I shall not distinguish between the @@ -211,5 +211,5 @@ \item In all cases, application code will call - \code{p_\{psAlloc,psRealloc,psFree\}} via the macros defined above. + \CODE|p_{psAlloc,psRealloc,psFree}| via the macros defined above. \item @@ -229,13 +229,15 @@ \item - Where practical and efficient, the memory manager shall call - the routine registered using the \code{psMemProblemSetCB} - (see section \ref{secMemAdvanced}) - whenever a corrupted block of memory is discovered. For example, - doubly-freed blocks can be detected by checking \code{psMemBlock.refcntr}. + Where practical and efficient, the memory manager shall call the + routine registered using the \code{psMemProblemSetCB} (see section + \ref{secMemAdvanced}) whenever a corrupted block of memory is + discovered. For example, doubly-freed blocks can be detected by + checking \code{psMemBlock.refcntr}. \item There is no \code{psCalloc} function. Initialisation of data is almost always more complex than setting all bytes to 0. + Correspondingly, the system call \code{calloc} should be disabled + using the pre-processor. \end{itemize} @@ -284,12 +286,12 @@ \begin{tabular}{ll|l} \textbf{type} & \textbf{Name} & \textbf{Function of callback} \\ -psMemProblemCallback & psMemProblemSetCB & +\code{psMemProblemCallback} & \code{psMemProblemSetCB} & Called when a problem is detected with data being managed on the heap \\ -psMemExhaustedCallback & psMemExhaustedSetCB & +\code{psMemExhaustedCallback} & \code{psMemExhaustedSetCB} & Called when \code{psAlloc} is unable to satisfy a memory request. \\ -psMemCallback & psMemAllocateSetCB & +\code{psMemCallback} & \code{psMemAllocateSetCB} & Callback is called when the \code{psMemBlock} with a specified ID is allocated. \\ -psMemCallback & psMemFreeSetCB & +\code{psMemCallback} & \code{psMemFreeSetCB} & Callback is called when the \code{psMemBlock} with a specified ID is freed. \\ @@ -310,5 +312,6 @@ \item - \code{psMemGetId} returns the current value of \code{psMemBlock.id}. + \code{psMemGetId} returns the next identification number to be + assigned to a \code{psMemBlock.id}. \item @@ -414,8 +417,5 @@ } \end{verbatim} -\begin{caption}{An example of reference counting} - \hlabel{tabReferenceCounting} - An example of using reference counting -\end{caption} +\caption{An example of reference counting} \end{table} @@ -443,5 +443,5 @@ \subsection{Tracing and Logging} -This document defines the \PS{} Tracing and Logging APIs; the former +This section defines the \PS{} Tracing and Logging APIs; the former refers to debug information that we wish to be able to turn on and off without recompiling (although it will \emph{not} be available in @@ -683,7 +683,7 @@ The fields included in the log message may be controlled using \code{psSetLogFormat} which expects a string consisting of the letters \code{H} (host), \code{L} (level), \code{M} (message), -\code{N} (name), and \code{T} (time). The default is \code{HLMNT}. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\code{N} (name), and \code{T} (time). The default is \code{THLNM}, as shown above. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Data Containers} @@ -768,5 +768,5 @@ If \code{psDlistFree}'s argument \code{elemFree} is NULL, the list should be deleted, but not the elements on it (although their -\code{refcounter}'s should be decremented). +\code{refcounter}s should be decremented). Iteration over all elements of the list is provided by the functions: @@ -781,5 +781,5 @@ many iteration cursors should be used; it must currently always be \code{0}. -Explicit traversal of the list using the \code{psDlistElem}'s +Explicit traversal of the list using the \code{psDlistElem}s \code{prev} and \code{next} pointers is also supported. @@ -793,15 +793,7 @@ \subsection{The \PS{} Array types} -\begin{table} - \begin{verbatim} - \end{verbatim} - \begin{caption}{The array creation macros defined in \file{psArray.h}} - \hlabel{tabPsArray} - \end{caption} -\end{table} - \subsubsection{Arrays of Simple Types} -Any \PS/ datatype \code{psType} may be associated with an array type +Any \PS{} datatype \code{psType} may be associated with an array type \code{psTypeArray}: \begin{verbatim} @@ -825,8 +817,8 @@ from \file{psArray.h} (table \ref{tabPsArray}), \code{PS_DECLARE_ARRAY_TYPE(psType)} and -\code{PS_CREATE_ARRAY_TYPE(psType)}. The former defines the typedef +\code{PS_CREATE_ARRAY_TYPE(psType)}. The former defines the \code{typedef} and declares the prototypes (and is thus suitable for use in a header file); the latter generates the code for the three functions -\code{psType(Alloc|Realloc|Free} (and should thus appear in exactly one +\code{psType(Alloc|Realloc|Free)} (and should thus appear in exactly one source file for a given type). @@ -866,5 +858,5 @@ declares the prototypes (and is thus suitable for use in a header file) and the latter generates the code for the three functions -\code{psType(Alloc|Realloc|Free} (and should thus appear in exactly one +\code{psType(Alloc|Realloc|Free)} (and should thus appear in exactly one source file for a given type). @@ -881,9 +873,9 @@ \hlabel{secArrayVoidPtr} -Arrays of \code{void *} are different, as the need an explicitly-specified +Arrays of \code{void *} are different, as they need an explicitly-specified destructor. -\file{psArray.h} shall specify a type \code{psVoidPtrArray} that -behaves in all respects as if it had been created with: +We require a type \code{psVoidPtrArray} that behaves in all respects +as if it had been created with: \begin{verbatim} typedef void *psVoidPtr; @@ -1011,5 +1003,5 @@ The routine \code{psHashInsert} must provide a non-NULL \code{itemFree} -argument if it wishes to change the value previously inserted keys; +argument if it wishes to change the value for previously inserted keys; if \code{itemFree} is NULL attempting to insert a pre-existing key is an error, and the routine will return NULL. If \code{psHashInsert} @@ -1023,7 +1015,4 @@ \subsection{Miscellaneous Utilities} - -The API for miscellaneous \PS{} utilities is provided by \file{psMisc.h} -which shall be included by \file{psUtils.h}. \begin{table} @@ -1053,7 +1042,7 @@ \code{psStringCopy} shall allocate and return a copy of the input string. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Data manipulation} @@ -1072,5 +1061,5 @@ \end{itemize} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Bit masks} @@ -1103,7 +1092,6 @@ \begin{itemize} \item Set a bit; -\item Check if a bit is set; -\item \code{OR} two bit masks; and -\item \code{AND} two bit masks. +\item Check if a bit is set; and +\item \code{OR}, \code{AND} and \code{XOR} two bit masks. \end{itemize} The corresponding APIs are defined below. @@ -1136,10 +1124,10 @@ \end{verbatim} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Vector and Image Arithmetic} We will need to be able to perform various operations on vectors and -matrices, e.g.\ dividing one image by another, subtracting a vector +images, e.g.\ dividing one image by another, subtracting a vector from an image, etc. Both binary operations and unary operations are required. @@ -1173,6 +1161,6 @@ It is desirable to use the same functions for both vectors and -matrices, so inputs are \code{void*}; this necessitates that vectors -and matrices each have a type element at a pre-determined and constant +images, so inputs are \code{void*}; this necessitates that vectors +and images each have a type element at a pre-determined and constant location in the \code{struct}. It is further desirable to allow scalar values to be used within these functions, which requires the @@ -1216,5 +1204,5 @@ Note that the \code{psUnaryOp} is performed on \code{B} in-place. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Sorting} @@ -1243,7 +1231,9 @@ \end{verbatim} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\subsection{Statistics} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Statistics Functions} + +\subsubsection{Array Statistics} We require a very general statistics function, which, given an array @@ -1284,4 +1274,42 @@ \end{verbatim} +The \code{psStats} structure is defined with entries for each of the +desired statistical quantities: + +\begin{verbatim} +/** generic statistics structure */ +typedef struct { + double sampleMean; // 1$). The output image represents a +one-to-one mapping of the pixels in the input image, except for edge +effects. Each pixel in the output image is derived from the +statistics of the corresponding input image pixels based on the +statistics specified by \code{psStats stats}. \tbd{interpolation?} \begin{verbatim} psImage * @@ -1786,5 +1818,5 @@ pixels should be set of \tbd{value}. The center of rotation is always the center pixel of the image. The rotation is specified in the sense -that a positive value is a clock-wise rotation. +that a positive angle is an anti-clockwise rotation. \begin{verbatim} psImage * @@ -1795,5 +1827,5 @@ Shift image by an arbitrary number of pixels (\code{dx,dy}) in either direction. If the shift values are fractional, the output pixel -values shoul interpolate between the input pixel values. The output +values should interpolate between the input pixel values. The output image has the same dimensions as the input image. Pixels which fall off the edge of the output image are loast. Newly exposed pixels are @@ -1853,16 +1885,17 @@ Read an image or subimage from a named file. This function is a -wrapper to the FITS library function. The input parameters allow or a -subimage to be read. The starting pixel of the region is specified by -\code{x,y}, while the dimensions of the requested region are specified -by \code{nx,ny}. A value of -1 for these two parameters specifies the -full array of the requested image. If the native image is a cube, the -value of z specifies the requested slice of the image. The data is -read from the extension specified by extname (matching the EXTNAME -keyword) or by the extnum value (with -1 representing the PHU, 0 the -first extension, etc). This function must return an error if any of -the specified parameters are out of range for the data in the image -file, if the specified image file does not exist. \tbd{what do we do -with a 0D or 1D image?} +wrapper to the FITS library function. The input parameters allow a +full image or a subimage to be read. The starting pixel of the region +is specified by \code{x,y}, while the dimensions of the requested +region are specified by \code{nx,ny}. A value of -1 for these two +parameters specifies the full array of the requested image. If the +native image is a cube, the value of z specifies the requested slice +of the image. The data is read from the extension specified by +extname (matching the EXTNAME keyword) or by the extnum value (with -1 +representing the PHU, 0 the first extension, etc). This function must +generate an error and return \code{NULL} if any of the specified +parameters are out of range for the data in the image file, if the +specified image file does not exist, or the image on disk is zero- or +one-dimensional. \begin{verbatim} psImage * @@ -1893,8 +1926,10 @@ \end{verbatim} +\TBD{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} + Write an image section to named file, which may exist. This operatation may write a portion of an image over the existing bytes of an existing image. If the file does not exist, it should be created. -If the specified extention does not exist, it should be created. If +If the specified extension does not exist, it should be created. If an extension is specified and no PHU exists, a basic PHU should be created. @@ -1905,5 +1940,5 @@ int y, ///< starting y coord of region int z, ///< plane of interest - char *extname, ///< MEF extension name ("PHU" for primary header) + char *extname, ///< MEF extension name ("PHU" for primary header) char *filename) ///< file to write data to \end{verbatim} @@ -1920,4 +1955,6 @@ \end{verbatim} +\TBD{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} + Read header data from a FITS image file into a \code{psMetaData} structure. If the named extension does not exist, the function should @@ -1941,5 +1978,6 @@ \end{verbatim} -Perform a 2-D FFT on the specified image. +Perform a 2-D FFT on the specified image. The returned image is of +type \code{psComplex}. \begin{verbatim} psImage * @@ -1960,6 +1998,7 @@ \end{verbatim} -Clip NaN image pixels to given value. Pixels with NaN or Inf values -are set to the specified value. +Clip NaN image pixels to given value. Pixels with NaN, +Inf or -Inf +values are set to the specified value. Returns the number of clipped +pixels. \begin{verbatim} int @@ -2045,5 +2084,5 @@ Plane is a four-dimensional polynomial, in order to account for any possible dependencies in the astrometry on the stellar magnitude and -colour; the latter serves as a check for charge transfer +colour; the former serves as a check for charge transfer inefficiencies, while the latter will correct chromatic refraction, both through the atmosphere and the corrector lenses. @@ -2058,9 +2097,9 @@ A frame is the result of a single read of a cell (or a portion -thereof). It contains a pointer to the data pixels with a -separate pointer to the overscan pixels, and additional pointers to -the objects found in the frame, and the frame metadata. It also -contains the offset from the lower-left corner of the chip, in the -case that the CCD was windowed. +thereof). It contains a pointer to the pixel data, a separate pointer +to the overscan pixels, and additional pointers to the objects found +in the frame, and the frame metadata. It also contains the offset +from the lower-left corner of the chip, in the case that the CCD was +windowed. \begin{verbatim} @@ -2619,7 +2658,6 @@ on both). -We are using the standard \PS{} doubly-linked list types \code{psDlist} and \code{psHash} -(see \href{file:utils#psDlist}{utils.pdf:psDlist} and \href{file:utils#psHash}{utils.pdf:psHash} for details). -For example: +We are using the standard \PS{} doubly-linked list types +\code{psDlist} and \code{psHash}. For example: \begin{verbatim} for (int i = 0; i < 10; i += 5) { @@ -2655,5 +2693,5 @@ The \code{psMetaDataItem} struct includes a name. This name should be of -the form \code{name1.name2.name3$\cdots$}, e.g.\hfil\break +the form \code{name1.name2.name3}$\cdots$, e.g.\hfil\break \null\qquad\qquad\code{IPP.phase1.ota12.biassec}. @@ -2732,21 +2770,17 @@ /** A point in 2-D space, with errors. */ -typedef struct { - union { - double x; //!< x position - double r; //!< x position - } x; - union { - double xErr; //!< Error in x position - double rErr; //!< Error in x position - } dx; - union { - double y; //!< y position - double d; //!< y position - } y; - union { - double yErr; //!< Error in y position - double dErr; //!< Error in y position - } dy; +typedef union { + struct { + double x; //!< x position + double y; //!< y position + double xErr; //!< Error in x position + double yErr; //!< Error in y position + } xy; + struct { + double r; //!< RA + double d; //!< Dec + double rErr; //!< Error in RA + double dErr; //!< Error in Dec + } rd; } psCoord; \end{verbatim} @@ -2811,6 +2845,6 @@ psGetOffset(const psCoord *restrict position1, //!< Position 1 const psCoord *restrict position2, //!< Position 2 - char *system) -; + const char *type //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc + ); \end{verbatim} @@ -2820,6 +2854,6 @@ psApplyOffset(const psCoord *restrict position, //!< Position const psCoord *restrict offset, //!< Offset - char *system) -; + const char *type //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc + ); \end{verbatim} @@ -2904,8 +2938,9 @@ -Photometric observations are performed in a photometric system, and -are must be related to other photometric systems. We require a data -structure which defines a photometric system, as well as a structure -to define the transformation between photometric systems. +Photometric observations are performed in an instrumental photometric +system, and must be related to other photometric systems. We +require a data structure which defines a photometric system, as well +as a structure to define the transformation between photometric +systems. The photometric system is defined by the psPhotSystem structure. @@ -2920,9 +2955,9 @@ \begin{verbatim} typedef struct { - int ID; - char *name; - char *camera; - char *filter; - char *detector; + int ID; //!< ID number for this photometric system + char *name; //!< Name of photometric system + char *camera; //!< Camera for photometric system + char *filter; //!< Filter used for photometric system + char *detector; //!< Detector used for photometric system } psPhotSystem; \end{verbatim} @@ -2932,10 +2967,10 @@ \begin{verbatim} typedef struct { - psPhotSystem src; - psPhotSystem dst; - psPhotSystem pP, pM; ///< Colour reference - psPhotSystem sP, sM; ///< Colour reference - float pA, sA; ///< - psPolynomial3D transform; + psPhotSystem src; //!< Source photometric system + psPhotSystem dst; //!< Destination photometric system + psPhotSystem pP, pM; ///< Primary colour reference + psPhotSystem sP, sM; ///< Secondary colour reference + float pA, sA; ///< Colour offset for primary and secondary references + psPolynomial3D transform; //!< Transformation from source to destination } psPhotTransform; \end{verbatim} @@ -2944,8 +2979,8 @@ airmass of the observation and on the colors of the object of interest. For a specific observation, such a transformations can be -defined as a polynomial function of the color the star and the airmass -of the observations. If sufficient data exists, the transformation -between the photometric systems may include more than one color, -constraining the curvature of the stellar spectral energy +defined as a polynomial function of the color of the star and the +airmass of the observations. If sufficient data exists, the +transformation between the photometric systems may include more than +one color, constraining the curvature of the stellar spectral energy distributions. This latter term may be significant for stars which are highly reddened, for example. Derived photometric quantities may @@ -2963,6 +2998,6 @@ $M_{\rm pM}$, $M_{\rm sP}$, $M_{\rm sM}$, observed at an airmass of $z$, the magnitude of the star in the target system $M_{\rm dst}$ is -given by: -$M_{\rm dst} = M_{\rm src} + transform(z, M_{\rm pP} - M_{\rm pM} - pA, M_{\rm sP} - M_{\rm sM} - sA)$ +given by: $M_{\rm dst} = M_{\rm src} + transform(z, M_{\rm pP} - +M_{\rm pM} - pA, M_{\rm sP} - M_{\rm sM} - sA)$. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%