MSOPCK User's Guide =========================================================================== Last revised on 2006 JUN 23 by B. V. Semenov. Abstract -------------------------------------------------------- MSOPCK is a program that converts time-tagged quaternions, Euler angles, or matrices provided in text files into a type 1, 2, or 3 SPICE C-kernel. Summary -------------------------------------------------------- The MSOPCK program creates a type 1, 2 or 3 CK segment from time tagged orientation data expressed as quaternions, Euler angles, or matrices. The data time tags have four acceptable formats: 1. Any format convertible by the SPICE time subsystem using the STR2ET routine. 2. SPICE SCLK values. 3. SCLK values provided a floating point number. 4. Double precision clock ticks. Note: MSOPCK cannot process time tags expressed as ephemeris seconds past J2000 (ET). All time tags in a data file must use a single format. Usage -------------------------------------------------------- Program usage: > msopck Setup File -------------------------------------------------------- This program takes setup information from a setup file in text kernel file format. A template for a setup file: \begindata LSK_FILE_NAME = 'LSK file' SCLK_FILE_NAME = 'SCLK file' FRAMES_FILE_NAME = 'FRAMES file' INTERNAL_FILE_NAME = 'internal file name string' COMMENTS_FILE_NAME = 'file containing comments' CK_TYPE = 1, 2, or 3 CK_SEGMENT_ID = 'segment ID string' INSTRUMENT_ID = NAIF instrument ID REFERENCE_FRAME_NAME = 'reference frame name' ANGULAR_RATE_PRESENT = 'YES', 'NO', 'MAKE UP', or 'MAKE UP/NO AVERAGING' ANGULAR_RATE_FRAME = 'REFERENCE' or 'INSTRUMENT' QUATERNION_NORM_ERROR = maximum normalization error ANGULAR_RATE_THRESHOLD = ( X_rate, Y_rate, Z_rate ) MAXIMUM_VALID_INTERVAL = interval length, seconds TIME_CORRECTION = bias to apply to input times, units of seconds INPUT_DATA_TYPE = 'MSOP QUATERNIONS', 'SPICE QUATERNIONS', 'EULER ANGLES', or 'MATRICES' INPUT_TIME_TYPE = 'SCLK', 'UTC', 'TICKS', or 'DSCLK' EULER_ROTATIONS_ORDER = ( Axis_1, Axis_2, Axis_3 ) EULER_ANGLE_UNITS = 'DEGREES' or 'RADIANS' EULER_ROTATIONS_TYPE = 'BODY' or 'SPACE' (default SPACE) OFFSET_ROTATION_ANGLES = ( Angle_1, Angle_2, Angle_3 ) OFFSET_ROTATION_AXES = ( Axis_1, Axis_2, Axis_3 ) OFFSET_ROTATION_UNITS = 'DEGREES' or 'RADIANS' DOWN_SAMPLE_TOLERANCE = down sampling tolerance, in radians INCLUDE_INTERVAL_TABLE = 'YES' or 'NO' (default 'YES') PRODUCER_ID = 'producer group/person name' \begintext Comments on the data source or information specific to the orientation model. where: LSK_FILE_NAME leapseconds file name. Required input. SCLK_FILE_NAME SCLK file name. Required input. FRAMES_FILE_NAME frames file name; this setup parameter is optional and must be provided only if orientation is given relative to a user-defined frame INTERNAL_FILE_NAME internal file name as 80-chars long string; optional, if not present, the application uses a default value COMMENTS_FILE_NAME file containing comments to add to the comment area of an output CK file, optional, but if not present, then only defaults are written to CK comment area CK_TYPE output CK segment type, either 1, 2 or 3. Required input. CK_SEGMENT_ID 40-char segment ID string, optional, if not present set to default value INSTRUMENT_ID the s/c structure NAIF ID of the orientation data. Required input. REFERENCE_FRAME_NAME reference frame name for orientation data. Required input. ANGULAR_RATE_PRESENT angular rates state flag, possible values: 'YES', 'NO', 'MAKE UP', or 'MAKE UP/NO AVERAGING' 'MAKE UP' and 'MAKE UP/NO AVERAGING' have meaning only when the output CK file is type 2 or 3. Both tags produce the same effect for type 2 CKs, in which manufactured rates will be consistent with orientation but not continuous in time. 'MAKE UP' creates angular rates for type 3 CKs by using three consecutive quaternions, calculating the angular rate between the first and second, then the second and third, then averaging the both angular rates, assigning this average as the angular rate for the second (middle) quaternion x--------------x-----------x Q1 Q2 Q3 angular_rate = angular rate from Q1 to Q2 12 angular_rate = angular rate from Q2 to Q3 23 so angular_rate = (1/2)( angular_rate Q2 12 + angular_rate ) 23 'MAKE UP/NO AVERAGING' creates angular rates for type 3 CKs by assigning the angular rate derived from the second and third quaternions to the second quaternion; angular rates made up for type 3 CK are continuous but not consistent with orientation change x--------------x-----------x Q1 Q2 Q3 angular_rate = angular rate from Q2 to Q3 23 so angular_rate = angular_rate Q2 23 Do not expect angular rates created with the 'MAKE UP' flag to accurately represent reality. QUATERNION_NORM_ERROR DP number specifying maximum normalization error for input quaternions, optional, but if not present, no filtering occurs. ANGULAR_RATE_FRAME specifies whether angular rates are given in the 'REFERENCE' frame or 'INSTRUMENT' frame, optional, bit if not present, assumed as 'REFERENCE'. ANGULAR_RATE_THRESHOLD three DP number specifying threshold for maximum X, Y and Z angular rates in radians per seconds, optional, but if not present, no filtering occurs. MAXIMUM_VALID_INTERVAL maximum interval between two adjacent input pint for which interpolation still allowed in seconds, optional, but if not present, interpolation allowed in the whole coverage interval TIME_CORRECTION signed number of seconds representing fixed correction to be added to each input time tag, optional, no correction applied if not provided INPUT_DATA_TYPE type of input data; can be one of 'MSOP QUATERNIONS', 'SPICE QUATERNIONS', 'EULER ANGLES' or 'MATRICES'. A required input. INPUT_TIME_TYPE the string description of input time tags type, possible values: 'SCLK', 'UTC', or 'TICKS'. * 'UTC' type indicates any time string convertible by the SPICE time subsystem, not strictly UTC. 'Consider 'UTC' a first option when dealing with vehicle attitude data. Refer to time.req for extended descriptions of SPICE time formats. * 'SCLK' type indicates an SCLK time string for the vehicle of interest. SCLK time strings are used with instrument pointing data. Note: use of SCLK strings requires the user to load the proper SCLK kernel. * 'TICKS' type indicates encoded double precision ticks for the instrument of interest. Tick values are also used with instrument pointing data. * 'DSCLK' type indicates an SCLK time represented by a floating point number rather than a traditional SCLK string consisting of cascading counters. The program allows such tags to be provided only for type 1 SCLKs with two fields (for example seconds and fractional seconds.) For such clock the floating point number is treated as giving the integer part and decimal fraction of the left clock field. Within the program it is converted into encoded double precision ticks with non-zero fractional part to preserve the full precision provided in the input tag. EULER_ROTATIONS_ORDER a 3-vector defining the order of rotations for Euler angles input (the first rotation is about the first listed axis, the second by the second, the third by the third); this keyword must be defined when INPUT_DATA_TYPE has value 'EULER ANGLES' and must consist of three elements, e.g. ( 'X' 'Y' 'Z' ) or ( 1, 2, 3 ) EULER_ROTATIONS_TYPE defines the rotation type for Euler rotation: 'BODY' or 'SPACE', function defaults to 'SPACE' Given a real rotation vector theta = (theta1, theta2, theta3), a BODY rotation mathematically relates to a SPACE rotation via: T M = M (-theta1,-theta2,-theta3) BODY SPACE with M a composition of real 3x3 Euler rotation matrices (Mi): M(theta1,theta2,theta3) = M1(theta1) M2(theta2) M3(theta3) As the Euler rotation matrices posses the property: T Mi(-angle) = Mi(angle) and matrices have the property: T T T T (M1 M2 M3) = M3 M2 M1 so T M (-theta1,-theta2,-theta3) = SPACE T (M1(-theta1) M2(-theta2) M3(-theta3)) = T T T M3(-theta3) M2(-theta2) M1(-theta1) = M3(theta3) M2(theta2) M1(theta1) = M(theta3, theta2, theta1) then a BODY rotation equates to a SPACE rotation with the reversal of the EULER_ROTATIONS_ORDER list, e.g. EULER_ROTATIONS_ORDER = ( 'X', 'Y', 'Z') EULER_ROTATIONS_TYPE = 'BODY' equates to EULER_ROTATIONS_ORDER = ( 'Z', 'Y', 'X') EULER_ROTATIONS_TYPE = 'SPACE' EULER_ANGLE_UNITS specifies units for input Euler angles: 'DEGREES' or 'RADIANS'; must be present if parameter setting INPUT_DATA_TYPE = 'EULER ANGLES'. OFFSET_ROTATION_ANGLES a 3-vector of Euler angles specifying fixed rotation from CK reference frame to the reference frame relative to which input orientation is given; optional, if present, companion keywords must be present also; must consist of three elements, e.g ( 0.5, 0.2, 0.1 ) OFFSET_ROTATION_AXES Euler angles specifying fixed rotation from CK reference frame to the reference frame relative to which input orientation is given, optional, but if present,companion keywords must also exist with three elements, e.g. ( 0.5, 0.2, 0.1 ) OFFSET_ROTATION_UNITS units for OFFSET_ROTATION_ANGLES angles: 'DEGREES' or 'RADIANS', optional, but if present, companion keywords must also exist DOWN_SAMPLE_TOLERANCE angle, in radians, representing maximum rotation difference between orientation provided by the data points eliminated from input data stream and orientation computed by interpolating using CK type 3 algorithm between data points written to the output CK file; if this keyword is present, MSOPCK creates output type 3 CK that includes only a subset of the input data points, resulting in smaller output CK file ``matching'' the input attitude to specified tolerance; optional, no down sampling is performed if not provided; ignored if provided for output CK types other than type 3 INCLUDE_INTERVAL_TABLE optional flag indicating whether the interpolation interval table should be included into the comment area of the output CK and program's screen output. This keyword can be set to either 'YES' or 'NO'. Omitting this keyword has the same effect as setting it to 'YES'. PRODUCER_ID name of a group or person who created the file Input File -------------------------------------------------------- The data input file must be an ASCII text file listing a space delimited table with information sets as described by the INPUT_DATA_TYPE specification: Example: INPUT_DATA_TYPE = 'MSOP QUATERNIONS' Corresponding data table: TIME1 [TIME2] -QSIN1 -QSIN2 -QSIN3 QCOS [ARX ARY ARZ] ..... ....... ..... ..... ..... .... ... ... ... TIME1 [TIME2] -QSIN1 -QSIN2 -QSIN3 QCOS [ARX ARY ARZ] Example: INPUT_DATA_TYPE = 'SPICE QUATERNIONS' Corresponding data table TIME1 [TIME2] QCOS QSIN1 QSIN2 QSIN3 [ARX ARY ARZ] ..... ....... .... ..... ..... ..... ... ... ... TIME1 [TIME2] QCOS QSIN1 QSIN2 QSIN3 [ARX ARY ARZ] Example: INPUT_DATA_TYPE = 'EULER ANGLES' Corresponding data table TIME1 [TIME2] ANG1 ANG2 ANG3 [ARX ARY ARZ] ..... ...... .... .... .... ... ... ... TIME1 [TIME2] ANG2 ANG2 ANG3 [ARX ARY ARZ] Example: INPUT_DATA_TYPE = 'MATRICES' Corresponding data table TIME1 [TIME2] M11 M12 M13 M21 ... M33 [ARX ARY ARZ] ..... ...... ... ... ... ... ... ... ... ... ... TIME1 [TIME2] M11 M12 M13 M21 ... M33 [ARX ARY ARZ] Input for Type 2 CKs requires 2 time tags -- the beginning (TIME1) and end (TIME2) of the interval. An exception exists when the ANGULAR_RATE_PRESENT flag has value 'MAKE UP'; then only one time column (TIME1) must be present on the input because stop time for each record will be assigned with the value of start time of the next record. Since parsing is word based, all time tags must be single words. Output File -------------------------------------------------------- The application outputs a CK segment of the requested type (1, 2 or 3) either written to a new CK or appended to an existing CK file. Note, the program cannot append data to non platform native CK files. Such a CK must be converted to a native binary file. Refer to the CONVERT User's Guide for details. The Line Terminator Issue -------------------------------------------------------- The nature of MSOPCK's FORTRAN (or f2c'd C) file read function requires each line in the data file to end with a line terminator. Several users experienced the situation where the application failed to read the final record from their data file because that line lacked a line terminator. Note: the terminators in the data file must be appropriate for the operating system.