| MSOPCK User's Guide |
Table of ContentsMSOPCK User's Guide Abstract Summary References Document Overview Usage Setup File Format Setup File Contents Keywords Specifying Additional Kernels Keywords Specifying the Input Data Keywords Providing CK Identification Parameters Keywords Providing Descriptive Information Keywords Modifying and Augmenting Input Data Is a Keyword Required, Optional, or Conditional? Additional Kernels LSK and SCLK Files FK file Input Data Format Input Times UTC Time Tags SCLK Time Tags ET Time Tags Input Attitude Input as Quaternions Input as Euler Angles Input as Matrices Input Angular Velocity Tips for Preparing Input Output CK Types Output CK Identification Parameters CK ID Reference Frame Angular Velocity Flag ICRF vs J2000 Output CK Metadata Output CK Comment Area Contents Applying Time Bias to Input Times Augmenting Input Attitude by Additional Rotation Adding Made-Up Angular Velocity Data to Output CK Controlling Coverage Provided by Output CK Reducing Size of Output CK (Downsampling) Examples Example 1: Typical Spacecraft CK, Input Includes Angular Velocities Example 2: Typical Spacecraft CK, Input Does Not Include Angular Velocities Example 3: Typical CK for Rotating Instrument Example 4: Typical CK for Constant Orientation Example 5: Typical Discrete CK MSOPCK User's Guide
Abstract
Summary
The MSOPCK program accepts one ASCII text file containing descriptions of input data (setup file) and a second ASCII text file (input file) containing the source attitude data to be processed. Source attitude data can be time ordered lists of quaternions, Euler angles, or matrices tagged with UTC, spacecraft on-board clock (SCLK), or Ephemeris Time (ET) times. All input data must provide attitude for a structure relative to a reference frame, both of which are specified in the setup file. The program buffers the input data by chunks of 100,000 records and writes each chunk into a separate CK segment. It uses the same point as the end of the previous and the start of the next chunk to provide continuity at the segment boundary. The program allows the user to optionally provide some descriptive text (metadata) in a separate file (comment file) to be placed into the ``comment area'' of the CK attitude file. Doing this is highly recommended. For archival documentation purposes the content of the MSOPCK setup file is automatically placed into the ``comment area'' of the CK file. References
Document Overview
The sections ``Setup File Format'' and ``Setup File Contents'' provide a complete specification of the setup file format and a brief description for each of the setup parameters. The section ``Additional Kernels'' discusses additional kernels that are required by the program for every run and those that are needed in special circumstances. The sections ``Input Data Format'', ``Input Times'', ``Input Attitude'', ``Input Angular Velocity'', and ``Tips for Preparing Input'' provide detailed specifications of the input file format and types of time tags, attitude and angular velocity data acceptable as input to the program. They also give some tips on how to prepare the input. The sections ``Output CK Types'', ``Output CK Identification Parameters'', ``Output CK Metadata'', and ``Output CK Comment Area Contents'' explain what CK types that the program can generate, the CK identification parameters that must be provided via the setup file, and the meta-information to be supplied by the user and generated by the program. The sections ``Applying Time Bias to Input Times'', ``Augmenting Input Attitude by Additional Rotation'', ``Adding Made-Up Angular Velocity Data to Output CK'', ``Controlling Coverage Provided by Output CK'', and ``Reducing Size of Output CK (Downsampling)'' cover in detail miscellaneous program capabilities. The final section of the document, ``Examples'', provides a few examples of program use. Usage
> msopck <setup_file> <input_data_file> <output_ck_file>
[-u|-usage]
[-h|-help]
[-t|-template]
All three file names -- the setup file name, the input data file name
and the output CK file name -- must be provided on the command line in
order to run the program to generate the output CK. The setup and input
data files must exist; the CK file may be a new file or may already
exist, in which case the new CK segments will be appended to it. Note
that the program cannot append data to an existing CK file if its format
is not native to the platform on which the program is running.
If the ``-u'' or ``-usage'' flag or no flags at all are specified on the command line, or if the command line has too few or too many arguments, the program will display a brief usage message. If the ``-h'' or ``-help'' flag is specified on the command line, the program will display a brief help message. If the ``-t'' or ``-template'' flag is specified on the command line, the program will display the complete setup file template. If the program successfully creates the output CK file it prints to the screen the complete comments that it wrote into the comment area of the file. The section ``Output CK Comment Area Contents'' below provides detailed information about what is written into the output CK's comment area. Setup File Format
KEYWORD = VALUE
Each assignment is restricted to a single line up to 132 characters
long. Any lines longer than 132 characters are truncated when the file
is read in. Sets of these assignments must be enclosed between
\begindata
\begintext
tokens, each of which must also be placed on a line by itself. Free-form
descriptive/explanatory text may occur after the
\begintext
token. Still more assignments could follow another
\begindata
token.
The names of the setup file keywords must be strictly uppercase while the values of keywords may be upper, lower or mixed case. Any white space preceding or following keyword names, values and equal sign is ignored. All character string values must be enclosed in single quotes, provided on a single line, and be no longer than 80 characters (not including the quotes). Any values longer than 80 characters are truncated. When multiple values are allowed and used, the complete set of these values must be enclosed in the "()" characters: KEYWORD = ( 'value1' 'value2' 'value3' ... ). All assignments are either required, conditional or optional as described below. A setup file may contain blank lines. Non-printing characters including TAB should not be used in the setup file lines containing keyword assignments or in blank lines separating assignments within the data sections of the setup file. The program may not be able to parse correctly any of the setup file lines that contain non-printing characters; on some computer platforms it will signal a setup file parsing error . Setup File Contents
The program recognizes the following keywords:
LSK_FILE_NAME = 'LSK file name'
SCLK_FILE_NAME = 'SCLK file name'
MAKE_FAKE_SCLK = 'name of fake SCLK file to be made'
FRAMES_FILE_NAME = 'FK file name'
INTERNAL_FILE_NAME = '60-char string describing attitude'
COMMENTS_FILE_NAME = 'name of file containing comments'
CK_TYPE = 1, 2, or 3
CK_SEGMENT_ID = '40-char string describing attitude'
INSTRUMENT_ID = CK ID
REFERENCE_FRAME_NAME = 'CK reference frame name'
ANGULAR_RATE_PRESENT = 'YES', 'NO', 'MAKE UP', or
'MAKE UP/NO AVERAGING'
QUATERNION_NORM_ERROR = maximum normalization error
ANGULAR_RATE_THRESHOLD = ( AVx_max, AVy_max, AVz_max )
MAXIMUM_VALID_INTERVAL = interval length, seconds
TIME_CORRECTION = time bias, seconds
INPUT_TIME_TYPE = 'SCLK', 'UTC', 'TICKS', 'DSCLK', or 'ET'
INPUT_DATA_TYPE = 'MSOP QUATERNIONS', 'SPICE QUATERNIONS',
'EULER ANGLES', or 'MATRICES'
EULER_ANGLE_UNITS = 'DEGREES' or 'RADIANS'
EULER_ROTATIONS_ORDER = ( 'X', 'Y', 'Z' ) or ( 1, 2, 3 )
EULER_ROTATIONS_TYPE = 'SPACE' or 'BODY'
ANGULAR_RATE_FRAME = 'REFERENCE' or 'INSTRUMENT'
OFFSET_ROTATION_ANGLES = ( angle1, angle2, angle3 )
OFFSET_ROTATION_AXES = ( 'X', 'Y', 'Z' ) or ( 1, 2, 3 )
OFFSET_ROTATION_UNITS = 'DEGREES' or 'RADIANS'
DOWN_SAMPLE_TOLERANCE = angle, in radian
INCLUDE_INTERVAL_TABLE = 'YES' or 'NO'
CHECK_TIME_ORDER = 'YES' or 'NO'
PRODUCER_ID = 'string identifying producer'
each of which falls into one or more of the following categories
depending on its purpose:
Keywords Specifying Additional Kernels
Keywords Specifying the Input Data
Keywords Providing CK Identification Parameters
Keywords Providing Descriptive Information
Keywords Modifying and Augmenting Input Data
Is a Keyword Required, Optional, or Conditional?
LSK_FILE_NAME required CK_TYPE required INSTRUMENT_ID required REFERENCE_FRAME_NAME required ANGULAR_RATE_PRESENT required INPUT_TIME_TYPE required INPUT_DATA_TYPE required PRODUCER_ID required SCLK_FILE_NAME conditional MAKE_FAKE_SCLK conditional FRAMES_FILE_NAME conditional EULER_ANGLE_UNITS conditional EULER_ROTATIONS_ORDER conditional EULER_ROTATIONS_TYPE conditional ANGULAR_RATE_FRAME conditional INTERNAL_FILE_NAME optional COMMENTS_FILE_NAME optional CK_SEGMENT_ID optional QUATERNION_NORM_ERROR optional ANGULAR_RATE_THRESHOLD optional MAXIMUM_VALID_INTERVAL optional TIME_CORRECTION optional OFFSET_ROTATION_ANGLES optional OFFSET_ROTATION_AXES optional OFFSET_ROTATION_UNITS optional DOWN_SAMPLE_TOLERANCE optional INCLUDE_INTERVAL_TABLE optional CHECK_TIME_ORDER optional Additional Kernels
LSK and SCLK Files
The NAIF ID of the clock for which the SCLK file should provide time conversion is not specified in the setup file. Instead it is determined from the CK ID provided by the INSTRUMENT_ID keyword using SPICE's CKMETA routine. If no FK file was provided to the program, then the clock ID returned by CKMETA is simply the CK ID divided by 1000. If an FK file defining the frame associated with the CK ID was provided to the program, CKMETA returns the clock ID set by the CK_*_SCLK keyword included in the frame definition. In most cases this clock ID will also be equal to the CK ID divided by 1000 but there might be exceptions. The user is encouraged to determine which SCLK file should be used with the CK file he/she is trying to make prior to running the program, and to provide the name of that SCLK file in the setup file. If an SCLK file for the clock of interest cannot be provided, the program can generate a ``fake'' SCLK kernel that will be used to create the output CK and should subsequently be used to access the data in it. To generate a fake SCLK file the MAKE_FAKE_SCLK keyword specifying the name of the fake SCLK file should be provided instead of the SCLK_FILE_NAME keyword. Providing both SCLK keywords, MAKE_FAKE_SCLK and SCLK_FILE_NAME, is not allowed and will terminate the program with an error message. All fake SCLK files created by the program provide the same correlation function. They implement a two field (seconds and milliseconds) clock with granularity of one millisecond running at the same rate as ET, starting at ET 2000-JAN-01-12:00:00.000 and going for 100 years. Due to its start date, a fake clock of this kind cannot be used for processing of any input data sets that pre-date 2000-JAN-01-12:00:00.000 ET. It is strongly recommended to avoid generating and distributing a fake SCLK file and, instead, make all possible efforts to obtain an official SCLK file for the mission of interest. The user is also reminded to make sure that he/she should use the most up-to-date LSK and SCLK kernels to avoid erroneous time conversions in the process of creating the output CK file. FK file
Input Data Format
The lines in the input file must be ordered by time; lines with identical time tags are not allowed. The program can be directed to check for time order and no duplicates conditions and stop if these conditions are not met by setting the CHECK_TIME_ORDER keyword to 'YES'. If this keyword is not present or set to 'NO' the program does not check time order and duplicates as it reads the input file and sorts each buffered chunk of 100,000 records before writing it to the output CK file as separate segment. The duplicate times are still detected and cause the program to stop with an error when the low level CK writers routines called by the program attempt to write segments to the file. If the input file contains Type 2 data with two time tags (begin time and end time), the end time must be equal to or greater than the begin time of that record and it must be less than or equal to the begin time of the next record. The items provided on each input line must be separated by one or more spaces; no other delimiters -- commas, tabs, etc. -- are supported by the program. The time tag must not contain any spaces and must be in one of the forms discussed later in this document. The components of the attitude and angular velocity must be numbers in scientific or engineering notation. The file cannot contain blank lines or comment lines of any kind. All lines in the file, including the last line must be terminated with the line terminators native to the computer platform on which the program is run. Input Times
The subsections below provide details and examples for each of the time types supported by the program. UTC Time Tags
2005-01-05T12:00:03.129 2005-005T12:00:03.129to a wide variety of common formats, in which blanks are replaced with dashes (``-''):
01/05/2005-12:00:03.129 2005-January-5-12:00:03.129 05-JAN-2005-12:00:03.129 2005-005//12:00:03.129The time tags in Julian Date format can also be provided under this type as long as they have the substring ``JD'' (case insensitive) preceding or following without any separators the time provided as a number in engineering notation:
2453376.0000362jd JD2453376.0000362While the value assigned to the INPUT_TIME_TYPE keyword for this type is 'UTC', the input time strings are not limited to the UTC time system. Since these tags are passed directly to the STR2ET routine, any of the time system and zone labels supported by the routine can be supplied as part of the tag. Just as the ``JD'' label, these labels should precede or follow the time without any separators. For example, a calendar ET tag can be provided as:
2005-01-05-12:01:07.313TDBa Julian date ET time can be provided as:
JD2453376.0000362TDBand a Pacific Day Time zone (PDT) time tag can be provided as:
2005-01-05-04:00:03.129PDTThe STR2ET source code header provides the complete specification of the input time formats supported by this routine. SCLK Time Tags
1483619164.085 1/0789393653.024 789393801:200In all of these examples, each of which is an SCLK tag for an actual mission -- CASSINI, MGS and M01, -- the left field is the count of on-board seconds and the right field is the count of 1/256 of a second ticks (rather than a decimal fraction). The second type of input SCLK times supported by the program are decimal SCLK times. Unlike traditional string SCLK times consisting of cascading counters the decimal SCLK times are floating point numbers, either in scientific or engineering notation. The program allows such tags to be provided only for Type 1 clocks with two fields (for example seconds and fractional seconds). For such clocks the floating point number is treated as the integer part and decimal fraction of the left clock field. Within the program it is converted into the encoded double precision ticks with non-zero fractional part to preserve the full precision provided in the input tag. For example, the decimal SCLK times corresponding to the string SCLK tags give above are:
1483619164.321 789393653.0901566 7.89393801755e+08The third type of input SCLK times supported by the program are encoded SCLKs, also known as SCLK ticks. The encoded SCLK time is the fundamental representation of SCLK in the SPICE system used for many purposes including mapping on-board clock time to the other time systems and tagging attitude data within CK files. The input encoded SCLK times must be provided as floating point numbers, in scientific or engineering notation. For example, the encoded SCLK times corresponding to the string SCLK tags give above are:
202085157205 65973440792.000 2.02084814522e11Complete information about the SCLK formats is provided in the SCLK.REQ document. ET Time Tags
158198467.313 1.58198467313e+8 Input Attitude
Vinst = Mref->inst * VrefThe input attitude can be provided as quaternions, Euler angles or matrices, with the INPUT_DATA_TYPE keyword set in the setup file to the proper value identifying the input attitude type. Input as Quaternions
The Alternate-Style quaternions are used predominantly in spacecraft articulation control system (ACS) software, both on-board the spacecraft and on the ground. Therefore the simulated quaternions produced by various spacecraft dynamics analysis utilities and the actual attitude quaternions sent back to Earth in telemetry are most likely to be of this type. The Alternate-Style quaternions have the scalar component last and the signs of the vector components inverted as compared to the equivalent SPICE-Style quaternions. While the SPICE-Style quaternions provided on the input are stored in the output CK ``as is'', the Alternate-Style quaternions are converted into the SPICE-Style quaternion before being written into the output CK file. The conversion involves rearranging the quaternion components to move the scalar component to the front and changing the sign of each of the vector components. I.e. if the Alternate-Style quaternion is:
Qalt = ( QV1, QV2, QV3, QS )then the SPICE-Style quaternion written to the output CK file is:
Qspice = ( QS, -QV1, -QV2, -QV3 )Whether the input quaternions are of the SPICE-Style or of the Alternate-Style, each quaternion must be provided as four floating point numbers in engineering or scientific notation. The quaternion components must separated by one or more blanks and must immediately follow the time tag(s). An input file containing quaternions and one time tag would look like this (optional angular velocity components are shown in [] following the quaternion components):
T(1) Q1(1) Q2(1) Q3(1) Q4(1) [AVX(1) AVY(1) AVZ(1)] T(2) Q1(2) Q2(2) Q3(2) Q4(2) [AVX(2) AVY(2) AVZ(2)] ... ... ... ... ... [... ... ... ] T(n) Q1(n) Q2(n) Q3(n) Q4(n) [AVX(n) AVY(n) AVZ(n)]An input file containing quaternions and two time tags -- begin and end times for each interval to be stored in the output type 2 CK file -- would look like this (if two time tags are provided, the angular velocities are required):
TB(1) TE(1) Q1(1) Q2(1) Q3(1) Q4(1) AVX(1) AVY(1) AVZ(1) TB(2) TE(2) Q1(2) Q2(2) Q3(2) Q4(2) AVX(2) AVY(2) AVZ(2) ... ... ... ... ... ... ... ... ... TB(n) TE(n) Q1(n) Q2(n) Q3(n) Q4(n) AVX(n) AVY(n) AVZ(n)If the input data are provided as quaternions in either of the two allowed forms the QUATERNION_NORM_ERROR keyword may be used to specify the maximum allowed quaternion normalization error used to filter out the input points with bad quaternions. If this keyword is provided, the norm of each input quaternion is computed and compared with 1. If the magnitude of the difference between the norm and 1 is smaller than or equal to the specified error, the input record is included in the output CK file. If the magnitude of the difference is greater than the specified error, the input record is not included in the CK data and instead is tagged as ``bad'' and recorded in the CK comment area. If this keyword is not provided, no filtering is performed. Input as Euler Angles
If the input data is provided as Euler angles, each input record must contain three angles given as floating point numbers in engineering or scientific notation. The angles must separated by one or more blanks and must immediately follow the time tag(s). An input file containing Euler Angles and one time tag would look like this (optional angular velocity components are shown in [] following the angles):
T(1) ANG1(1) ANG2(1) ANG3(1) [AVX(1) AVY(1) AVZ(1)] T(2) ANG1(2) ANG2(2) ANG3(2) [AVX(2) AVY(2) AVZ(2)] ... ... ... ... [... ... ... ] T(n) ANG1(n) ANG2(n) ANG3(n) [AVX(n) AVY(n) AVZ(n)]An input file containing Euler angles and two time tags -- begin and end times for each interval to be stored in the output type 2 CK file -- would look like this (if two time tags are provided, the angular velocities are required):
TB(1) TE(1) ANG1(1) ANG2(1) ANG3(1) AVX(1) AVY(1) AVZ(1) TB(2) TE(2) ANG1(2) ANG2(2) ANG3(2) AVX(2) AVY(2) AVZ(2) ... ... ... ... ... ... ... ... ... TB(n) TE(n) ANG1(n) ANG2(n) ANG3(n) AVX(n) AVY(n) AVZ(n)The input Euler angles can be provided either in degrees or in radians. If the input Euler angles are provided in degrees, the EULER_ANGLE_UNITS keyword must set to 'DEGREES'. If they are provided is radians, the EULER_ANGLE_UNITS keyword must set to 'RADIANS'. The EULER_ROTATIONS_ORDER keyword must be used to define the rotation axis corresponding to each of the input angles. The axes may be specified by letters -- 'X', 'Y', 'Z' -- or by indexes -- 1 (for X), 2 (for Y), 3 (for Z). Mixing of the letter and index specifications is not allowed; for example the value ( 'X', 3, 'Y' ) will be flagged as an error. Since the input records must each contain three angles, the value of this keyword must contain specifications for all three axes. The first axis specified in this keyword corresponds to the first angle specified on each input data line, the second axis corresponds to the second angle, and the third axis corresponds to the third angle. If the EULER_ROTATIONS_TYPE keyword is not specified or if it is set to 'SPACE' the program constructs the transformation matrix rotating vectors from the reference frame to the instrument frame as follows:
Mref->inst = R(angle1)axis1 * R(angle2)axis2 * R(angle3)axis3
If the EULER_ROTATIONS_TYPE keyword is set to 'BODY' the program
constructs this matrix as follows:
Mref->inst = R(angle3)axis3 * R(angle2)axis2 * R(angle1)axis1
where
Input as Matrices
If the input data is provided as matrices, each input record must contain nine matrix elements given as floating point numbers in engineering or scientific notation. These elements must separated by one or more blanks and must immediately follow the time tag(s). The matrix elements must be provided in the row-major order, i.e. if the matrix rotating vectors from the reference frame to the instrument frame is:
| M11 M12 M13 |
Mref->inst = | M21 M22 M23 |
| M31 M32 M33 |
it must be provided to the program as follows:
TIME M11 M12 M13 M21 M22 M23 M31 M32 M33An input file containing matrices and one time tag would look like this (optional angular velocity components are shown in [] following the matrix elements):
T(1) M11(1) M12(1) ... M33(1) [AVX(1) AVY(1) AVZ(1)] T(2) M11(2) M12(2) ... M33(2) [AVX(2) AVY(2) AVZ(2)] ... ... ... ... ... [... ... ... ] T(n) M11(n) M12(n) ... M33(n) [AVX(n) AVY(n) AVZ(n)]An input file containing matrices and two time tags -- begin and end times for each interval to be stored in the output type 2 CK file -- would look like this (if two time tags are provided, the angular velocities are required):
TB(1) TE(1) M11(1) M12(1) ... M33(1) AVX(1) AVY(1) AVZ(1) TB(2) TE(2) M11(2) M12(2) ... M33(2) AVX(2) AVY(2) AVZ(2) ... ... ... ... ... ... ... ... ... TB(n) TE(n) M11(n) M12(n) ... M33(n) AVX(n) AVY(n) AVZ(n) Input Angular Velocity
In such cases the angular velocity must be provided on each of the input lines and must consist of three elements -- AVx, AVy, AVz -- given as floating point numbers in engineering or scientific notation. These elements must be separated by one or more blanks and must immediately follow the attitude data. The angular velocity vectors provided in the input file must represent the angular velocity of rotation of the instrument frame with respect to the reference frame. The ANGULAR_RATE_FRAME keyword can be used to specify if these vectors are defined in the reference frame or in the instrument frame. If this keyword is not present or if it is set to 'REFERENCE', the angular velocity vectors are considered to be defined in the reference frame. If this keyword is set to 'INSTRUMENT', the angular velocity vectors are considered to be defined in the instrument frame. In all cases except one the angular velocities must be provided in radians per second. The only exception is when the input attitude data is provided as Euler angles in degrees (INPUT_DATA_TYPE='EULER ANGLES' and EULER_ANGLE_UNITS='DEGREES'). In this case the angular velocities must be provided in degrees per second. If no angular velocity data are provided in the input file, the ANGULAR_RATE_PRESENT keyword can be set to 'NO' to generate the output CK without angular velocities, or this keyword can be set to 'MAKE UP' or 'MAKE UP/NO AVERAGING' to have the program compute the angular velocities using the input attitude data and store these velocities in the output CK file. The section ``Adding Made-Up Angular Velocity Data to Output CK'' provides more details about how angular velocities are computed using the input attitude data. If the input data include angular velocities, the ANGULAR_RATE_THRESHOLD keyword may be used to specify the maximum allowed values for the angular velocity X, Y, and Z components used to filter out the input points with bad angular velocities. If this keyword is provided, the magnitude of each of the input angular velocity components is compared with the corresponding component of this keyword's value. If the magnitude is smaller than or equal to the specified threshold, the input record is included in the output CK file. If the magnitude is greater than the specified threshold, the input record is not included in the CK data and instead is tagged as ``bad'' and recorded in the CK comment area. If this keyword is not provided, no filtering of the angular velocities is performed. Tips for Preparing Input
Sample attitude data recno, mode, ang1, ang2, ang3, et 1, INERTIAL, 10, 20, -10, 2453377.0 2, INERTIAL, 10, 20, -10, 2453376.0 3, ROLL, 20, 40, -10, 2453376.5``As is'' this file is not acceptable for MSOPCK input for many reasons including the presence of non-data lines, use of commas as delimiters, extra fields (recno and mode), and required fields being out of order (the angles provided before the time.) All of these problems can be easily fixed using this simple chain of Unix utilities connected with pipes:
> cat unacceptable_file.txt | \
grep '^[0-9]' | \
sed 's/,/ /g' | \
awk '{print "JD"$6"TDB "$3" "$4" "$5}' | \
sort > acceptable_file.txt
In this chain of pipes ``grep'' extracts only the data lines, ``sed''
replaces commas with blanks, ``awk'' prints out in the right order only
the time tag and angles and adds to each time tag the JD and TDB labels
needed for STR2ET to process the times correctly, and finally ``sort''
puts all records in time increasing order. The output of this operation
looks like this:
JD2453376.0TDB 10 20 -10 JD2453376.5TDB 20 40 -10 JD2453377.0TDB 10 20 -10Should this file have contained data points with duplicate times, Unix's ``uniq'' utility could have been used as the last step to eliminate them. This pre-processing could have been easily done by hand using MS Excel or another spreadsheet application to eliminate unnecessary rows and columns, move around the columns of interest, sort the data, augment the times with necessary labels, and export the result into a space delimited text file. For repetitive processing of data sets like this a simple script written in Perl or Python could have accomplished the same job. Output CK Types
Type 1 CK files contain data points each providing the attitude and optionally angular velocity at a given time. Type 1 CK files do not provide interpolation between the attitude data points, returning attitude only at those request times matching exactly times of the pointing instances included in the file. Due to their discrete nature Type 1 CK files are in general not usable with the higher level SPICE interfaces accessing CK data using the frames subsystem with CK lookup tolerance set to zero. For this reason generating CK files of this type should be avoided. Instead, produce a Type 2 or Type 3 CK file in which each of the discrete points is represented by a small interval -- for example equal to the exposure duration of an image for which the pointing is provided. Type 2 CK files contain data records specifying attitude for joined or disjoint intervals of time, within each of which the attitude is computed by extrapolating the attitude provided at the interval begin time using the angular velocity included in the record. Type 2 CK files are best used to capture the orientation of a spinning spacecraft, for which the attitude points are more than one half of a full revolution apart and the angular velocity provided with each point is accurate enough to extrapolate to the next point without resulting in too a large discontinuity at the end time. Type 2 can also be used for CK files that provide fixed orientation over periods of time (angular velocity set to zero), both for collections of short intervals (as a substitute for discrete data) and for very long periods (placeholder attitude for articulating instruments providing the parked position at all times). Type 3 CK files contain data points each providing attitude and optionally angular velocity at a given time. Unlike Type 1 CK files, Type 3 CK files provide interpolation between data points using a linear approach -- rotation about fixed axis with a constant rate. The attitude points between which interpolation is allowed are identified by special bookkeeping information stored in each CK segment. The program generates this information based on the values of the MAXIMUM_VALID_INTERVAL keyword discussed in detail in the section ``Controlling Coverage Provided by Output CK'' below. Of the three CK types that can be generated by the program the Type 3 CK is the most usable and flexible and should be chosen as the output CK type in almost all cases. The CK.REQ document provides the complete specification for each of the CK types. Output CK Identification Parameters
CK ID
Frequently the CK IDs for the spacecraft bus and various articulating instruments and structures are pre-defined in the mission FK file. Each of these IDs is associated with a particular frame using the ``CLASS_ID'' keyword. For example if the ``SUPER_SC_BUS'' frame defined in the mission FK as a CK-based frame has its ``CLASS_ID'' set to -37000, then this ID should be used in the setup file INSTRUMENT_ID keyword to make the CK file for the SUPER spacecraft bus. When such a CK is loaded by SPICE along with the FK, the ``SUPER_SC_BUS'' frame can be used in high level SPICE interfaces to access the attitude data from the CK file. Note that unless an FK is specified in the setup file using the FRAMES_FILE_NAME keyword, and that FK defines the clock ID to be used for the CK ID (see section ``Additional Kernels'' above), the clock ID is derived from the CK ID by dividing the CK ID by 1000. Reference Frame
Angular Velocity Flag
If this keyword is set to 'NO', the output Type 1 or Type 3 CK will contain no angular velocities. For Type 2 CK files this setting will stop the program with an error. If this keyword is set to 'YES', the output CK will include the angular velocities that are provided in the input file. If the input does not contain angular velocities this setting will stop the program with an error. If this keyword is set to 'MAKE UP' or 'MAKE UP/NO AVERAGING', the output CK file will include the angular velocities that were computed using the input attitude data. The section ``Adding Made-Up Angular Velocity Data to Output CK'' discusses how the angular velocities are computed for each of these two settings. It is highly recommended to generate CK files containing angular velocity data -- either provided via the input file or computed from the attitude data -- because such CK files can be used to compute the 6x6 state transformation matrices returned or used internally by many high level SPICE routines such as SPKEZR and SXFORM. CK files without the angular velocities will make the high level interfaces dealing with states fail with the ``orientation-data-not-available'' error. ICRF vs J2000
The rotational offset between the J2000 frame and the ICRS has magnitude of under 0.1 arcseconds. Certain JPL data products are referenced to the ICRF or later versions of it. These include, but are not limited to,
Modern spacecraft ephemerides and attitude data, other than those for Earth orbiters, are likely referenced to the ICRF. Users should consult documentation or data providers to verify this for data sets of interest. SPK and binary PCK files produced by NAIF from the data sources listed above are referenced to the same version of the ICRF as the corresponding data sources. For historical and backward compatibility reasons, these data products are labeled as being referenced to the J2000 frame. No transformation is required to convert state vectors or orientation data from the J2000 frame to the ICRF (or later version), if the vectors or orientation data are computed using SPICE kernels created from the data sources listed above. For example:
SPICE users who export kernel data to non-SPICE file formats may need to transform the data, depending on the frame to which the SPICE data are actually referenced (as opposed to the frame to which the kernel indicates the data are referenced), and depending on the desired output frame. Output CK Metadata
The PRODUCER_ID keyword must be used to identify the producer of the CK file. The value for this required keyword can be a string up to 80 characters in length, ideally providing the producer name, affiliation, e-mail and/or phone number. For example:
'John Smith, ACS Team, SUPER Project, John.Smith@nasa.gov'The INTERNAL_FILE_NAME keyword may be used to specify a short descriptive string (up to 60 characters) that is placed in the internal file name field of the output CK file record (see DAF.REQ). An example of an internal file name is:
'SUPER SOLAR ARRAY CK; RECONSTRUCTED; PRODUCED BY ACS'Since the internal file name is usually assigned to the file at the time it is opened for write access for the first time, this keyword is ignored if the program is run to append segments to the existing CK file. The CK_SEGMENT_ID keyword may be used to specify a short descriptive string (up to 40-characters) that is placed in the segment identifier in each of the output CK file segments (see CK.REQ). An example of the segment identifier is:
'SUPER SA+X INNER GIMBAL TLM-BASED DATA'The INTERNAL_FILE_NAME and CK_SEGMENT_ID keywords are optional. If either is not specified, the first 60 characters (for INTERNAL_FILE_NAME) or 40 characters (for CK_SEGMENT_ID) of the input data file name are used as the value. Output CK Comment Area Contents
The optional COMMENTS_FILE_NAME keyword may be used to specify the name of a text file containing comments that should be included at the top of the comment area of the new output CK file. Ideally these comments should provide an extensive description of the data stored in the CK file covering the pedigree and accuracy of the data, explaining any specific details regarding the data usage, identifying other kernels that should be used together with the CK file, and so on. The contents of the comment file specified using this keyword are added to the comments only if a new CK is being created; if the program is run to add segments to an existing CK file this keyword is ignored. Since the comment area cannot contain any non-printing ASCII characters, such characters present in the comments file are replaced with blanks before the comment file lines are written into the comment area. While the contents of the external comment file specified using the COMMENTS_FILE_NAME keyword are included only if the keyword was provided and a new CK is being made, the complete contents of the setup file are always placed in the comment area. Doing so provides a record of the setup parameters used by the program as well as gives another way to place the descriptive information into the comment area by providing it in the text section of the setup file preceding the keyword assignments. For example, the setup file below has a large block of descriptive text preceding the keywords. This text will be available for future users of the file because it will be recorded in the comment area:
Orientation Data for ...
---------------------------
This CK file was produced by ... on ...
Data Summary
---------------------------
This CK file provides attitude ... relative to ...
Pedigree
---------------------------
The data stored in this CK was generated using ...
Additional Kernels
---------------------------
This CK file must be used with the SCLK ... and the FK ...
Contact Information
---------------------------
...
MSOPCK Setup Parameters
---------------------------
\begindata
CK_TYPE = ...
...
\begintext
As with the comments file, any non-printing ASCII characters contained
in the setup file are replaced with blanks before the setup file lines
are written into the comment area.
Following the contents of the setup file, the program adds to the comment area a block of lines called ``Run Time Meta Information''. This block includes three time tags -- the time when the program was run (taken off the CPU clock at the start of the run), the time of the first data point written to the CK file and the time of the last data point written to the CK file. This block looks like this:
********************************************************* ********************************************************* PRODUCT_CREATION_TIME = YYYY-MM-DDTHR:MN:SC START_TIME = YYYY-MM-DDTHR:MN:SC.NNN STOP_TIME = YYYY-MM-DDTHR:MN:SC.NNNThe ``Run Time Meta Information'' block is usually followed by one or more tables summarizing the interpolation intervals for each of the segments added to the file. These tables have the following format:
SEG.SUMMARY: ID [ckid], COVERG: [begin] [end]
---------------------------------------------------------
[interval_1_begin] [interval_1_end]
[interval_2_begin] [interval_2_end]
... ...
[interval_N_begin] [interval_N_end]
where [ckid] is the CK ID, [begin] and [end] are the segment coverage
begin and end times, and [interval_N_begin] and [interval_N_end] are the
individual interpolation intervals' begin and end times, with all times
given as UTC in YYYY-MM-DDTHR:MN:SC.NNN format.
The interpolation interval tables are included by default for each of the Type 2 and Type 3 CK segments but not for the Type 1 CK segments as interpolation is not applicable for Type 1 CK files. If including the tables is not desirable -- which might be the case for inputs that result in CK files with a very large number of very short interpolation intervals -- the INCLUDE_INTERVAL_TABLE keyword may be set to 'NO' to suppress the inclusion of the table(s). Applying Time Bias to Input Times
TIME_CORRECTION = -2.3 Augmenting Input Attitude by Additional Rotation
The rotation provided by these keywords is combined with the rotation represented by the input attitude as follows:
Vinst = Minp->inst * Mref->inp * Vrefwhere
Mref->inst = R(angle1)axis1 * R(angle2)axis2 * R(angle3)axis3
where
For example, imagine a spacecraft with a solar array that can rotate about the spacecraft's +Y axis. In the zero position the reference frame of the array is not co-aligned with the spacecraft frame; instead it is rotated from it by +90 degrees about +Y. If the solar array orientation data are given as rotation angles relative to the zero position, the following OFFSET_ROTATION_* keywords may be used to adjust the attitude to be with respect to the spacecraft frame prior to storing it in the CK file:
OFFSET_ROTATION_ANGLES = ( 0.0, 0.0, 90.0 ) OFFSET_ROTATION_AXES = ( 'Z', 'X', 'Y' ) OFFSET_ROTATION_UNITS = 'DEGREES' Adding Made-Up Angular Velocity Data to Output CK
If this keyword is set to 'MAKE UP/NO AVERAGING' and the output CK type is 3, or if it is set to either 'MAKE UP' or 'MAKE UP/NO AVERAGING' and the output CK type is 2, the program computes the angular velocities using pairs of input attitude data points. For each pair it calculates a constant angular velocity of rotation from the attitude of the first point to the attitude of the second point and assigns this angular velocity to the first attitude point:
x--------------x
A1 A2
angular_velocity = angular velocity from A1 to A2
12
so
angular_velocity = angular_velocity
A1 12
If this keyword is set to 'MAKE UP' and the output CK type is set to 3
the program computes angular velocities using triplets of the
consecutive input data points. For each triplet it calculates constant
angular velocities of rotation from the attitude of the first point to
the attitude of the second point and from the attitude of the second
point to the attitude of the third point, then it computes the average
of the two angular velocities and assigns this average to the second
(middle) attitude point:
x--------------x-----------x
A1 A2 A3
angular_velocity = angular velocity from A1 to A2
12
angular_velocity = angular velocity from A2 to A3
23
so
angular_velocity = (1/2)( angular_velocity
A2 12
+ angular_velocity )
23
In both approaches the points at the ends of the interpolation intervals
determined using the MAXIMUM_VALID_INTERVAL keyword are treated
differently. The angular velocities computed for the interval start
points are the ones that rotate from the start point to the next point.
The angular velocities for the interval end points are the ones that
rotate from the previous point to the end point. The angular velocities
for the points that do not belong to any interval are set to zero.
The program does not compute angular velocities for Type 1 CK files. If the CK_TYPE is set to 1 and the ANGULAR_RATE_PRESENT keyword is set to either 'MAKE UP' or 'MAKE UP/NO AVERAGING', the program stops with an error. The 'MAKE UP/NO AVERAGING' option is the preferred option because the angular velocities computed from the attitude data using it are more consistent with the Type 3 interpolation approach. For the same reason they match the actual angular velocities more closely then the angular velocities generated using the 'MAKE UP' option. Controlling Coverage Provided by Output CK
The interval, specified in seconds, is compared with the time spacing of every pair of input points. If the spacing between the points is less than or equal to the specified interval, then the output CK file will allow interpolation between these points and will compute attitude at any request time between them. If the spacing is greater than the specified interval, then the CK file will not allow interpolation and will not return any attitude for the request times between the two points. For example, if the MAXIMUM_VALID_INTERVAL keyword is set to 8 seconds:
MAXIMUM_VALID_INTERVAL = 8and the input data looks like this:
2000-01-01T12:00:00.000 .... 2000-01-01T12:00:04.000 .... 2000-01-01T12:00:08.000 .... 2000-01-01T12:00:24.000 .... 2000-01-01T12:00:32.000 .... 2000-01-01T12:00:48.000 ....the output CK file will return the attitude data for request times between 12:00:00 and 12:00:08, between 12:00:24 and 12:00:32, and at 12:00:48 but it will not return any attitude for request times between 12:00:08 and 12:00:24 and between 12:00:32 and 12:00:48. The MAXIMUM_VALID_INTERVAL keyword is applicable only for Type 3 CK files, and for Type 2 CK files when the input data includes one time tag and no angular velocity data. This keyword is not applicable to Type 1 CK files of the Type 1 because they, by design, return discrete attitude data. It is also not applicable for Type 2 CK files when the input contains two time tags and angular velocities because the combination of the coverages provided by the pairs of times from the input records determines the coverage of the output CK file. In Type 3 CK files the interpolation interval information determined using the value of the MAXIMUM_VALID_INTERVAL keyword and the spacing between the input attitude data points is stored in the special bookkeeping area within the CK segments. This information can be modified using the CKSPANIT or CKSMRG SPICE utility programs at a later time. Unlike for Type 3, in Type 2 CK files the information about the interpolation intervals set using the value of the MAXIMUM_VALID_INTERVAL keyword is not stored as separate bookkeeping information. Instead it becomes a part of the data records because it is used to set the end time for each of the records stored in the output CK file (the start time is the time provided in the input). If the spacing between the points is less than or equal to the specified interval, the end time of the previous point is set to the start time of the next point, thus providing continuous coverage between the points. No utilities capable of modify this information in the Type 2 CK files are available from NAIF. The right value for the MAXIMUM_VALID_INTERVAL keyword should be chosen by taking into account the type of input attitude data (predicted vs. reconstructed), frequency of the input data points, knowledge of the spacecraft dynamics and limits, knowledge of the attitude profile during the period covered by the input data, and the attitude knowledge accuracy requirements. Due to so many different considerations it is hard to give a solid recommendation beyond suggesting one consider the aspects mentioned above and use common sense. For example, an interval of 60 seconds is probably appropriate for an orbiter with a 2-hour circular orbit, constantly tracking nadir -- the attitude of such spacecraft is essentially a uniform rotation about an axis normal to the orbital plane. But it is certainly not OK for a spinning spacecraft with a spin rate of 1 revolution per minute -- if the input data points for such a spacecraft will be 50 seconds apart the output Type 3 CK file would provide interpolation in the wrong direction, choosing the shorter way to get from one point to the next. For this kind of spinner, the interval must be less than one half the rotation period to ensure that the interpolation in done in the right direction. If the MAXIMUM_VALID_INTERVAL keyword is omitted the program generates an output CK that provides interpolation between all input data points. Reducing Size of Output CK (Downsampling)
For example, if the DOWN_SAMPLE_TOLERANCE keyword is set to one milliradian:
DOWN_SAMPLE_TOLERANCE = 0.001and the input data, providing the attitude as Euler angels for a structure rotating about the +X axis of the reference frame, first at the rate of 1 degree per second and then at the rate of 2 degrees per second, looks like this:
2000-01-01T12:00:00.000 0.0 0.0 0.0 1.0 0.0 0.0 2000-01-01T12:00:04.000 4.0 0.0 0.0 1.0 0.0 0.0 2000-01-01T12:00:08.000 8.0 0.0 0.0 1.0 0.0 0.0 2000-01-01T12:00:12.000 16.0 0.0 0.0 2.0 0.0 0.0 2000-01-01T12:00:16.000 24.0 0.0 0.0 2.0 0.0 0.0 2000-01-01T12:00:20.000 32.0 0.0 0.0 2.0 0.0 0.0the data stored in the output Type 3 CK file will include only these points:
2000-01-01T12:00:00.000 0.0 0.0 0.0 1.0 0.0 0.0 2000-01-01T12:00:08.000 8.0 0.0 0.0 1.0 0.0 0.0 2000-01-01T12:00:20.000 32.0 0.0 0.0 2.0 0.0 0.0In this example the second, fourth, and fifth points were excluded because CK Type 3 interpolation between points one and three and between points three and six produces results that match the input values to better than the specified tolerance. The reduction of the size of the output CK file (compared to the CK created without downsampling) depends greatly on the value of the downsampling tolerance, the noisiness of the input data and the attitude profile represented by the input data. If the level of noise in the input data is comparable to the specified tolerance value the reduction will be very small, a few percent at best. On the other hand if the tolerance value is one or two orders of magnitude larger than the noise and if the attitude represented by the input is changing very slowly, a rate of reduction of 10x or even 100x may be achieved. Note that since the points are eliminated after the interpolation intervals were determined based on the MAXIMUM_VALID_INTERVAL keyword, the data in the output CK file become unsuitable for subsequent modification of the interpolation interval bookkeeping information using the CKSPANIT or CKSMRG utilities. These utilities use the same maximum allowed interval approach as this program does but this approach will no longer work with the downsampled data because some of the original points needed to determine intervals are no longer part of the data set. Examples
Example 1: Typical Spacecraft CK, Input Includes Angular Velocities
The input file looks like this:
843868819.466029 -0.195 0.578 -0.163 -0.774 0.00006 -0.00095 -0.00002 843868820.466124 -0.196 0.578 -0.163 -0.774 0.00006 -0.00091 -0.00002 843868821.466147 -0.196 0.579 -0.163 -0.774 0.00007 -0.00093 -0.00002 843868822.466177 -0.196 0.579 -0.163 -0.773 0.00006 -0.00094 -0.00002 843868822.466177 -0.196 0.579 -0.163 -0.773 0.00006 -0.00094 -0.00002 ...Each line contains the on-board clock time with a decimal fractional part, the spacecraft orientation quaternions in the Alternate-style form, and the angular velocity of rotation given in the spacecraft reference frame. On the input example lines above the quaternion values were truncated to three decimal places and the angular velocities were truncated to five decimal places to fit into the width of the page; in the actual input all numbers are provided with eight decimal places. The setup file looks like this:
\begindata LSK_FILE_NAME = 'naif0008.tls' SCLK_FILE_NAME = 'MRO_SCLKSCET.00017.tsc' FRAMES_FILE_NAME = 'mro_v08.tf' COMMENTS_FILE_NAME = 'msopck.mro_sc.comments' INTERNAL_FILE_NAME = 'MRO TLM-Based SC Bus CK File by NAIF/JPL' CK_TYPE = 3 CK_SEGMENT_ID = 'MRO SC BUS TLM-BASED QUATS/AVS' INSTRUMENT_ID = -74000 REFERENCE_FRAME_NAME = 'MRO_MME_OF_DATE' ANGULAR_RATE_PRESENT = 'YES' MAXIMUM_VALID_INTERVAL = 60 INPUT_DATA_TYPE = 'MSOP QUATERNIONS' INPUT_TIME_TYPE = 'DSCLK' ANGULAR_RATE_FRAME = 'INSTRUMENT' QUATERNION_NORM_ERROR = 1.0E-3 PRODUCER_ID = 'Boris Semenov, NAIF/JPL' \begintextThe first three keywords -- LSK_FILE_NAME, SCLK_FILE_NAME, and FRAMES_FILE_NAME -- specify the additional kernels needed to perform the time conversions and to resolve the name of the reference frame, MRO_MME_OF_DATE, defined in the MRO mission Frames Kernel file. The COMMENTS_FILE_NAME keyword specifies the name of the text file containing comments to be included in the comment area of the output CK file. The INTERNAL_FILE_NAME and CK_SEGMENT_ID keywords provide the descriptive strings that will be placed in the CK file's internal file name and in the segment ID. The PRODUCER_ID keyword identifies the producer of the CK file. The CK_TYPE, ANGULAR_RATE_PRESENT, INSTRUMENT_ID, and REFERENCE_FRAME_NAME keywords state that the program should create a Type 3 CK file containing angular velocities included in the input, providing the attitude for the CK ID -74000 (MRO spacecraft bus ID associated with the MRO_SPACECRAFT frame) relative to the MRO_MME_OF_DATE reference frame. The INPUT_DATA_TYPE, INPUT_TIME_TYPE, and ANGULAR_RATE_FRAME keywords specify that the input data records contain the Alternate-style quaternions and the angular velocities given in the spacecraft frame, tagged with the SCLK times with the decimal fractional part. The QUATERNION_NORM_ERROR keyword indicates that any input quaternion with its norm different from 1 by more than 0.001 should be excluded. The MAXIMUM_VALID_INTERVAL keyword states that the output CK file should allow interpolation between any input data points that are no more than 60 seconds apart. Example 2: Typical Spacecraft CK, Input Does Not Include Angular Velocities
The input file looks like this:
0845510690.090 -0.37087941 -0.62105451 0.13371727 0.67739165 0845510696.090 -0.37248821 -0.62006920 0.13546434 0.67706435 0845510696.243 -0.37265360 -0.61996974 0.13564068 0.67702911 0845510702.090 -0.37409255 -0.61908378 0.13721136 0.67672969 0845510708.090 -0.37569219 -0.61809302 0.13895463 0.67639338 ...It contains the on-board clock times in the traditional SCLK format (with the fractional part given as a count of 1/256 of second ticks), and the spacecraft orientation quaternions in the Alternate-style form. The setup file looks like this:
\begindata LSK_FILE_NAME = 'naif0008.tls' SCLK_FILE_NAME = 'ORB1_SCLKSCET.00134.tsc' COMMENTS_FILE_NAME = 'msopck.m01.comments' INTERNAL_FILE_NAME = 'M01 SC Bus CK File by NAIF/JPL' CK_TYPE = 3 CK_SEGMENT_ID = 'M01 SC BUS TLM QUATS/MADEUP AVS ATT.' INSTRUMENT_ID = -53000 REFERENCE_FRAME_NAME = 'MARSIAU' ANGULAR_RATE_PRESENT = 'MAKE UP' INPUT_DATA_TYPE = 'MSOP QUATERNIONS' INPUT_TIME_TYPE = 'SCLK' MAXIMUM_VALID_INTERVAL = 60 QUATERNION_NORM_ERROR = 1.0E-3 PRODUCER_ID = 'NAIF/JPL' \begintextThe first two keywords -- LSK_FILE_NAME and SCLK_FILE_NAME -- specify the additional kernels needed to perform time conversions. In this case there is no need to specify an FK file because the reference frame of the data -- MARSIAU -- is built into the SPICE System. The COMMENTS_FILE_NAME keyword specifies the name of the text file containing comments to be included in the comment ares of the output CK file. The INTERNAL_FILE_NAME and CK_SEGMENT_ID keywords provide the descriptive strings that will be placed in the CK file's internal file name and in the segment ID. The PRODUCER_ID keyword identifies the producer of the CK file. The CK_TYPE, ANGULAR_RATE_PRESENT, INSTRUMENT_ID, and REFERENCE_FRAME_NAME keywords state that the program should create a Type 3 CK file containing made-up angular velocities computed using the input attitude, providing the attitude for the CK ID -53000 (M01 spacecraft bus ID associated with the M01_SPACECRAFT frame) relative to the MARSIAU reference frame. The INPUT_DATA_TYPE and INPUT_TIME_TYPE keywords specify that the input data records contain the Alternate-style quaternions tagged with the traditional SCLK times. The QUATERNION_NORM_ERROR keyword indicated that any input quaternion with its norm different from 1 by more than 0.001 should be excluded. The MAXIMUM_VALID_INTERVAL keyword states that the output CK file should allow interpolation between any input data points that are no more than 60 seconds apart. Example 3: Typical CK for Rotating Instrument
The input file looks like this:
1999-084T05:41:22 94.0 0 0 1999-183T12:17:37 94.0 0 0 1999-183T12:47:06 271.0 0 0 1999-183T13:07:37 271.0 0 0 1999-183T13:08:06 268.0 0 0 1999-232T15:06:09 268.0 0 0 ...It contains the UTC times in ISO DOY format, the position angle and two zeros provided to meet the requirement that exactly three rotation angle must be included on each input line. The setup file looks like this:
CASSINI CDA Orientation CK File
========================================================
[Approximately two page long descriptive text was chopped
from here to keep the size of the example small.]
MSOPCK Setup Parameters
========================================================
\begindata
LSK_FILE_NAME = 'naif0008.tls'
SCLK_FILE_NAME = 'cas00101.tsc'
FRAMES_FILE_NAME = 'cas_v39.tf'
INTERNAL_FILE_NAME = 'CASSINI CDA Orientation'
CK_TYPE = 3
CK_SEGMENT_ID = 'CASSINI CDA Orientation'
INSTRUMENT_ID = -82791
REFERENCE_FRAME_NAME = 'CASSINI_CDA_BASE'
ANGULAR_RATE_PRESENT = 'MAKE UP/NO AVERAGING'
INPUT_DATA_TYPE = 'EULER ANGLES'
INPUT_TIME_TYPE = 'UTC'
EULER_ROTATIONS_ORDER = ( 'Z' 'Y' 'X' )
EULER_ANGLE_UNITS = 'DEGREES'
PRODUCER_ID = 'Boris Semenov, NAIF/JPL'
\begintext
The first three keywords -- LSK_FILE_NAME, SCLK_FILE_NAME, and
FRAMES_FILE_NAME -- specify the additional kernels needed to perform
time conversions and to resolve the name of the reference frame,
CASSINI_CDA_BASE, defined in the CASSINI mission Frames Kernel file.
The COMMENTS_FILE_NAME keyword is not included because the descriptive comments are provided in the text section of the setup file. The INTERNAL_FILE_NAME and CK_SEGMENT_ID keywords provide the descriptive strings that will be placed in the CK file's internal file name and in the segment ID. The PRODUCER_ID keyword identifies the producer of the CK file. The CK_TYPE, ANGULAR_RATE_PRESENT, INSTRUMENT_ID, and REFERENCE_FRAME_NAME keywords state that the program should create a Type 3 CK file containing made-up angular velocities computed using the input attitude, providing the attitude for the CK ID -82791 (CASSINI CDA articulating structure ID associated with the CASSINI_CDA_ART frame) relative to the CASSINI_CDA_BASE reference frame. The INPUT_DATA_TYPE and INPUT_TIME_TYPE keywords specify that the input data records contain Euler angles tagged with UTC. The EULER_ROTATIONS_ORDER keyword specifies the rotation axes for each of the input angles. It sets the rotation by the CDA position angle -- the first angle in the input file -- to be about the Z axis to comply with the way the CDA reference frames are defined; the other two axes, assigned to Y and X, are insignificant because the angles corresponding to them are zero. The EULER_ANGLE_UNITS keyword specifies that the input angles are provided in degrees. The MAXIMUM_VALID_INTERVAL keyword is not provided, resulting in a CK file that performs interpolation between all input data points. Example 4: Typical CK for Constant Orientation
The input file looks like this:
2005-01-01T00:00:00 2010-01-01T00:00:00 0.0 0.0 0.0 0.0 0.0 0.0It contains the two UTC times, in ISO format, specifying the period for which the output CK file should return attitude, and six zeros, three for the zero-offset attitude expressed as Euler angles, and three for the zero angular velocity. The setup file looks like this:
PHX ``Local Level'' to ``Lander Mechanical'' Fixed Rotation CK
==============================================================
[Approximately two page long descriptive text was chopped
from here to keep the size of the example small.]
Appendix 1 -- MSOPCK Inputs
==============================================================
\begindata
LSK_FILE_NAME = 'naif0008.tls'
SCLK_FILE_NAME = 'PHX_SCLKSCET.00001.tsc'
FRAMES_FILE_NAME = 'phx_v00.tf'
INTERNAL_FILE_NAME = 'PHX NOMINAL LL -> LANDER CK'
CK_TYPE = 2
CK_SEGMENT_ID = 'PHX NOMINAL LL -> LANDER ORIENTATION'
INSTRUMENT_ID = -84001
REFERENCE_FRAME_NAME = 'PHX_LL'
ANGULAR_RATE_PRESENT = 'YES'
INPUT_TIME_TYPE = 'UTC'
INPUT_DATA_TYPE = 'EULER ANGLES'
EULER_ANGLE_UNITS = 'DEGREES'
EULER_ROTATIONS_ORDER = ( 'X' 'Y' 'Z' )
ANGULAR_RATE_FRAME = 'REFERENCE'
OFFSET_ROTATION_ANGLES = ( 0.0, 0.0, 180.0 )
OFFSET_ROTATION_AXES = ( 'Z' 'Y' 'Z' )
OFFSET_ROTATION_UNITS = 'DEGREES'
PRODUCER_ID = 'Boris Semenov, NAIF/JPL, x4-8136'
\begintext
The first three keywords -- LSK_FILE_NAME, SCLK_FILE_NAME, and
FRAMES_FILE_NAME -- specify the additional kernels needed to perform
time conversions and to resolve the name of the reference frame, PHX_LL,
defined in the PHOENIX mission Frames Kernel file.
The COMMENTS_FILE_NAME keyword is not included because the descriptive comments are provided in the text section of the setup file. The INTERNAL_FILE_NAME and CK_SEGMENT_ID keywords provide the descriptive strings that will be placed in the CK file's internal file name and in the segment ID. The PRODUCER_ID keyword identifies the producer of the CK file. The CK_TYPE, ANGULAR_RATE_PRESENT, INSTRUMENT_ID, and REFERENCE_FRAME_NAME keywords state that the program should create a Type 2 CK file containing the angular velocities included in the input, providing the attitude for the CK ID -84001 (PHOENIX Lander ID associated with the PHX_LANDER frame) relative to the PHX_LL reference frame. The combination of the CK_TYPE keyword is set to 2 and the ANGULAR_RATE_PRESENT keyword set to 'YES' requires that the input records contain two time tags, attitude, and the angular velocities. The INPUT_DATA_TYPE and INPUT_TIME_TYPE keywords specify that the input data records contain the Euler angles tagged with UTC. Although the conditional EULER_ANGLE_UNITS, EULER_ROTATIONS_ORDER, and ANGULAR_RATE_FRAME keywords are specified as required by the values assigned to the INPUT_DATA_TYPE and ANGULAR_RATE_PRESENT keywords, their values are insignificant because all input data items are set to zeros. Unlike the previous examples in which the attitude data was provided in the input file, in this example the actual attitude to be written to the CK file is given using the OFFSET_ROTATION_* keywords. These keywords specify that the instrument frame is rotated from the reference frame by 180 degrees about the +Z axis. This rotation, combined with the zero rotation from the input data, is written into the output CK file. The MAXIMUM_VALID_INTERVAL keyword is not provided because it is not applicable for cases when the CK_TYPE keyword is set to 2 and the input contains two time tags. Example 5: Typical Discrete CK
For example, if the data providing the C-smithed orientation as Euler angles at the UTC times corresponding the image mid-exposure points looked like this:
1999-183T12:17:37.500 127.987 -12.456 33.561 1999-183T12:47:06.450 87.110 -66.112 123.442 1999-183T13:07:37.705 12.549 -87.001 150.776 1999-183T13:08:06.652 -11.405 -77.051 121.006and assuming that each exposure was 8 milliseconds long, this original data can be changed into input suitable for a Type 2 CK file (the date was replaced with <> to make the lines fit into the page width):
<>T12:17:37.495 <>T12:17:37.505 127.987 -12.456 33.561 0 0 0 <>T12:47:06.445 <>T12:47:06.455 87.110 -66.112 123.442 0 0 0 <>T13:07:37.700 <>T13:07:37.710 12.549 -87.001 150.776 0 0 0 <>T13:08:06.647 <>T13:08:06.657 -11.405 -77.051 121.006 0 0 0or into this input for a Type 3 CK file:
1999-183T12:17:37.495 127.987 -12.456 33.561 1999-183T12:17:37.505 127.987 -12.456 33.561 1999-183T12:47:06.445 87.110 -66.112 123.442 1999-183T12:47:06.455 87.110 -66.112 123.442 1999-183T13:07:37.700 12.549 -87.001 150.776 1999-183T13:07:37.710 12.549 -87.001 150.776 1999-183T13:08:06.647 -11.405 -77.051 121.006 1999-183T13:08:06.657 -11.405 -77.051 121.006As seen in the examples, each of the original times was ``expanded'' into an interval of 10 milliseconds (8 millisecond exposure + 1 millisecond of padding on each side). Both of these inputs will result in a CK file providing data within each small exposure window but not between them. In the case of making a Type 3 CK output file the MAXIMUM_VALID_INTERVAL keyword must be set to a number slightly larger than the maximum exposure window size, for example to 0.012 seconds.
|