Index Page
SPACIT User's Guide

Table of Contents 


   SPACIT User's Guide
      Abstract
      Introduction
      References
      Changes
      File Naming and Usage Conventions

   Using SPACIT
      The SPACIT Main Menu
      SPACIT Options
         SPACIT Option: Q -- Quit.
         SPACIT Option: L -- Log SPACIT output to a text file.
         SPACIT Option: T -- Convert transfer file to binary file.
         SPACIT Option: B -- Convert binary file to transfer file.
         SPACIT Option: S -- Summarize binary file.
         CK summaries
         PCK summaries
         SPK summaries
         EK summaries
         SPACIT Option: R -- Read comment area of binary file.
      Integrating SPACIT Functionality into a Program

   Appendix: Sample SPACIT Session


Top

SPACIT User's Guide




Last revised on 2002 DEC 13 by B. V. Semenov.



Top

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.



Top

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).



Top

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).



Top

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.



Top

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.



Top

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.



Top

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.


Top

SPACIT Options



In this section, each of the options available on the SPACIT main menu will be described in detail.



Top

SPACIT Option: Q -- Quit.



Gracefully exit the program.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

EK summaries



The only type of summary currently available for an EK file is a summary of the entire file by segment.



Top

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.



Top

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.



Top

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.