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:
- QUAT: Quaternion [Z, Y, Z, double],
- EULER: Z-Y-Z Euler angles (phi, theta, psi in degrees), or
- 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
- Modify an attitude file containing the attitude in the quaternion format,
correcting only for the annual aberration.
aberattitude infile=attitude.att outfile=attitude-corr.att alignfile=align.fits \
annaber=yes clobber=yes
- Modify an attitude file containing the attitude in the Euler angle format,
correcting for the annual and orbital aberration.
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