WIRE Position Refinement Software


Introduction

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.

Description

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:

  1. Read and store FITS keywords and source position data. The FITS keywords in the source data file are taken first; if this file contains an incomplete set of keywords, then the additional ones needed are taken from a FITS image whose filename is specified on the command line. Image-header FITS keywords are read using Tim Conrow's perl extension for FITS I/O routines. It is assumed that axis 1 is the x or horizontal axis, and that axis 2 is the y or vertical axis. The software uses only FITS keywords CRPIX1, CRPIX2, CRVAL1, CRVAL2, CDELT1, CDELT2, and CROTA2 explicitly in its processing.

  2. Transform star-catalog equatorial coordinates (RA, Dec) into pixel coordinates using the FITS keyword values with FITS library software (the driver used is lonlattoxy3.f).

  3. Rescale the extracted-source positions if image focal lengths different from 1000 mm are specified (via -fx and -fy command-line options).

  4. Register the star-catalog pixel coordinates to the source-extracted pixel coordinates using an iterated, five-parameter, least-squares fitting method (lsqtrsdrv.f). The goodness of fit measure chi2 and the associated number of degrees of freedom are reported; logic is in place to determine the occurrence of a poor fit, alert the user of this event, and inhibit the position refinement by passing along the input FITS keywords as output.

  5. Derive from the image registration data refined values for the FITS keywords CRPIX1, CRPIX2, CDELT1, CDELT2, and CROTA2, keeping CRVAL1 and CRVAL2 fixed. Thus the tangent point on the celestial sphere for the gnomonic projection into the image plane is not moved, but rather the image is shifted and rotated in the tangent plane.

  6. Recompute CRVAL1, CRVAL2, and CROTA2 for the input set of CRPIX1 and CRPIX2 values. This step can be optionally omitted using the -nokeepRefPt switch. This effectively moves the tangent point on the celestial sphere to the original reference point of the image.

  7. Optionally modify headers of FITS images specified with the -outf command-line option. The keyword-value changes are relative to the original values in the image headers, with one exception (see description of -fx and -fy command-line options in table below).

    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.

    Required and Optional Inputs

    The following is a list of the required inputs for Positionrefine.pl:

    1. FITS keywords for position reconstruction.
    2. Filename of IPAC table of source positions and weights.

    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.

    Outputs

    The outputs are refined values of the FITS keywords CRPIX1, CRPIX2, CRVAL1, CRVAL2, CDELT1, CDELT2, and CROTA2. Outputs are sent both to STDOUT and to a data file, whose filename has the same base as the source-data file, with the filename extension .pos.

    Usage and Sample Outputs

    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

    Return to Home Page