 
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 <setup_file> <input_data_file> <output_ck_file>
              [-u|-usage]
              [-h|-help]
              [-t|-template]
 
   All three file names -- the setup file name, the input data file name
   and the output CK file name -- must be provided on the command line in
   order to run the program to generate the output CK. The setup and input
   data files must exist; the CK file may be a new file or may already
   exist, in which case the new CK segments will be appended to it. Note
   that the program cannot append data to an existing CK file if its format
   is not native to the platform on which the program is running.
 
   If the ``-u'' or ``-usage'' flag or no flags at all are specified on the
   command line, or if the command line has too few or too many arguments,
   the program will display a brief usage message.
 
   If the ``-h'' or ``-help'' flag is specified on the command line, the
   program will display a brief help message.
 
   If the ``-t'' or ``-template'' flag is specified on the command line,
   the program will display the complete setup file template.
 
   If the program successfully creates the output CK file it prints to the
   screen the complete comments that it wrote into the comment area of the
   file. The section ``Output CK Comment Area Contents'' below provides
   detailed information about what is written into the output CK's comment
   area.
 
 
Setup File Format
--------------------------------------------------------
 
   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.
 
