WIRE Position Reconstruction Software


Introduction

The WIRE input processor takes WIRE downlink telemetry data, which include image and ACS (attitude control system) data, and creates FITS image files, each with header information that includes:

Some of the computer codes used by the input processor for deriving this information from ACS and other data, and also by subsequent software in the data-analysis (DA) pipeline for making use of this information, are described here.

The FORTRAN code xytolonlat.f uses FITS file header data and other information to compute celestial coordinates for selected pixel coordinates in the associated FITS image. The FORTRAN code lonlattoxy.f uses FITS file header data and other information to compute pixel coordinates for selected celestial coordinates in the associated FITS image (but ignores scaling/distortion corrections-see below).

The perl subroutine quattolonlat converts ACS quaternions and band-dependent star-tracker/telescope misalignment angles into CRVAL1, CRVAL2, and CROTA2 for the WIRE image centers, which are defined to have pixel coordinates (CRPIX1=64.5, CRPIX2=64.5). Subroutine quattolonlat2 is similar, except that it uses band-dependent "correction" quaternions to characterize the star-tracker/telescope misalignment.


xytolonlat.f, xytolonlat2.f, and xytolonlat3.f

Description

Transforms an inputted list of WIRE pixel coordinates into celestial coordinates, based in part on the following FITS-keyword data provided in an associated FITS image:

CTYPE1, CRPIX1, CRPIX2, CDELT1, CDELT2, CRVAL1, CRVAL2, CROTA2

The WIRE simulator now defines (CRPIX1,CRPIX2) = (64.5, 64.5) as the FPA center. This is a new convention; previously (64, 64) was used.

Makes image scaling and distortion corrections to input pixel coordinates. Requires the same subroutine distortf (distortion.f) as used by the coadder.

Can account for the misalignment (translation and rotation) between the 12-µm and 25-µm WIRE FPAs.

Assumes that the misalignment between the star tracker and the WIRE telescope boresight has already been corrected for by the WIRE input processor.

Requires wcslib-2.4, a collection of FITS projection routines by Dr. Mark Calabretta, based on the Astronomy and Astrophysics paper "Representations of celestial coordinates in FITS" by Greisen and Calabretta (September 9, 1996).

The code negates CROTA2 after reading it in; this is required to produce results that are nearly identical to those of skyview, which has adopted a sign convention for CROTA2 that is opposite of that chosen by Greisen and Calabretta for left-handed coordinate systems.

Handles up to 50,000 input coordinate pairs, and FITS files with images as large as 1300x1300 pixels (the latter limitation is imposed by leftover code, which is unneeded for the present application).

Difference between xytolonlat.f and xytolonlat2.f: the former reads some of its inputs from a namelist file, while the latter can read the same inputs from the command line.

Difference between xytolonlat2.f and xytolonlat3.f: the former reads FITS keyword values from a FITS file, while the latter reads the same inputs from the command line.

Links with /proj/wire/russ/pipe/coad/distortion.f.

The software is now under both CVS version control (/proj/wire/cvsroot/da/russ/acs), and make control. The executables have been delivered to /proj/wire/ops/bin. The source codes are located in /proj/wire/russ/acs:

xytolonlat.f
xytolonlat2.f
xytolonlat3.f
xytolonlat.nl (currently set up with test case for cf. skyview)
xytolonlat.txt
makefile.f
libwcs_f.a
test.fits

Required and Optional Inputs

  1. FITS image file (only xytolonlat.f and xytolonlat2.f require a FITS file; xytolonlat3.f reads FITS keyword values from the command line).
  2. Namelist file with namelist variable settings (see table below). Only xytolonlat.f requires a namelist file; on the other hand, xytolonlat2.f can read the same inputs from the command line.
  3. Pixel coordinates to be transformed, read in from standard input an (i, j) pair at a time (where i and j are real*4 values), and terminated by a control-d. If testflag is set to .true., then five sets of internally hard-coded pixel coordinates are processed, and none are read in from standard input.

Namelist variables, defaults, and definitions:

Namelist variable = default value Definition
ifile = "test.fits" FITS image filename
iband=1 IR band
distortflag = f Correct for optical distortion?
testflag = f Execute test case?
verbflag = f Verbose outputs?
focallenx = 1000. x focal length (mm)
focalleny = 1000. y focal length (mm)
xdc = 64.5 x distortion center in FPA (pixels)
ydc = 64.5 y distortion center in FPA (pixels)
fpadx = 0. x shift of 25-µm FPA w.r.t. 12-µm FPA (pixels) (Shift along 25-µm image axes before rotating.)
fpady = 0. y shift of 25-µm FPA w.r.t. 12-µm FPA (pixels) (Shift along 25-µ image axes before rotating.)
fpadtheta = 0. Rotation of 25-µm; FPA w.r.t. 12-µ FPA (degrees)

Usage

In these examples, the namelist file has the extension ".nl", the input data are stored in a text file with the extension ".dat" where one set of pixel coordinates are stored per line, and the FITS image file has the extension ".fits".

xytolonlat save2.nl < save2.dat

xytolonlat2 -ifile test42.fits < save2.dat

xytolonlat3 -crval1 0 -crval2 -90 -crpix1 295 -crpix2 305 
            -cdelt1 -0.001 -cdelt2 0.001 -crota2 -42 < save2.dat

Outputs

Outputs are sent to both standard output, and to an output data file with the same name as the executable, plus the extension ".out".

For xytolonlat.f and xytolonlat2.f, the outputs that are sent to standard output consist of, first, a printout of the namelist variables and, second, a list of data records, where each data record includes the five following values:

  1. Pixel coordinate index;
  2. Inputted pixel coordinates, (i,j); and
  3. (RA, Dec) coordinates (in degrees) corresponding to the inputted pixel coordinates.

The outputs from xytolonlat3.f that are sent to standard output are simply banner information followed by a listing of (RA, Dec) output points.

The *.out outputs consist of only the aforementioned list of five-value data records (no banner information).

Test Results

Gives (RA, Dec) results that are within at least +/- 1.8 arcseconds of comparable results from skyview (probably the error is less than an arcsecond, but can't tell since skyview outputs only 6 significant digits).


lonlattoxy.f, lonlattoxy2.f, and lonlattoxy3.f

The FORTRAN code lonlattoxy.f does the inverse transformation of xytolonlat.f, with the exception that inverse scaling/distortion corrections are not applied. The code is useful for closure testing of xytolonlat.f in the absence of scaling/distortion correction requirements. It accepts the same namelist file as xytolonlat.f (but ignores those variables associated with scaling/distortion corrections). It requires pairs of (RA, Dec) points (in degrees) as inputs, and computes corresponding pairs of pixel coordinates. It gives very similar results to skyview.

Difference between lonlattoxy.f and lonlattoxy2.f: the former reads some of its inputs from a namelist file, while the latter can read the same inputs from the command line.

Difference between lonlattoxy2.f and lonlattoxy3.f: the former reads FITS keyword values from a FITS file, while the latter reads the same inputs from the command line.

The software is now under both CVS version control (/proj/wire/cvsroot/da/russ/acs), and make control. The executables have been delivered to /proj/wire/ops/bin. The source codes are located in /proj/wire/russ/acs:

lonlattoxy.f
lonlattoxy2.f
lonlattoxy3.f
lonlattoxy.nl (currently set up with test case for cf. skyview)
makefile.f
libwcs_f.a
test.fits


Subroutines quattolonlat and quattolonlat2 (posrecutils.pl)

Perl subroutine quattolonlat converts WIRE ACS quaternions and star-tracker/telescope boresight misalignment angles into (CRVAL1, CRVAL2, CROTA2) values for direct assignment to FITS file headers of corresponding WIRE images. The star-tracker/telescope boresight misalignment angles are band-dependent.

The input quaternions are checked to assure that the sum of their squares adds to within 10-6 of one.

The boresight misalignment angles are determined from IOC data using WIRE boresight calibration software. They are expressed in terms of a set of quaternions for the additional rotations required to register WIRE images with the star-tracker image reference frame. You must convert the quaternions to Euler angles (in decimal degrees) yourself in order to use quattolonlat, as the boresight calibration software no longer performs this step; instead, it is preferable to use the quaternions directly in subroutine quattolonlat2, which is documented below.

The outputs are in units of decimal degrees. CRVAL1 will be in the [0, 360] range; CRVAL2 will be in the [-90, 90] range; CROTA2 will be in the [-180, 180] range.

The software is now under both CVS version control (/proj/wire/cvsroot/da/russ/acs), and make control (makefile.p). The perl source has been delivered to /proj/wire/ops/lib/perl. The source codes reside in /proj/wire/russ/acs.

Usage:

( $crval1, $crval2, $crota2 ) = &quattolonlat ( $q1, $q2, $q3, $q4,
                                                $thetacorr, $phicorr, $psicorr );

Subroutine quattolonlat2 is similar to subroutine quattolonlat, except that it uses band-dependent "correction" quaternions to characterize the star-tracker/telescope misalignment:

( $crval1, $crval2, $crota2 ) = &quattolonlat ( $q1, $q2, $q3, $q4,
                                                $q1corr, $q2corr,
                                                $q3corr, $q4corr );


Subroutine ditherfromheader (posrecutils.pl)

Perl subroutine for processing FITS keyword data from two FITS files, a "reference" frame, and an "input" frame. Converts (RA, Dec) specified by (CRVAL1, CRVAL2) for the input frame into pixel coordinates in the reference frame. Uses this information to determine relative x and y offsets between the two frames. Assumes that both FITS files are gnonomic projections (but does no error checking on CTYPE keywords to verify this). Also assumes that the input image is first rotated about (xcen, ycen) prior to offseting. Finds the relative twist between the two frames by subtracting CROTA2 of the reference frame from that of the input frame (THIS APPROXIMATION IS NOT ACCURATE NEAR THE POLES; THE CODE WILL BE CHANGED ONCE THIS EFFECT IS PROPERLY INCLUDED IN THE WIRE SIMULATOR).

The software assumes that the pixel spacing is 4.297183463481e-3 degrees, consistent with that of a raw WIRE frame (after rescaling with a focal length of 1000 mm). This can be overridden by explicitly specifying values for CDELT1 and CDELT2 in the subroutine argument list. (The default values are CDELT1=-4.297183463481e-3 and CDELT2=4.297183463481e-3.)

The default pixel coordinates of the rotational center are (0,0); this is consistent with the values currently assumed by the stacker. These values can also be overridden in the subroutine argument list. In this case, explicit values for CDELT1 and CDELT2 must also be supplied.

The projection transformations used are based on Greisen and Calabretta (A&A, September 9, 1996), and FORTRAN software developed by Calabretta. A straightforward translation from FORTRAN to perl was done for the narrower application to only gnonomic projections (CTYPE1='RA---TAN', CTYPE2='DEC--TAN').

The output x and y offsets are in pixels, and the output twist angle is in decimal degrees. The twist angle is restricted to the [-180, 180] range.

The software is now under both CVS version control (/proj/wire/cvsroot/da/russ/acs), and make control (makefile.p). The perl source has been delivered to /proj/wire/ops/lib/perl. The source codes reside in /proj/wire/russ/acs.

Usage:

($dx,$dy,$theta) = &ditherfromheader(
				    $CRPIX1_0,
			     	    $CRVAL1_0,
				    $CRPIX2_0,
				    $CRVAL2_0,
			      	    $CROTA2_0,
			       	    $CRPIX1,
			       	    $CRVAL1,
			       	    $CRPIX2,
			       	    $CRVAL2,
			       	    $CROTA2,
                                    $CDELT1,
                                    $CDELT2,
                                    $xcen,
                                    $ycen );


Eqcoorddiff.pl

Finds the linear distance in arcseconds between two (RA, Dec) points.

skyrocket% Eqcoorddiff.pl -r1 4.29718e-3 -d1 4.29718e-3 -r2 4.2971e-3 -d2 4.2971e-3


Eqcoorddiff.pl version $Id: Eqcoorddiff.pl,v 1.1 1998/07/02 18:29:52 laher Exp $  update Thu_1998/07/02(183)_11:29:52 , PID=29485
Date/time: Thu_1998/07/02(183)_11:36:13   PCPU: 1.13/0.19/8  CCPU: 0.13/0.17


Named parameters for Eqcoorddiff.pl:
  ra1 = 0.00429718; dec1 = 0.00429718; ra2 = 0.0042971; dec2 = 0.0042971; 
  debug = undef; execpath = undef; verbose = undef; log = undef; 

Distance (arcseconds) = 0.000407293505391654


End of Eqcoorddiff.pl status 0, PID=29485
Date/time: Thu_1998/07/02(183)_11:36:13   PCPU: 1.19/0.19/8  CCPU: 0.13/0.17



Checkdither.pl

Computes the dithers between two or more input images.

skyrocket% /proj/wire/russ/acs/Checkdither.pl -xc 64.5 -yc 64.5 -inf sws450000106.fits,sws450000101.fits,sws450000102.fits,sws450000103.fits,sws450000104.fits,sws450000105.fits,sws450000107.fits,sws450000108.fits


Checkdither.pl version $Id: Checkdither.pl,v 1.5 1998/07/14 00:25:12 laher Exp $  update Mon_1998/07/13(194)_17:25:12 , PID=15865
Date/time: Mon_1998/07/13(194)_17:33:49   PCPU: 1.16/0.15/2  CCPU: 0.19/0.12


Named parameters for Checkdither.pl:
  infits = sws450000106.fits,sws450000101.fits,sws450000102.fits,sws450000103.fits,sws450000104.fits,sws450000105.fits,sws450000107.fits,sws450000108.fits; 
  debug = undef; execpath = undef; verbose = undef; log = undef; 
  xcenter = 64.5; ycenter = 64.5; 

                             Delta Rotation Angles         Stack Offset Values

Filename                    dRA      dDec   dCROTA2      dx       dy      dtheta

sws450000106.fits          0.0000   0.0000   0.0000     0.0000   0.0000   0.0000
sws450000101.fits          0.0015   0.0037   0.0006    -0.3408   0.8674   0.0006
sws450000102.fits         -0.0551   0.0008   0.0022    12.8164   0.1555   0.0022
sws450000103.fits          0.0284  -0.0034   0.0013    -6.6032  -0.7801   0.0013
sws450000104.fits         -0.0106   0.0012  -0.0011     2.4753   0.2691  -0.0011
sws450000105.fits          0.0074   0.0018  -0.0072    -1.7284   0.4341  -0.0072
sws450000107.fits          0.0023   0.0035   0.0085    -0.5353   0.8277   0.0085
sws450000108.fits          0.0003  -0.0021   0.0007    -0.0679  -0.4778   0.0007


End of Checkdither.pl status 0, PID=15865
Date/time: Mon_1998/07/13(194)_17:34:08   PCPU: 1.35/0.23/21  CCPU: 10.15/3.12


These results are directly comparable to DA pipeline results for the same case (Cf. results below), where extracted source positions have been used to derive the frame registration data, and therefore the x and y offsets do not agree exactly, but are close. Note that the theta values are in large disagreement because they are smaller than the rotation angle error associated with the latter method.

skyrocket% more cws450000100.of
\INT NFRAMES = 8
\CHAR VERSION = '$Id: stack,v 1.21 1998/06/26 01:28:30 tim Exp $ '
\CHAR RUNTIME = 'Sat_1998/07/11(192)_13:43:54 '
\CHAR IAM = '/proj/wire/dev/bin/stack'
\INT NMASTER = 1
\CHAR MASTERFR = 'sws450000106'
|frame         |ncol|nlin|nmat|  xcen|  ycen|    zoff|   theta|    xdel|    ydel
| xmin| xmax| ymin| ymax| xsig| ysig|
| c            |  i |  i |  i |    r |    r |      r |      r |      r |      r 
|   r |   r |   r |   r |   r |   r |
sws450000106     128  128  140  64.50  64.50    0.000    0.000    0.000    0.000
     0   129     0   129 0.000 0.000
sws450000101     128  128  142  64.50  64.50    0.000   -0.037   -0.319    0.880
    -0   129     1   130 0.124 0.136
sws450000102     128  128  121  64.50  64.50    0.000   -0.007   12.829    0.145
    13   142     0   129 0.187 0.141
sws450000103     128  128  126  64.50  64.50    0.000    0.015   -6.587   -0.784
    -7   122    -1   128 0.193 0.132
sws450000104     128  128  136  64.50  64.50    0.000   -0.002    2.488    0.262
     2   131     0   129 0.199 0.160
sws450000105     128  128  134  64.50  64.50    0.000    0.019   -1.717    0.425
    -2   127     0   129 0.226 0.160
sws450000107     128  128  140  64.50  64.50    0.000   -0.015   -0.522    0.833
    -1   128     1   130 0.143 0.110
sws450000108     128  128  135  64.50  64.50    0.000   -0.015   -0.077   -0.473
    -0   129    -0   129 0.156 0.129
\# SUMRY: #frames= 8    master= 1    maxdx= 12.8   maxdy= 0.9    maxdtheta= -0.0
   
\# TAG: Stack-$Id: stack,v 1.21 1998/06/26 01:28:30 tim Exp $ -Mon_1998/07/06(18
7)_11:58:35 (/proj/wire/dev/bin/stack)
\# Sat_1998/07/11(192)_13:43:54  by laher in directory /stage/wire-well/russ/rad
hits/reduce13



Last revised: July 13, 1998

Software developer: Russ Laher (laher@ipac.caltech.edu)

URL: http://spider.ipac.caltech.edu/staff/laher/posrec.html

Return to Home Page