Perl script Positionrefine.pl computes improved estimates for coadd-image FITS keywords CRPIX1, CRPIX2, CDELT1, CDELT2, and CROTA2 by fitting image source positions to star catalog positions. In the DA pipeline, this software is run after the source extractor. The software optionally modifies specified FITS file headers with the refined FITS keyword values.
The input star-catalog positions are computed by WIRE star-catalog-search software, which searches both the ACT and USNOA star catalogs.
The sofware requires the filename of an IPAC table file containing star-catalog positions, source-extracted positions, and source weights. This filename must be specified on the command line. Pathname may also be included with filename. The sofware also requires an input set of FITS keywords for position reconstruction. The set includes CRPIX1, CRPIX2, CRVAL1, CRVAL2, CDELT1, CDELT2, and CROTA2. These values may be read from either the IPAC table file, or from a FITS image file specified on the command line.
Data for at least three sources are required, except when special command-line switches are enabled. The -noscale switch fixes the image scale parameters, so that only two sources are required. Alternatively, the -norotation switch fixes the image rotation parameter, so that only two sources are required. When both of these switches are enabled, only one source is required.
The source weights follow the standard convention that a bigger weight indicates a higher confidence in the star-catalog and source-extracted positions. It is expected that source extraction errors will predominate over star catalog errors. For the ACT catalog, with its 30-miliarcsecond errors, the margin will be typically 2 or more orders of magnitude. For the USNOA catalog, in which 1-2 arcsecond errors are expected, due to less-accurate data and lack of proper-motion corrections, the gap is much narrower.
The algorithm employed by the software is described as follows:
The software is now under both CVS version control (/proj/wire/cvsroot/da/russ/acs), and make control (makefile.p-bin). The executables have been delivered to /proj/wire/dev/bin. The source codes are located in /proj/wire/russ/acs.
The following is a list of the required inputs for Positionrefine.pl:
A sample IPAC-table file of source positions and weights is given below (this is test43.dat referred to in the example below):
| ra | dec | x | y | weight | | r | r | r | r | r | 179.862 -89.5726 14.0 24 1.0 -2.37358 -89.5345 614 600 1.0 75.1333 -89.6228 93 585 1.0
The required FITS keywords may be given in the header of this table, as well. The first two columns are star-catalog equatorial coordinates, in units of degrees. The next two columns are pixel coordinates of the same sources found by a source extractor such as DAOPHOT. Extracted positions must be in terms of integer pixel coordinates at the pixel centers. The last column is source weights.
The required FITS keywords may be alternatively read from the header of a specified FITS image. Keywords read from a FITS image header take precedence over any FITS keywords that may be present in the IPAC table of source data.
| Command-line input | Definition |
|---|---|
| -infits or -inf path and file name | Coadd image specification. Required if the source-data file contains an incomplete set of the required FITS keywords. |
| -indat or -ind path and file name | Source-data file specification. Required. |
| -outfits or -outf /path/FITSfilename1,/path/FITSfilename2,... | FITS files whose headers are to be modified. No files are modified if this option is omitted. Multiple files are modified if specified with comma-separations (no spaces). |
| -x0 value | Initial guess for x offset, in pixels (see lsqtrsdrv.f documentation for x0). The default value is zero. |
| -y0 value | Initial guess for y offset, in pixels (see lsqtrsdrv.f documentation for y0). The default value is zero. |
| -x0 value | Initial guess for the rotation angle, in degrees (see lsqtrsdrv.f documentation for t0). The default value is zero. |
| -nsigLim or -nsl value | Outlier rejection parameter (see lsqtrsdrv.f documentation for npostol). The default value is 5. |
| -radtol or -rad value | Outlier rejection parameter (see lsqtrsdrv.f documentation). The default value is 0.25 pixels. |
| -chi2tol or -chi value | Outlier rejection parameter (see lsqtrsdrv.f documentation). The default value is 0.8. |
| -siginp or -sig value | Estimated weighted-average standard deviation of the source position data (see lsqtrsdrv.f documentation). The default value is 0.1 pixels (= 1.6 arcseconds for WIRE pixels). |
| -noscale or -nos | Switch that causes the data fitting to be done with no scale change between image coordinate systems. The image CDELT1 and CDELT2 will be fixed at their current values. |
| -norotation or -nor | Switch that causes the data fitting to be done with no rotation between image coordinate systems. |
| -nrep value | Coadd-image up-sampling factor. Optional. If specified, causes input CDELT1 and CDELT2 to be computed from the nominal values of CDELT for WIRE frames. |
| -fx value | x focal length (mm). Optional. If
given, the input extracted-source positions and the output CDELT1
value will be scaled by 1000/fx. The default is 1000 mm.
If both -fx and -fy are specified when the -outf command-line option is invoked, then the old values of CDELT1 and CDELT2 will be overwritten in the image headers with new values (i.e., the changes to CDELT1 and CDELT2 will not be relative to the previous values in the image header). |
| -fy value | y focal length (mm). Optional. If given, the input extracted-source positions and the output CDELT2 value will be scaled by 1000/fy. The default is 1000 mm. |
| -degfreedomthresh value | Threshold on degrees of freedom of the data fit. If the number of degrees of freedom of fit is greater than this threshold, then position-refinement may be inhibited if chi2 value of fit indicates fit is bad. Default value is 10. If at or below this threshold, a warning is generated. |
| -normvarthresh value | Threshold for inhibiting position refinement, which is done only if the data fit has a sufficient number of degrees of freedom (given by -degfreedomthresh), the usual case. If sqrt(2*chi2offit)-sqrt(2*numberofdegreesoffreedom-1) is greater than this threshold (ONE-SIDED TEST), then the fit is declared bad and position-refinement is inhibited by reverting to the input FITS keyword values. Default value is 3. |
| -nokeepRefPt or -nk | Switch that allows the output image reference point (CRPIX1, CRPIX2) to be different from the input image reference point. By default, CRVAL1 and CRVAL2 are recomputed so that the input image reference point will be the same as the output image reference point. |
| -verbose or -v | Verbose mode. Default is off. |
| -execPath or -xp path | Pathname for the binaries used by Positionrefine.pl. |
Example of how to execute Positionrefine.pl for the special case where the -nk switch is set:
Positionrefine.pl -inf test40.fits -ind test43.dat -outf test43o.fits -nk
Prior to executing this command, test40.fits was copied to test43o.fits, so that test43o.fits will become a version of test40.fits with refined FITS keyword values.
The corresponding output is
Positionrefine.pl version $Id: Positionrefine.pl,v 1.32 1998/07/10 02:09:47 laher Exp $ update Thu_1998/07/09(190)_19:09:47 , PID=26426 Date/time: Thu_1998/07/09(190)_21:50:59 PCPU: 1.61/0.19/8 CCPU: 0.13/0.17 Named parameters for Positionrefine.pl: infits = test40.fits; outfits = (test43o.fits); indat = test43.dat; debug = undef; execpath = undef; noscale = undef; verbose = undef; log = undef; siginp = 0.1; nsiglim = 5; radtol = 0.25; chi2tol = 0.8; x0 = 0; y0 = 0; t0 = 0; nrep = undef; fx = undef; fy = undef; normvarthresh = 3; degfreedomthresh = 9; nokeeprefpt = 1; FITS keyword values extracted from coadd image test40.fits: CRPIX1old = 300. CRPIX2old = 300. CRVAL1old = 0.000000000000E+00 CRVAL2old = -9.000000000000E+01 CROTA2old = -4.730000000000E+01 CDELT1old = -0.00107429584 CDELT2old = 0.00107429584 Making plate scale corrections to extracted star image positions... From lsqtrsdrv: Iterated linear LSQ routine converged after 7 iterations. Image registration data derived from linear least-squares fit: Rotation center = (0, 0) # sources kept = 3 # outliers rejected = 0 chi2 = 24.884151371184 # deg frdm = 1 dx (pixels) = -8.6944705923166 dy (pixels) = 7.2263389725049 theta (degrees) = 5.3154206829459 scalex = 0.94577484846683 scaley = 1.0456502121996 Refined FITS keyword values: CRPIX1 = 296.312477232117 CRPIX2 = 306.136496023616 CROTA2 = 318.015420682946 CDELT1 = -0.00101604198528455 CDELT2 = 0.00112333767306115 CRVAL1 = 0.000000000000E+00 CRVAL2 = -9.000000000000E+01 Change in CRPIX1 = -3.68752276788274 Change in CRPIX2 = 6.13649602361556 Scale change for CDELT1 = 0.94577484846683 Scale change for CDELT2 = 1.0456502121996 Input quaternions: q1 = -0.401148557352466 q2 = 0.916013010242778 q3 = -2.45632648372138e-17 q4 = 5.60896200485575e-17 Delta quaternions: q1del = 3.08148791101958e-33 q2del = -6.16297582203915e-33 q3del = -0.0463691635407477 q4del = -0.998924371848305 Output quaternions: q1new = -0.358242313593766 q2new = 0.933628643921654 q3new = -2.19360151330874e-17 q4new = 5.71682665185469e-17 Name of output data file: test43.pos WARNING: Number of degrees of freedom for position-refinement fit <= 9 New equatorial coordinates of old image reference point: RAboresight = 250.50954706880 Decboresight = -89.992154238857 These values should agree with the refined values of CRVAL1 and CRVAL2 when the -nokeepRefPt switch is not set. Modifying CRPIX1, CRPIX2, CDELT1, CDELT2, and CROTA2 in header of test43o.fits. Old FITS keyword values: CRPIX1 = 300. CRPIX2 = 300. CRVAL1 = 0.000000000000E+00 CRVAL2 = -9.000000000000E+01 CROTA2 = -4.730000000000E+01 CDELT1 = -0.00107429584 CDELT2 = 0.00107429584 New FITS keyword values: CRPIX1 = 296.312477232117 CRPIX2 = 306.136496023616 CRVAL1 = 270 CRVAL2 = -89.9999987925817 CROTA2 = 48.0154206829459 CDELT1 = -0.00101604198528455 CDELT2 = 0.00112333767306115 End of Positionrefine.pl status 0, PID=26426 Date/time: Thu_1998/07/09(190)_21:51:08 PCPU: 2.61/0.49/17 CCPU: 0.48/0.39
This particular case is much more stressing than what is normally expected. Comparing the initial and refined FITS keyword values, it is seen that CRPIX1 and CRPIX2 changed by about 5 pixels, CROTA2 changed by about 5 degrees, and CDELT1 and CDELT2 changed by about 5%.
No errors have been included in the source positions for this case, so values very close to the true values are expected, that is, as long as the differences between initial values and true values are sufficiently small. The true values are:
CRPIX1 = 295
CRPIX2 = 305
CROTA2 = -42 degrees
CDELT1 = -0.001020581 (95% of initial value)
CDELT2 = 0.00128011 (105% of initial value)
The results show that CRPIX1 and CRPIX2 are in error by about 5 arcseconds, a large value because this particular case tests the limits of the linear approximation assumed for the data fitting; much smaller errors are obtained when the initial values deviate lesser amounts from the true values.
Below is shown an example of how to execute Positionrefine.pl for normal use, where the -nk switch is not set. In this case, the input and output values of CRPIX1 and CRPIX2 are the same, which necessitates the recalculation of CRVAL1, CRVAL2, and CROTA2. The set of keywords computed below is equivalent to the set computed in the example above.
Positionrefine.pl -inf test40.fits -ind test43.dat -outf test43o.fits
The corresponding output is
Positionrefine.pl version $Id: Positionrefine.pl,v 1.32 1998/07/10 02:09:47 laher Exp $ update Thu_1998/07/09(190)_19:09:47 , PID=25365 Date/time: Thu_1998/07/09(190)_20:31:06 PCPU: 1.45/0.29/14 CCPU: 0.21/0.19 Named parameters for Positionrefine.pl: infits = test40.fits; outfits = (test43o.fits); indat = test43.dat; debug = undef; execpath = undef; noscale = undef; verbose = undef; log = undef; siginp = 0.1; nsiglim = 5; radtol = 0.25; chi2tol = 0.8; x0 = 0; y0 = 0; t0 = 0; nrep = undef; fx = undef; fy = undef; normvarthresh = 3; degfreedomthresh = 9; nokeeprefpt = undef; FITS keyword values extracted from coadd image test40.fits: CRPIX1old = 300. CRPIX2old = 300. CRVAL1old = 0.000000000000E+00 CRVAL2old = -9.000000000000E+01 CROTA2old = -4.730000000000E+01 CDELT1old = -0.00107429584 CDELT2old = 0.00107429584 Making plate scale corrections to extracted star image positions... From lsqtrsdrv: Iterated linear LSQ routine converged after 7 iterations. Image registration data derived from linear least-squares fit: Rotation center = (0, 0) # sources kept = 3 # outliers rejected = 0 chi2 = 24.884151371184 # deg frdm = 1 dx (pixels) = -8.6944705923166 dy (pixels) = 7.2263389725049 theta (degrees) = 5.3154206829459 scalex = 0.94577484846683 scaley = 1.0456502121996 Refined FITS keyword values: CRPIX1 = 300. WARNING: Number of degrees of freedom for position-refinement fit <= 9 CRPIX2 = 300. CROTA2 = -150.674843541483 CDELT1 = -0.00101604198528455 CDELT2 = 0.00112333767306115 CRVAL1 = 251.309735775572 CRVAL2 = -89.9926570271313 Change in CRPIX1 = 0 Change in CRPIX2 = 0 Scale change for CDELT1 = 0.94577484846683 Scale change for CDELT2 = 1.0456502121996 Input quaternions: q1 = -0.401148557352466 q2 = 0.916013010242778 q3 = -2.45632648372138e-17 q4 = 5.60896200485575e-17 Delta quaternions: q1del = -2.87596180500001e-05 q2del = -5.72631653760722e-05 q3del = -0.0463691634455453 q4del = -0.998924369797421 Output quaternions: q1new = -0.358242312858263 q2new = 0.933628642004826 q3new = -4.93152204834821e-05 q4new = -4.09169252013433e-05 Name of output data file: test43.pos New equatorial coordinates of old image reference point: RAboresight = 251.30973577557 Decboresight = -89.992657027131 These values should agree with the refined values of CRVAL1 and CRVAL2 when the -nokeepRefPt switch is not set. Modifying CRPIX1, CRPIX2, CDELT1, CDELT2, and CROTA2 in header of test43o.fits. Old FITS keyword values: CRPIX1 = 300. CRPIX2 = 300. CRVAL1 = 0.000000000000E+00 CRVAL2 = -9.000000000000E+01 CROTA2 = -4.730000000000E+01 CDELT1 = -0.00107429584 CDELT2 = 0.00107429584 New FITS keyword values: CRPIX1 = 300 CRPIX2 = 300 CRVAL1 = 251.309735775572 CRVAL2 = -89.9926570268961 CROTA2 = 209.325156458517 CDELT1 = -0.00101604198528455 CDELT2 = 0.00112333767306115 End of Positionrefine.pl status 0, PID=25365 Date/time: Thu_1998/07/09(190)_20:31:19 PCPU: 2.52/0.61/27 CCPU: 0.55/0.35
Last revised: October 26, 1998
Software developer: Russ Laher (laher@ipac.caltech.edu)
URL: http://spider.ipac.caltech.edu/staff/laher/Positionrefine.html