 
SPACIT User's Guide
===========================================================================
 
   Last revised on 2002 DEC 13 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   SPACIT is an interactive program that converts kernels in transfer
   format to binary format, converts binary kernels to transfer format, and
   summarizes the contents of binary kernels.
 
 
Introduction
--------------------------------------------------------
 
   The SPACIT utility is an interactive menu driven program which provides
   a collection of services useful for manipulating and examining SPICE
   binary kernel files. The program may be used to convert SPICE binary
   kernel files into equivalent ASCII files, called SPICE transfer files,
   and to convert the SPICE transfer files back to binary. SPACIT may also
   be used to summarize the information contained in SPICE binary kernel
   files and to read the comments contained in the comment area of a SPICE
   binary kernel file.
 
   The SPACIT program currently supports the CK, EK, PCK, and SPK SPICE
   binary kernel file formats.
 
       --   CK files contain orientation information, commonly called
            ``pointing,'' for various spacecraft structures or instruments.
 
       --   EK files contain time tagged event information for a spacecraft
            during a mission.
 
       --   PCK files contain highly accurate body orientation and shape
            information for performing rotations, etc. Binary PCK files are
            currently only available for the Moon with limited time
            coverage.
 
       --   SPK files contain ephemeris information for solar system
            objects: planets, satellites, comets, asteroids, and
            spacecraft.
 
   In addition to SPICE binary kernel files, SPACIT requires additional
   SPICE files when used to summarize a binary kernel file.
 
       --   Leapseconds kernel files contain a tabulation of leapseconds
            which have occurred. The leapseconds information is required to
            perform time conversions between ephemeris time (ET, TDB),
            which is used for representing times within the SPICE system,
            and Universal Time Coordinated (UTC), which is used for input
            and output purposes by the SPACIT program. This file is
            required for summarizing CK, EK, PCK and SPK binary kernel
            files.
 
       --   SCLK kernel files contain information which describes a
            spacecraft clock for a particular mission, e.g.: clock rates,
            partition information, etc.. The SCLK information is required
            to perform time conversions between a standard time system such
            as ET (TDB) or UTC and the mission dependent encoded spacecraft
            clock times. See the SCLK Required Reading document, sclk.req,
            listed in the references section for details. This file is
            required for summarizing binary CK files.
 
   The SPACIT program is one component of the portable NAIF Toolkit.
 
   Note that NAIF uses the terminology ``ephemeris time'' (ET) to mean
   ``barycentric dynamical time'' (TDB).
 
 
References
--------------------------------------------------------
 
   Detailed descriptions of the SPICE CK, EK, PCK and SPK binary kernel
   file formats may be found in the NAIF documents:
 
       1.   CK Required Reading (ck.req).
 
       2.   EK Required Reading (ek.req).
 
       3.   PCK Required Reading (pck.req).
 
       4.   SPK Required Reading (spk.req).
 
   Information related to other aspects of the SPACIT program and its
   options may be found in the NAIF documents:
 
       1.   SPC Required Reading (spc.req).
 
       2.   NAIF IDS Required Reading (naif_ids.req).
 
       3.   SCLK Required Reading (sclk.req).
 
 
Changes
--------------------------------------------------------
 
   This version of the SPACIT utilty program has been modified in several
   significant ways:
 
       1.   Support for automatic identification of SPICE binary file types
            has been enhanced.
 
       2.   The user interface to the program has been modified slightly to
            enhance the presentation.
 
       3.   The summary display formats for the SPK and CK files have been
            modified. The new summary format is, hopefully, more readable
            than the old summary format. Names for bodies, reference
            frames, and data type descriptions have also been added to the
            summaries.
 
 
File Naming and Usage Conventions
--------------------------------------------------------
 
   Filenames are required for options in the SPACIT program. In order to
   maintain portability a filename must, in addition to any conditions
   imposed by a particular computer or operating system, satisfy the
   following conditions.
 
       --   A filename must be nonblank.
 
       --   A filename may not contain embedded spaces.
 
       --   A filename may not contain nonprinting or ``control''
            characters, e.g., tabs, line feeds, carriage returns, nulls,
            form feeds, etc.. The nonprinting and control characters are
            those having ASCII decimal values 0-31 and 127.
 
   Be aware that on many computer systems filenames are case sensitive. On
   such a system, the filenames `program.for' and `PROGRAM.FOR' are
   different. On a computer system that does not support case sensitive
   filenames these filenames would both refer to the same file.
 
   Also be aware that each computer system will have a limit on the length
   of a filename. Care must be taken when moving files from a computer
   system which supports longer filenames to a computer system which
   supports shorter filenames, in particular if the initial portion of the
   filenames are identical.
 
   When creating a new file the SPACIT program will not allow an existing
   filename to be used. Before the program creates a file it determines
   whether a file with the entered filename already exists. If so, a brief
   message reporting this is displayed and an opportunity to reenter the
   filename will be provided. This is done in order to prevent accidental
   modification of existing files.
 
   If at any time an improper filename is entered: a file which did not
   exist when it should have, a file which existed when it should not have,
   or a filename containing improper characters, an appropriate error
   message will be displayed. A chance to reenter the filename will be
   provided via a ``Try again? (Yes/No)'' prompt. A response of ``Yes'' and
   the prompt for the filename will be redisplayed. A response of ``No''
   will return the program to the main menu.
 
 
Using SPACIT
===========================================================================
 
   The SPACIT utility program is an interactive menu driven program which
   provides a collection of services useful for manipulating and examining
   SPICE binary kernel files. The SPACIT utility program provides four
   services for use with SPICE binary kernel files.
 
       --   Convert a SPICE transfer file into an equivalent binary kernel
            file.
 
       --   Convert a binary kernel file to an equivalent SPICE transfer
            file.
 
       --   Summarize the data contained in a binary kernel file.
 
       --   Read the comment area of a binary kernel file.
 
   The desired service may be selected by choosing the appropriate option
   from the main menu of the SPACIT program. An option is selected by
   entering the letter or number appearing in parentheses to the left of
   the option description. The selection of an option is not case
   sensitive.
 
   In addition to the four basic services for each type of binary kernel
   file, the SPACIT utility program has the ability to maintain a log of
   its actions in a text file. This feature was provided so that the
   information obtained through the SPACIT program could be saved and read
   or printed at a later time. By default, output from the SPACIT program
   is displayed only on the terminal screen.
 
   The SPICE transfer files produced by the SPACIT utility are the
   recommended means for porting data contained in SPICE binary kernel
   files among various computer systems. The SPICE transfer files are
   useful only for porting data among different computer systems or for
   system independent archival storage. The SPICE transfer file cannot be
   used directly as a means of providing data to a program which uses the
   SPICE system. This capability is provided through the SPICE binary
   kernel files and their associated readers.
 
   When summarizing a SPICE binary kernel file additional files are
   required: a SPICE leapseconds file and a SPICE SCLK file when
   summarizing a CK file. See the descriptions of these files in the
   introduction. A name for each of these files is supplied only once
   during a SPACIT session and they are valid throughout the session. These
   files are loaded the first time that a summary option requiring one of
   the files is selected. If an SCLK file has been loaded and a different
   SCLK file is desired, the current SPACIT session must be abandoned and a
   new SPACIT session begun by restarting the program.
 
 
The SPACIT Main Menu
--------------------------------------------------------
 
   A SPACIT option is selected from the main menu.
 
               SPACIT Options
 
         ( Q ) Quit.
         ( L ) Log SPACIT output to a file.
         ( T ) Convert transfer file to binary file.
         ( B ) Convert binary file to transfer file.
         ( S ) Summarize binary file.
         ( R ) Read comment area of binary file.
 
 
SPACIT Options
--------------------------------------------------------
 
   In this section, each of the options available on the SPACIT main menu
   will be described in detail.
 
 
SPACIT Option: Q -- Quit.
 
   Gracefully exit the program.
 
 
SPACIT Option: L -- Log SPACIT output to a text file.
 
   Create and maintain a new SPACIT log file.
 
   This option may be selected at any time during a SPACIT session and it
   is active throughout the remainder of that session. The first time that
   this option is selected a prompt requesting a name for the log file will
   be displayed. A filename for the SPACIT log file should be entered at
   this time. The name entered must be the name of a new file. If not,
   SPACIT will report that the file already exists, and provide an
   opportunity to reenter the filename.
 
   There is no default filename for the SPACIT log file, and only one log
   file may be open during a SPACIT session. If a log file has already been
   successfully opened and this option is selected, a brief message stating
   that a SPACIT log file is currently open will be displayed, and the
   program will return to the main menu. If an error occurs while
   attempting to open the SPACIT log file, it will be reported and the
   program will return to the main menu.
 
 
SPACIT Option: T -- Convert transfer file to binary file.
 
   Convert a portable SPICE transfer file into its binary kernel
   equivalent.
 
   This option requires two filenames:
 
       --   The name of an existing SPICE transfer file to be converted to
            binary.
 
       --   The name of the binary file to be created.
 
   When option ``T'' is selected, prompts requesting each of the required
   filenames will be displayed. For each prompt the appropriate filename
   should be entered. The name entered for the binary file to be created
   must be that of a new file. Otherwise SPACIT will report that the file
   already exists and provide an opportunity to reenter the filename.
 
 
SPACIT Option: B -- Convert binary file to transfer file.
 
   Convert a SPICE binary kernel file into an equivalent portable SPICE
   transfer file.
 
   This option requires that two filenames be supplied:
 
       --   The name of an existing SPICE binary kernel file to be
            converted into an equivalent SPICE transfer file.
 
       --   The name of the SPICE transfer file to be created.
 
   When option ``B'' is selected, prompts requesting each of the required
   file names will be displayed. For each prompt the appropriate filename
   should be entered. The name entered for the SPICE transfer file to be
   created must be that of a new file. Otherwise SPACIT will report that
   the file already exists and provide an opportunity to reenter the
   filename.
 
   The SPICE transfer file produced will be approximately three times the
   size of the original binary kernel file.
 
   The SPICE transfer files produced by SPACIT may be used as a vehicle for
   porting the data that was contained in the original binary kernel files
   to different computer systems. Once the SPICE transfer files have been
   ported to a new computer, the SPACIT program may be used to convert them
   into their binary equivalents on that computer. This capability is
   necessary if data files created or stored on one computer system are to
   be used on computer systems having different representations for similar
   data objects, like double precision numbers.
 
 
SPACIT Option: S -- Summarize binary file.
 
   Summarize the information contained in a SPICE binary kernel file.
 
   This option requires the name of the SPICE binary kernel file that is to
   be summarized. In addition, names for a SPICE leapseconds kernel file or
   a SPICE SCLK kernel file may be necessary, depending on the type of the
   kernel file being summarized and the files that are currently loaded.
 
   When option ``S'' is selected, prompts requesting each of the required
   filenames will be displayed. For each prompt the appropriate filename
   should be entered. The prompt for the SPICE leapseconds kernel file will
   only be displayed if SPACIT has not already loaded a leapseconds file.
   Similarly, the prompt for the SPICE SCLK kernel file will only be
   displayed if this file has not already been loaded.
 
   Names for bodies, reference frames, and data types are included in the
   summaries when they are available. ID codes for body names, reference
   frames, and data types appear enclosed in parentheses to the right of
   the name. If a name is not available for a particular body ID code a
   ``Name Not Found'' indicator will be placed where the name would
   normally appear in the summary. Similarly, if the ID code for an
   inertial reference frame or SPICE data type is not recognized, an
   indication of this will be placed where their names would normally
   appear in the summary.
 
 
CK summaries
 
   A SPICE binary CK file may be summarized in one of the following ways by
   selecting the appropriate option from the summarize submenu.
 
       --   Summarize the pointing information in the entire file.
 
       --   Summarize the pointing information for a specified instrument.
 
       --   Summarize the pointing information for a specified time
            interval, specifying the times in UTC.
 
       --   Summarize the pointing information for a specified time
            interval, specifying the times using spacecraft clock (SCLK)
            time.
 
 
PCK summaries
 
   A SPICE binary PCK file may be summarized in any of the following ways
   by selecting the appropriate option from the summarize submenu.
 
       --   Summarize the entire file.
 
       --   Summarize for a specified solar system body.
 
       --   Summarize for specified time interval specifying the times in
            UTC.
 
 
SPK summaries
 
   A SPICE binary SPK file may be summarized in any of the following ways
   by selecting the appropriate option from the summarize submenu.
 
       --   Summarize the ephemeris information in the entire file.
 
       --   Summarize the ephemeris information for a specified solar
            system body.
 
       --   Summarize the ephemeris information for a specified time
            interval specifying the times in UTC.
 
 
EK summaries
 
   The only type of summary currently available for an EK file is a summary
   of the entire file by segment.
 
 
SPACIT Option: R -- Read comment area of binary file.
 
   Read the comments in the comment area of a SPICE binary kernel file.
 
   This option requires only the name of the SPICE binary kernel file which
   contains the comments to be read.
 
   When option ``R'' is selected, a prompt requesting the required filename
   will be displayed. The appropriate filename should be entered. The
   comments contained in the binary kernel file will then be displayed.
 
 
Integrating SPACIT Functionality into a Program
--------------------------------------------------------
 
   SPACIT is built upon a few high--level subroutines which perform the
   various services offered. These services may be incorporated into any
   program by invoking the appropriate high--level subroutines. The source
   code for the SPACIT program itself may be used as a guide for
   incorporating these services into another program.
 
 
Appendix: Sample SPACIT Session
===========================================================================
 
   This appendix contains an example session which demonstrates a typical
   use of the SPACIT utility program. In the example some of the vertical
   white space has been compressed for readability.
 
   In this example session, SPACIT is used to convert a SPICE transfer file
   into its equivalent binary kernel file. The binary kernel file is then
   summarized and its comment area is read. The file used in this example
   is an SPK file provided with the NAIF toolkit called cook_02.tsp.
   Comments describing the actions as they are performed are included, but
   everything was done during a single SPACIT session.
 
 
   Convert the transfer file cook_02.tsp to binary.
 
          Welcome to SPACIT Version: 7.1.0
 
               SPACIT Options
 
         ( Q ) Quit.
         ( L ) Log SPACIT output to a file.
         ( T ) Convert transfer file to binary file.
         ( B ) Convert binary file to transfer file.
         ( S ) Summarize binary file.
         ( R ) Read comment area of binary file.
 
         Option: t
 
         Transfer file: cook_02.tsp
         Binary file  : cook_02.bsp
 
         Converting from transfer file to binary file.
 
         Converting Transfer File: cook_02.tsp
         To Binary File          : cook_02.bsp
 
         Please wait...
 
 
         Binary file 'cook_02.bsp' created.
 
   Summarize the file cook_02.bsp.
 
 
               SPACIT Options
 
         ( Q ) Quit.
         ( L ) Log SPACIT output to a file.
         ( T ) Convert transfer file to binary file.
         ( B ) Convert binary file to transfer file.
         ( S ) Summarize binary file.
         ( R ) Read comment area of binary file.
 
         Option: s
 
         Binary file     : cook_02.bsp
         Leapseconds file: leapseconds.ker
 
         Loading the Leapseconds kernel file. Please wait ...
 
 
               SPK Summary Options
 
         ( Q ) Quit, returning to main menu.
 
         ( F ) Summarize entire file.
         ( B ) Summarize by NAIF body ID code.
         ( T ) Summarize by time interval.
 
         Option: f
 
      ******************************************************************
 
      Summary for SPK file: cook_02.bsp
      Leapseconds File    : leapseconds.ker
      Summary Type        : Entire File
 
      ------------------------------------------------------------------
         Segment ID     : NAIF Source Ephemeris TEST/0.
         Target Body    : Body -77, GALILEO ORBITER
         Center Body    : Body 10, SUN
         Reference frame: Frame 11, DE-125
         SPK Data Type  : Type 1
            Description : Modified Difference Array
         UTC Start Time : 1990 DEC 12 01:06:51.329
         UTC Stop Time  : 1991 JAN 31 23:59:58.000
         ET Start Time  : 1990 DEC 12 01:07:48.512
         ET Stop time   : 1991 FEB 01 00:00:56.184
      ------------------------------------------------------------------
      ------------------------------------------------------------------
         Segment ID     : NAIF Source Ephemeris TEST/0.
         Target Body    : Body -77, GALILEO ORBITER
         Center Body    : Body 399, EARTH
         Reference frame: Frame 11, DE-125
         SPK Data Type  : Type 1
            Description : Modified Difference Array
         UTC Start Time : 1990 DEC 05 15:32:32.716
         UTC Stop Time  : 1990 DEC 12 01:06:51.329
         ET Start Time  : 1990 DEC 05 15:33:29.899
         ET Stop time   : 1990 DEC 12 01:07:48.512
      ------------------------------------------------------------------
 
                                      .
                                      .
                                      .
              ( Many segment summaries deleted to save paper. )
                                      .
                                      .
                                      .
 
      ------------------------------------------------------------------
         Segment ID     : NAIF Source Ephemeris TEST/0.
         Target Body    : Body 2, VENUS BARYCENTER
         Center Body    : Body 0, SOLAR SYSTEM BARYCENTER
         Reference frame: Frame 11, DE-125
         SPK Data Type  : Type 2
            Description : Fixed Width, Fixed Order Chebyshev
                          Polynomials: Pos
         UTC Start Time : 1989 OCT 19 01:35:00.000
         UTC Stop Time  : 1991 JAN 31 23:59:58.000
         ET Start Time  : 1989 OCT 19 01:35:56.182
         ET Stop time   : 1991 FEB 01 00:00:56.184
      ------------------------------------------------------------------
      ------------------------------------------------------------------
         Segment ID     : NAIF Source Ephemeris TEST/0.
         Target Body    : Body 1, MERCURY BARYCENTER
         Center Body    : Body 0, SOLAR SYSTEM BARYCENTER
         Reference frame: Frame 11, DE-125
         SPK Data Type  : Type 2
            Description : Fixed Width, Fixed Order Chebyshev
                          Polynomials: Pos
         UTC Start Time : 1989 OCT 19 01:35:00.000
         UTC Stop Time  : 1991 JAN 31 23:59:58.000
         ET Start Time  : 1989 OCT 19 01:35:56.182
         ET Stop time   : 1991 FEB 01 00:00:56.184
      ------------------------------------------------------------------
 
      ******************************************************************
 
 
               SPK Summary Options
 
         ( Q ) Quit, returning to main menu.
 
         ( F ) Summarize entire file.
         ( B ) Summarize by NAIF body ID code.
         ( T ) Summarize by time interval.
 
         Option: q
 
   Read the comments in the file cook_02.bsp
 
 
               SPACIT Options
 
         ( Q ) Quit.
         ( L ) Log SPACIT output to a file.
         ( T ) Convert transfer file to binary file.
         ( B ) Convert binary file to transfer file.
         ( S ) Summarize binary file.
         ( R ) Read comment area of binary file.
 
         Option: r
 
 
         Binary file  : cook_02.bsp
 
      ******************************************************************
 
      Comments From File: cook_02.bsp
 
      This is a sample binary SPK file for use in NAIF Toolkit
      cookbook and utility programs.
 
      For more information about the SPICELIB subroutine library
      and NAIF Toolkit software contact the NAIF task manager,
      Chuck Acton, at the following address:
 
              Navigational Ancillary Information Facility
              Jet Propulsion Laboratory
              Mail Stop 301-125L
              4800 Oak Grove Drive
              Pasadena, California 91109
 
      ******************************************************************
 
               SPACIT Options
 
         ( Q ) Quit.
         ( L ) Log SPACIT output to a file.
         ( T ) Convert transfer file to binary file.
         ( B ) Convert binary file to transfer file.
         ( S ) Summarize binary file.
         ( R ) Read comment area of binary file.
 
         Option:
 
   Quit the program.
 
 
               SPACIT Options
 
         ( Q ) Quit.
         ( L ) Log SPACIT output to a file.
         ( T ) Convert transfer file to binary file.
         ( B ) Convert binary file to transfer file.
         ( S ) Summarize binary file.
         ( R ) Read comment area of binary file.
 
         Option: q
 
         Quitting SPACIT.
 
