DESCRIPTION

The attconvert task is a mission-independent task for converting attitude files from one format to another. This task supports three formats: quaternion [X, Y, X, real], Z-Y-Z Euler angles, and pointing angles [right ascension, declination, roll].

The attconvert task has two modes.

Single point mode:

the 'input' parameter is a list of components separated by commas. The 'inform' parameter is used to specify the format of 'input'. The output quantities are written to standard output and also stored in task parameters 'quatx', 'quaty', 'quatz', 'quatr', 'eulerphi', 'eulertheta', 'eulerpsi', 'outra', 'outdec', and 'outroll', for the three different formats supported.

FITS file mode:

the 'input' parameter is a FITS file containing the columns to be converted, and the 'outfile' parameter is a FITS file where the output columns are written. The column names for the input and the output files are specified with the 'incol' and 'outcol' parameters, respectively. The output columns are created in 'outfile' if they do not already exist.

In general, a quaternion or a set of Euler angles describes spacecraft attitude, and the set of pointing angles describes a target position on the sky. In general, the instrument, the spacecraft and the instrument coordinate systems may be offset from each other, relative to the intended alignments. The relationship between the two coordinate systems is described by a telescope definition (teldef) file. This file contains a 3x3 matrix describing the rotation between instrument and spacecraft axes in Cartesian coordinates, along with a roll angle offset and sign. The name of a teldef file may be supplied using the 'alignfile' parameter.

The 'alignfile' parameter may also be used to specify an alignment file as opposed to a teldef file. An alignment file also describes a constant rotation of the spacecraft coordinate axes relative to the instrument coordinate axes. Pointing on the sky is defined by the +Z direction in the rotated system.

Special cases of 'alignfile' are the values STANDARD and NONE, both of which are interpreted as a rotation angle of zero, the two differing only in the sign convention for the roll angle (see description of 'alignfile' parameter).

PARAMETERS

input [filename]

Either a comma-separated list of the input attitude components or the name of the attitude file containing the columns to be converted.

inform = EULER [string QUAT|EULER|POINTING]

Input attitude format.

(outfile) [filename]

Output file name. This parameter is required in FITS file mode and otherwise ignored.

(outform = EULER) [string QUAT|EULER|POINTING]

One or more output attitude formats for FITS file mode. Multiple formats are specified in a comma-separated list. The order of the format names must match the order of the corresponding column names in the 'outcol' parameter.

(outcol = QPARAM) [string]

One or more output attitude column names for FITS file mode. Multiple column names are specified in a comma-separated list. The order of the column names must match the order of the corresponding format names in the 'outform' parameter.

(alignfile = NONE) [string NONE|STANDARD|file name]

Description of the alignment, which is either a file name or a string denoting a simple form of the alignment. The alignment describes the relative orientation of the instrument and spacecraft axes, together with the sign convention and offset for converting between roll angle and the 3rd Euler angle, psi. The roll and psi are related by the formula, roll = ROLLSIGN * (psi - 90 + ROLL_OFF). Two simple alignments do not require an alignment file, because the instrument and spacecraft coordinate axes are all coaligned. These alignments are specified by 'alignfile=NONE' and 'alignfile=STANDARD'. Only the sign convention for the roll angle differs between these two cases. If 'alignfile=NONE', then ROLL_OFF = 0 and ROLLSIGN = +1. If 'alignfile=STANDARD', the ROLL_OFF = 0 and ROLLSIGN = -1; STANDARD is the configuration for XRISM, Hitomi, Swift, and Suzaku.

(attext = ATTITUDE) [string]

Name of the attitude extension of the attitude file, for FITS file mode.

(incol = EULER) [string]

Name of the existing attitude column, for FITS file mode.

(quatx = 0.0) [double]

Value of the output quaternion x-component, for single point mode.

(quaty = 0.0) [double]

Value of the output quaternion y-component, for single point mode.

(quatz = 0.0) [double]

Value of the output quaternion z-component, for single point mode.

(quatr = 1.0) [double]

Value of the output quaternion real component, for single point mode.

(eulerphi = 0.0) [double]

Value of the output first Euler angle (phi, in degrees), for single point mode.

(eulertheta = 0.0) [double]

Value of the output second Euler angle (theta, in degrees), for single point mode. When theta is 0 or 180 degrees, there are an infinite number of first and third Euler angle pairs that represent the same rotation. In these cases, the output Euler angles may be displayed in an alternative, but equivalent representation.

(eulerpsi = 0.0) [double]

Value of the output third Euler angle (psi, in degrees), for single point mode.

(outra = 0.0) [double]

Value of the output right ascension [degrees], for single point mode.

(outdec = 90.0 ) [double]

Value of the output declination [degrees], for single point mode.

(outroll= 270.0) [double]

Value of the output roll [degrees], for single point mode.

(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.

(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. Convert a single attitude quaternion to all formats using the default roll definition.

   attconvert input="0,0,0.7071,0.7071" inform=QUAT

2. Convert a single attitude quaternion to all formats using the standard roll definition.

   attconvert input="0,0,0.7071,0.7071" inform=QUAT alignfile=STANDARD  

3. Convert the Euler angles in an attitude column to quaternions for a Suzaku attitude file.

   attconvert input=ae107010010.att outfile=ae107010010_eq.att \
      inform=EULER incol=EULER outform=QUAT outcol=QUATERNION alignfile=STANDARD

4. Convert the quaternions in the attitude column QPARAM to both Euler and pointing angles for a Swift attitude file, using a Swift alignment matrix and roll definition.

   attconvert input=sw00020215001sat.fits inform=QUAT \
      outfile=sw00020215001sat_pe.fits outform=EULER,POINTING \
      incol=QPARAM outcol=EPARAM,PPARAM alignfile=swalign20041115v012.fits

SEE ALSO

LAST MODIFIED