NAME

aberattitude - Correct an attitude file for aberration effects

USAGE

aberattitude infile outfile

DESCRIPTION

The aberattitude task is a mission-independent task that modifies an attitude file to correct for aberration effects. The task requires an attitude input file (parameter 'infile') and computes the correction for each row as a function of the TIME column. The output file, specified by the parameter 'outfile', contains the corrected attitude column, along with the original ones, renamed with the string "_OLD" appended. For example, for an input file with a QPARAM attitude column, the output file has a column named QPARAM_OLD containing the original values, and a column named QPARAM containing the corrected values.

The aberration of light (also referred to as stellar aberration) is a phenomenon that produces an apparent motion of celestial objects about their catalog positions, that is dependent on the velocity of the observer. The aberration correction may be calculated for either or both of two orbital motions, namely, that of the earth about the sun, and that of the satellite about the earth. These calculations are invoked by setting the parameters 'annaber' and 'orbaber' to yes, respectively. To correct for orbital aberration, an orbit file is necessary.

If the parameter 'debug' is set to yes, the following quantities are printed for each row of the input table: TIME (mission time), VTOT (spacecraft speed), VSATX, VSATY, and VSATZ (X, Y, and Z components of the satellite velocity respectively), VEARTH (Earth speed), VEARTHX, VEARTHY, and VEARTHZ (X, Y, and Z components of the earth velocity respectively), and ERADVEL (projection of earth velocity onto the unit vector toward the observed target). The coordinate system is a right-handed equatorial system where X points toward the vernal equinox and Z toward the north celestial pole. The velocities are in units of km s^{-1}.

An optional input file, whose name is specifed by the parameter 'alignfile', enables a rotational offset to be applied to the spacecraft axes. The file is a FITS file, and the elements of the rotation matrix are supplied as keywords in the header of the file. The keyword names are ALIGNmn, where m=0,1,2, or 3, and n=0,1,2, or 3. The format is identical to that in a "telescope definotion file" (or teldef) for a particular instrument.

PARAMETERS

infile [filename]
Name of input attitude file.

outfile [filename]
Name of output attitude file.

(orbfile = NONE) [string NONE|file name]
Name of orbit file used to retrieve spacecraft velocity in Earth-Centered Inertial (ECI) Cartesian coordinates. This file is required only if 'orbaber=yes'.

(alignfile = NONE) [string NONE|file name]
Name of the spacecraft alignment calibration file. The alignment file specifies a rotational offset to be applied to the spacecraft axes.

(annaber = yes) [string yes|no|invert]
Option for correcting annual aberration. If 'annaber=yes', the correction is applied. If 'annaber=no', the correction is not applied. If 'annaber=invert', the correction is applied after being multiplied by -1; this option is only used for debugging. Annual aberration is the apparent change in the direction of incident light from a distant object, on a yearly cycle, caused by the earth's orbital velocity about the sun. The effect is at most a ~20.49 arcsec shift in the object's detected position.

(orbaber = no) [string yes|no|invert]
Option for correcting orbital aberration. If 'orbaber=yes', the correction is applied, provided that an input orbit file is specified in the parameter 'orbfile'. If 'orbaber=no', the correction is not applied. If 'orbaber=invert', the correction is applied after being multiplied by -1; this option is used only for debugging. Orbital aberration is the apparent change in the direction of incident light from a distant object caused by the satellite's orbital velocity about the earth. For a satellite in low earth orbit, the effect is at most a ~5 arcsec effect.

(attext = ATTITUDE) [string]
Name of the FITS binary table extension of the input attitude file containing the attitude to be corrected. The attitude in the input file can be in one of the three following formats specified by the parameter 'attform': QUAT, EULER, or POINTING. If the attitude file contains separate columns giving the attitude in more than one format, only the column formatted as specified with the 'attform' parameter is corrected.

(attcol = QPARAM) [string]
Name of the column in the input attitude file containing the attitude to be corrected. The data in this column must be in the format given by the 'attform' parameter.

(attform = QUAT) [string QUAT|EULER|POINTING]
Format of the attitude table. The following three formats are supported:
  1. QUAT: Quaternion [Z, Y, Z, double],
  2. EULER: Z-Y-Z Euler angles (phi, theta, psi in degrees), or
  3. POINTING: Pointing angles (right ascension, declination, roll in degrees).

(orbext = NONE) [string]
Name of the FITS binary table extension of the orbit file containing the velocity vectors.

(orbcol = VELOCITY) [string]
Name(s) of the FITS column(s) containing orbit values in the 'orbext' extension of the orbit file. This parameter is linked to the parameter 'orbform'. If 'orbform=VECTOR', then 'orbcol' is the name of the single FITS column containing the velocity values as a vector. If 'orbform=COMPONENTS', then 'orbcol' must be a string containing three comma-separated column names, specifying in order the X, Y, and Z components. If 'orbform=KEPLERIAN', then 'orbcol' must be a string containing six comma-separated column names, specifying the Keplerian orbital elements in the following order: semi-major axis(A), eccentricity(E), inclination(I), ascending node right ascension(AN), ascending node angle(AP) and the mean anomaly (MA). These columns must be scalars. Velocity must be in km s^{-1} in an ECI system.

(orbform = VECTOR) [string VECTOR|COMPONENTS|KEPLERIAN]
Format of the orbital velocity column(s) in the orbit file; three formats are supported. For the VECTOR format, the velocity is provided as a vector column with three elements (X, Y, and Z in the ECI system). For the COMPONENTS format, the velocity is provided in three separate columns. If the 'orbform=KEPLERIAN', six column names must be provided that specify the Keplerian orbital elements from which the velocity is derived (see 'orbcol').

(clobber = no) [boolean yes|no]
Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]
Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]
Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]
Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]
Records tool parameters in HISTORY.

EXAMPLES

  1. Modify an attitude file containing the attitude in the quaternion format, correcting only for the annual aberration.
  2.    aberattitude infile=attitude.att outfile=attitude-corr.att alignfile=align.fits \
          annaber=yes clobber=yes 
    
  3. Modify an attitude file containing the attitude in the Euler angle format, correcting for the annual and orbital aberration.
  4.    aberattitude infile=attitude.att outfile=attitude-corr.att alignfile=align.fits \
          annaber=yes orbaber=yes attform=EULER attcol=EULER \
          orbfile=orbit.fits orbext=SAT_ORBIT orbcol=SAT_VELOCITY orbform=VECTOR clobber=yes 
    

SEE ALSO

aberposition

LAST MODIFIED

February 22, 2024