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

  1. 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.
  2.    aberposition ra=161.2649625 dec=-59.68451667 time="2009-06-10T01:49:30" chatter=2
    
  3. Derive the annual and orbital aberration for a given pointing and time. The orbit file has the orbit velocity stored in three separate columns.
  4.    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