NAME
aberposition - Correct coordinates for aberration effects
USAGE
aberposition ra dec time
DESCRIPTION
The aberposition task is a mission-independent task that corrects
equatorial coordinates for aberration effects.
The task requires initial RA and DEC coordinates in degrees and a time (UTC format).
The aberration of light (also referred to as stellar aberration)
is a phenomenon that produces an apparent motion of a distant object
about its catalog position that is dependent upon the velocity of the observer.
The aberposition task adjusts the apparent position of a target
in order to correct for this effect.
The adjustment 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.
The task outputs the corrected RA and DEC in the 'outra' and 'outdec'
parameters.
PARAMETERS
- ra = 180.0 [double]
- Input right ascension [degrees], a value between 0 and 360.
- dec = 0.0 [double]
- Input declination [degrees], a value between -90 and +90.
- time = 2019-01-01T00:00:00 [string]
- Input UTC date and time in the format YYYY-MM-DDThh:mm:ss.
- (orbfile = NONE) [string NONE|file name]
- Name of the orbit file used to retrieve spacecraft velocity in
Earth-Centered
Inertial (ECI) Cartesian coordinates. This is required for orbital aberration
corrections. If 'orbfile=NONE', the orbital correction is skipped, and
only the annual correction is performed.
- (annaber = no) [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 used only for debugging).
Annual aberration is the apparent bending
of light from a distant object caused by the earth's orbital velocity
about the sun. The effect is at most a ~20.49 arcsec
shift in the object's measured 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 only used for debugging).
Orbital aberration is the apparent bending of 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
shift in the object's detected position.
- (leapsecfile = REFDATA) [string CALDB|REFDATA|file name]
- Name of the FITS file containing the table of leap seconds.
This file is necessary to convert UTC accurately to the time system used
in the orbit file.
If set to CALDB or REFDATA, the file is read from the calibration database,
CalDB, or the REFDATA area respectively is used.
- (orbext = ORBIT) [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' is a string containing three
comma-separated names of scalar columns, specifying in order the X, Y, and Z components of
the orbital velocity. If 'orbform=KEPLERIAN', then 'orbcol' is a string containing six
comma-separated names of scalar columns, specifying the Keplerian orbital elements in
the following order: semi-major axis, eccentricity, inclination, ascending node right ascension,
ascending node angle, and the mean anomaly.
Velocity must be in units of 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 'orbform=KEPLERIAN', six column names are provided that
specify the Keplerian orbital elements from which the velocity is derived (see 'orbcol').
- (outra = 0.0) [double]
- The adjusted value of the ouput right ascension is stored in this parameter
in the .par file upon exit from the task.
- (outdec = 0.0 ) [double]
- The adjusted value of the output declination is stored in this parameter
in the .par file upon exit from the task.
- (buffer = -1) [integer -1|0|N]
- Rows to buffer (-1=auto, 0=none, N>0=numrows).
- (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
- Derive the annual aberration for a given pointing and time using the
leapsecond file in the CalDB. The 'chatter' parameter is set to 2, which prints
the output values to the screeen.
aberposition ra=161.2649625 dec=-59.68451667 time="2009-06-10T01:49:30" chatter=2
- Derive the annual and orbital aberration for a given pointing and time.
The orbit file has the orbit velocity stored in three separate columns.
aberposition ra=161.2649625 dec=-59.68451667 time=2009-06-10T01:49:30 \
leapsecfile=CALDB orbaber=yes orbfile=orbit.fits \
orbcol="VX,VY,VZ" orbform=COMPONENTS chatter=2
SEE ALSO
aberattitude
LAST MODIFIED
November 2, 2023