Index: trunk/doc/modules/CameraImages.tex =================================================================== --- trunk/doc/modules/CameraImages.tex (revision 5367) +++ trunk/doc/modules/CameraImages.tex (revision 5377) @@ -724,5 +724,5 @@ output; otherwise it shall return \code{false}. -\subsection{Astrometry Fitting Support Routines} +\subsection{Astrometry Analysis} Astrometry is performed on an astronomical image after a collection of @@ -734,6 +734,6 @@ of the other coordinate system. For example, it might be necessary to determine the coordinates of the \code{psReadout} pixels relative to -the \code{psCell} (rather accept the relationship defined by the -metadata). +the \code{psCell} (rather than accept the relationship defined by the +metadata). For the moment, we define two layers of astrometric analysis which @@ -747,7 +747,7 @@ the second case, a collection of detectors on a collection of chips from a mosaic camera are used to measure the position of the telescope -boresite, the camera rotation, the impact of distortion from the +boresight, the camera rotation, the impact of distortion from the telescope optics, and the chip-to-focal plane transformation resulting -from chip placement errors or possible detector tilts or warps. +from chip placement errors or possible detector tilts or warps. The process of performing astrometry involves the following steps: @@ -769,63 +769,68 @@ possible the above analysis steps. +\subsubsection{Astrometry Objects} + We define the following structure to carry the necessary information about each detection. \begin{datatype} typedef struct { - double X, Y; - double L, M; - double P, Q; - double R, D; - double Mag; + psPlane pix; + psPlane FP; + psPlane TP; + psSphere sky; + double mag; } pmAstromObj; \end{datatype} This structure specifies the coordinate of the detection in each of -the four necessary coordinate frames: \code{X,Y} define the position -in the \code{psReadout} frame, \code{L,M} define the position in the -\code{psChip} frame, \code{P,Q} define the position in the -\code{psFPA} frame, \code{R,D} define the position on the Celestial -Sphere. \tbd{re-write using psPlane and psSphere?}. In addition, a -measurement of the brightness is given by the element \code{Mag}. -Such a data structure should be used for both the raw and the -reference stars. In astrometric processing, the raw detections will -be projected using the best available information to each of these -coordinate frames from the \code{X,Y} coordinates, while the reference -detections will be projected to the other frames from the \code{R,D} -coordinates. +the four necessary coordinate frames: \code{pix} defines the position +in the \code{psReadout} frame, \code{FP} defines the position in the +Focal Plane frame, \code{TP} defines the position in the Tangent Plane +frame, \code{sky} defines the position on the Celestial Sphere. In +addition, a measurement of the brightness is given by the element +\code{Mag}. Such a data structure should be used for both the raw and +the reference stars. In astrometric processing, the raw detections +will be projected using the best available information to each of +these coordinate frames from the \code{pix} coordinates, while the +reference detections will be projected to the other frames from the +\code{sky} coordinates. The raw detections and the reference stars are both projected to a -common coordinate frame for analysis. In these modules, we -principally use the Focal Plane for this reference frame. After -projection to the common frame, it is necessary to determine the match -between corresponding objects in the two lists. In order to match the -raw detections to the reference stars, different methods are used -depending on the circumstance. +common coordinate frame for analysis. In these modules, we use the +Focal Plane for this reference frame. After projection to the common +frame, it is necessary to determine the match between corresponding +objects in the two lists. In order to match the raw detections to the +reference stars, different methods are used depending on the +circumstance. + +\subsubsection{Matching Stars : Close Match} If the two sets of coordinates are expected to agree very well (ie, the current best-guess astrometric solution is quite close to the -'true' astrometric solution), then it is possible to use the simplest +`true' astrometric solution), then it is possible to use the simplest matching process: cross-correlation within a fixed radius. The following function accepts two sets of \code{pmAstromObj} sources and determines the matched objects between the two lists. The input sources must have been projected to the Focal Plane coordinates -(\code{pmAstromObj.L,M}), and the supplied \code{config} entry must +(\code{pmAstromObj.FP}), and the supplied \code{options} entry must contain the desired match radius (keyword: -\code{ASTROM_MATCH_RADIUS}). The output consists an array of +\code{ASTROM.MATCH.RADIUS}). The output consists an array of \code{pmAstromMatch} values, defined below. \begin{prototype} -psArray *pmAstromRadiusMatch (psArray *st1, psArray *st2, pmAstromOpt *opt); +psArray *pmAstromRadiusMatch (psArray *starlist1, psArray *starlist2, psMetadata *options); \end{prototype} \begin{datatype} typedef struct { - int i1; - int i2; + int idx1; + int idx2; } pmAstromMatch; \end{datatype} The \code{pmAstromMatch} structure defines the cross-correlation between two arrays. An single such data item specifies that item -number \code{pmAstromMatch.i1} in the first list corresponds to -\code{pmAstromMatch.i2} in the second list. +number \code{pmAstromMatch.idx1} in the first list corresponds to +\code{pmAstromMatch.idx2} in the second list. + +\subsubsection{Matching Stars : Rough Match} If the two sets of coordinates are not known to agree well, a somewhat @@ -857,57 +862,41 @@ rotations. We define the following function to apply this matching algorithm: \begin{prototype} -pmAstromGridMatchStat pmAstromGridMatch (psArray *st1, psArray *st2, psMetadata *options); +psArray *pmAstromGridMatch (psArray *starlist1, psArray *starlist2, psMetadata *options); \end{prototype} The input sources must have been projected to the Focal Plane -coordinates (\code{pmAstromObj.L,M}), and the supplied \code{config} +coordinates (\code{pmAstromObj.FP}), and the supplied \code{options} entry must contain the following user-defined parameters: \begin{itemize} -\item \code{GRID_OFFSET} : maximum allowed displacement in search -\item \code{GRID_SCALE} : grid bin size in focal-plane coordinate units -\item \code{MIN_ANGLE} : minimum tested relative rotation -\item \code{MAX_ANGLE} : maximum tested relative rotation -\item \code{DEL_ANGLE} : relative rotation step size +\item \code{GRID.OFFSET} : maximum allowed displacement in search +\item \code{GRID.SCALE} : grid bin size in focal-plane coordinate units +\item \code{GRID.MIN.ANGLE} : minimum tested relative rotation +\item \code{GRID.MAX.ANGLE} : maximum tested relative rotation +\item \code{GRID.DEL.ANGLE} : relative rotation step size \end{itemize} -The output from this process is the statistics of the best-fit -(rotation and offset grid cell). This information is returned in the -\code{pmAstromGridMatchStats} structure: -\begin{datatype} -typedef struct { - double angle; - double dL; - double dM; - double minMetric; - double minVar; - int nMatch; -} pmAstromGridMatchStats; -\end{datatype} -The elements \code{angle}, \code{dL}, \code{dM} define the best -rotation and offset; the element \code{nMatch} indicates the number of -matched sources which fell within the match bin; the element -\code{minVar} defines the variance of the sources within the match -bin; the element \code{minMetric} specifies the value of the selection -metric for the matched bin. Note that the metric of choice may not -necessarily be either the simple number of sources or the varience. -We find that a combination based on both which enhances the importance -of having a well-populated bin with a minimal variance gives good -results: $\mbox{metric} = \mbox{var} \times N^{-4}$. - -We define two additional functions which are used in two build -\code{pmAstromGridMatch}, but which may be useful on their own: - -\begin{prototype} -pmAstromGridMatchStats pmAstromGridMatchAngle (psArray *st1, psArray *st2, psMetadata *config); -\end{prototype} -This function is identical to \code{pmAstromGridMatch}, but is valid -for only a single relative rotation. The input \code{config} -information need not contain any of the \code{ANGLE} entries. - -\begin{prototype} -psArray *pmAstromRotateObj (psArray *old, double angle, double pCenter, double qCenter); -\end{prototype} -This function accepts an array of \code{pmAstromObj} objects and -rotates them by the given \code{angle} about the given center -coordinate \code{pCenter,qCenter} in the Focal Plane Array -coordinates. +Note that the angles are defined as counter-clockwise rotations of +starlist 1 relative to starlist 2. + +This function returns all matched pairs identified in the grid cell. +It also adds to the \code{options} metadata several elements defining +the statistics of the best-fit (rotation and offset grid cell): +\begin{itemize} +\item \code{GRID.FIT.ANGLE} +\item \code{GRID.FIT.LOFF} +\item \code{GRID.FIT.MOFF} +\item \code{GRID.FIT.METRIC} +\item \code{GRID.FIT.VARIANCE} +\item \code{GRID.FIT.NMATCH} +\end{itemize} +The elements \code{GRID.FIT.ANGLE}, \code{GRID.FIT.LOFF}, +\code{GRID.FIT.MOFF} define the best rotation and offset; the element +\code{GRID.FIT.NMATCH} indicates the number of matched sources which +fell within the match bin; the element \code{GRID.FIT.VAR} defines the +variance of the sources within the match bin; the element +\code{GRID.FIT.METRIC} specifies the value of the selection metric for +the matched bin. Note that the metric of choice may not necessarily +be either the simple number of sources or the varience. We find that +a combination based on both which enhances the importance of having a +well-populated bin with a minimal variance gives good results: +$\mbox{metric} = \mbox{var} \times N^{-4}$. The result of a \code{pmAstromGridMatch} may be used to modify the @@ -920,8 +909,29 @@ two adjustments are made using the function: \begin{prototype} -pmAstromApplyGridMatch (pmFPA *fpa, pmAstromGridMatchStats stats); +bool pmAstromApplyGridMatch (pmFPA *fpa, pmAstromGridMatchStats stats); \end{prototype} This function modifies the supplied \code{pmFPA} entry as described above. + +We define two additional functions which are used in two build +\code{pmAstromGridMatch}, but which may be useful on their own: + +\begin{prototype} +psArray *pmAstromGridMatchAngle (psArray *starlist1, psArray *starlist2, psMetadata *options); +\end{prototype} +This function is identical to \code{pmAstromGridMatch}, but is valid +for only a single relative rotation. The input \code{config} +information need not contain any of the \code{GRID.*.ANGLE} entries +(they will be ignored). + +\begin{prototype} +psArray *pmAstromRotateObj (psArray *old, double angle, double pCenter, double qCenter); +\end{prototype} +This function accepts an array of \code{pmAstromObj} objects and +rotates them by the given \code{angle} about the given center +coordinate \code{pCenter,qCenter} in the Focal Plane Array +coordinates. + +\subsubsection{Astrometry Fitting Routines} The result of a \code{pmAstromRadiusMatch} operation is a list of @@ -937,9 +947,9 @@ fitting uses clipping to exclude outliers, likely representing poor matches. The \code{config} element must contain the information -\code{ASTROM_NSIGMA} (specifying the number of sigma used in the -clipping) and \code{ASTROM_NCLIP} (specifying the number of clipping +\code{ASTROM.NSIGMA} (specifying the number of sigma used in the +clipping) and \code{ASTROM.NCLIP} (specifying the number of clipping iterations must be performed). The \code{config} element must also specify the order of the polynomial fit (keyword: -\code{ASTROM_ORDER}). The result of this fit is a set of +\code{ASTROM.ORDER}). The result of this fit is a set of modifications of the components of the \code{pmFPA.toTangentPlane} transformation, and the modifications of the reference coordinate of @@ -961,9 +971,9 @@ systems. The fitting uses clipping to exclude outliers, likely representing poor matches. The \code{config} element must contain the -information \code{ASTROM_NSIGMA} (specifying the number of sigma used -in the clipping) and \code{ASTROM_NCLIP} (specifying the number of +information \code{ASTROM.NSIGMA} (specifying the number of sigma used +in the clipping) and \code{ASTROM.NCLIP} (specifying the number of clipping iterations must be performed). The \code{config} element must also specify the order of the polynomial fit (keyword: -\code{ASTROM_ORDER}). The result of this fit is a set of +\code{ASTROM.ORDER}). The result of this fit is a set of modifications of the components of the \code{pmChip.toFPA} transformation. @@ -980,23 +990,20 @@ plane, for a collection of raw measurements and matched reference stars. The configuration data must include the bin size over which -the gradient is measured (keyword: \code{ASTROM_GRAD_BOX}). The +the gradient is measured (keyword: \code{ASTROM.GRAD.BOX}). The function returns an array of \code{pmAstromGradient} structures, defined below. \begin{prototype} -psArray pmAstromMeasureGradients (psArray *st1, psArray *st2, psArray *match, psMetadata *config); +psArray pmAstromMeasureGradients (psArray *starlist1, psArray *starlist2, psArray *match, psMetadata *config); \end{prototype} The following data structure carries the information about the residual gradient of source positions in the tangent plane -(\code{P,Q}) as a function of position in the focal plane -(\code{L,M}). +(\code{pmAstromObj.TP}) as a function of position in the focal plane +(\code{pmAstromObj.FP}). \begin{datatype} typedef struct { - double L; - double M; - double dPdL; - double dPdM; - double dQdL; - double dQdM; + psPlane FP; + psPlane dTPdL; + psPlane dTPdM; } pmAstromGradient; \end{datatype} @@ -1008,10 +1015,6 @@ transformation of the supplied \code{pmFPA} structure. The configuration variable supplies the polynomial order (keyword: -\code{ASTROM_DISTORT_ORDER}). +\code{ASTROM.DISTORT.ORDER}). \begin{prototype} psArray pmAstromFitDistortion (pmFPA *fpa, psArray *gradients, psMetadata *config); \end{prototype} - -\tbd{can we use the pmAstromFitMatch func above to fit the remaining - power in the chips?} -