WIRE Boresight Calibration Software

Introduction

Perl script Calboresight.pl analyzes WIRE data acquired during IOC to determine the misalignment between the star tracker and the telescope. The real-time ACS quaternions, together with the static misalignment data computed by this code, are used by the WIRE input processor to compute and assign celestial coordinates to the center of WIRE images.

The misalignment between the star tracker and the telescope is expressed in terms of quaternions. This code must be executed separately for each WIRE band, in order to generate the two required sets of band-dependent "correction" quaternions.

It is assumed that the orientation of the telescope relative to the star tracker does not change during the WIRE mission. Thus, boresight calibration, in principle, need only be done once, early in the mission. However, it is desirable to perform this calibration many times, and average the independently obtained results, in order to get a more accurate estimate.

This software optionally modifies CRVAL1, CRVAL2, and CROTA2 in the headers of specified FITS files with the values it calculates. This is useful since the WIRE coadd images acquired during IOC, that are analyzed for the boresight calibration, do not yet have accurate CRVAL1, CRVAL2, and CROTA2 values (since up until IOC the star-tracker correction quaternions are unknown).

Description

The sofware requires 12-µm and 25-µm WIRE coadd images of a set of calibration stars, the celestial coordinates of the calibration stars, and their pixel coordinates in each coadd image. ACS quaternions, as measured during the acquisition time of the master frame of the coadd image, are also needed.

The celestial coordinates of the calibration stars are from a star catalog, for example. They should be equatorial coordinates (right ascension and declination) in units of decimal degrees.

The coadd image is created by the DA pipeline from many WIRE frames acquired during IOC. The more WIRE frames in the coadd image, the more accurate will be the measurements of pixel coordinates of the calibration stars in the coadd image. At least two calibration stars are required, but many more are preferable since a least-squares fit technique is used to reduce random errors in measured star positions. Note that this applies not only to position errors in the coadd image, but also to absolute position errors on the celestial sphere.

The pixel coordinates of the calibration stars in the coadd image are found either by picking them out of a source extractor list (using skyview as a visualization aide), or by measuring them using IRAF. Since these positions are derived from a coadd image, the required scaling/distortion corrections to the star positions have already been made (by the coadder). This is the manual step of the boresight calibration process. Once these data have been properly formatted into an ASCII data file (as described below), the boresight calibration software can be executed.

The algorithm employed by the boresight calibration software (Calboresight.pl) is as follows:

  1. Read CRPIX1, CRPIX2, CDELT1, and CDELT2 from the header of the FITS coadd image. A FORTRAN code called readfitsheader.f does this job.

  2. Compute and/or set FITS keywords for the star tracker. (Keep in mind that actual images from the the star tracker are not required; FITS keywords for such images, however, are useful for projecting spherical coordinates into the star-tracker image plane using standard FITS library routines.) Part of this can be accomplished with the perl subroutine quattolonlat2 (set the correction quaternions equal to [0, 0, 0, 1] for this run), which accepts the star-tracker quaternions as inputs, and outputs values for CRVAL1, CRVAL2, and CROTA2. CRPIX1, CRPIX2, CDELT1, and CDELT2 for the star tracker are set to the values read from the header of the FITS coadd image.

  3. Read data from calibration-star ASCII data file.

  4. Compute the pixel coordinates of the calibration stars in the star-tracker image reference frame. The FORTRAN code latlontoxy3.f is used for this job (this code accepts command-line inputs of FITS keywords and equatorial coordinates from standard input, and outputs the corresponding pixels coordinates).

  5. Co-register the star tracker "image" and the coadd image using rotlsqdrv2.f, a nonlinear least-squares fitting code that accepts the pixel coordinates of two or more sources in two different images and returns the relative x and y offsets and rotation angle between the two images. A weight can be assigned to each calibration star to indicate its relative importance in computing the image registration data.

  6. Use the relative x and y offsets and rotation angle returned from rotlsqdrv2.f in the rotational transformation equations solved by this code to compute the pixel coordinates of the WIRE master frame center in the star tracker "image" (this point has the coordinates CRPIX1 and CRPIX2 in the coadd image)

  7. Transform the pixel coordinates of the WIRE master frame center in the star tracker "image" into equatorial coordinates. To do this, use xytolonlat3.f, which accepts command-line inputs of FITS keywords and pixel coordinates from standard input, and outputs the corresponding celestial coordinates.

  8. Once the celestial coordinates of the center of the WIRE master frame have been established, two of the Euler rotation angles of the imaging system for the WIRE band being treated are computed from 

        phi(telescope) = RA (image center) + 90 degrees
    theta(telescope) = 90 degrees - Dec (image center)

    (See Outputs section below for explanation of nomenclature.)

  9. Finally, the Eulerian-rotation correction angles, between the telescope and the star tracker, are given by 

        delta phi = phi(telescope) - phi(star tracker)
    delta theta = theta(telescope) - theta(star tracker)
    delta psi = rotation angle from the nonlinear least-squares fit

    and from these angles correction quaternions are computed.

    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/ops/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 Calboresight.pl:

    1. Filename of the FITS coadd image of the calibration star set.
    2. Filename of the ASCII data file containing the calibration star data (see below for format).
    3. ACS quaternions that apply to the master frame of the coadd image (the pointing error can be reduced by improving these values with the ACS data processor).
    Coadd-image and calibration-star filenames and quaternion values are given as command-line inputs.

    The format of the calibration star ASCII data file is straightforward. The first line is the number of calibration stars. Each subsequent line includes data for a particular star. The required data for each star are the five values: right ascension (degrees), declination (degrees), x coadd-pixel position, y coadd-pixel position, and position measurement confidence-weight. These values should be separated by whitespace (no commas, etc.). An example data file is given as follows (this is test13.dat, referred to in the Usage section below): 

       2
   -178.719 -89.573    14.0   24.0  1.0   
   0.993808 -89.5335  614    600    1.0

    The table below describes the available command-line inputs. Note that the first six are required, and have no default values.

    Command-line input Definition
    -infits or -inf filename FITS coadd-image filename
    -indat or -ind filename Calibration-star ASCII data filename
    -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).
    -q1 value Quaternion #1
    -q2 value Quaternion #2
    -q3 value Quaternion #3
    -q4 value Quaternion #4
    -verbose or -v Verbose mode. Default is off.
    -test Execute test case? Default is no test case. This switch sets the -verbose switch, and computes the quaternions for a case where the misalignment is 1-2 degrees for each Euler angle relative to the WIRE telescope pointing direction defined by the header information in test13.fits (see outputs of the test case below).
    -execPath or -xp path Pathname for the binaries used by Calboresight.pl.
    -nsigLim or -nsl Outlier rejection parameter (see rotlsqdrv2.f documentation for npostol). The default value is 5.
    -radtol or -rad Outlier rejection parameter (see rotlsqdrv2.f documentation). The default value is 0.25 pixels.
    -chi2tol or -chi Outlier rejection parameter (see rotlsqdrv2.f documentation). The default value is 0.8.
    -siginp or -sig Estimated weighted-average standard deviation of the source position data (see rotlsqdrv2.f documentation). The default value is 0.05 pixels (= 0.8 arcseconds for WIRE pixels).

    Outputs

    The outputs are four "correction" quaternion values that correspond to the three delta Eulerian-rotation angles: delta phi, delta theta, and delta psi, that define the rotation of the WIRE telescope in a given WIRE band relative to the star tracker.

    The Euler-angle nomenclature used here is defined in Goldstein (Classical Mechanics, Second Ed., p. 146). The x-y plane contains the celestial equator, with the equinox on the x axis, and the z' axis is the star tracker (or telescope) pointing direction.

    Usage

    Example of how to execute Calboresight.pl for normal use: 
       Calboresight.pl -inf test13.fits -ind test13.dat -q1 0.364050283583858  
                                                    -q2 0.931338412501439 
                                                    -q3 0.00331838217013145 
                                                    -q4 0.00807098269021478
    Example of how to execute Calboresight.pl for the test case: 
       Calboresight.pl -inf test13.fits -ind test13.dat -test

    For the test case, the star tracker pointing direction is set to RA = 279.0 degrees, Dec = -2.30 degrees, and a roll misalignment angle of = - 1.0 degrees.

    Note that psi and CROTA2 are not equivalent; as of January 19, 1998 we define WIRE images to be flipped about the spacecraft body X-axis, and therefore CROTA2 = psi + 180 degrees. The next section gives test case results.

    Test Case Outputs

    Outputs from Calboresight.pl test case: 
    
Calboresight.pl version $Id: Calboresight.pl,v 1.6 1998/02/04 18:53:07 laher Exp $  update Wed_1998/02/04(035)_10:53:07 , PID=5433
Date/time: Wed_1998/02/04(035)_10:54:11   PCPU: 0.97/0.11/1  CCPU: 0.03/0.09


Named parameters for Calboresight.pl:
  infits = test13.fits; indat = test13.dat; debug = undef; execpath = undef; 
  verbose = undef; test = 1; log = undef; nsiglim = 5; radtol = 0.25; 
  siginp = 0.05; q1 = undef; q2 = undef; q3 = undef; q4 = undef; 

FITS keyword values extracted from coadd image test13.fits:
   CRPIX1 =  300.00000000000
   CRPIX2 =  300.00000000000
   CRVAL1 =  0.
   CRVAL2 =  -90.000000000000
   CROTA2 =  -47.300000000000
   CDELT1 =  -1.0742958400000E-03
   CDELT2 =  1.0742958400000E-03

Running test case...  Set verbose mode.

Specified inputs for star tracker:
   RA (degrees)  = 1
   Dec (degrees) = -89
   CROTA2 (degrees) = -46.3

Computing quaternions from inputs...

Quaternions for star tracker:
   q1 = 0.931338412501262
   q2 = -0.364050283584309
   q3 = 0.00807098269021317
   q4 = -0.00331838217013536

Star tracker orientation derived from quaternions (unprimed system):
   RA (degrees)  = 1
   Dec (degrees) = -88.9999999999999
   CROTA2 (degrees) = -46.2999999998889

FITS keywords derived for star tracker "image" (double-primed system):
   CRPIX1 = 300.00000000000
   CRPIX2 = 300.00000000000
   CRVAL1 = -90.0000000000273
   CRVAL2 = 0
   CDELT1 = -1.0742958400000E-03
   CDELT2 = 1.0742958400000E-03
   CROTA2 = -46.2999999998889

Calibrator star data read in from test13.dat:
   Star #1: RA = -178.719  Dec = -89.573  i = 14.0  j = 24.0  Weight = 1.0
   Star #2: RA = 0.993808  Dec = -89.5335  i = 614  j = 600  Weight = 1.0

Image registration data derived from nonlinear least-squares fit:
   dx (pixels)     = -673.088
   dy (pixels)     = -643.224
   theta (degrees) = -2.12177E-04

Master-frame-center pixel coordinates...
   ...in coadd image: 300.00000000000, 300.00000000000
   ...in star tracker "image": -373.088, -343.224

Celestial coordinates of master-frame-center (double-primed system):
   RA (degrees) = -90.000005532302
   Dec (degrees) = -1.0000814585876

Celestial coordinates of master-frame-center (unprimed system):
   RA (degrees) = -175.115302080647
   Dec (degrees) = -89.9999183540865

Master-frame-center Euler angles (degrees; unprimed system):
 phi   = -85.1153020806467
 theta = 179.999918354087
 psi   = 132.699787823111

Correction quaternions:
   q1corr = -0.00656070156601254
   q2corr = 0.00575517362665614
   q3corr = 0.999053478219087
   q4corr = 0.0426143500458924

Closure check:
   Error in CRVAL1 (arcseconds)                             = -630415.087490265
   Error in CRVAL2 (arcseconds)                             = 0.29395732726698
   Error in linear distance (arcseconds)                    = 0.293957527241361
   Error in CROTA2 (arcseconds, 0.39 deg. from rot. center) = -0.00518445900526201

   Input Telescope Values:  0., -90.000000000000, -47.300000000000
   Output Telescope Values: -175.115302080629, -89.9999183451869, -47.3002121768715


End of Calboresight.pl status 0, PID=5433
Date/time: Wed_1998/02/04(035)_10:54:13   PCPU: 1/0.15/3  CCPU: 0.4/0.43

    Outstanding Issues

    A scheme for assigning position measurement confidence-weights to calibration stars needs to be adopted.

    The number of WIRE frames to be used in computing the coadd image must be chosen.

    The number of times that this calibration will be repeated needs to be decided.

    Three sources of error in the boresight calibration process have been identified so far; they are:

    The first two error sources on the above list contribute to the image registration error, which can be reduced by increasing the number of calibration stars. Notice that the first error source is negligible compared to the second.

    The third error source affects the estimate of the absolute pointing direction of the WIRE telescope. The error associated with this estimate can be reduced by repeating the boresight calibration process with independent data and averaging the results.

    Last revised: February 5, 1998

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

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

    Return to Home Page