MSOPCK User's Guide =========================================================================== Last revised on 2021 DEC 31 by B. V. Semenov. Abstract -------------------------------------------------------- MSOPCK is a command-line program that converts attitude data provided in a text file as UTC, SCLK, or ET-tagged quaternions, Euler angles, or matrices, optionally accompanied by angular velocities, into a type 1, 2, or 3 SPICE C-kernel. Summary -------------------------------------------------------- MSOPCK is a command-line utility program that generates a new, or appends data to an existing, attitude data file in SPICE CK format using one of the following CK types: 1, 2, 3. This CK file is a binary file constructed according to the SPICE DAF (Double Precision Array File) architecture, containing one or more CK data segments. 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 -------------------------------------------------------- 1. CK Required Reading, CK.REQ 2. DAF Required Reading, DAF.REQ 3. Rotations Required Reading, ROTATION.REQ 4. Frames Required Reading, FRAMES.REQ 5. Quaternion White Paper, ftp://naif.jpl.nasa.gov/pub/naif/misc/Quaternion_White_Paper 6. CKSPANIT User's Guide 7. CKSMRG User's Guide Document Overview -------------------------------------------------------- The first section of the document, ``Usage'', provides a brief description of the program usage. 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 -------------------------------------------------------- The program usage is: > msopck [-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 -------------------------------------------------------- Other than the input and output file names, which must be provided on the command line, the program requires all configuration parameters to be provided in a setup file. The format of this file must conform to the SPICE text kernel specification since the data from the setup file are loaded into the kernel pool. This means that the input values must be assigned to the keyword variables using the 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 -------------------------------------------------------- This section briefly summarizes the keywords that can be provided in the setup file. Details about the keywords are provided in the later sections addressing specific aspects of the inputs, output and the operation of the program. Note that all non-numeric values must be enclosed in single quotes. 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 time tag and data types and filtering -- keywords specifying the identification parameters for the output CK segments -- keywords providing the descriptive information to be included within the output CK -- keywords modifying or augmenting the input data and controlling how the input data is packaged into the output CK Brief descriptions of the keywords belonging to each of these categories are provided in the subsections below. Keywords Specifying Additional Kernels The following keywords are used to specify the additional SPICE kernels that may be required for the program execution: LSK_FILE_NAME provides the name of a leapseconds kernel (LSK) file. This keyword is required. SCLK_FILE_NAME provides the name of a spacecraft clock kernel (SCLK) file. This keyword is conditional; it must be specified if the MAKE_FAKE_SCLK keyword is not specified. MAKE_FAKE_SCLK provides the name of a ``fake'' SCLK file to be made by the program. This keyword is conditional; it must be specified if the SCLK_FILE_NAME keyword is not specified. FRAMES_FILE_NAME provides the name of a frames kernel (FK) file. This keyword is conditional; it must be specified only if the reference frame of the attitude data given by the REFERENCE_FRAME_NAME keyword is not one the frames built into SPICE. In such cases the FK file given by this keyword should contain the definition of this frame. The section ``Additional Kernels'' below provides more information about the usage of these keywords. Keywords Specifying the Input Data The following keywords are used to specify the types of the input data and time tags, availability of the angular velocities, and filtering to be done on the input data: INPUT_DATA_TYPE specifies the type of the input data. This keyword is required and can have one of these four values: 'MSOP QUATERNIONS', 'SPICE QUATERNIONS', 'EULER ANGLES', or 'MATRICES'. INPUT_TIME_TYPE specifies the type of the input time tags. This keyword is required and can have one of these five values: 'UTC', 'SCLK','DSCLK', 'TICKS', or 'ET'. ANGULAR_RATE_PRESENT is the multi-purpose angular velocity flag. This keyword is required and can have one of these four values: 'YES', 'NO', 'MAKE UP', or 'MAKE UP/NO AVERAGING'. If the input file provides angular velocity data that must be included in the output CK, this keyword must be set to 'YES'. If the input file does not provide angular velocity data, this keyword must be set to 'NO', 'MAKE UP', or 'MAKE UP/NO AVERAGING' depending on whether the output CK file should or shouldn't include the angular velocity data. ANGULAR_RATE_FRAME specifies whether the input angular velocities are provided in the reference frame given in the REFERENCE_FRAME_NAME keyword or in the ``instrument'' frame associated with the CK ID provided by the INSTRUMENT_ID keyword. This keyword is optional and can be set to either 'REFERENCE' or 'INSTRUMENT'. It is considered only if the ANGULAR_RATE_PRESENT keyword is set to 'YES'. If this keyword is not present, the program defaults to 'REFERENCE'. QUATERNION_NORM_ERROR specifies the number representing the maximum normalization error to be used to filter out input points with bad quaternions. This keyword is optional; if it is not present no filtering is performed. ANGULAR_RATE_THRESHOLD specifies the three numbers representing the maximum allowed values for the angular velocity X, Y, and Z components to be used to filter out input points with bad angular velocities. The values of this keyword must be specified in radians per second. This keyword is optional; if it is not present no filtering is performed. CHECK_TIME_ORDER specifies whether the program should check if the input data records are time-ordered and report an error if not. The check is done if this keyword is set to 'YES'. The check is not done if this keyword is set to 'NO'. This keyword is optional; if it is not present no checking is performed. EULER_ROTATIONS_ORDER specifies the order of rotations for the input data provided as Euler angles. This keyword is conditional; it must be provided when the INPUT_DATA_TYPE keyword is set to 'EULER ANGLES'. If it is provided, its values must consist of three elements specifying the rotation axes either as letters -- ( 'X' 'Y' 'Z' ) -- or as numbers -- ( 1, 2, 3 ). EULER_ROTATIONS_TYPE defines the order in which the rotations corresponding to each of the input Euler angles are multiplied to compute the transformation that is stored in the CK file. This keyword is optional and can have one of the two values: 'BODY' or 'SPACE'. If this keyword is not present, the program defaults to 'SPACE'. EULER_ANGLE_UNITS specifies the units used for the input Euler angles. This keyword is conditional; it must be provided when the INPUT_DATA_TYPE keyword is set to 'EULER ANGLES'. The only units supported by the program are 'DEGREES' and 'RADIANS'. Details on the usage of the keywords from this category are provided below in the sections describing how to setup the program to process each kind of input. Keywords Providing CK Identification Parameters The following keywords are used to set the output CK file type and to provide identification parameters for the output CK segments: CK_TYPE specifies the output CK segment type. This keyword is required and can be set to 1, 2, or 3. INSTRUMENT_ID specifies the NAIF ID of the structure for which the orientation is stored in the output CK file. This keyword is required. REFERENCE_FRAME_NAME provides the name of the reference frame with respect to which the orientation data stored in the output CK is given. This keyword is required. ANGULAR_RATE_PRESENT is the multi-purpose angular velocity flag. This keyword is required and can have one of these four values: 'YES', 'NO', 'MAKE UP', or 'MAKE UP/NO AVERAGING'. If the output CK should contain angular velocity data, this keyword must be set to 'YES', 'MAKE UP', or 'MAKE UP/NO AVERAGING'. Otherwise it should set to 'NO'. The sections ``Output CK Types'' and ``Output CK Identification Parameters'' below provide more details on how to set keywords from this category. Keywords Providing Descriptive Information The following keywords are used to provide descriptive information to be attached to the output CK file record, individual segments and placed into the comment area of the output CK file: INTERNAL_FILE_NAME specifies a 60-characters long string describing the attitude. This string is placed into the internal file name field of the output CK file record (see DAF.REQ). This keyword is optional; if it is not specified, the first 60 characters of the input file name are used instead. This keyword is ignored if the program is run to append segments to an existing CK file. CK_SEGMENT_ID specifies a 40-characters long string describing the attitude. This string is placed into the segment identifier for each of the output CK file segments (see CK.REQ). The keyword is optional; if it is not specified, the first 40 characters of the input file name are used instead. COMMENTS_FILE_NAME is the name of a text file containing comments that are to be included in the comment area of the output CK file. This keyword is optional; if it is not present, only the setup file contents and the interpolation interval summary (if applicable and not suppressed) are written into the CK comment area. This keyword is ignored if the program is run to append segments to an existing CK file. INCLUDE_INTERVAL_TABLE is the flag indicating whether the interpolation interval table should be included in the comment area of the output CK and the program's screen output. This keyword is optional and can be set to either 'YES' or 'NO'. If this keyword is omitted the program defaults to 'YES'. PRODUCER_ID is the name of the group, person or other entity that created the CK file. This keyword is required. The section ``Output CK Metadata'' below provides recommendations on the scope of the information that should be supplied by each of these keywords. Keywords Modifying and Augmenting Input Data The following keywords are used to control how the program modifies and/or augments the input data prior to writing it into the CK file: ANGULAR_RATE_PRESENT is the multi-purpose angular velocity flag. This keyword is required and can have one of these four values: 'YES', 'NO', 'MAKE UP', or 'MAKE UP/NO AVERAGING'. If the output CK is to contain the angular velocity data computed using the input attitude data, this keyword must be set to 'MAKE UP' or 'MAKE UP/NO AVERAGING'. Otherwise it should set to either 'YES' (for input angular velocities to be included into the output CK file) or 'NO' (for no angular velocities to be included into the output CK file). The section ``Adding Made-Up Angular Velocity Data to Output CK'' below provides additional details about how the angular velocities are computed using the input attitude data. MAXIMUM_VALID_INTERVAL specifies the maximum interval between adjacent input points, in seconds, for which the output CK file should support interpolation. This keyword is optional; if it is not present, the program generates a continuous CK file in which interpolation is allowed between all points. The section ``Controlling Coverage Provided by Output CK'' below provides additional details about how the interpolation intervals are computed for different output CK types. TIME_CORRECTION specifies a constant bias to be applied to each input time, in seconds. This keyword is optional; if it is not provided, no bias is applied to the input time tags. The section ``Applying Time Bias to Input Times'' below provides additional details about how this bias is applied to the input times. OFFSET_ROTATION_ANGLES specifies the three Euler angles representing an additional constant rotation to be applied to the input attitude data before it is written to the CK file. This rotation is from the reference frame defined by the REFERENCE_FRAME_NAME keyword to the reference frame relative to which the input orientation is given. This keyword is optional; if it is not present, no offset rotation is applied to the input data. If this keyword is provided, its value must consist of three numbers, e.g. ( 90.0, 45.0, 180.0 ). The section ``Augmenting Input Attitude by Additional Rotation'' below provides additional details about when applying an additional rotation is useful and how such rotation is combined with the input attitude data. OFFSET_ROTATION_AXES specifies the axes for the offset rotation angles provided by the OFFSET_ROTATION_ANGLES keyword. This keyword is conditional. It must be provided if the OFFSET_ROTATION_ANGLES keyword is provided; otherwise it is ignored. If it is provided, its value must consist of three elements specifying the rotation axes either as letters -- ( 'X' 'Y' 'Z' ) -- or as numbers -- ( 1, 2, 3 ). OFFSET_ROTATION_UNITS specifies the units of the Euler angles given in the OFFSET_ROTATION_ANGLES keyword. This keyword is conditional. It must be provided if the OFFSET_ROTATION_ANGLES keyword is provided; otherwise it is ignored. The only units supported by the program are 'DEGREES' and 'RADIANS'. DOWN_SAMPLE_TOLERANCE is the angle, in radians, used as the threshold in reducing the set of pointing data written to the output CK by eliminating some of the input data points (``downsampling''). This angle represents the maximum rotation difference between the orientation provided by the data points eliminated from the input data stream and the orientation computed by interpolating between the data points written to the output CK file using the Type 3 CK algorithm. This keyword is optional; if it is present, the program creates a Type 3 CK file that includes only a subset of the input data points, resulting in a smaller output CK file matching the input attitude to the specified tolerance. It this keyword is not provided, no down sampling is performed. Because downsampling is applicable only for producing Type 3 CK files this keyword is ignored if the output CK type specified by the CK_TYPE keyword is not 3. The section ``Reducing Size of Output CK (Downsampling)'' below provides additional details about downsampling of the input data. Is a Keyword Required, Optional, or Conditional? While the previous subsections have already identified each keyword as required, optional, or conditional, for convenience the table below provides a summary of these identifications: 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 -------------------------------------------------------- This section discusses additional kernels that are required by the program for every run and/or in special circumstances. LSK and SCLK Files In order to perform time conversions the program needs to load an LSK file providing the data for converting between UTC and ET, and an SCLK file providing the data for the clock associated with the CK ID given by the INSTRUMENT_ID keyword. The names of these exiting files are specified using the LSK_FILE_NAME and SCLK_FILE_NAME keyword. 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 The FRAMES_FILE_NAME keyword is used to provide the name of an FK file required by the program in two cases: -- If the reference frame specified in the REFERENCE_FRAME_NAME keyword is not one of the frames built into the SPICE System (see FRAMES.REQ), the FRAMES_FILE_NAME keyword should point to an FK file defining this frame. -- If the ID of the clock to be used with the CK is not equal to the CK ID divided by 1000, the FRAMES_FILE_NAME keyword should point to an FK file defining the frame associated with the CK ID and specifying the clock ID to be used for it. Input Data Format -------------------------------------------------------- The program requires the input data to be provided in an ASCII text file. Each line of the file must contain a single attitude data point consisting of a time tag followed by the attitude provided as quaternion, Euler angles, or rotation matrix, optionally followed by the angular velocity vector. The only exception from this requirement is when a type 2 CK file containing input angular velocities is to be made; in this case each input line must contain two time tags -- begin and end time, -- the attitude and the angular velocity. All lines of the file must have the same type of time tag, attitude, and angular velocity data. 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 -------------------------------------------------------- A time tag must be provided as the first item (or the first two items) on each line of the input data file. The INPUT_TIME_TYPE keywords must be set in the setup file to identify the type of the time tag. The program supports the following input time types: -- UTC strings (INPUT_TIME_TYPE='UTC') -- three kinds of SCLK times (INPUT_TIME_TYPE='SCLK', 'DSCLK', or 'TICKS') -- ET seconds past J2000 (INPUT_TIME_TYPE='ET') In order to be processed by the program the time tags of any of these types must not contains blanks. The subsections below provide details and examples for each of the time types supported by the program. UTC Time Tags Any time string that does not have spaces and is a legitimate input for SPICE's STR2ET routine can be used to tag the program's input data. To process such tags the INPUT_TIME_TYPE keyword must be set to 'UTC'. Examples of blank-less time strings acceptable for STR2ET range from the standard ISO ``T'' formats: 2005-01-05T12:00:03.129 2005-005T12:00:03.129 to 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.129 The 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.0000362 While 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.313TDB a Julian date ET time can be provided as: JD2453376.0000362TDB and a Pacific Day Time zone (PDT) time tag can be provided as: 2005-01-05-04:00:03.129PDT The STR2ET source code header provides the complete specification of the input time formats supported by this routine. SCLK Time Tags The program allows on-board clock (SCLK) times to be provided in three different formats: -- string SCLK (INPUT_TIME_TYPE='SCLK') -- decimal SCLK (INPUT_TIME_TYPE='DSCLK') -- encoded SCLK (INPUT_TIME_TYPE='TICKS') The first type of input SCLK times supported by the program are string SCLK times. They are the traditional form of the on-board clock -- strings consisting of one or more cascading counters, optionally augmented with the SPICE partition number. These SCLK times are converted to ET times utilized within the program using the SCS2E routine. For example, all of these are acceptable SCLK strings: 1483619164.085 1/0789393653.024 789393801:200 In 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+08 The 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.02084814522e11 Complete information about the SCLK formats is provided in the SCLK.REQ document. ET Time Tags The program also allows the input time to be provided as ET seconds past J2000. For such input times the INPUT_TIME_TYPE keyword must be set to 'ET' and the times must be given as floating point numbers in scientific or engineering notation. For example: 158198467.313 1.58198467313e+8 Input Attitude -------------------------------------------------------- The input attitude data must provide information sufficient to compute the rotation matrix that transforms vectors from the reference frame into the instrument frame, i.e.: Vinst = Mref->inst * Vref The 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 program recognizes two types of quaternions described in the ``Quaternions White Paper'': -- SPICE-Style quaternions (INPUT_DATA_TYPE='SPICE QUATERNIONS') -- Alternate-Style quaternions (INPUT_DATA_TYPE='MSOP QUATERNIONS') The SPICE-Style quaternions are the quaternions used throughout the SPICE system -- as input to Q2M and output from M2Q routines, as the means of storing the attitude data in CK files, etc. These quaternions have the scalar component first. They are described in detail in the ROTATION.REQ document. 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 The program allows the input attitude to be provided as sets of Euler angles from which the transformations from the reference frame to the CK frame can be constructed. When the input attitude is provided as Euler angles, the INPUT_DATA_TYPE keyword must be set to 'EULER ANGLES'. In addition to this the conditional keywords EULER_ANGLE_UNITS and EULER_ROTATIONS_ORDER must be defined to specify the units of the input angles and the rotation axes corresponding to each of the angles. The EULER_ROTATIONS_TYPE keyword may also be specified to explicitly tell the program in which order the rotation matrices corresponding to the the input angles should combined to compute the transformation to be stored in the CK file. 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 R(angleN)axisN is the coordinate transformation consisting of the rotation by the angle angleN about the coordinate axis axisN. angle1 is the first angle from each input data line. angle2 is the second angle from each input data line. angle3 is the third angle from each input data line. axis1 is the first axis defined in the EULER_ROTATIONS_ORDER keyword. axis2 is the second axis defined in the EULER_ROTATIONS_ORDER keyword. axis3 is the third axis defined in the EULER_ROTATIONS_ORDER keyword. Input as Matrices The program allows the input attitude to be provided as rotation matrices transforming vectors from the reference frame to the instrument frame. If the input file contains matrices, the INPUT_DATA_TYPE keyword must be set to '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 M33 An 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 -------------------------------------------------------- Optionally the program can store in the output CK file the angular velocity data accompanying the input attitude data. If the angular velocities provided in the input file are to be stored in the output CK file, the ANGULAR_RATE_PRESENT keyword must be set to 'YES'. 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 -------------------------------------------------------- While it may appear that the program has rather limited abilities when it comes to parsing the input file, this deficiency can be easily alleviated by using a wide variety of external utilities -- from Unix commands (grep, sed, awk) to Perl and Pyhton to Microsoft Excel -- to turn complex data files into simple space delimited tables that the program will accept. In general such preprocessing would include one of more of these steps: -- modifying the time tags so that they don't contain blanks and comply with the requirements of one of the supported time types -- striping off all extraneous information -- extra fields, blank and comment lines, non-blank delimiters, -- arranging the data items on each line in the proper order -- time, then attitude, then optional angular velocity, -- sorting the data lines by time and eliminating lines with duplicate times. Let's take as an example a rather contrived sample attitude file shown below. It contains a comma-delimited data table with a header, a few blank lines and a few data lines, each including the record number, a word identifying the pointing mode, three Euler angles providing orientation, and the time tag given as Julian Date ET: 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 -10 Should 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 -------------------------------------------------------- The program can create a Type 1, Type 2, or Type 3 CK file. The type of the CK file to be made is specified using the CK_TYPE keyword. 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 -------------------------------------------------------- The data stored in CK segments is identified by the CK ID of the structure for which the attitude is provided, the reference frame with respect to which the attitude is given, and the flag indicating whether angular velocities are included along with the attitude data. These parameters must be specified in the setup file using the INSTRUMENT_ID, REFERENCE_FRAME_NAME, and ANGULAR_RATE_PRESENT keywords. CK ID The CK ID of the structure for which the attitude is provided must be specified in the setup file using the INSTRUMENT_ID keyword. Normally this ID is a negative integer number derived from the NAIF ID of the spacecraft by multiplying the spacecraft ID by 1000 and subtracting the structure or instrument number from it. For most spacecraft the instrument number of the spacecraft bus is 0, thus the CK ID is simply the spacecraft ID multiplied by 1000. For example, for the spacecraft with the ID -37, the CK ID for the spacecraft bus is -37000. The instrument numbers for the articulating spacecraft structures and instruments are usually non zero. If an articulating structure or instrument mounted on this example spacecraft had the number 5, its CK ID would be -37005. 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 The name of the reference frame with respect to which the attitude stored in the CK is given must be specified using the REFERENCE_FRAME_NAME keyword. If this frame is one of the frames built into the SPICE System -- ``J2000'', ``ECLIPJ2000'', etc. -- then it is recognized by the program without requiring any additional FK file. If the frame is not one of the frames built into the SPICE system, then an FK file defining this frame must be specified using the FRAMES_FILE_NAME keyword. If input data is referenced to ICRF and CK created from it is intended to be used as described below in the section ``ICRF vs J2000'', the REFERENCE_FRAME_NAME keyword should be set to the value 'J2000'. Angular Velocity Flag Type 1 and Type 3 CK files can optionally store angular velocity data; in Type 2 CK files the angular velocity data are required. Whether the angular velocity data is to be included in the output CK file is controlled by the ANGULAR_RATE_PRESENT keyword. 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 International Celestial Reference System (ICRS) defines coordinate axes that are closely aligned with those of the J2000 (aka EME2000) reference frame. The International Celestial Reference Frame (ICRF) and later versions of it (ICRF1, etc.) are realizations of the ICRS. For brevity, we'll simply refer to ``the ICRF'' below. 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, -- DE4xx series planetary ephemerides -- Satellite ephemerides compatible with DE4xx planetary ephemerides -- Small body ephemerides compatible with DE4xx planetary ephemerides -- Orientation of the terrestrial frame ITRF93 -- Orientation of the lunar principal axes frame Rotation models provided by the IAU are referenced to the ICRF. 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: -- A call to spkezr_c with the input frame name J2000 will return a state vector referenced to the ICRF, if the SPK data are from a JPL planetary ephemeris SPK, or from any other SPK in which data are referenced to the ICRF and labeled as referenced to the J2000 frame. -- A call to pxform_c with the input ``from'' frame name J2000 and input ``to'' frame name ITRF93 will return a 3x3 matrix that transforms position vectors from the ICRF to the ITRF93 terrestrial frame, if the Earth orientation data are provided by a NAIF high-precision, binary Earth PCK. -- A call to pxform_c with the input ``from'' frame name J2000 and input ``to'' frame name IAU_MARS will return a 3x3 matrix that transforms position vectors from the ICRF to the Mars body-fixed, body-centered IAU_MARS frame, if the orientation data are provided by a NAIF generic text PCK. -- A call to pxform_c with the input ``from'' frame name J2000 and an input ``to'' CK frame name will return a 3x3 matrix that transforms position vectors from the ICRF to the specified CK frame, if the CK data used by this call are referenced to the ICRF and labeled as referenced to the J2000 frame. SPICE kernel creators intending to support use of data referenced to the ICRF, as shown above, should write the data without first converting it to the J2000 frame. Segments of such SPK, CK, or binary PCK files should indicate the frame is J2000. It is strongly recommended that kernel creators add comments to the files to explain the actual characteristics of the data. 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 program provides a number of keywords that can used to supply metadata, or descriptive information, for the output CK file. These keywords include the PRODUCER_ID, INTERNAL_FILE_NAME, and CK_SEGMENT_ID keywords discussed in this section and the COMMENTS_FILE_NAME and INCLUDE_INTERVAL_TABLE keywords discussed in the ``Output CK Comment Area Contents'' section below. 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 comment area of each CK file produced by the program includes the contents of the text file specified using the COMMENTS_FILE_NAME keyword, the contents of the setup file, a block of lines called ``Run Time Meta Information'', and an interpolation interval summary table for each of the segments written to the output CK file. 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.NNN The ``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 -------------------------------------------------------- The optional TIME_CORRECTION keyword may be used to apply a constant bias to each of the times provided in the input file. If provided, this keyword should be set to the number of seconds to be added to each of the input time tags prior to writing it to the output CK file. This keyword is applicable to the input tags of all types because it is applied to the ET times that the program stores internally. For example, to adjust all input times by -2.3 seconds this keyword should be set as follows: TIME_CORRECTION = -2.3 Augmenting Input Attitude by Additional Rotation -------------------------------------------------------- In some cases it is desirable to adjust the input data to make the attitude stored in the output CK file be given relative to a different reference frame than the input attitude is given relative to. Examples of such cases are modifying the input rotation angles to be relative to a different zero reference position or changing the data given relative to an uncommon reference frame to be with respect to a more traditional frame (such as J2000). Assuming that the rotation from the desired reference frame to the reference frame of the input data is known and can be represented by a set of Euler angles, the program provides a way to apply this rotation by using the OFFSET_ROTATION_ANGLES, OFFSET_ROTATION_AXES, and OFFSET_ROTATION_UNITS keywords. The rotation provided by these keywords is combined with the rotation represented by the input attitude as follows: Vinst = Minp->inst * Mref->inp * Vref where Vref is the vector in the reference frame specified using the REFERENCE_FRAME_NAME keyword Vinst is the vector in the instrument frame associated with the CK ID given using the INSTRUMENT_ID keyword Minp->inst is the 3x3 matrix rotating vectors from the reference frame of the input data into the instrument frame Mref->inp is the 3x3 matrix rotating vectors from the reference frame specified using the REFERENCE_FRAME_NAME keyword into the reference frame of the input data. The Mref->inp matrix is computed from the values provided using the OFFSET_ROTATION_* keywords as follows: Mref->inst = R(angle1)axis1 * R(angle2)axis2 * R(angle3)axis3 where R(angleN)axisN is the coordinate transformation consisting of the rotation by the angle angleN about the coordinate axis axisN. angle1 is the first angle provided in the OFFSET_ROTATION_ANGLES keyword. angle2 is the second angle provided in the OFFSET_ROTATION_ANGLES keyword. angle3 is the third angle provided in the OFFSET_ROTATION_ANGLES keyword. axis1 is the first axis defined in the OFFSET_ROTATION_AXES keyword. axis2 is the second axis defined in the OFFSET_ROTATION_AXES keyword. axis3 is the third axis defined in the OFFSET_ROTATION_AXES keyword. If the OFFSET_ROTATION_ANGLES keyword is specified, then the OFFSET_ROTATION_AXES and OFFSET_ROTATION_UNITS keywords must be provided as well. The value of the OFFSET_ROTATION_ANGLES keyword must consist of exactly three angles given as numbers, in units specified using the OFFSET_ROTATION_UNITS keyword. The rules for forming values of the OFFSET_ROTATION_AXES and OFFSET_ROTATION_UNITS keywords are the same as the rules for the EULER_ROTATIONS_ORDER and EULER_ANGLE_UNITS keywords explained earlier in this document. If the OFFSET_ROTATION_AXES and OFFSET_ROTATION_UNITS keywords are specified without the OFFSET_ROTATION_ANGLES keyword they are ignored. 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 -------------------------------------------------------- Although angular velocity data are frequently not available in the input data set, it is still highly desirable to produce the output CK with angular velocities (see the section ``Angular Velocity Flag'' above for an explanation). For such cases the program provides a way to compute angular velocities using the input attitude data. In order to do this the ANGULAR_RATE_PRESENT keyword must be set to 'MAKE UP' or 'MAKE UP/NO AVERAGING'. 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 time periods for which the output CK allows interpolation are determined by the value of the MAXIMUM_VALID_INTERVAL keyword. This keyword specifies the longest interval between the input data points over which the linear interpolation should be permitted. 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 = 8 and 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) -------------------------------------------------------- The program provides a way to reduce the size of the output CK by storing only a subset of the input data points. This capability is called ``downsampling'' and is applied when the output CK type is 3 and the DOWN_SAMPLE_TOLERANCE keyword is set to the angular tolerance, in radians, to which the attitude returned by the CK should match the input attitude data. When the DOWN_SAMPLE_TOLERANCE keyword is set, the program eliminates from the input data all data points for which Type 3 CK interpolation between the bounding points that are not eliminated produces results that are within the specified tolerance of the input attitude. The elimination is done within each individual interpolation interval determined using the value of the MAXIMUM_VALID_INTERVAL keyword. For example, if the DOWN_SAMPLE_TOLERANCE keyword is set to one milliradian: DOWN_SAMPLE_TOLERANCE = 0.001 and 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.0 the 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.0 In 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 -------------------------------------------------------- This section provides a few examples of program use. Example 1: Typical Spacecraft CK, Input Includes Angular Velocities This example shows a sample input file and a sample setup file used to create CK files containing the attitude of the Mars Reconnaissance Orbiter (MRO) spacecraft, for which both attitude quaternions and angular velocities are available in channelized telemetry. 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' \begintext The 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 This example shows a sample input file and a sample setup file that are used to create CK files containing the attitude of the 2001 Mars Odyssey (M01) spacecraft, for which only attitude quaternions but not angular velocities are available in channelized telemetry. 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' \begintext The 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 This example shows a sample input file and a sample setup file that are used to create CK files containing the attitude of the CASSINI CDA instrument, which has one degree of freedom and can move from one observation position to another by rotating about a fixed axis. The orientation of the moving part of this instrument with respect to its base is available in the form of position angles given at the start and the end of each stationary observation period. 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 This example shows a sample input file and a sample setup file that are used to create a CK file containing the nominal attitude of the PHOENIX lander relative to the local level frame at the landing site. 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.0 It 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 There are some cases when the input attitude data seems to be truly discrete in nature, for example the sparse attitude points derived by a C-smithing image navigation process and corresponding to the times of the images. While such data may seem as a perfect match for the Type 1 CK files that provide the attitude only at the exact times of the data points stored in the file, making the Type 1 CK from it should be avoided. The main reason for this recommendation is that the Type 1 CK files are in general not usable with the higher level SPICE interfaces accessing the CK data using frames with lookup tolerance set to zero. Instead each of these data points should be ``expanded'' into a small interval, for example covering from the beginning to the end of the image exposure plus some small margin on both sides, formatted as input records with two time tags and zero angular velocity suitable for Type 2 CK input or as pairs of records suitable for Type 3 CK input. 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.006 and 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 0 or 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.006 As 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.