|
|
|
|
|
SynopsisCreate a frame transformation to minimize the aspect difference between data from the same sky region. Syntaxwcs_match infile refsrcfile outfile [wcsfile] [logfile] [radius] [residlim] [residtype] [residfac] [clobber] [verbose] Descriptionwcs_match compares two sets of source lists from the same sky region. If three or more sources are found to be a close match in position, wcs_match will calculate a transformation matrix which, when used with wcs_update, can be used to align the input (infile) set of source positions with the reference (refsrcfile) set of source positions. The position differences will be minimized in a least-squares sense. Options allow the user to specify how close sources from each list must be to each other to be considered as possible matches (radius) and to limit the acceptable error between reference source positions and updated input source positions (residlim, residtype and residfac). The calculated six element transformation matrix is output to the transform file (outfile). WCS parameters specifying a tangent point must be provided for the transform calculations. This can be done by specifying either a fits image or table file containing a WCS in the wcsfile input parameter. Alternately, if a WCS is already present in either the input or reference source lists, those values will be used and wcsfile can be left blank. When a wcsfile is specified, it should contain a WCS that identifies a tangent point that is relatively close to the sources to be matched. Transform Calculation Controlswcs_match calculates a transformation matrix which minimizes (in a least squares sense) the error between tangent plane projections of the reference sources and the transformed input sources. The transformation matrix specifies a 2-D translation, a rotation about the tangent point, and a scale factor. Applying this matrix to the input sources results in the best attempt at aligning the reference and transformed input source positions. A transformation matrix is initially calculated using data from all matched input and reference source positions (source pairs). The transformation matrix is then applied to the input source positions and the updated positions are compared to the positions of the reference sources. The differences between these source positions (the residuals) are used to determine whether the transformation matrix is sufficient, or whether certain source pairs should be excluded (e.g., mismatched sources) and the transformation calculation repeated. Running wcs_match with verbose=1 shows details of the residuals during successive calculations of the transformation matrix. If residlim is greater than 0, the transform calculation stops when the largest residual is smaller than residlim. If the largest residual is greater than residlim, the source pair with this residual is excluded from the matched set of sources and the transformation matrix is recalculated. This continues iteratively until all residuals are less than the specified value of residlim. If residfac is greater than 0, the residual-to-source pair position error ratio is examined. This ratio is determined by dividing a residual by the sum in quadrature of its reference and input source position errors. A comparison is made to residfac and if residfac is exceeded, the source pair with the largest ratio is excluded from the matched set of sources and the transformation matrix is recalculated. This continues iteratively until residfac is no longer exceeded. Two different comparisons can be made with residfac. If residtype = 0, the transform calculation stops when all ratios are less than residfac. If residtype = 1, the calculation stops when the average of all ratios is less than residfac. Example 1wcs_match infile=src1.fits refsrcfile=src2.fits wcsfile=image.fits outfile=xfm.fits radius=2 residlim=1 verbose=1 Match sources from src1.fits and src2.fits that are within 2 arcseconds. Eliminate any source pairs with a position difference greater than 1 arcsecond from the transform calculation. Output the elements of the input-to-reference source position transformation matrix in xfm.fits. Display the intermediate and final position errors for all matched sources (verbose=1). Example 2wcs_match infile=src1.fits refsrcfile=src2.fits outfile=xfm.fits verbose=0 Use default values for matching sources and limiting source pairs used in transform calculation. Use a WCS for the transform calculation from either the input source file (infile) or the reference source file (refsrcfile). Do not display any source pair position error information (verbose=0). Example 3wcs_match infile=src1.fits refsrcfile=src2.fits wcsfile=image.fits outfile=xfm.fits residlim=0 residtype=1 residfac=1.5 verbose=1 Do not use the absolute value of the residual to limit source pairs to include in the transform calculation (residlim=0), but do use the residual-to-position pair position error ratio to limit source pairs in the transform. Whenever the average of all ratios (residtype=1) is greater than 1.5, remove the source pair with the largest ratio from the calculation and repeat. Display the intermediate and final position errors for all matched sources (verbose=1). Parameters
Detailed Parameter DescriptionsParameter=infile (file required filetype=input)File with input sources. File with input source positions. Must contain columns RA and Dec., either internally or through use of datamodel column filter. RA and Dec. columns must be in decimal-degree (i.e., not sexagesimal) format. At least 3 input sources must be found to be a match for 3 reference sources. residfac parameter will only be useful if columns RA_err and Dec_err are present in infile and refsrcfile. Parameter=refsrcfile (file required filetype=input)File of reference sources File of reference source positions. Must contain columns RA and Dec., either internally or through use of datamodel column filter. RA and Dec. columns must be in decimal-degree (i.e., not sexagesimal) format. At least 3 input sources must be found to be a match for 3 reference sources. residfac parameter will only be useful if columns RA_err and Dec_err are present in infile and refsrcfile. Parameter=outfile (file required filetype=output)File containing transform matrix data. This file contains the six elements of the transform matrix and WCS coordinate information used in calculating the transform. It can be used by wcs_update to update fits images, tables, or asol files. Parameter=wcsfile (file not required filetype=input)World Coordinate System (WCS) file. The WCS file must contain WCS coordinate transform data with a tangent point near the sources of the infile or refsrcfile. It can be either a fits image file with a "EQPOS" WCS, or a fits table file with "EQPOS" or "EQSRC" WCS. A WCS file must be specified unless a WCS is present in either the input or reference source file. If a wcsfile is provided and a WCS is present in either source file, the WCS from the wcsfile will be used. Parameter=logfile (file not required filetype=output default=STDOUT)Debug log file. Allowable values are either a filename - to send the output to a given file - or one of stdout or STDOUT, which sends the information to the standard output (normally the screen). Parameter=radius (real not required filetype=input default=12 units=arcseconds)Source match radius Source positions from the two source files can only match each other if they are no farther apart than the value specified as the source match radius. Only a single reference source can be within the source match radius of a input source, and only a single input source can be within the source match radius of a reference source. If multiple sources are found in either case, the source pair is not used to calculate the transform. Parameter=residlim (real not required filetype=input default=5 units=arcseconds)Residual Limit After the transform is calculated and initially applied to the input source positions, if the largest source pair position error exceeds the value of residlim, then that pair is eliminated from the transform calculation and the calculation is repeated. This process of eliminating the source pair with the largest residual and repeating the calculation continues until all remaining source pair position errors are less than the residlim value. Set residlim to 0 to disable this feature and prevent source pairs from being removed based on absolute residual value. Residlim takes precedence over residfac if both are nonzero. Parameter=residtype (integer not required filetype=input default=0 units=)Residual ratio limit type Two different options can be used to eliminate source pairs from the transform calculation when the residual ratio limit factor (residfac) is specified. If residtype is set to 0, residfac is interpreted as an upper limit on the residual-to-source pair position error ratio. Any sources with ratios above residfac will be eliminated from the transform calculation. If residtype is set to 1, residfac is interpreted as an upper limit on the average of all ratios. Source pairs with the highest ratios will be incrementally removed from the transform calculation until the average of all ratios drops below residfac. Parameter=residfac (real not required filetype=input default=2.0 units=)Residual ratio limit factor After the transform is calculated and initially applied to the input source positions, if either the largest residual-to-source pair position error ratio exceeds the value of residfac (when residtype=0), or the average of all ratios exceeds the value of residfac (when residtype = 1) then the source pair with the largest ratio is eliminated from the transform calculation and the calculation is repeated. This process of eliminating a source pair and repeating the calculation continues until the appropriate ratio test is met. Set residfac to 0 to disable this feature and prevent source pairs from being removed based on the residual-to-source pair position error ratio. Residlim takes precedence over residfac if both are nonzero. Parameter=clobber (boolean not required filetype=input default=no)Overwrite existing output dataset with same name? Parameter=verbose (integer not required filetype=input default=0 min=0 max=5)Level of debug detail. Increasing amounts of debug information is printed to "logfile" as the value of verbose is increased from 0 to 5. Setting verbose=1 shows details of the source pair errors after applying the transform to the input source positions. CHANGES IN CIAO 3.4Using Non-Chandra ImagesPrevious bugs restricting use to Chandra images are fixed. The tool can now correctly update WCS in non-Chandra images. BugsSee the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs. |
 |
The Chandra X-Ray
Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA. Email: cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2004. All rights reserved. |
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}