Introduction =========================================================================== This document describes the structure and contents of the latest version of the NAIF cspice Toolkit for the Sun/Solaris/gcc(64bit) platform. ANSI C -------------------------------------------------------- Most C compilers come with a large set of compilation options that can be used when compiling source code. The compiler options we (NAIF) used when creating the various object libraries are discussed in the section "LIB" that appears later in this document. Version Information -------------------------------------------------------- Creation Date: Wed Apr 20 10:47:57 PDT 2005 Version : CSPICE.............V.N0058 (special engineering release for Sun/Solaris gcc 64-bit) Directory Structure and Contents =========================================================================== cspice -------------------------------------------------------- The cspice directory contains the file makeall.csh. This is a script that builds all of the object libraries and executables in the cspice Toolkit. (installation directory) | cspice | makeall.csh cspice also contains several subdirectories that will be described in more detail in the following sections. (installation directory) | cspice | data doc etc exe include lib src 1. DATA This directory contains example data files for use with various programs. These files are provided only as examples and are not intended for use for any serious analysis or planning work. 2. DOC This directory contains all of the documentation for this package. This includes User's Guides for the programs, Required Reading files for the library subsystems, and documents describing the contents and installation of this package. 3. ETC The subdirectories of this directory contain product-specific files that are neither source, documentation, nor data. This includes configuration files, set up files, and help files. 4. EXE This directory contains all of the package executables, and where applicable, scripts or batch files to run the executables. 5. INCLUDE This directory contains the header files that are required by applications that call library functions. 6. LIB This directory contains all of the object libraries. 7. SRC The subdirectories of this directory contain all of the source for the products in this package. DATA -------------------------------------------------------- The DATA directory contains all of the data that are pertinent for this package. These data files are intended only to be used with the cookbook programs, and are included only to help you get started using the cspice Toolkit. (installation directory) | cspice | data | cook_01.tc cook_01.tls cook_01.tpc cook_01.tsc cook_01.tsp cook_02.tc cook_02.tsp DOC -------------------------------------------------------- The DOC directory contains all of the NAIF documentation for this package that is available on-line. This includes the User's Guides for the programs, Required Reading files for the library subsystems, and documents describing the installation and contents of this package. (installation directory) | cspice | doc | dscriptn.txt version.txt cspice.idx *.ug *.req *.txt This package also includes HTML version of the documentation. It is provided in the HTML subdirectory of the DOC directory. The ``index.html'' file contains links to the individual HTML documents spread across numerous branches of this subdirectory tree. (installation directory) | cspice | doc | html | index.html ... ETC -------------------------------------------------------- The ETC directory contains all files for the cspice Toolkit products that are not source, documentation, or data such as set up files, configuration files or help files. (installation directory) | cspice | etc EXE -------------------------------------------------------- The EXE directory contains the cspice Toolkit executables and, where applicable, scripts to run executables. (installation directory) | cspice | exe | brief chronos ckbrief commnt simple states subpt tictoc inspekt mkspk spacit spkmerge tobin toxfr version INCLUDE -------------------------------------------------------- The INCLUDE directory contains all of the cspice Toolkit include files that are part of the public interface to the CSPICE library. Users will need to include the master include file SpiceUsr.h into their C code that references CSPICE functions. Code that references underlying f2c'd routines directly should include SpiceZfc.h as well. (installation directory) | cspice | include | SpiceCK.h SpiceCel.h SpiceEK.h SpiceEll.h SpicePln.h SpiceSPK.h SpiceUsr.h SpiceZdf.h SpiceZfc.h SpiceZim.h SpiceZmc.h SpiceZpl.h SpiceZpr.h SpiceZst.h f2c.h f2cMang.h fio.h fmt.h fp.h lio.h rawio.h signal1.h LIB -------------------------------------------------------- The LIB directory contains the object libraries for this cspice Toolkit package. All libraries are compiled using the following compiler options: -c -ansi -m64 -O2 -DNON_UNIX_STDIO The libraries contained in this directory are listed below. Each library is discussed in more detail later in the section devoted to the SRC directory. (installation directory) | cspice | lib | cspice.a csupport.a SRC -------------------------------------------------------- The SRC directory contains one subdirectory for each product in the cspice Toolkit. Each of these product directories contains the source code files and procedures to create the executable or object library. (installation directory) | cspice | src | brief_c chrnos_c ckbref_c commnt_c cook_c inspkt_c mkspk_c spacit_c cspice spkmrg_c csupport tobin_c toxfr_c versn_c BRIEF BRIEF is a utility program that allows you to summarize the ephemeris coverage for one or more SPK files. This directory contains the BRIEF main program, supporting routines, and a script to create the executable program brief. (installation directory) | cspice | src | brief_c | main.x brief.pgm *.c *.h mkprodct.csh CHRONOS CHRONOS is a utility program that allows you to easily convert from one representation of time to another. This directory contains the CHRONOS main program, supporting routines, and a script to create the executable program chronos. (installation directory) | cspice | src | chrnos_c | main.x chronos.pgm *.c mkprodct.csh CKBRIEF CKBRIEF is a utility program that allows you to summarize the ephemeris coverage for one or more CK files. This directory contains the CKBRIEF main program, supporting routines, and a script to create the executable program ckbrief. (installation directory) | cspice | src | ckbref_c | main.x ckbrief.pgm *.c mkprodct.csh COMMNT COMMNT is a utility program that is used to add comments, extract comments, read comments, or delete comments in SPICE SPK, CK and EK files. This directory contains the COMMNT main program and a script to create the executable file commnt. (installation directory) | cspice | src | commnt_c | main.x commnt.pgm *.h mkprodct.csh COOKBOOK The cookbook programs are sample programs that demonstrate how to use CSPICE routines to obtain state vectors, convert between different time representations, and solve simple geometry problems. This directory contains the COOKBOOK source files and a script to create the executable files. (installation directory) | cspice | src | cook_c | simple.pgm states.pgm subpt.pgm tictoc.pgm mkprodct.csh INSPEKT INSPEKT is a program that allows you to examine the contents of an events component of an E-kernel. This directory contains the INSPEKT main program, supporting routines, and a script to create the executable program inspekt. (installation directory) | cspice | src | inspkt_c | main.x inspekt.pgm *.c *.h mkprodct.csh MKSPK MKSPK is a program that creates SPK files from a reasonably general text file. This directory contains the MKSPK main program, supporting routines, and a script to create the executable program mkspk. (installation directory) | cspice | src | mkspk | main.x mkspk.pgm *.c mkprodct.csh SPACIT SPACIT (space-it) is a utility program that performs three functions: it converts transfer format SPK, CK and EK files to binary format, it converts binary SPK, CK and EK files to transfer format, and it summarizes the contents of binary SPK, CK and EK files. This directory contains the SPACIT main program, supporting routines, and a script to create the executable program spacit. (installation directory) | cspice | src | spacit_c | main.x spacit.pgm *.c *.h mkprodct.csh CSPICE This directory contains the CSPICE C source files needed for creating the CSPICE object library. The library contains about 1500 functions. This directory also contains a script for creating CSPICE. (installation directory) | cspice | src | cspice | *.c *.h mkprodct.csh SPKMERGE SPKMERGE is a utility program that is used to subset and merge a collection of SPK files into a single SPK file. This directory contains the SPKMERGE main program, supporting routines, and a script to create the executable file spkmerge. (installation directory) | cspice | src | spkmrg_c | main.x spkmerge.pgm *.c *.h mkprodct.csh CSUPPORT CSUPPORT is a C source code library that contains routines that support the Toolkit programs. These routines are not intended to be used by anyone except NAIF. These routines are not officially supported and may undergo radical changes such as calling sequence changes. They may even be deleted. Do not use them! This directory contains the CSUPPORT library source files and a script to create the object library csupport.a. (installation directory) | cspice | src | csupport | *.c *.h mkprodct.csh TOBIN TOBIN (to-bin) is a command line utility program that converts transfer format SPK, CK and EK files to binary format. This directory contains the TOBIN main program, supporting routines, and a script to create the executable program tobin. (installation directory) | cspice | src | tobin_c | main.x tobin.pgm *.h mkprodct.csh TOXFR TOXFR (to-transfer) is a command line utility program that converts binary format SPK, CK and EK files to transfer format. This directory contains the TOXFR main program, supporting routines, and a script to create the executable program toxfr. (installation directory) | cspice | src | toxfr_c | main.x toxfr.pgm *.h mkprodct.csh VERSION VERSION is a command line utility program that prints the current version number of the SPICE Toolkit. This directory contains the VERSION main program. and a script to create the executable program version. (installation directory) | cspice | src | version | main.x version.pgm mkprodct.csh Using the cspice Toolkit Package =========================================================================== After the installation has been completed successfully, there are a few things that you need to do to get started using this toolkit. We recommend that you print out the source code for the cookbook programs and examine it. Try running some of the cookbook programs yourself. The cookbook programs demonstrate how to use the library routines to obtain state vectors, convert between different time representations, and solve simple geometry problems. Once you're ready to get your hands dirty, you should read the required reading files provided in the package. The required reading files are located in the directory ``doc'' (see above) with the extension ``.req''. They are text files that describe families of functions and how they interact with each other. The most important required reading files are: CSPICE, TIME, FRAMES, SPK, CK, PCK, SCLK, KERNEL, and NAIF_IDS. You should read at least these. If this package includes ICY you should also read the ICY required reading. After you've done these things, you're ready to start programming with SPICE! Appendix -- NAIF's File Naming Conventions =========================================================================== NAIF follows a set of conventions for naming files based on the contents of the files. This allows you to find certain types of files in a directory tree quickly. Source code modules: *.pgm Fortran or C source files for program modules. *.for Fortran source code files. *.f *.inc Fortran include files. *.c C source code files. *.h C header files. *.pro IDL source code files. Executables, libraries, object files: (no ext) Executable files. *.exe *.o Object files. *.obj *.a Object library files. *.lib *.olb *.so *.dlm IDL library definition modules. *.def Documents: *.req Text format Required Reading files. *.ug Text format User's Guides. *.idx Permuted index files. *.txt Text format documentation files. *.tex TeX files. *.dvi Device independent files produced by TeX. *.ps Postscript files. *.pdf PDF files. *.htm HTML files. *.html SPICE Kernel files: *.bsp Binary SPK (ephemeris) files. *.tsp Transfer format SPK files. *.xsp *.bc Binary CK (pointing) files. *.tc Transfer format CK files. *.xc *.tpc Text PCK (planetary constants) files. *.bpc Binary PCK files. *.xpc Transfer format PCK files. *.ti Text IK (instrument parameters) files. *.tls Text LSK (leapseconds) files. *.tsc Text SCLK (spacecraft clock) files. *.tf Text FK (frame definitions) files. *.bes Binary EK (events) Sequence files. *.tes Transfer format EK Sequence files. *.xes *.ten Text EK Experimenter's Notebook files. *.tep Text EK Science Plan files. *.bdb Binary SPICE Database files. *.xdb Transfer format SPICE Database files. Build scripts: mkprodct.csh Unix build scripts. mkprodct.sh mkprodct.com VAX/Dec Alpha build scripts. mkprodct.bat PC/DOS, PS/WIN build scripts. mkprodct.mpw MAC MPW build scripts. mkprodct.mas MAC Apple Script build scripts.