Main Page Preface - Other Stuff (The Red Shirt topics) (MATLAB)
## Table of Contents
       Preface - Other Stuff (The Red Shirt topics) (MATLAB)
       Coding and Use Lessons
          Note About HTML Links
          NAIF Documentation
             Required Reading and Users Guides
             Library Source Code Documentation
             API Documentation
             Tutorials
          Text kernels
             Text kernel format
          Kernels for lessons
             Input kernel files
             Output
       Lesson 1: Kernel Management with the Kernel Subsystem
          Relevant Routines
          Requirements and References
          Programming Task
          Code Solution
             First, create a meta text kernel:
             Now the solution source code:
             Run the code example
       Lesson 2: The Kernel Pool
          Relevant Routines
          Requirements and References
          Programming Task
          Code Solution
             Run the code example
       Lesson 3: Coordinate Conversions
          Relevant Routines
          Requirements and References
          Programming Task
          Code Solution
             Run the code example
       Lesson 4: Advanced Time Manipulation Routines
          Relevant Routines
          Requirements and References
          Programming Task
          Code Solution
             Run the code example
       Lesson 5: Error Handling
          Relevant Routines:
          Requirements and References
          Programming Task
          Code Solution
             Run the code example
       Lesson 6: Windows, and Cells
          Relevant Routines
          Requirements and References
          Programming task:
          Code Solution
             Run the code example
       Lesson 7: Utility and Constants Routines
          Relevant Routines
          Requirements and References
          Programming Task
          Code Solution
             Run the code example
          Programming Task
          Code Solution
             Run the code example
Top # Preface - Other Stuff (The Red Shirt topics) (MATLAB) October 20, 2008 The extensive scope of the Mice system's functionality includes features the average user may not expect or appreciate, features NAIF refers to as "Other Stuff." This workbook includes a set of lessons to introduce the beginning to moderate user to such features. The lessons provide a brief description to several related sets of routines, associated reference documents, a programming task designed to teach the use of the routines, and an example solution to the programming problem. Top # Coding and Use Lessons This workbook contains lessons to demonstrate use of the less celebrated Mice routines. `1.` Kernel Management with the Kernel Subsystem `2.` The Kernel Pool `3.` Coordinate Conversions `4.` Advanced Time Manipulation Routines `5.` Error Handling `6.` Windows and Cells `7.` Utility and Constants Routines Top ## Note About HTML Links The HTML version of this lesson contains links pointing to various HTML documents provided with the Toolkit. All of these links are relative and, in order to function, require this document to be in a certain location in the Toolkit HTML documentation directory tree. In order for the links to be resolved, create a subdirectory called ``lessons'' under the ``doc/html'' directory of the Toolkit tree and copy this document to that subdirectory before loading it into a Web browser. Top ## NAIF Documentation The technical complexity of the various Mice subsystems mandates an extensive, user-friendly documentation set. The set differs somewhat depending on your choice of development language, FORTRAN, C, IDL, or MATLAB but provides the same information with regards to SPICE operation. The sources for a user needing information concerning the Mice System or other NAIF product: `--` Required Readings and Users Guides `--` Library Source Code Documentation `--` API Documentation `--` Tutorials Top ### Required Reading and Users Guides NAIF Required Reading (*.req) documents introduce the functionality of particular Mice subsystems:
       cells.req
       ck.req
       cspice.req
       daf.req
       das.req
       ek.req
       ellipses.req
       error.req
       frames.req
       icy.req
       intrdctn.req
       kernel.req
       mice.req
       naif_ids.req
       pck.req
       planes.req
       problems.req
       rotation.req
       scanning.req
       sclk.req
       sets.req
       spc.req
       spk.req
       symbols.req
       time.req
       windows.req
NAIF Users Guides (*.ug) describe the proper use of particular Mice tools:
       brief.ug
       chronos.ug
       ckbrief.ug
       commnt.ug
       convert.ug
       inspekt.ug
       mkspk.ug
       msopck.ug
       simple.ug
       spacit.ug
       spkdiff.ug
       spkmerge.ug
       states.ug
       subpt.ug
       tictoc.ug
       tobin.ug
       toxfr.ug
       version.ug
These text documents exist in the 'doc' directory of the main Toolkit directory:
          ../mice/doc/
HTML format documentation The Mice distributions include HTML versions of Required Readings and Users Guides, accessible from the HTML documentation directory:
         ../mice/doc/html/index.html
Top ### Library Source Code Documentation All SPICELIB and CSPICE source files include usage and design information incorporated in a comment block known as the "header." (Every toolkit includes either the SPICELIB or CSPICE library.) A header consists of several marked sections: `--` Procedure: Routine name and one line expansion of the routine's name. `--` Abstract: A tersely worded explanation describing the routine. `--` Copyright: An identification of the copyright holder for the routine. `--` Required_Reading: A list of Mice required reading documents relating to the routine. `--` Brief_I/O: A table of arguments, identifying each as either input, output, or both, with a very brief description of the variable. `--` Detailed_Input & Detailed_Output: An elaboration of the Brief_I/O section providing comprehensive information on argument use. `--` Parameters: Description and declaration of any parameters (constants) specific to the routine. `--` Exceptions: A list of error conditions the routine detects and signals plus a discussion of any other exceptional conditions the routine may encounter. `--` Files: A list of other files needed for the routine to operate. `--` Particulars: A discussion of the routine's function (if needed). This section may also include information relating to "how" and "why" the routine performs an operation and to explain functionality of routines that operate by side effects. `--` Examples: Descriptions and code snippets concerning usage of the routine. `--` Restrictions: Restrictions or warnings concerning use. `--` Literature_References: A list of sources required to understand the algorithms or data used in the routine. `--` Author_and_Institution: The names and affiliations for authors of the routine. `--` Version: A list of edits and the authors of those edits made to the routine since initial delivery to the Mice system. The source code for Mice products is stored in 'src' sub-directory of the main Mice directory:
          ../mice/src/
Find the CSPICE library source code in:
          ../mice/src/cspice/
Note: The CSPICE source files have two forms: C files created by the f2c conversion process on a SPICELIB files, indicated with a name of the form "module.c," and wrappers files indicated by names of the form "module_c.c" The f2c converted source code is very difficult to read, refer to the wrapper routines if possible. In some cases, NAIF replaced an f2c converted file with a hand written version. Top ### API Documentation The Mice package includes the CSPICE Reference Guide, an index of all CSPICE wrapper APIs with hyperlinks to API specific documentation. Each API documentation page includes cross-links to any other wrapper API mentioned in the document and links to the wrapper source code.
          ...mice/doc/html/cspice/index.html
Also included is Mice Reference Guide, an index of all Mice APIs with hyperlinks to API specific documentation. Each API documentation page includes cross-links to any other Mice APIs mentioned in the document and a link to the API documentation for the CSPICE routine called by the Mice interface.
          ...mice/doc/html/mice/index.html
This Mice API documentation (the same information as in the Reference Guide but without hyperlinks) is also available from the Matlab "help" command:
       >> help cspice_illum
        -Abstract

           CSPICE_ILLUM calculates the illumination angles at a specified
           surface point of a target body.

                                       ...
Top ### Tutorials A set of Microsoft PowerPoint presentations provide a general overview of the complete Mice toolkit. Download the set at:
          http://naif.jpl.nasa.gov/naif/tutorials.html
Access individual files in the 'office/individual_docs/' directory; an archive of all tutorial files is available in the 'office/packages/' directory. Top ## Text kernels Several workbooks use SPICE text kernels. SPICE identifies a text kernel as an ASCII text file containing the mark-up tags the kernel subsystem requires to identify data assignments in that file, and "name=value" data assignments. The subsystem uses two tags:
          \begintext
and
          \begindata
to mark information blocks within the text kernel. The \begintext tag specifies all text following the tag as comment information to be ignored by the subsystem. Things to know: `1.` The \begindata tag marks the start of a data definition block. The subsystem processes all text following this marker as SPICE kernel data assignments until finding a \begintext marker. `2.` The kernel subsystem defaults to the \begintext mode until the parser encounters a \begindata tag. Once in \begindata mode the subsystem processes all text as variable assignments until the next \begintext tag. `3.` Enter the tags as the only text on a line, i.e.:
          \begintext

             ... commentary information on the data assignments ...

          \begindata

             ... data assignments ...
`4.` CSPICE delivery N0059 added to the CSPICE and Icy text kernel parsers the functionality to read non native text kernels, i.e. a Unix compiled library can read a MS Windows native text kernel, a MS Windows compiled library can read a Unix native text kernel. Mice acquires this capability from CSPICE. `5.` With regards to the FORTRAN distribution, as of delivery N0057 the FURNSH call includes a line terminator check, signaling an error on any attempt to read non-native text kernels. Top ### Text kernel format Scalar assignments.
          VAR_NAME_DP  = 1.234
          VAR_NAME_INT = 1234
          VAR_NAME_STR = 'FORBIN'
Please note the use of a single quote in string assignments. Vector assignments. Vectors must contain the same type data.
          VEC_NAME_DP  = ( 1.234   , 45.678  , 901234.5 )
          VEC_NAME_INT = ( 1234    , 456     , 789      )
          VEC_NAME_STR = ( 'FORBIN', 'FALKEN', 'ROBUR'  )

          also

          VEC_NAME_DP  = ( 1.234,
                          45.678,
                          901234.5 )

          VEC_NAME_STR = ( 'FORBIN',
                           'FALKEN',
                           'ROBUR' )
Time assignments.
          TIME_VAL = @31-JAN-2003-12:34:56.798
          TIME_VEC = ( @01-DEC-2004, @15-MAR-2004 )
The at-sign character '@' indicates a time string. The pool subsystem converts the strings to double precision TDB (a numeric value). Please note, the time strings must not contain embedded blanks. WARNING - a TDB string is not the same as a UTC string. The above examples depict direct assignments via the '=' operator. The kernel pool also permits incremental assignments via the '+=' operator. Please refer to the kernels required reading, kernel.req, for additional information. Top ## Kernels for lessons Top ### Input kernel files The following kernels are used in examples provided in these lessons:
          FILE NAME                TYPE  DESCRIPTION
          -----------------------  ----  ----------------------
          naif0008.tls             LSK   Generic LSK
          leapseconds.tls          LSK   The current leapseconds
                                         kernel (naif0008.tls as
                                         of Jan 2006)
          de405s.bsp               SPK   Planet Ephemeris SPK
          pck00008.tpc             PCK   Generic PCK
These SPICE kernels are included in the lesson package available from the NAIF server at JPL:
       ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/
Top ### Output The code examples listed in this workbook include corresponding outputs for the described inputs. The output of a given example on a particular platform may not exactly match that shown since compilers and math libraries differ between platform architectures. Top # Lesson 1: Kernel Management with the Kernel Subsystem Lesson Goals: This lesson demonstrates use of the kernel subsystem to load, unload, and list loaded kernels. This lesson requires creation of a SPICE meta kernel. Top ## Relevant Routines `--` cspice_furnsh loads the meta kernel and the SPICE kernels listed within that kernel. `--` cspice_ktotal retrieves the number of SPICE kernels loaded by the kernel subsystem. `--` cspice_kdata returns information about each loaded kernel. `--` cspice_unload removes a kernel and deletes any pool variables defined by that kernel from the kernel subsystem. `--` cspice_kclear deletes all kernel pool data from the kernel subsystem. Top ## Requirements and References Knowledge of information in the kernels.req document, the mk.ppt and intro_to_kernels.ppt tutorial files. Top ## Programming Task Write a program to load a meta kernel, interrogate the Mice system for the names and types of all loaded kernels, then demonstrate the unload functionality and the resulting effects. Top ## Code Solution Top ### First, create a meta text kernel: You can use two versions of a meta kernel with code examples (meta.tm) in this lesson. Either a kernel with explicit path information:
       \begindata

          KERNELS_TO_LOAD = ( 'kernels/spk/de405s.bsp',
                              'kernels/pck/pck00008.tpc',
                              'kernels/lsk/leapseconds.tls')

       \begintext
... or a more generic meta kernel using the PATH_VALUES/PATH_SYMBOLS functionality to declare path names as variables:
       \begintext

       Define the paths to the kernel directory. Use the PATH_SYMBOLS
       as aliases to the paths.

       \begindata

          PATH_VALUES     = ( 'kernels/lsk',
                              'kernels/spk',
                              'kernels/pck' )

          PATH_SYMBOLS    = ( 'LSK', 'SPK', 'PCK' )

          KERNELS_TO_LOAD = ( '$LSK/naif0008.tls',
                              '$SPK/de405s.bsp',
                              '$PCK/pck00008.tpc' )

       \begintext
Top ### Now the solution source code:
       function kernel()

          %
          % Assign the path name of the meta kernel to META.
          %
          META = 'meta.tm';

          %
          % Load the meta kernel then use KTOTAL to interrogate the SPICE
          % kernel subsystem.
          %
          cspice_furnsh( META )

          count = cspice_ktotal( 'ALL' );
          fprintf( 'Kernel count after load: %i\n', count )

          %
          % Loop over the number of files; interrogate the SPICE system
          % with kdata_c for the kernel names and the type. 'found'
          % returns a boolean indicating whether any kernel files of
          % the specified type were loaded by the kernel subsystem.
          % This example ignores checking 'found' as kernels are known
          % to be loaded.
          %
          for i = 1:count
             [ file, type, source, handle, found] = cspice_kdata(i, 'ALL');
             fprintf( 'File   %s\n', file )
             fprintf( 'Type   %s\n', type )
             fprintf( 'Source %s\n\n', source )
          end

          %
          % Unload one kernel then check the count.
          %
          cspice_unload( '/kernels/gen/spk/de405s.bsp')
          count = cspice_ktotal( 'ALL' );

          %
          % The subsystem should report one less kernel.
          %
          fprintf( 'Kernel count after one unload : %i\n', count )

          %
          % Now unload the meta kernel. This action unloads all
          % files listed in the meta kernel.
          %
          cspice_unload( META )

          %
          % Check the count. Icy should return a count of zero.
          %
          count = cspice_ktotal( 'ALL');
          fprintf( 'Kernel count after meta unload: %i\n', count )

          %
          % Done. Unload the kernels.
          %
          cspice_kclear
Top ### Run the code example First we see the number of all loaded kernels returned from the cspice_ktotal call:
        Kernel count after load:   4
Now the cspice_kdata loop returns the name of each loaded kernel, the type of kernel (SPK, CK, TEXT, etc.) and the source of the kernel - the mechanism that loaded the kernel. The source either identifies a meta kernel, or contains an empty string. An empty source string indicates a direct load of the kernel with a cspice_furnsh call.
       File   meta.tm
       Type   META
       Source

       File   kernels/spk/de405s.bsp
       Type   SPK
       Source meta.tm

       File   kernels/pck/pck00008.tpc
       Type   TEXT
       Source meta.tm

       File   kernels/lsk/naif0008.tls
       Type   TEXT
       Source meta.tm

       Kernel count after one unload :   3
       Kernel count after meta unload:   0
Top # Lesson 2: The Kernel Pool Lesson Goals: The lesson demonstrates the Mice system's facility to retrieve different types of data (string, numeric, scalar, array) from the kernel pool. For the code examples, use this generic text kernel (cassini.tm) containing PCK-type data, kernels to load, and example time strings:
       \begintext

       Ring model data.

       \begindata

          BODY699_RING1_NAME     = 'A Ring'
          BODY699_RING1          = (122170.0 136780.0 0.1 0.1 0.5)

          BODY699_RING1_1_NAME   = 'Encke Gap'
          BODY699_RING1_1        = (133405.0 133730.0 0.0 0.0 0.0)

          BODY699_RING2_NAME     = 'Cassini Division'
          BODY699_RING2          = (117580.0 122170.0 0.0 0.0 0.0)

       \begintext

       The kernel pool recognizes values preceded by '@' as time
       values. When read, the kernel subsystem converts these
       representations into double precision ephemeris time.

       Caution: The kernel subsystem interprets the time strings
       identified by '@' as TDB. The same string passed as input
       to @STR2ET is processed as UTC.

       The three expressions stored in the EXAMPLE_TIMES array represent
       the same epoch.

       \begindata

          EXAMPLE_TIMES       = ( @APRIL-1-2004-12:34:56.789,
                                  @4/1/2004-12:34:56.789,
                                  @JD2453097.0242684
                                 )

       \begintext

       Name the kernels to load. Use path symbols.

       \begindata

          PATH_VALUES     = ('kernels/spk',
                             'kernels/pck',
                             'kernels/lsk')

          PATH_SYMBOLS    = ('SPK' , 'PCK' , 'LSK' )

          KERNELS_TO_LOAD = ( '$SPK/de405s.bsp',
                              '$PCK/pck00008.tpc',
                              '$LSK/leapseconds.tls')

       \begintext
Top ## Relevant Routines `--` cspice_gipool retrieves integer values from the kernel subsystem. `--` cspice_gdpool retrieves double precision values from the kernel subsystem `--` cspice_gcpool retrieves character values from the kernel subsystem `--` cspice_dtpool returns data (name, type, size) describing a kernel pool variable. `--` cspice_gnpool retrieves the names of kernel pool variables matching a given template. Top ## Requirements and References Knowledge of the material in the kernels.req document and the intro_to_kernels.ppt tutorial file. The main references for pool routines are found in the help command or API documentation for the particular routines. Top ## Programming Task Write a program to retrieve particular string and numeric text kernel variables, both scalars and arrays. Interrogate the kernel pool for assigned variable names. Top ## Code Solution
       function kervar()

          %
          % Define the max number of kernel variables
          % of concern for this examples.
          %
          N_ITEMS =  20;

          %
          % Load the example kernel containing the kernel variables.
          % The kernels defined in KERNELS_TO_LOAD load into the
          % kernel pool with this call.
          %
          cspice_furnsh( 'cassini.tm' )

          %
          % Initialize the start value. This values indicates
          % index of the first element to return if a kernel
          % variable is an array. START = 1 indicates return everything.
          % START = 2 indicates return everything but the first element.
          %
          START = 1;

          %
          % Set the template for the variable names to find. Let's
          % look for all variables containing  the string RING.
          % Define this with the wildcard template '*RING*'. Note:
          % the template '*RING' would match any variable name
          % ending with the RING string.
          %
          tmplate = '*RING*';

          %
          % We're ready to interrogate the kernel pool for the
          % variables matching the template. cspice_gnpool tells us:
          %
          %  1. Does the kernel pool contain any variables that
          %     match the template (value of found).
          %  2. If so, how many variables?
          %  3. The variable names. (cvals, an array of strings)
          %

          [cvals,found] = cspice_gnpool( tmplate, START, N_ITEMS );

          if ( found )
             fprintf( 'No. variables matching template: %i\n\n', ...
                                                   size(cvals,1) )
          else
             disp( 'No kernel variables matched template.\n\n' )
          return
          end

          %
          % For convenience, convert the character array to a cell of
          % strings.
          %
         cvals = cellstr( cvals );

          %
          % Okay, now we know something about the kernel pool
          % variables of interest to us. Let's find out more...
          %
          for i=1:size(cvals,1)

             %
             % Use cspice_dtpool to return the dimension and type,
             % C (character) or N (numeric), of each pool
             % variable name in the cvals array. We know 'found'
             % will have value true.
             %
             [found, dim, type] = cspice_dtpool( cvals(i) );

             disp( cvals(i) )
             fprintf( ' No. items: %i Of type: %s\n', dim, type );

             %
             % Test character equality, 'N' or 'C'.
             %
             switch type

                case 'N'

                   %
                   % If 'type' equals 'N', we found a numeric array.
                   % In this case any numeric array will be an array
                   % of double precision numbers ('doubles').
                   % cspice_gdpool retrieves doubles from the
                   % kernel pool.
                   %
                   [dvars,found] = cspice_gdpool( cvals(i), ...
                                                  START,    ...
                                                  N_ITEMS );
                   fprintf('  Numeric value: %13.6f\n', dvars )

                case 'C'

                   %
                   % If 'type' equals 'C', we found a string array.
                   % cspice_gcpool retrieves string values from the
                   % kernel pool.
                   %
                   [cvars,found] = cspice_gcpool( cvals(i), ...
                                                  START,    ...
                                                  N_ITEMS );

                   for j=1:size(cvars,1)

                      fprintf('  String value: %s\n', cvars(j,:) )

                   end

             end

             disp(' ')

          end

          %
          % Now look at the time variable EXAMPLE_TIMES. Extract this
          % value as an array of doubles.
          %
          [dvars,found] = cspice_gdpool( 'EXAMPLE_TIMES', START, N_ITEMS );

          disp( 'EXAMPLE_TIMES' )
          fprintf('  Time value:  %24.6f\n', dvars)

          %
          % Done. Unload the kernels.
          %
          cspice_kclear
Top ### Run the code example The program runs and first reports the number of kernel pool variables matching the template, 6.
       No. variables matching template:   6
The program then loops over the cspice_dtpool 6 times, reporting the name of each pool variable, the number of data items assigned to that variable, and the variable type. Within the cspice_dtpool loop, a second loop outputs the contents of the data variable using cspice_gcpool or cspice_gdpool.
           'BODY699_RING1'

        No. items: 5 Of type: N
         Numeric value: 122170.000000
         Numeric value: 136780.000000
         Numeric value:      0.100000
         Numeric value:      0.100000
         Numeric value:      0.500000

           'BODY699_RING2'

        No. items: 5 Of type: N
         Numeric value: 117580.000000
         Numeric value: 122170.000000
         Numeric value:      0.000000
         Numeric value:      0.000000
         Numeric value:      0.000000

           'BODY699_RING1_1'

        No. items: 5 Of type: N
         Numeric value: 133405.000000
         Numeric value: 133730.000000
         Numeric value:      0.000000
         Numeric value:      0.000000
         Numeric value:      0.000000

           'BODY699_RING1_NAME'

        No. items: 1 Of type: C
         String value: A Ring

           'BODY699_RING2_NAME'

        No. items: 1 Of type: C
         String value: Cassini Division

           'BODY699_RING1_1_NAME'

        No. items: 1 Of type: C
         String value: Encke Gap
Note the final time value differs from the previous values in the final three decimal places despite the intention that all three strings represent the same time. This results from round-off when converting a decimal Julian day representation to the seconds past J2000 ET representation.
       EXAMPLE_TIMES
         Time value:          134094896.789000
         Time value:          134094896.789000
         Time value:          134094896.789753
Top # Lesson 3: Coordinate Conversions Lesson Goals: The Mice system provides functions to convert coordinate tuples between Cartesian and various non Cartesian coordinate systems including conversion between geodetic and rectangular coordinates. This lesson presents these coordinate transform routines for rectangular, cylindrical, and spherical systems. Top ## Relevant Routines `--` cspice_latrec, latitudinal to rectangular `--` cspice_latcyl, latitudinal to cylindrical `--` cspice_latsph, latitudinal to spherical `--` cspice_reccyl, rectangular to cylindrical `--` cspice_recgeo, rectangular to geodetic `--` cspice_reclat, rectangular to latitudinal `--` cspice_recsph, rectangular to spherical `--` cspice_recrad, rectangular to right ascension - declination `--` cspice_sphrec, spherical to rectangular `--` cspice_sphcyl, spherical to cylindrical `--` cspice_sphlat, spherical to latitudinal `--` cspice_cyllat, cylindrical to latitudinal `--` cspice_cylsph, cylindrical to spherical `--` cspice_cylrec, cylindrical to rectangular `--` cspice_georec, geodetic to rectangular Top ## Requirements and References Basic knowledge of the standard coordinate systems used in celestial mechanics. The contents of concepts.ppt and derived_quant.ppt tutorial files. Top ## Programming Task Write a program to convert a Cartesian 3-vector representing some location to the other coordinate representations. Use the position of the Moon with respect to Earth in an inertial and non-inertial reference frame as the example vector. Top ## Code Solution
       function coord()

          %
          % Define the inertial and non inertial frame names.
          %
          % Initialize variables or set type. All variables
          % used in a PROMPT construct must be initialized
          % as strings.
          %
          INRFRM = 'J2000';
          NONFRM = 'IAU_EARTH';

          %
          % Load the needed kernels using a cspice_furnsh call on the
          % meta kernel.
          %
          cspice_furnsh( 'meta.tm' )

          %
          % Prompt the user for a time string. Convert the
          % time string to ephemeris time J2000 (ET).
          %
          timstr = input( 'Time of interest: ', 's' );
          et     = cspice_str2et( timstr );

          %
          % Access the kernel pool data for the triaxial radii of the
          % Earth, rad[0] holds the equatorial radius, rad[2]
          % the polar radius.
          %
          rad = cspice_bodvrd( 'EARTH', 'RADII', 3 );

          %
          % Calculate the flattening factor for the Earth.
          %
          %          equatorial_radius - polar_radius
          % flat =   ________________________________
          %
          %                equatorial_radius
          %
          flat = (rad(1) - rad(3))/rad(1);

          %
          % Make the cspice_spkpos call to determine the apparent
          % position of the Moon w.r.t. to the Earth at 'et' in the
          % inertial frame.
          %
          [pos, ltime] = cspice_spkpos('MOON', et, INRFRM, 'LT+S','EARTH');

          %
          % Show the current frame and time.
          %
          disp( [' Time : ' timstr ] )
          disp( [' Inertial Frame: ' INRFRM  ] )

          %
          % First convert the position vector
          % X = pos(1), Y = pos(2), Z = pos(3), to RA/DEC.
          %
          [ range, ra, dec ] = cspice_recrad( pos );
          disp('   Range/Ra/Dec' )
          fprintf('    Range: %f\n'  , range )
          fprintf('    RA   : %f\n'  ,  ra * cspice_dpr )
          fprintf('    DEC  : %f\n\n', dec* cspice_dpr )

          %
          % ...latitudinal coordinates...
          %
          [ range, lon, lat ] = cspice_reclat( pos );
          disp('   Latitudinal ' )
          fprintf('    Rad  : %f\n'  , range )
          fprintf('    Lon  : %f\n'  , lon * cspice_dpr )
          fprintf('    Lat  : %f\n\n', lat * cspice_dpr )

          %
          % ...spherical coordinates use the colatitude,
          % the angle from the Z axis.
          %
          [ range, colat, lon ] = cspice_recsph( pos );
          disp( '   Spherical' )
          fprintf('    Rad  : %f\n'  , range )
          fprintf('    Lon  : %f\n'  , lon   * cspice_dpr )
          fprintf('    Colat: %f\n\n', colat * cspice_dpr )

          %
          % Make the cspice_spkpos call to determine the apparent
          % position of the Moon w.r.t. to the Earth at 'et' in the
          % non-inertial, body fixed, frame.
          %
          [pos, ltime] = cspice_spkpos('MOON', et, NONFRM, 'LT+S','EARTH');

          disp( ['  Non-inertial Frame: ' NONFRM ] )

          %
          % ...latitudinal coordinates...
          %
          [ range, lon, lat ] = cspice_reclat( pos );
          disp('   Latitudinal ' )
          fprintf('    Rad  : %f\n'  , range )
          fprintf('    Lon  : %f\n'  , lon * cspice_dpr )
          fprintf('    Lat  : %f\n\n', lat * cspice_dpr )

          %
          % ...spherical coordinates use the colatitude,
          % the angle from the Z axis.
          %
          [ range, colat, lon ] = cspice_recsph( pos );
          disp( '   Spherical' )
          fprintf('    Rad  : %f\n'  , range )
          fprintf('    Lon  : %f\n'  , lon   * cspice_dpr )
          fprintf('    Colat: %f\n\n', colat * cspice_dpr )

          %
          % ...finally, convert the position to geodetic coordinates.
          %
          [ lon, lat, range ] = cspice_recgeo( pos, rad(1), flat );
          disp( '   Geodetic' )
          fprintf('    Rad  : %f\n'  , range )
          fprintf('    Lon  : %f\n'  , lon * cspice_dpr )
          fprintf('    Lat  : %f\n\n', lat * cspice_dpr )

          %
          % Done. Unload the kernels.
          %
          cspice_kclear
Top ### Run the code example Input a time/date at which to calculate the Moon's position. (the 'TDB' tag indicates a Barycentric Dynamical Time value).
       Time of interest: Feb 3 2002 TDB
Examine the Moon position in the J2000 inertial frame, display the time and frame:
        Time : Feb 3 2002 TDB
         Inertial Frame: J2000
Convert the Moon Cartesian coordinates to right ascension declination.
         Range/Ra/Dec
           Range: 369340.815193
           RA   : 203.643686
           DEC  : -4.979010
Latitudinal. Note the difference in the expressions for longitude and right ascension though they represent a measure of the same quantity. The RA/DEC system measures RA in the interval [0,2Pi). Latitudinal coordinates measures longitude in the interval (-Pi,Pi].
          Latitudinal
           Rad  : 369340.815193
           Lon  : -156.356314
           Lat  : -4.979010
Spherical. Note the difference between the expression of latitude in the Latitudinal system and the corresponding Spherical colatitude. The spherical coordinate system uses the colatitude, the angle measure away from the positive Z axis. Latitude is the angle between the position vector and the x-y (equatorial) plane with positive angle defined as toward the positive Z direction
          Spherical
           Rad  : 369340.815193
           Lon  : -156.356314
           Colat: 94.979010
The same position look-up in a body fixed (non-inertial) frame, IAU_EARTH.
         Non-inertial Frame: IAU_EARTH
Latitudinal coordinates return the geocentric latitude.
          Latitudinal
           Rad  : 369340.815193
           Lon  : 70.973950
           Lat  : -4.989675
Spherical.
          Spherical
           Rad  : 369340.815193
           Lon  : 70.973950
           Colat: 94.989675
Geodetic. The cartographic lat/lon.
          Geodetic
           Rad  : 362962.836755
           Lon  : 70.973950
           Lat  : -4.990249
Top # Lesson 4: Advanced Time Manipulation Routines Lesson Goals: Introduce the routines used for advanced manipulation of time strings. Understand the concept of ephemeris time (ET) as used in Mice. Top ## Relevant Routines `--` cspice_str2et converts time strings to ephemeris time (ET). `--` cspice_timout formats a time string output. `--` cspice_tpictr creates a format template for use in cspice_timout. `--` cspice_tsetyr sets the reference century/year for two digit representation of the year. Top ## Requirements and References Knowledge of the time.req document, the time.ppt, lsk_and_sclk.ppt, and other_functions.ppt tutorial files. Also, examine the header of cspice_timout for a list of the string markers used by cspice_timout and cspice_tpictr to describe time string format. Always keep in mind cspice_str2et assumes 'UTC' unless indicated otherwise. Top ## Programming Task Demonstrate the advanced functions of the time utilities with regard to formatting of time strings for output. Formatting options include altering calendar representations of the time strings. Convert time-date strings between different Mice-supported formats. Top ## Code Solution Caution: Be sure to assign sufficient string lengths for time formats/pictures.
       function xtic()

          %
          % Assign the LSK variable to the name of the leapsecond,
          % kernel and create an arbitrary time string.
          %
          % Define the maximum length for any string, 80
          % characters plus one null terminator for C.
          %
          CALSTR    = 'Mar 15, 2003 12:34:56.789 AM PST';
          LSK       = 'kernels/lsk/naif0008.tls';
          AMBIGSTR  = 'Mar 15, 79 12:34:56';
          T_FORMAT1 = 'Wkd Mon DD HR:MN:SC PDT YYYY ::UTC-7';
          T_FORMAT2 = 'Wkd Mon DD HR:MN ::UTC-7 YR (JULIAND.##### JDUTC)';

          %
          % Load the leapseconds kernel.
          %
          cspice_furnsh( LSK )
          disp( [ 'Original time string       : ' CALSTR ] )

          %
          % Convert the time string to the number of ephemeris
          % seconds past the J2000 epoch. This is the most common
          % internal time representation used by the CSPICE
          % system; CSPICE refers to this as ephemeris time (ET).
          %
          et = cspice_str2et( CALSTR );
          fprintf( 'Corresponding ET           : %13.6f\n', et )

          %
          % Make a picture of an output format. Describe a Unix-like
          % time string then send the picture and the 'et' value through
          % cspice_timout to format and convert the ET representation
          % of the time string into the form described in cspice_timout.
          % The '::UTC-7' token indicates the time zone for the 'timstr'
          % output - PDT. 'PDT' is part of the output, but not a time
          % system token.
          %
          timstr = cspice_timout( et, T_FORMAT1);
          fprintf( 'Time in string format 1    : %s\n', timstr )

          timstr = cspice_timout( et, T_FORMAT2);
          fprintf( 'Time in string format 2    : %s\n', timstr )

          %
          % Why create a picture by hand when Mice can do it for you?
          % Input a string to cspice_tpictr with the format of interest.
          % 'ok' returns a boolean indicating whether an error occurred
          % while parsing the picture string, if so, an error diagnostic
          % message returns in 'xerror'. In this example the picture
          % string is known as correct.
          %
          pic = '12:34:56.789 P.M. PDT January 1, 2006';
          [ pictr, ok, xerror] = cspice_tpictr(pic);

          if ( ~ok )
             error( xerror )
          end

          timstr = cspice_timout( et, pictr);
          fprintf( 'Time in string format 3    : %s\n', timstr )

          %
          % Two digit year representations often cause problems due to
          % the ambiguity of the century. The routine cspice_tsetyr gives
          % the user the ability to set a default range for 2 digit year
          % representation. SPICE uses 1969AD as the default start
          % year so the numbers inclusive of 69 to 99 represent years
          % 1969AD to 1999AD, the numbers inclusive of 00 to 68 represent
          % years 2000AD to 2068AD.
          %
          % The defined time string 'AMBIGSTR' contains a two-digit
          % year. Since the SPICE base year is 1969, the time subsystem
          % interprets the string as 1979.
          %
          et1 = cspice_str2et( AMBIGSTR );

          %
          % Set 1980 as the base year causes SPICE to interpret the
          % time string's "79" as 2079.
          %
          cspice_tsetyr( 1980 )
          et2 = cspice_str2et( AMBIGSTR );

          %
          % Calculate the number of years between the two ET
          % representations, ~100.
          %
          fprintf( 'Years between evaluations  :  %16.6f\n', ...
                                      (et2 - et1)/cspice_jyear )

          %
          % Reset the default year to 1969.
          %
          cspice_tsetyr( 1969 )

          %
          % Done. Unload the kernels.
          %
          cspice_kclear
Top ### Run the code example
       Original time string      : Mar 15, 2003 12:34:56.789 AM PST
       Corresponding ET          : 100989360.974561
       Time in string format 1   : Sat Mar 15 01:34:56 PDT 2003
       Time in string format 2   : Sat Mar 15 01:34 03 (2452713.85760 JDUTC)
       Time in string format 3   : 01:34:56.789 A.M. PDT March 15, 2003
       Years between evaluations :        100.000000
Top # Lesson 5: Error Handling Lesson Goal: The Mice error subsystem differs from CSPICE and SPICELIB packages in that the user cannot alter the state of the error subsystem, rather the user can respond to an error signal using try-catch blocks. This block natively receives and processes any SPICE error signaled from Mice. The user can therefore "catch" an error signal so as to respond in an appropriate manner. Top ## Relevant Routines: `--` MATLAB try-catch blocks grants the user control over response to error Mice signals. Top ## Requirements and References Knowledge of material in the error.req document and the exceptions.ppt tutorial file. Comprehension of the catch/throw concept. Top ## Programming Task Write an interactive program to return a state vector based on a user's input. Code the program with the capability to recover from user input mistakes, inform the user of the mistake, then continue to run. Top ## Code Solution
       function aderr()

          %
          % Set initial parameters.
          %
          SPICETRUE =  logical(1);
          SPICEFALSE=  logical(0);
          doloop    =  SPICETRUE;

          %
          % Load the data we need for state evaluation.
          %
          cspice_furnsh( 'meta.tm' )

          %
          % Start our input query loop to the user.
          %
          while (doloop)

             %
             % For simplicity, we request only one input.
             % The program calculates the state vector from
             % Earth to the user specified target 'targ' in the
             % J2000 frame, at ephemeris time zero, using
             % aberration correction LT+S (light time plus
             % stellar aberration).
             %
             targ = input( 'Target: ', 's' );

             if ( strcmpi( targ, 'NONE') )

                %
                % An exit condition. If the user inputs NONE
                % for a target name, set the loop to stop...
                %
                doloop = SPICEFALSE;

             else

                %
                % ...otherwise evaluate the state between the Earth
                % and the target. Initialize an error handler.
                %
                try

                   %
                   % Perform the state lookup.
                   %
                   [ state, ltime] = cspice_spkezr( targ, 0., 'J2000', ...
                                                              'LT+S' , ...
                                                              'EARTH');

                   %
                   % No error, output the state.
                   %
                   fprintf( 'R : %17.5f %17.5f %17.5f\n', state(1:3)' )
                   fprintf( 'V : %17.5f %17.5f %17.5f\n', state(4:6)' )
                   fprintf( 'LT: %f\n\n', ltime )

                catch

                   %
                   % What if cspice_spkezr signaled an error?
                   % Then Mice signals an error to MATLAB.
                   %
                   % Examine the value of 'lasterr' to retrieve the
                   % error message.
                   %
                   disp( lasterr )
                   disp(' ')

               end

             end

          end

          %
          % Done. Unload the kernels.
          %
          cspice_kclear
Top ### Run the code example Now run the code with various inputs to observe behavior. Begin the run using known astronomical bodies. Recall the Mice default units are kilometers, kilometers per second, kilograms, and seconds. The 'R' marker identifies the (X,Y,Z) position of the body in kilometers, the 'V' marker identifies the velocity of the body in kilometers per second, and the 'LT' marker identifies the one-way light time between the bodies at the requested evaluation time.
       Target: Moon
       R :     -291584.61659     -266693.40236      -76095.64756
       V :           0.64353          -0.66608          -0.30132
       LT: 1.342311

       Target: Mars
       R :   234536077.41914  -132584383.59557   -63102685.70619
       V :          30.95976          28.93646          13.11449
       LT: 923.001080

       Target: Pluto barycenter
       R : -1451304742.83853 -4318174144.40632  -918251433.58736
       V :          35.03838           3.06560          -0.01514
       LT: 15501.258293

       Target: Puck
       SPICE(SPKINSUFFDATA): [spkezr_c->SPKEZR->SPKEZ->SPKAPP->SPKSSB->
       SPKGEO] Insufficient ephemeris data has been loaded to compute
       the state of 715 (PUCK) relative to 0 (SOLAR SYSTEM BARYCENTER)
       at the ephemeris epoch 2000 JAN 01 12:00:00.000.
Perplexing. What happened? The kernel files named in meta.tm did not include ephemeris data for Puck. When the SPK subsystem tried to evaluate Puck's position, the evaluation failed due to lack of data, so an error signaled. The above error signifies an absence of state information at ephemeris time 2000 JAN 01 12:00:00.000 (the requested time, ephemeris time zero). Try another look-up.
       Target: Casper
       SPICE(IDCODENOTFOUND): [spkezr_c->SPKEZR] The target, 'Casper',
       is not a recognized name for an ephemeris object. The cause of this
       problem may be that you need an updated version of the SPICE Toolkit.
       Alternatively you may call SPKEZ directly if you know the SPICE ID
       codes for both 'Casper' and 'EARTH'
An easy to understand error. The SPICE system does not contain information on a body named 'Casper.' Another look-up, this time, something easy.
       Target: Venus
       R :   -80970027.54053  -139655772.57390   -53860125.95820
       V :          31.16969         -27.00018         -12.31622
       LT: 567.655074
The look-up succeeded despite two errors in our run. The Mice system can respond to error conditions (not system errors) in much the same fashion as languages with catch/throw instructions. Top # Lesson 6: Windows, and Cells Lesson Goal: This lesson introduces the concepts of the SPICE data type 'window'. The Mice implementation of a SPICE windows consists of double precision Nx1 arrays with N an even or zero value. A 'window' is a type of cell containing ordered, double precision values describing a collection of zero or more intervals. We define an interval, 'i', as all double precision values bounded by and including an ordered pair of numbers,
          [ a , b ]
             i   i
where
          a    <   b
           i   -    i
The intervals within a window are both ordered and disjoint. That is, the beginning of each interval is greater than the end of the previous interval:
          b  <  a
           i     i+1
A common use of the windows facility is to calculate the intersection set of a number of time intervals. Top ## Relevant Routines `--` cspice_wncomd determines the compliment of a window with respect to a defined interval. `--` cspice_wncond contracts a window's intervals. `--` cspice_wndifd : Calculate the difference between two windows; i.e. every point existing in the first but not the second. `--` cspice_wnelmd returns TRUE or FALSE if a value exists in a window. `--` cspice_wnexpd expands the size of the intervals in a window. `--` cspice_wnextd extracts a window's endpoints . `--` cspice_wnfetd retrieves a specified interval from a window. `--` cspice_wnfild fills gaps between intervals in a window. `--` cspice_wnfltd filter/removes small intervals from a window. `--` cspice_wnincd determines if an interval exists within a window. `--` cspice_wninsd inserts an interval into a window. `--` cspice_wnintd calculates the intersection of two windows. `--` cspice_wnreld compares two windows. Comparison operations available, equality '=', inequality '<>', subset '<=' and '>=', proper subset '<' and '>'. `--` cspice_wnunid calculates the union of two windows. Top ## Requirements and References Knowledge of mice.req. Top ## Programming task: Given the times of line-of-sight for a vehicle from a ground station and the times for an acceptable Sun-station-vehicle phase angle, write a program to determine the time intervals common to both configurations. Top ## Code Solution
       function win

          %
          % The windows hold 8 data, i.e. values four intervals.
          %
          MAXSIZ = 8;

          %
          % Define a set of time intervals. For the purposes of this
          % tutorial program, define time intervals representing
          % an unobscured line of sight between a ground station
          % and some body.
          %
          los = { 'Jan 1, 2003 22:15:02', 'Jan 2, 2003  4:43:29',  ...
                  'Jan 4, 2003  9:55:30', 'Jan 4, 2003 11:26:52',  ...
                  'Jan 5, 2003 11:09:17', 'Jan 5, 2003 13:00:41',  ...
                  'Jan 6, 2003 00:08:13', 'Jan 6, 2003  2:18:01' };

          %
          % A second set of intervals representing the times for which
          % an acceptable phase angle exits between the ground station,
          % the body and the Sun.
          %
          phase = { 'Jan 2, 2003 00:03:30', 'Jan 2, 2003 19:00:00', ...
                    'Jan 3, 2003  8:00:00', 'Jan 3, 2003  9:50:00', ...
                    'Jan 5, 2003 12:00:00', 'Jan 5, 2003 12:45:00', ...
                    'Jan 6, 2003 00:30:00', 'Jan 6, 2003 23:00:00' };

          %
          % Load our meta kernel for the leapseconds data.
          %
          cspice_furnsh( 'meta.tm' )

          %
          % SPICE windows consist of double precision values; convert
          % the string time tags defined in the 'los'and 'phase'
          % arrays to double precision ET. Store the double values
          % in the 'loswin' and 'phswin' windows.
          %
          los_et = cspice_str2et( los   );
          phs_et = cspice_str2et( phase );

          %
          % Initialize the windows with the 'los_et' and 'phs_et'
          % values.
          %
          % Create two empty windows.
          %
          loswin = zeros(0,1);
          phswin = zeros(0,1);

          %
          % Mice windows lack a constant size as the windows interfaces
          % dynamically adjust window size before return, therefore the
          % SPICE concept of window cardinality degenerates to window size.
          %

          for i=1:(MAXSIZ/2)
             loswin = cspice_wninsd( los_et(2*i - 1), los_et(2*i), loswin );
             phswin = cspice_wninsd( phs_et(2*i - 1), phs_et(2*i), phswin );
          end

          %
          % The issue for consideration, at what times do line of
          % sight events coincide with acceptable phase angles?
          % Perform the set operation AND on loswin, phswin,
          % (the intersection of the time intervals)
          % place the results in the window 'sched'.
          %
          sched = cspice_wnintd( loswin, phswin);

          %
          % Output the results. The number of intervals in 'sched'
          % is half the number of data points (the cardinality).
          %
          card = numel(sched);

          fprintf( 'No. data values in sched            : %i\n\n', card )

          fprintf( 'Time intervals meeting defined criterion.\n' )

          for i=1:(card/2)

             %
             % Extract from the derived 'sched' the values defining the
             % time intervals.
             %
             [left, right ] = cspice_wnfetd( sched, i );

             %
             % Convert the ET values to UTC for human comprehension.
             %
             utcstr_l = cspice_et2utc( left , 'C', 3 );
             utcstr_r = cspice_et2utc( right, 'C', 3 );

             %
             % Output the UTC string and the corresponding index
             % for the interval.
             %
             fprintf( '%i   %s   %s\n', i, utcstr_l, utcstr_r )

          end
Top ### Run the code example The output window has the name 'sched' (schedule). Output the amount of data held in 'sched'.
        No. data values in sched            : 6
List the time intervals for which a line of sight exists during the time of a proper phase angle.
       Time intervals meeting defined criterion.
       1   2003 JAN 02 00:03:30.000   2003 JAN 02 04:43:29.000
       2   2003 JAN 05 12:00:00.000   2003 JAN 05 12:45:00.000
       3   2003 JAN 06 00:30:00.000   2003 JAN 06 02:18:01.000
Top # Lesson 7: Utility and Constants Routines Lesson Goals: Mice provides several routines to perform commonly needed tasks. Among these: `--` convert values between unit expressions `--` identify the toolkit version Mice also includes a set of functions that return constant values often used in astrodynamics, time calculations, and geometry. Top ## Relevant Routines `--` cspice_convrt converts between measurements units `--` cspice_tkvrsn returns the current version of the toolkit `--` cspice_clight : velocity of light in a vacuum, kilometers per second `--` cspice_dpr : number of degrees per radian (180/Pi) `--` cspice_rpd : number radians per degree (Pi/180) `--` cspice_spd : number of seconds per day (60*60*24) `--` cspice_b1900 : Julian Date of the epoch Besselian Date 1900.0 `--` cspice_b1950 : Julian date of the epoch Besselian Date 1950.0 `--` cspice_j1900 : Julian date of 1900 JAN 0.5 this corresponds to calendar date 1899 DEC 31 12:00:00 `--` cspice_j1950 : Julian date of 1950 JAN 1.0 this corresponds to calendar date 1950 JAN 01 00:00:00 `--` cspice_j2000 : Julian date of 2000 JAN 1.5 (2000 JAN 01 12:00:00) `--` cspice_j2100 : Julian date of 2100 JAN 1.5, this corresponds to calendar date 2100 JAN 01 12:00:00 `--` cspice_twopi : double precision value of 2 * Pi `--` cspice_pi : double precision value of Pi `--` cspice_halfpi : double precision value of 0.5 * Pi `--` cspice_jyear : seconds per Julian year (365.25 Julian days) `--` cspice_tyear : seconds per tropical year (approximately the number of seconds from one spring equinox to the next) Top ## Requirements and References The references used to define or calculate the constants functions are found in the source code file and/or the API reference. Also reference the other_functions.ppt tutorial file. Top ## Programming Task Write an interactive program to convert values between various units. Demonstrate the flexibility of the unit conversion routine, the string equality function, and show the version ID function. Top ## Code Solution
       function units()

          %
          % Display the Toolkit version string with a
          % cspice_tkvrsn call.
          %
          vers = cspice_tkvrsn( 'TOOLKIT' );
          disp( ['Convert demo program compiled against CSPICE Toolkit ' ...
                                                                     vers] )

          %
          % The user first inputs the name of a unit of measure.
          % Send the name through TOSTAN for de-aliasing.
          %
          funits = input( 'From Units : ', 's' );
          funits = tostan( funits );

          %
          % Input a double precision value to express in a new
          % unit format.
          %
          fvalue = input( 'From Value : ' );

          %
          % Now the user inputs the name of the output units.
          % Again we send the units name through TOSTAN for
          % de-aliasing.
          %
          tunits = input( 'To Units   : ', 's' );
          tunits = tostan( tunits );

          tvalue = cspice_convrt( fvalue, funits, tunits );
          fprintf( '%f %s\n', tvalue, tunits )

       function value = tostan( alias )

          value = alias;

          %
          % As a convenience, let's alias a few common terms
          % to their appropriate counterpart. Use strcmpi
          % to compare strings. The comparison ignores
          % letter case and trailing/leading spaces. NOTE: the SWITCH
          % statement performs the same function as the multiple
          % 'if' blocks. SWITCH was not used in order to demonstrate
          % the strcmpi call.
          %

          if ( strcmpi( alias, 'meter') )

                %
                % First, a 'meter' by any other name is a
                % 'METER' and smells as sweet ...
                %
                value = 'METERS';

          elseif ( strcmpi( alias, 'klicks'    ) || ...
                   strcmpi( alias, 'kilometers') || ...
                   strcmpi( alias, 'kilometer' )     )

                %
                % ... 'klicks' and 'KILOMETERS' and 'KILOMETER'
                % identifies 'KM'....
                %
                value = 'KM';

          elseif ( strcmpi( alias, 'secs') )

                %
                % ... 'secs' to 'SECONDS'.
                %
                value = 'SECONDS';

          elseif ( strcmpi( alias, 'miles') )

                %
                % ... and finally 'miles' to 'STATUTE_MILES'.
                % Normal people think in statute miles.
                % Only sailors think in nautical miles - one
                % minute of arc at the equator.
                %
                value = 'STATUTE_MILES';

          end

          %
          % Much better. Now return. If the input matched
          % none of the aliases, this function did nothing.
          %
Top ### Run the code example Run a few conversions through the application to ensure it works. The intro banner gives us the Toolkit version against which the application was linked:
       Convert demo program compiled against CSPICE Toolkit CSPICE_N0061
       From Units : klicks
       From Value : 3
       To Units   : miles
       1.864114 STATUTE_MILES
Now we know. Three kilometers equals 1.864 miles. Legend states Pheidippides ran from the Marathon Plain to Athens. The modern marathon race (inspired by this event) spans 26.2 miles. How far in kilometers?
       Convert demo program compiled against CSPICE Toolkit CSPICE_N0061
       From Units : miles
       From Value : 26.2
       To Units   : km
       42.164813 km
Top ## Programming Task Write a program to output Mice constants and use those constants to calculate some rudimentary values. Top ## Code Solution
       function xconst();

          %
          % All the function have the same calling sequence:
          %
          %    VALUE = function_name
          %
          %    some_procedure( function_name )
          %
          % First a simple example using the seconds per day
          % constant...
          %
          fprintf( ...
             'Number of (S)econds (P)er (D)ay           :  %19.12f\n', ...
                                                              cspice_spd )

          %
          % ...then show the value of degrees per radian, 180/Pi...
          %
          fprintf( ...
             'Number of (D)egrees (P)er (R)adian        :  %19.12f\n', ...
                                                              cspice_dpr )

          %
          % ...and the inverse, radians per degree, Pi/180.
          % It is obvious cspice_dpr() equals 1.d/cspice_rpd(), or
          % more simply cspice_dpr() * cspice_rpd() equals 1
          %
          fprintf( ...
             'Number of (R)adians (P)er (D)egree        :  %19.12f\n', ...
                                                              cspice_rpd )

          %
          % What's the value for the astrophysicist's favorite
          % physical constant (in a vacuum)?
          %
          fprintf( ...
             'Speed of light in KM per second           :  %19.12f\n', ...
                                                           cspice_clight )

          %
          % How long (in Julian days) from the J2000 epoch to the
          % J2100 epoch?
          %
          fprintf( ...
             'Number of days between epochs J2000/J2100 :  %19.12f\n', ...
                                             cspice_j2100 - cspice_j2000 )

          %
          % Redo the calculation returning seconds...
          %
          fprintf( ...
             'Number of seconds between epochs          :  %19.5f\n', ...
                            cspice_spd * (cspice_j2100 - cspice_j2000 ) )
          fprintf( ...
             '                            J2000/J2100   :\n')

          %
          % ...then tropical years.
          %
          fprintf( ...
             'Number of tropical years between epochs   :  %19.12f\n', ...
                (cspice_spd/cspice_tyear) * (cspice_j2100- spice_j2000 ) )
          fprintf( ...
             '                            J2000/J2100   :\n')

          %
          % Finally, how can I convert a radian value to degrees.
          %
          fprintf( ...
             'Number of degrees in Pi/2 radians of arc  :  %19.12f\n', ...
                                             cspice_halfpi  * cspice_dpr )

          %
          % and degrees to radians.
          %
          fprintf( ...
             'Number of radians in 250 degrees of arc   :  %19.12f\n', ...
                                                       250. * cspice_rpd )
Top ### Run the code example
       Number of (S)econds (P)er (D)ay           :   86400.000000000000
       Number of (D)egrees (P)er (R)adian        :      57.295779513082
       Number of (R)adians (P)er (D)egree        :       0.017453292520
       Speed of light in KM per second           :  299792.457999999984
       Number of days between epochs J2000/J2100 :   36525.000000000000
       Number of seconds between epochs          :    3155760000.000000
                                   J2000/J2100   :
       Number of tropical years between epochs   :     100.002135902909
                                   J2000/J2100   :
       Number of degrees in Pi/2 radians of arc  :      90.000000000000
       Number of radians in 250 degrees of arc   :       4.363323129986