Index: /trunk/doc/modules/ModulesSDRS.tex =================================================================== --- /trunk/doc/modules/ModulesSDRS.tex (revision 4040) +++ /trunk/doc/modules/ModulesSDRS.tex (revision 4041) @@ -1,3 +1,3 @@ -%%% $Id: ModulesSDRS.tex,v 1.41 2005-05-19 02:58:14 price Exp $ +%%% $Id: ModulesSDRS.tex,v 1.42 2005-05-27 21:27:13 jhoblitt Exp $ \documentclass[panstarrs]{panstarrs} @@ -100,9 +100,9 @@ standard locations, with optional command-line override values. -\begin{verbatim} +\begin{prototype} bool pmConfigLoadSite (psMetadata **site, int *argc, char **argv); bool pmConfigLoadCamera (psMetadata **camera, psMetadata *site, psMetadata *header, int *argc, char **argv); bool pmConfigLoadRecipe (psMetadata **recipe, psMetadata *camera, int *argc, char **argv, char *script); -\end{verbatim} +\end{prototype} \code{pmConfigLoadSite} loads basic configuration information from a @@ -198,10 +198,10 @@ before being returned as a \code{psRegion} pointer. -\begin{verbatim} +\begin{prototype} psSTR pmConfigLookupSTR (psMetadata *config, psMetadata *header, char *name); psS32 pmConfigLookupS32 (psMetadata *config, psMetadata *header, char *name); psF64 pmConfigLookupF64 (psMetadata *config, psMetadata *header, char *name); psRegion *pmConfigLookupRegion (psMetadata *config, psMetadata *header, char *name); -\end{verbatim} +\end{prototype} \section{Camera Data Organization \& Camera Geometry} @@ -291,7 +291,7 @@ \subsection{Determine the Camera from the Primary Header} -\begin{verbatim} +\begin{prototype} char *pmCameraFromHeader (psFitsHeader *header, psMetadata *rules); -\end{verbatim} +\end{prototype} This function examines a primary header unit (\code{header}) and @@ -340,8 +340,8 @@ \subsection{Validate the Header set \& Construct the FPA} -\begin{verbatim} +\begin{prototype} bool pmCameraValidateHeaders (psMetadata *headers, psMetadata *camera); psFPA *pmFPAfromHeader (psMetadata *headers, psMetadata *camera); -\end{verbatim} +\end{prototype} These funtions examine the collection of \code{headers} and compare @@ -505,9 +505,9 @@ offset and/or astrometry parameters. -\begin{verbatim} +\begin{prototype} bool pmFPADefineOffsets (psFPA fpa); bool pmFPADefineWCS (psFPA fpa); bool pmFPADefineWCSfromOffsets (psFPA fpa); -\end{verbatim} +\end{prototype} The first function takes a \code{psFPA} structure which has been @@ -569,7 +569,7 @@ boundaries of the cells within chip-based images. -\begin{verbatim} +\begin{prototype} psReadout *pmReadoutLoad (psReadout *input, psFits *f, psCell *cell, int plane); -\end{verbatim} +\end{prototype} \section{Phase 2} @@ -608,9 +608,9 @@ \code{pmSubtractBias} shall subtract the bias from the image. The API shall be the following: -\begin{verbatim} +\begin{prototype} psReadout *pmSubtractBias(psReadout *in, void *fitSpec, const psList *overscans, pmOverscanAxis overscanAxis, const psStats *stat, int nBin, pmFit fit, const psReadout *bias); -\end{verbatim} +\end{prototype} Two types of bias correction may optionally be performed on the input @@ -638,5 +638,5 @@ The \code{overscanAxis} specifies how the prescan/overscan subtraction is to be performed. It is an enumerated type: -\begin{verbatim} +\begin{datatype} /** Overscan axis */ typedef enum { @@ -646,5 +646,5 @@ PM_OVERSCAN_ALL ///< Subtract the statistic of all pixels in overscan region } pmOverscanAxis; -\end{verbatim} +\end{datatype} If the \code{overscanAxis} is \code{PM_OVERSCAN_NONE}, then the @@ -681,5 +681,5 @@ \code{fit} is an enumerated type: -\begin{verbatim} +\begin{datatype} /** Fit types */ typedef enum { @@ -688,5 +688,5 @@ PM_FIT_SPLINE ///< Fit cubic splines } pmFit; -\end{verbatim} +\end{datatype} If \code{fitSpec} is \code{NULL}, or \code{fit} is \code{PM_FIT_NONE}, @@ -738,7 +738,7 @@ \code{coeff}, acting on the flux. The API shall be the following: -\begin{verbatim} +\begin{prototype} psReadout *pmNonLinearityPolynomial(psReadout *in, const psPolynomial1D *coeff); -\end{verbatim} +\end{prototype} The polynomial coefficients, \code{coeff}, will be supplied by the @@ -749,7 +749,7 @@ shall be the following: -\begin{verbatim} +\begin{prototype} psReadout *pmNonLinearityLookup(psReadout *in, const psVector *inFlux, const psVector *outFlux); -\end{verbatim} +\end{prototype} For each pixel in the input image, the function shall find the flux @@ -785,7 +785,7 @@ divide the input image by the flat-field image and return it in place, updating the mask as appropriate. The API shall be the following: -\begin{verbatim} +\begin{prototype} bool pmFlatField(psReadout *in, psReadout *mask, const psReadout *flat); -\end{verbatim} +\end{prototype} Note that the input image, \code{in}, and the flat-field image, @@ -827,5 +827,5 @@ We define several mask values for use in the phase 2 processing: -\begin{verbatim} +\begin{datatype} /** Mask values */ typedef enum { @@ -835,5 +835,5 @@ PM_MASK_FLAT = 0x0008, ///< The pixel is non-positive in the flat-field } pmMaskValue; -\end{verbatim} +\end{datatype} Of these, masks for the charge traps need to be grown by the extent of @@ -850,8 +850,8 @@ pixels in the bad pixel mask that match the value to mask. The API shall be the following: -\begin{verbatim} +\begin{prototype} psReadout *pmMaskBadPixels(psReadout *in, const psImage *mask, unsigned int maskVal, float sat, unsigned int growVal, int grow); -\end{verbatim} +\end{prototype} Note that the input image, \code{in}, is modified in-place. All @@ -882,8 +882,8 @@ subtract a model for the background of the image. The API shall be the following: -\begin{verbatim} +\begin{prototype} psReadout *pmSubtractSky(psReadout *in, psPolynomial2D *poly, psImage *mask, psU8 maskVal, int binFactor, psStats *stats, float clipSD); -\end{verbatim} +\end{prototype} Note that the input image, \code{in}, shall be subtracted in-place. @@ -933,5 +933,5 @@ and so each input image will have the same noise characteristics. -\begin{verbatim} +\begin{datatype} typedef struct { psStats *stats; // Statistics to use in combining pixels @@ -941,5 +941,7 @@ int nKeep; // Number of pixels to be sure to keep } pmCombineParams; - +\end{datatype} + +\begin{prototype} psImage * pmReadoutCombine(psImage *output, // Output image, or NULL @@ -952,5 +954,5 @@ float readnoise // Read noise in e ); -\end{verbatim} +\end{prototype} \code{pmReadoutCombine} combines input images pixel by pixel --- for @@ -1104,5 +1106,5 @@ We start by defining a single source detected in a single band: -\begin{verbatim} +\begin{datatype} typedef struct { pmPeak *peak; // description of peak pixel @@ -1113,10 +1115,10 @@ pmSourceType type; // best identification of object } pmSource; -\end{verbatim} +\end{datatype} This source has the capacity for several types of measurements. The simplest measurement of a source is the location and flux of the peak pixel associated with the source: -\begin{verbatim} +\begin{datatype} typedef struct { int x; // x-coordinate of peak pixel @@ -1125,5 +1127,5 @@ pmPeakType class; // description of peak } pmPeak; -\end{verbatim} +\end{datatype} A peak pixel may have several features which may be determined when @@ -1135,5 +1137,5 @@ than a specific number of neighbors at the same value, within some tolarence: -\begin{verbatim} +\begin{datatype} typedef enum { PM_PEAK_LONE; // isolated peak @@ -1141,5 +1143,5 @@ PM_PEAK_FLAT; // peak has equal-value neighbors } pmPeakType; -\end{verbatim} +\end{datatype} The pixels which contain the source may be specified with the @@ -1154,5 +1156,5 @@ moment information for a specific source: -\begin{verbatim} +\begin{datatype} typedef struct { float x; // x-coord of centroid @@ -1166,5 +1168,5 @@ int nPixels; // number of pixels used } pmMoments; -\end{verbatim} +\end{datatype} An object's flux distribution may be modelled with some analytical @@ -1174,5 +1176,5 @@ discuss the details of these models in section~\ref{ObjectModels}. -\begin{verbatim} +\begin{datatype} typedef struct { pmObjectModel type; // model to be used @@ -1183,7 +1185,7 @@ psS32 nIter; // number of iterations } pmModel; -\end{verbatim} - -\begin{verbatim} +\end{datatype} + +\begin{datatype} typedef enum { PM_MODEL_GAUSS; @@ -1194,5 +1196,5 @@ PM_MODEL_SERSIC_CORE; } pmModelType; -\end{verbatim} +\end{datatype} A given source may be identified as most-likely to be one of several @@ -1202,5 +1204,5 @@ source classification code is developed.} -\begin{verbatim} +\begin{datatype} typedef enum { PM_SOURCE_PSFSTAR; @@ -1213,19 +1215,19 @@ PM_SOURCE_OTHER; } pmSourceType; -\end{verbatim} - -\begin{verbatim} +\end{datatype} + +\begin{datatype} typedef enum { PM_CONTOUR_CRUDE; } pmContourType; -\end{verbatim} +\end{datatype} Allocators for the above structures are defined as follows: -\begin{verbatim} +\begin{prototype} pmSource *pmSourceAlloc (); pmPeak *pmPeakAlloc (int x, int y, float counts, psPeakType class); pmMoments *pmMomentsAlloc (); pmModel *pmModelAlloc (pmModelType type); -\end{verbatim} +\end{prototype} \subsection{Basic Object Detection APIs} @@ -1235,7 +1237,7 @@ which we expect to use them in a basic object detection process. -\begin{verbatim} +\begin{prototype} psVector *pmFindVectorPeaks(const psVector *vector, float threshold); -\end{verbatim} +\end{prototype} Find all local peaks in the given vector above the given threshold. A @@ -1255,7 +1257,7 @@ \code{psU32}). -\begin{verbatim} +\begin{prototype} psArray *pmFindImagePeaks(const psImage *image, float threshold); -\end{verbatim} +\end{prototype} Find all local peaks in the given image above the given threshold. @@ -1272,7 +1274,7 @@ this function is an array of \code{pmPeak} entries. -\begin{verbatim} +\begin{prototype} psArray *pmPeaksSubset(psArray *peaks, float maxvalue, const psRegion valid); -\end{verbatim} +\end{prototype} Create a new peaks array, removing certain types of peaks from the @@ -1282,7 +1284,7 @@ function is a new array with a reduced number of peaks. -\begin{verbatim} +\begin{prototype} pmSource *pmSourceLocalSky(const psImage *image, const pmPeak *peak, psStatsOptions statsOptions, float innerRadius, float outerRadius); -\end{verbatim} +\end{prototype} Measure the local sky in the vicinity of the given \code{peak}. The @@ -1297,7 +1299,7 @@ which is then returned. -\begin{verbatim} +\begin{prototype} bool pmSourceMoments(pmSource *source, float radius); -\end{verbatim} +\end{prototype} Measure source moments for the given \code{source}, using the value of @@ -1309,7 +1311,7 @@ value indicates the success (TRUE) of the operation. -\begin{verbatim} +\begin{prototype} bool pmSourceRoughClass(pmArray *source, psMetadata *metadata); -\end{verbatim} +\end{prototype} Based on the specified data values, make a guess at the source @@ -1401,7 +1403,7 @@ \end{enumerate} -\begin{verbatim} +\begin{prototype} bool pmSourceSetPixelsCircle(pmSource *source, const psImage *image, float radius, int maskVal); -\end{verbatim} +\end{prototype} Define pixels associated with a source based on a circular aperture. @@ -1413,7 +1415,7 @@ success or \code{FALSE} on failure. -\begin{verbatim} +\begin{prototype} bool pmSourceModelGuess(pmSource *source, const psImage *image, pmModelType model); -\end{verbatim} +\end{prototype} Convert available data to an initial guess for the given model. This @@ -1424,7 +1426,7 @@ function returns \code{TRUE} on success or \code{FALSE} on failure. -\begin{verbatim} +\begin{prototype} psArray *pmSourceContour(const pmSource *source, const psImage *image, float level, pmContourType type); -\end{verbatim} +\end{prototype} Find points in a contour for the given source at the given level. If @@ -1440,7 +1442,7 @@ \tbd{Other contour types may be specified in the future for more refined contours} -\begin{verbatim} +\begin{prototype} bool pmSourceFitModel(pmSource *source, psImage *image); -\end{verbatim} +\end{prototype} Fit the requested model to the specified source. The starting guess @@ -1451,8 +1453,8 @@ returns \code{TRUE} on success or \code{FALSE} on failure. -\begin{verbatim} +\begin{prototype} bool pmSourceAddModel(psImage *image, pmSource *source, bool center, bool sky); bool pmSourceSubModel(psImage *image, pmSource *source, bool center, bool sky); -\end{verbatim} +\end{prototype} Add or subtract the given source model flux to/from the provided @@ -1473,7 +1475,7 @@ \subsubsection{Real 2D Gaussian} -\begin{verbatim} +\begin{prototype} float pmMinLM_Gauss2D(psVector *deriv, psVector *params, psVector *x); -\end{verbatim} +\end{prototype} This function is a two-dimensional Gaussian with an elliptical @@ -1485,7 +1487,7 @@ \subsubsection{Pseudo-Gaussian} -\begin{verbatim} +\begin{prototype} float pmMinLM_PseudoGauss2D(psVector *deriv, psVector *params, psVector *x); -\end{verbatim} +\end{prototype} This function is a polynomial approximation of a 2D Gaussian otherwise @@ -1498,7 +1500,7 @@ \subsubsection{Waussian} -\begin{verbatim} +\begin{prototype} float pmMinLM_Wauss2D(psVector *deriv, psVector *params, psVector *x); -\end{verbatim} +\end{prototype} The Waussian is a modified polynomial approximation of a 2D Gaussian, @@ -1508,7 +1510,7 @@ \subsubsection{Twisted Gaussian} -\begin{verbatim} +\begin{prototype} float pmMinLM_TwistGauss2D(psVector *deriv, psVector *params, psVector *x); -\end{verbatim} +\end{prototype} This function describes an object with power-law wings and a flattened @@ -1522,19 +1524,19 @@ \subsubsection{Sersic Galaxy Model} -\begin{verbatim} +\begin{prototype} float pmMinLM_Sersic(psVector *deriv, psVector *params, psVector *x); -\end{verbatim} +\end{prototype} \subsubsection{Sersic with Core Galaxy Model} -\begin{verbatim} +\begin{prototype} float pmMinLM_SersicCore(psVector *deriv, psVector *params, psVector *x); -\end{verbatim} +\end{prototype} \subsubsection{Pseudo Sersic Galaxy Model} -\begin{verbatim} +\begin{prototype} float pmMinLM_PseudoSersic(psVector *deriv, psVector *params, psVector *x); -\end{verbatim} +\end{prototype} @@ -1556,5 +1558,5 @@ \subsection{Combining images} -\begin{verbatim} +\begin{prototype} psImage *pmCombineImages(psImage *combined, // Combined image psArray **questionablePixels, // Array of rejection masks @@ -1568,5 +1570,5 @@ const psStats *stats // Statistics to use in the combination ); -\end{verbatim} +\end{prototype} \code{pmCombineImages} shall combine the input \code{images}, @@ -1602,5 +1604,5 @@ \subsection{Rejecting pixels} -\begin{verbatim} +\begin{prototype} psArray *pmRejectPixels(const psArray *images, // Array of input images const psArray *pixels, // These are the pixels which were rejected in the combination @@ -1610,5 +1612,5 @@ float gradLimit // Gradient limit ); -\end{verbatim} +\end{prototype} \code{pmRejectPixels} inspects those questionable \code{pixels} @@ -1764,10 +1766,10 @@ equally useful and faster, though not as tried and proven. -\begin{verbatim} +\begin{datatype} typedef enum { PM_SUBTRACTION_KERNEL_POIS, // POIS kernel --- delta functions PM_SUBTRACTION_KERNEL_ISIS // ISIS kernel --- gaussians modified by polynomials } pmSubtractionKernelsType; -\end{verbatim} +\end{datatype} In order to simplify the book-keeping for the kernels, we will define @@ -1775,5 +1777,5 @@ each of the kernel basis functions: -\begin{verbatim} +\begin{datatype} typedef struct { pmSubtractionKernelType type; // Type of kernels --- allowing the use of multiple kernels @@ -1785,5 +1787,5 @@ // accelerate ISIS; don't use for POIS) } pmSubtractionKernels; -\end{verbatim} +\end{datatype} This structure caters for both choices of kernel type. For a POIS @@ -1811,9 +1813,9 @@ The \code{pmSubtractionKernels} are generated by the following functions: -\begin{verbatim} +\begin{prototype} pmSubtractionKernels *pmSubtractionKernelsAllocPOIS(int size, int spatialOrder); pmSubtractionKernels *pmSubtractionKernelsAllocISIS(const psVector *sigmas, const psVector *orders, int size, int spatialOrder); -\end{verbatim} +\end{prototype} \code{pmSubtractionKernelsAllocPOIS} shall generate the @@ -1847,5 +1849,5 @@ convolution kernel are referred to as ``stamps''. -\begin{verbatim} +\begin{datatype} typedef struct { int x, y; // Position @@ -1854,5 +1856,5 @@ psStampStatus status; // Status of stamp } pmStamp; -\end{verbatim} +\end{datatype} A stamp is the region around a central pixel, \code{x,y}. The @@ -1868,5 +1870,5 @@ \code{status}, an enumerated type: -\begin{verbatim} +\begin{datatype} typedef enum { PM_STAMP_USED, // Use this stamp @@ -1875,7 +1877,7 @@ PM_STAMP_NONE // No stamp in this region } pmStampStatus; -\end{verbatim} - -\begin{verbatim} +\end{datatype} + +\begin{prototype} psArary *pmSubtractionFindStamps(psArray *stamps, // Output stamps, or NULL const psImage *image, // Image for which to find stamps @@ -1886,5 +1888,5 @@ int border // Border around image to ignore (should be size of kernel) ); -\end{verbatim} +\end{prototype} \code{pmSubtractionFindStamps} returns an array of stamps on the @@ -1914,5 +1916,5 @@ stamps. -\begin{verbatim} +\begin{prototype} bool pmSubtractionCalculateEquation(psArray *stamps, // The stamps for which to calculate the equation const psImage *reference, // Reference image @@ -1921,5 +1923,5 @@ int footprint // Half-size of region over which to calculate equation ); -\end{verbatim} +\end{prototype} \code{pmSubtractionCalculateEquation} shall calculate the @@ -1961,9 +1963,9 @@ subtraction, care should be taken with optimisation. -\begin{verbatim} +\begin{prototype} psVector *pmSubtractionSolveEquation(psVector *solution, // Solution vector, or NULL const psArray *stamps // Array of stamps ); -\end{verbatim} +\end{prototype} \code{pmSubtractionSolveEquation} shall solve the matrix equation @@ -1982,5 +1984,5 @@ \subsection{Rejection of stamps} -\begin{verbatim} +\begin{prototype} bool pmSubtractionRejectStamps(psArray *stamps, // Array of stamps to check for rejection psImage *mask, // Mask image @@ -1993,5 +1995,5 @@ const pmSubtractionKernels *kernels // Array of kernel parameters ); -\end{verbatim} +\end{prototype} \code{pmSubtractionRejectStamps} shall apply the \code{solution} to @@ -2014,8 +2016,8 @@ it. -\begin{verbatim} +\begin{prototype} psImage *pmSubtractionKernelImage(psImage *out, const psVector *solution, const pmSubtractionKernels *kernels, float x, float y); -\end{verbatim} +\end{prototype} \code{pmSubtractionKernelImage} shall create an image of the kernel @@ -2208,5 +2210,5 @@ corresponding parameters, \code{psPhase2MaskCRs} shall mask cosmic rays on the input image on the basis of their morphology. The API shall be the following: -\begin{verbatim} +\begin{prototype} /** Masks Cosmic Rays on the input image on the basis of morphology. */ psReadout *psPhase2MaskCRs(psReadout *in, ///< Input image to be masked, and output @@ -2214,5 +2216,5 @@ const void *params ///< Parameters for algorithm ); -\end{verbatim} +\end{prototype} This is one case in which the best choice of algorithm is not known, @@ -2229,5 +2231,5 @@ \code{psPhase2MaskOpticalDefects} shall mask optical defects on the image. The API shall be the following: -\begin{verbatim} +\begin{prototype} /** Masks optical defects in the input image */ psChip *psPhase2MaskOpticalDefects(psChip *in, ///< Image to be masked (with astrometry), and output @@ -2235,5 +2237,5 @@ int grow ///< Number of pixels to grow ); -\end{verbatim} +\end{prototype} \tbd{It's not clear to me how this is accomplished apart from an @@ -2251,5 +2253,5 @@ parameters, \code{psPhase2MeasurePSF} shall return the PSF for the image. The API shall be the following: -\begin{verbatim} +\begin{prototype} /** Measures the PSF on the input image. Returns the PSF */ psImage *psPhase2MeasurePSF(const psReadout *in, ///< Input image for which to measure the PSF @@ -2257,5 +2259,5 @@ const void *params ///< Parameters for algorithm ); -\end{verbatim} +\end{prototype} This is another case where the algorithm is not currently clear, and @@ -2270,5 +2272,5 @@ readout with the \code{objects} member set to a list of objects. The API shall be the following: -\begin{verbatim} +\begin{prototype} /** Find and measure objects on the input image. Fills in the "objects" member of the psReadout. */ /** THIS NEEDS WORK. */ @@ -2277,5 +2279,5 @@ const psVector *levels ///< Threshold levels (std dev.s) ); -\end{verbatim} +\end{prototype} Note that the input image shall be modified in-place, only insofar as @@ -2293,5 +2295,5 @@ clipping parameters, \code{psPhase2Astrometry} shall fit an astrometric solution. The API shall be the following: -\begin{verbatim} +\begin{prototype} /** Corrects astrometry on the input chip */ psChip *psPhase2Astrometry(psChip *in, ///< Input chip for which to do astrometry, and output @@ -2300,5 +2302,5 @@ float clipLevel ///< Level at which to clip ); -\end{verbatim} +\end{prototype} Note that the input chip shall be modified in-place, only insofar as @@ -2319,5 +2321,5 @@ coordinates. We define a \code{psPostageStampSpec} to specify the parameters for a postage stamp: -\begin{verbatim} +\begin{datatype} /** Specification of a postage stamp: location on the sky */ typedef struct { @@ -2325,5 +2327,5 @@ psSphereCoord *size; ///< Size of postage stamp } psPostageStampSpec; -\end{verbatim} +\end{datatype} The \code{center} shall be specified in ICRS coordinates, which is the @@ -2336,5 +2338,5 @@ chip, \code{psPhase2PostageStamps} shall output an array of subimages, containing each of the regions. The API shall be the following: -\begin{verbatim} +\begin{prototype} /** Return postage stamps of a set of regions */ psImageArray *psPhase2PostageStamps(const psChip *in, ///< Chip from which to form postage stamps @@ -2342,5 +2344,5 @@ ///< psPostageStampSpec ); -\end{verbatim} +\end{prototype} \code{regions} shall be a linked list of \code{psPostageStampSpec}s,