 
Preface - Other Stuff (The Red Shirt topics) (IDL)
===========================================================================
 
   March 14, 2006
 
   The extensive scope of the Icy 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.
 
 
Coding and Use Lessons
===========================================================================
 
   This workbook contains lessons to demonstrate use of the less celebrated
   Icy 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
 
 
NAIF Documentation
--------------------------------------------------------
 
   The technical complexity of the various Icy subsystems mandates an
   extensive, user-friendly documentation set. The set differs somewhat
   depending on your choice of development language, FORTRAN, C, or IDL,
   but provides the same information with regards to SPICE operation.
 
   The sources for a user needing information concerning the Icy System or
   other NAIF product:
 
       --   Required Readings and Users Guides
 
       --   Source Code Documentation
 
       --   API Documentation
 
       --   Tutorials
 
 
Required Reading and Users Guides
 
   NAIF Required Reading (*.req) documents introduce the functionality of
   particular Icy subsystems:
 
 
         cells.req       ek.req          intrdctn.req    problems.req
         ck.req          ellipses.req    kernel.req      rotation.req
         cspice.req      error.req       naif_ids.req    scanning.req
         daf.req         frames.req      pck.req         sclk.req
         das.req         icy.req         planes.req      sets.req
 
         spc.req
         spk.req
         symbols.req
         time.req
         windows.req
 
 
   NAIF Users Guides (*.ug) describe the proper use of particular Icy
   tools:
 
 
         brief.ug        convert.ug      spacit.ug       tictoc.ug
         chronos.ug      inspekt.ug      spkmerge.ug     tobin.ug
         ckbrief.ug      mkspk.ug        states.ug       toxfr.ug
         commnt.ug       simple.ug       subpt.ug        version.ug
 
 
   These text documents exist in the 'doc' directory of the main Toolkit
   directory:
 
         ../icy/doc/
 
   HTML format documentation
 
   As of delivery N57, the Icy distributions include HTML versions of
   Required Readings and Users Guides, accessible from the HTML
   documentation directory:
 
        ../icy/doc/html/index.html
 
 
Source Code
 
   All SPICELIB and CSPICE source files include usage and design
   information incorporated in a comment block known as the "header."
 
   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 Icy 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 Icy system.
 
   The source code for Icy products is stored in 'src' sub-directory of the
   main Icy directory:
 
 
API Documentation
 
   The Icy 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.
 
         ...icy/doc/html/cspice/index.html
 
   Also included is Icy Reference Guide, an index of all Icy APIs with
   hyperlinks to API specific documentation. Each API documentation page
   includes cross-links to any other Icy APIs mentioned in the document and
   a link to the API documentation for the CSPICE routine called by the Icy
   interface.
 
         ...icy/doc/html/icy/index.html
 
 
Tutorials
 
   A set of Microsoft PowerPoint presentations provide a general overview
   of the complete Icy 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.
 
 
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.
 
       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.
            \subsection 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.
 
 
Kernels for lessons
--------------------------------------------------------
 
 
Input kernel files
 
   The lessons may include kernels a program must load to operate. For this
   workbook, a user can download all kernels from the NAIF anonymous ftp
   site:
 
         ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/
 
         FILE NAME                TYPE  DESCRIPTION
         -----------------------  ----  ----------------------
         naif0008.tls             LSK   Generic LSK
         pck00008.tpc             PCK   Generic PCK
         de405s.bsp               SPK   Planet Ephemeris SPK
 
 
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.
 
 
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.
 
 
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 from the kernel subsystem.
 
 
Requirements and References
--------------------------------------------------------
 
   Knowledge of information in the kernels.req document, the mk.ppt and
   intro_to_kernels.ppt tutorial files.
 
 
Programming Task
--------------------------------------------------------
 
   Write a program to load a meta kernel, interrogate the Icy system for
   the names and types of all loaded kernels, then demonstrate the unload
   functionality and the resulting effects.
 
 
Code Solution
--------------------------------------------------------
 
 
First, create a meta text kernel:
 
   You can use two versions of a meta kernel with code examples (meta.ker)
   in this lesson. Either a kernel with explicit path information:
 
 
      \begindata
 
         KERNELS_TO_LOAD = ( 'kernels/spk/de405s.bsp',
                             'kernels/pck/pck00008.tpc',
                             'kernels/lsk/naif0008.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
 
 
 
Now the solution source code:
 
 
      PRO KERNEL
 
         ;;
         ;; Assign the path name of the meta kernel to META.
         ;;
         META = 'meta.ker'
 
         ;;
         ;; Load the meta kernel then use KTOTAL to interrogate the SPICE
         ;; kernel subsystem.
         ;;
         cspice_furnsh, META
         cspice_ktotal, 'ALL', count
         print, 'Kernel count after load: ', 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 = 0, (count-1)  do begin
            cspice_kdata, i, 'ALL', file, type, source, handle, found
            print, 'File   ' + file
            print, 'Type   ' + type
            print, 'Source ' + source
            print
         endfor
 
         ;;
         ;; Unload one kernel then check the count.
         ;;
         cspice_unload, 'kernels/spk/de405s.bsp'
         cspice_ktotal, 'ALL', count
 
         ;;
         ;; The subsystem should report one less kernel.
         ;;
         print, 'Kernel count after one unload : ', 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.
         ;;
         cspice_ktotal, 'ALL', count
         print, 'Kernel count after meta unload: ', count
 
      END
 
 
 
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.ker
      Type   META
      Source
 
      File   kernels/spk/de405s.bsp
      Type   SPK
      Source meta.ker
 
      File   kernels/pck/pck00008.tpc
      Type   TEXT
      Source meta.ker
 
      File   kernels/lsk/naif0008.tls
      Type   TEXT
      Source meta.ker
 
      Kernel count after one unload:   3
      Kernel count after meta unload:   0
 
 
 
Lesson 2: The Kernel Pool
===========================================================================
 
   Lesson Goals:
 
   The lesson demonstrates the Icy 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.ker)
   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/naif0008.tls')
 
      \begintext
 
 
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.
 
 
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 source files or
   API documentation for the particular routines.
 
 
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.
 
 
Code Solution
--------------------------------------------------------
 
 
      PRO KERVAR
 
         ;;
         ;; Define the max number of kernel variables
         ;; of concern for this examples.
         ;;
         N_ITEMS =  20
 
         ;;
         ;; Define the maximum length for any string. 80 characters,
         ;; plus on for the C null terminator.
         ;;
         STRLEN  = 81
 
         ;;
         ;; 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.ker"
 
         ;;
         ;; Initialize the start value. This values indicates
         ;; index of the first element to return if a kernel
         ;; variable is an array. start = 0 indicates return everything.
         ;; start = 1 indicates return everything but the first element.
         ;;
         start = 0;
 
         ;;
         ;; 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. 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)
         ;;
 
         cspice_gnpool, tmplate, start, N_ITEMS, STRLEN, cvals, found
 
         if ( found) then begin
            print, "No. variables matching template: ", n_elements(cvals)
         endif else begin
            print, "No kernel variables matched template"
         stop
         endelse
 
         ;;
         ;; Okay, now we know something about the kernel pool
         ;; variables of interest to us. Let's find out more...
         ;;
         for i=0, (n_elements(cvals)-1) do begin
 
            ;;
            ;; Use dtpool to return the dimension and type,
            ;; C (character) or N (numeric), of each pool
            ;; variable name in the cvals array.
            ;;
            cspice_dtpool, cvals[i], found, dim, type
            print, cvals[i]
            print, " No. items: " + string(dim) + " Of type: " + type
 
            ;;
            ;; Test character equality, 'N' or 'C'.
            ;;
            case type of
 
               'N': begin
 
                     ;;
                     ;; 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.
                     ;;
                     cspice_gdpool, cvals[i], start, N_ITEMS, dvars, $
                                                              found
 
                     for j=0, (n_elements(dvars)-1) do begin
 
                        print, "  Numeric value: ", dvars[j]
 
                     endfor
 
                  end
 
               'C': begin
 
                     ;;
                     ;; If 'type' equals 'C', we found a string array.
                     ;; gcpool retrieves string values from the
                     ;; kernel pool.
                     ;;
                     cspice_gcpool, cvals[i], start, N_ITEMS, STRLEN, $
                                                        cvars, found
 
                     for j=0, (n_elements(cvars)-1) do begin
 
                        print, "  String value : ", cvars[j]
 
                     endfor
 
            end
 
            endcase
 
            print
 
         endfor
 
         ;;
         ;; Now look at the time variable EXAMPLE_TIMES. Extract this
         ;; value as an array of doubles.
         ;;
         cspice_gdpool, "EXAMPLE_TIMES", start, N_ITEMS, dvars, found
 
         print, "EXAMPLE_TIMES"
 
         for j=0, (n_elements(dvars)-1) do begin
 
            print, FORMAT='(A14,F24.5)', "  Time value: ", dvars[j]
 
         endfor
 
      END
 
 
 
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.00
        Numeric value:        136780.00
        Numeric value:       0.10000000
        Numeric value:       0.10000000
        Numeric value:       0.50000000
 
      BODY699_RING2
       No. items:            5 Of type: N
        Numeric value:        117580.00
        Numeric value:        122170.00
        Numeric value:        0.0000000
        Numeric value:        0.0000000
        Numeric value:        0.0000000
 
      BODY699_RING1_1
       No. items:            5 Of type: N
        Numeric value:        133405.00
        Numeric value:        133730.00
        Numeric value:        0.0000000
        Numeric value:        0.0000000
        Numeric value:        0.0000000
 
      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
   two 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.78900
        Time value:          134094896.78900
        Time value:          134094896.78975
 
 
 
Lesson 3: Coordinate Conversions
===========================================================================
 
   Lesson Goals:
 
   The Icy 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.
 
 
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
 
   As of Icy 1.1, the following routines allow vectorized arguments:
 
       --   cspice_latrec
 
       --   cspice_reccyl
 
       --   cspice_recgeo
 
       --   cspice_reclat
 
       --   cspice_recsph
 
       --   cspice_recrad
 
       --   cspice_sphrec
 
       --   cspice_cylrec
 
       --   cspice_georec
 
 
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.
 
 
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.
 
 
Code Solution
--------------------------------------------------------
 
 
      PRO 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"
         timstr = ''
 
         ;;
         ;; Load the needed kernels using a cspice_furnsh call on the
         ;; meta kernel.
         ;;
         cspice_furnsh, "meta.ker"
 
         ;;
         ;; Prompt the user for a time string. Convert the
         ;; time string to ephemeris time J2000 (ET).
         ;;
         read, timstr, PROMPT = "Time of interest: "
         cspice_str2et,  timstr, et
 
         ;;
         ;; Access the kernel pool data for the triaxial radii of the
         ;; Earth, rad[0] holds the equatorial radius, rad[2]
         ;; the polar radius.
         ;;
         cspice_bodvrd, "EARTH", "RADII", 3, rad
 
         ;;
         ;; Calculate the flattening factor for the Earth.
         ;;
         ;;          equatorial_radius - polar_radius
         ;; flat =   ________________________________
         ;;
         ;;                equatorial_radius
         ;;
         flat = (rad[0] - rad[2])/rad[0];
 
         ;;
         ;; 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.
         ;;
         cspice_spkpos,  "MOON", et, INRFRM, "LT+S","EARTH", pos, ltime
 
         ;;
         ;; Show the current frame and time.
         ;;
         print, " Time : "         , timstr
         print, "  Inertial Frame: ", inrfrm
 
         ;;
         ;; First convert the position vector
         ;; X = pos[0], Y = pos[1], Z = pos[2], to RA/DEC.
         ;;
         cspice_recrad,  pos, range, ra, dec
         print, "   Range/Ra/Dec"
         print, "    Range: ", range
         print, "    RA   : ", ra * cspice_dpr()
         print, "    DEC  : ", dec* cspice_dpr()
 
         ;;
         ;; ...latitudinal coordinates...
         ;;
         cspice_reclat,  pos, range, lon, lat
         print, "   Latitudinal"
         print, "    Rad  : ", range
         print, "    Lon  : ", lon * cspice_dpr()
         print, "    Lat  : ", lat * cspice_dpr()
 
         ;;
         ;; ...spherical coordinates use the colatitude,
         ;; the angle from the Z axis.
         ;;
         cspice_recsph,  pos, range, colat, lon
         print, "   Spherical"
         print, "    Rad  : ", range
         print, "    Lon  : ", lon   * cspice_dpr()
         print, "    Colat: ", 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.
         ;;
         cspice_spkpos,  "MOON", et, nonfrm, "LT+S","EARTH", pos, ltime
 
         print
         print, "  Non-inertial Frame: " + nonfrm
 
         ;;
         ;; ...latitudinal coordinates...
         ;;
         cspice_reclat,  pos, range, lon, lat
         print, "   Latitudinal "
         print, "    Rad  : ", range
         print, "    Lon  : ", lon * cspice_dpr()
         print, "    Lat  : ", lat * cspice_dpr()
 
         ;;
         ;; ...spherical coordinates...
         ;;
         cspice_recsph,  pos, range, colat, lon
         print, "   Spherical"
         print, "    Rad  : ", range
         print, "    Lon  : ", lon   * cspice_dpr()
         print, "    Colat: ", colat * cspice_dpr()
 
         ;;
         ;; ...finally, convert the position to geodetic coordinates.
         ;;
         cspice_recgeo,  pos, rad[0], flat, lon, lat, range
         print, "   Geodetic"
         print, "    Rad  : ", range
         print, "    Lon  : ", lon * cspice_dpr()
         print, "    Lat  : ", lat * cspice_dpr()
         print
 
      END
 
 
 
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.82
          RA   :        203.64369
          DEC  :       -4.9790104
 
 
   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.82
          Lon  :       -156.35631
          Lat  :       -4.9790104
 
 
   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.82
          Lon  :       -156.35631
          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.82
          Lon  :        70.986950
          Lat  :       -4.9896751
 
 
   Spherical.
 
 
         Spherical
          Rad  :        369340.82
          Lon  :        70.986950
          Colat:        94.989675
 
 
   Geodetic. The cartographic lat/lon.
 
 
         Geodetic
          Rad  :        362962.84
          Lon  :        70.986950
          Lat  :       -4.9902493
 
 
 
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 Icy.
 
 
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.
 
   As of Icy 1.1, the following routines allow vectorized arguments:
 
       --   cspice_str2et
 
       --   cspice_timout
 
 
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.
 
 
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 Icy-supported formats.
 
 
Code Solution
--------------------------------------------------------
 
   Caution: Be sure to assign sufficient string lengths for time
   formats/pictures.
 
 
      PRO TIC
 
         ;;
         ;; 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";
         STRLEN   = 81
 
         ;;
         ;; Load the leapseconds kernel.
         ;;
         cspice_furnsh, LSK
         print, "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).
         ;;
         cspice_str2et, CALSTR, et
         print, "Corresponding ET           : ", 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.
 
         ;;
         cspice_timout, et, 'Wkd Mon DD HR:MN:SC PDT YYYY ::UTC-7', $
                                                       STRLEN, timstr
         print, "Time in string format 1    : " + timstr
 
         ;;
         ;; Create another picture, this time combine a calendar,
         ;; 2 digit year , with Julian Day format.
         ;;
         cspice_timout, et,                                     $
           'Wkd Mon DD HR:MN ::UTC-7 YR (JULIAND.##### JDUTC)', $
            STRLEN, timstr
         print, "Time in string format 2    : " + timstr
 
         ;;
         ;; Why create a picture by hand when Icy 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 'error'. In this example the picture
         ;; string is known as correct..
         ;;
         cspice_tpictr, '12:34:56.789 P.M. PDT January 1, 2006', $
                         STRLEN, pictr, ok, error
 
         if ( NOT ok ) then begin
            print, 'ERROR from cspice_tpictr: ' + error
            stop
         endif
 
         cspice_timout, et, pictr, STRLEN, timstr
         print, "Time in string format 3    : " + 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.
         ;;
         cspice_str2et, AMBIGSTR, et1
 
         ;;
         ;; Set 1980 as the base year causes SPICE to interpret the
         ;; time string's "79" as 2079.
         ;;
         cspice_tsetyr, 1980
         cspice_str2et, AMBIGSTR, et2
 
         ;;
         ;; Calculate the number of years between the two ET
         ;; representations, ~100.
         ;;
         print, "Years between evaluations  :  ", $
                         (et2 - et1)/cspice_jyear()
 
         ;;
         ;; Reset the default year to 1969 so other scripts use the
         ;; default.
         ;;
         cspice_tsetyr, 1969
 
      END
 
 
 
Run the code example
 
 
      Original time string      : Mar 15, 2003 12:34:56.789 AM PST
      Corresponding ET          :    1.0098936e+08
      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.00000
 
 
 
Lesson 5: Error Handling
===========================================================================
 
   Lesson Goal:
 
   The Icy error subsystem differs from other SPICE packages in that the
   user cannot alter the state of the subsystem, rather the user can
   respond to an error signal using the "catch" function. This function
   natively receives and processes any SPICE error signaled from Icy. The
   user can therefore "catch" an error signal so as to respond in an
   appropriate manner.
 
 
Relevant Routines:
--------------------------------------------------------
 
       --   "catch" sets an IDL error handler flagging an error signal in
            the current procedure. The mechanism operates like
            setjump/longjump, or catch/throw.
 
       --   "catch, \cancel" deletes an IDL error handler.
 
 
Requirements and References
--------------------------------------------------------
 
   Knowledge of material in the error.req document and the exceptions.ppt
   tutorial file. Comprehension of the catch/throw concept.
 
 
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.
 
 
Code Solution
--------------------------------------------------------
 
 
      PRO ADERR
 
         ;;
         ;; Set initial parameters.
         ;;
         SPICETRUE = 1L
         SPICEFALSE= 0L
         doloop    = SPICETRUE;
 
         ;;
         ;; Load the data we need for state evaluation.
         ;;
         cspice_furnsh, "meta.ker"
 
         ;;
         ;; Start our input query loop to the user.
         ;;
         while (doloop) do begin
 
            ;;
            ;; Initialize the input value as a string. YOU MUST
            ;; do this to use PROMPT in a read.
            ;;
            targ = ''
 
            ;;
            ;; 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).
            ;;
            read, targ, PROMPT= "Target: "
 
            if cspice_eqstr( targ, "NONE") then begin
 
               ;;
               ;; An exit condition. If the user inputs NONE
               ;; for a target name, set the loop to stop...
               ;;
               doloop = SPICEFALSE;
 
            endif else begin
 
               ;;
               ;; ...otherwise evaluate the state between the Earth
               ;; and the target. Initialize an error handler.
               ;;
               catch, err
 
               ;;
               ;; What if the program can't perform the evaluation?
               ;; Then ICY sets an error message informing
               ;; the user of the problem's cause.
               ;;
               ;; Examine the value of 'err' to determine if we
               ;; output a state vector or not.
               ;;
               if ( err ne 0 ) then begin
 
                  ;;
                  ;; Error signal detected. Output the error response
                  ;; information.
                  ;;
                  print, !error_state.name
                  print, !error_state.msg
                  print
 
               endif else begin
 
                  ;;
                  ;; Perform the state lookup. If an error occurs,
                  ;; program flow returns the first line after the
                  ;; "catch, err"; in that case, 'err' will have a
                  ;; non-zero value.
                  ;;
                  cspice_spkezr, targ, 0.d, "J2000", "LT+S", "EARTH", $
                                 state, ltime
 
                  ;;
                  ;; No error, output the state.
                  ;;
                  print, FORMAT = '( "R : ", 3F17.5)', state[0:2]
                  print, FORMAT = '( "V : ", 3F17.5)', state[3:5]
                  print, "LT: ", ltime
                  print
 
               endelse
 
              catch, /cancel
 
            endelse
 
         endwhile
 
         ;;
         ;; Done. Unload the kernels.
         ;;
         cspice_unload, "meta.ker"
 
      END
 
 
 
Run the code example
 
   Now run the code with various inputs to observe behavior. Begin the run
   using known astronomical bodies. Recall the Icy 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.3423106
 
      Target: Mars
      R :   234536077.41914 -132584383.59557  -63102685.70619
      V :          30.95976         28.93646         13.11449
      LT:        923.00108
 
      Target: Pluto barycenter
      R : -1451304742.83853-4318174144.40632 -918251433.58736
      V :          35.03838          3.06560         -0.01514
      LT:        15501.258
 
      Target: Puck
      ICY_M_SPICE_ERROR
      CSPICE_SPKEZR: 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.ker 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
      ICY_M_SPICE_ERROR
      CSPICE_SPKEZR: 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.65507
 
 
   The look-up succeeded despite two errors in our run. The Icy system can
   respond to error conditions (not system errors) in much the same fashion
   as languages with catch/throw instructions.
 
 
Lesson 6: Windows, and Cells
===========================================================================
 
   Lesson Goal:
 
   This lesson introduces the concepts of the Icy data types 'cell' and
   'window'. A 'cell' is a data structure designed to provide easy and safe
   manipulation of typed array data.
 
   An IDL SPICE cell consists of an IDL structure comprised of the same
   fields as a C SPICE cell.
 
   A user should create cells by use of the appropriate Icy calls. NAIF
   recommends against manual creation of cells.
 
   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.
 
 
Relevant Routines
--------------------------------------------------------
 
       --   cspice_celld, create a cell for double precision data
 
       --   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_wnsumd creates a window summary.
 
       --   cspice_wnunid calculates the union of two windows.
 
       --   cspice_wnvald validates/creates a window from a cell array.
 
 
Requirements and References
--------------------------------------------------------
 
   Knowledge of cells.req, and windows.req documents, as well as the
   other_functions.ppt tutorial file.
 
 
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.
 
 
Code Solution
--------------------------------------------------------
 
 
      PRO WIN
 
         ;;
         ;; Define the cells to use as windows.
         ;; The windows can hold 8 data values i.e.
         ;; four intervals.
         ;;
         MAXSIZ = 8
         loswin = cspice_celld( MAXSIZ )
         phswin = cspice_celld( MAXSIZ )
         sched  = cspice_celld( MAXSIZ )
 
         ;;
         ;; 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.ker"
 
         ;;
         ;; 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.
         ;;
         cspice_str2et, los  , los_et
         cspice_str2et, phase, phs_et
 
         ;;
         ;; Initialize the cells from the double precision arrays,
         ;; then validate the cells as windows.
         ;;
         for i=0, (MAXSIZ/2) -1 do begin
               cspice_wninsd, los_et[i*2], los_et[i*2 + 1], loswin
               cspice_wninsd, phs_et[i*2], phs_et[i*2 + 1], phswin
         endfor
 
         cspice_wnvald, MAXSIZ, MAXSIZ, loswin
         cspice_wnvald, MAXSIZ, MAXSIZ, phswin
         cspice_wnvald, MAXSIZ, MAXSIZ, sched
 
 
         ;;
         ;; 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'.
         ;;
         cspice_wnintd, loswin, phswin, sched
 
         ;;
         ;; Output the results. The number of intervals in 'sched'
         ;; is half the number of data points (the cardinality).
         ;; Use a call to card_c to retrieve the window's cardinality.
         ;;
 
         print
         print, "No. data values in sched            : ",            $
                                                    cspice_card(sched)
         print, "Space available for values in sched : ",            $
                                                    cspice_size(sched)
         print
         print, "Time intervals meeting defined criterion."
 
         for i=0, (cspice_card(sched)/2)-1 do begin
 
            ;;
            ;; Extract from the derived 'sched' the values defining the
            ;; time intervals.
            ;;
            cspice_wnfetd, sched, i, left, right
 
            ;;
            ;; Convert the ET values to UTC for human comprehension.
            ;;
            cspice_et2utc, left , "C", 3, utcstr_l
            cspice_et2utc, right, "C", 3, utcstr_r
 
            ;;
            ;; Output the UTC string and the corresponding index
            ;; for the interval.
            ;;
            print, i, " ", utcstr_l, utcstr_r
 
         endfor
 
 
         ;;
         ;; Summarize the 'sched' window.
         ;;
         cspice_wnsumd, sched, meas, avg, stddev, small, large
 
         print
         print, "Summary of sched window"
 
         print, "o Total measure of sched    : ", meas
         print, "o Average measure of sched  : ", avg
         print, "o Standard deviation of "
         print, "  the measures in sched     : ", stddev
 
         ;;
         ;; The values for small and large refer to the indexes of the
         ;; values in the window ('sched'). The shortest interval is
         ;;
         ;;      [ sched.base[ sched.data + small]
         ;;        sched.base[ sched.data + small +1]  ];
         ;;
         ;; the longest is
         ;;
         ;;      [ sched.base[ sched.data + large]
         ;;        sched.base[ sched.data + large +1]  ];
         ;;
         ;; Output the interval indexes for the shortest and longest
         ;; intervals. As IDL bases an array index on 0, the interval
         ;; index is half the array index.
         ;;
         print, "o Index of shortest interval: ", small/2
         print, "o Index of longest interval : ", large/2
 
      END
 
 
 
Run the code example
 
   The output window has the name SCHED (schedule).
 
   Output the amount of data held in SCHED compared to the maximum possible
   amount.
 
       No. data values in SCHED            :   6
       Space available for values in SCHED :   8
 
   List the time intervals for which a line of sight exists during the time
   of a proper phase angle.
 
 
      Time intervals meeting defined criterion.
             0 2003 JAN 02 00:03:30.0002003 JAN 02 04:43:29.000
             1 2003 JAN 05 12:00:00.0002003 JAN 05 12:45:00.000
             2 2003 JAN 06 00:30:00.0002003 JAN 06 02:18:01.000
 
 
   Finally, an analysis of the SCHED data. The measure of an interval [a,b]
   (a <= b) equals b-a. Real values output in units of seconds.
 
 
      Summary of sched window
      o Total measure of sched    :        25980.000
      o Average measure of sched  :        8660.0000
      o Standard deviation of
        the measures in sched     :        5958.5502
      o Index of shortest interval:            1
      o Index of longest interval :            0
 
 
 
Lesson 7: Utility and Constants Routines
===========================================================================
 
   Lesson Goals:
 
   Icy provides several routines to perform commonly needed tasks. Among
   these include calls to convert values between unit expressions,
   determine the equality of strings, and indicate whether a file exists.
 
   Icy also includes a set of functions that return constant values often
   used in astrodynamics, time calculations, and geometry.
 
 
Relevant Routines
--------------------------------------------------------
 
       --   cspice_convrt converts between measurements units
 
       --   cspice_tkvrsn returns the current version of the toolkit
 
       --   cspice_eqstr returns a boolean describing the equality of two
            strings. The comparison is case insensitive and ignores spaces.
 
       --   cspice_exists returns a boolean indicating the existence of a
            file.
 
       --   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 (1899 DEC 31
            12:00:00)
 
       --   cspice_j1950 : Julian date of 1950 JAN 1.0 (1950 JAN 1
            00:00:00)
 
       --   cspice_j2000 : Julian date of 2000 JAN 1.5 (2000 JAN 1
            12:00:00)
 
       --   cspice_j2100 : Julian date of 2100 JAN 1.5 (2100 JAN 1
            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)
 
 
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.
 
 
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.
 
 
Code Solution
--------------------------------------------------------
 
 
      PRO UNITS
 
         ;;
         ;; Initialize variables. All variables used in a PROMPT
         ;; construct must be initialized as strings.
         ;;
         funits  = ''
         fromstr = ''
         tunits  = ''
 
         ;;
         ;; Display the Toolkit version string with a
         ;; cspice_tkvrsn call.
         ;;
         vers = cspice_tkvrsn( "TOOLKIT" )
         print, "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.
         ;;
         read, funits, PROMPT= "From Units : "
         tostan, funits
 
         ;;
         ;; Input a double precision value to express in a new
         ;; unit format.
         ;;
         read, fromstr, PROMPT = "From Value : "
         cspice_prsdp, fromstr, fvalue
 
         ;;
         ;; Now the user inputs the name of the output units.
         ;; Again we send the units name through TOSTAN for
         ;; de-aliasing.
         ;;
         read, tunits, PROMPT = "To Units   : "
         tostan, tunits
 
         cspice_convrt, fvalue, funits, tunits, tvalue
         print,  tvalue, " ", tunits
 
      END
 
      PRO TOSTAN, alias
 
         ;;
         ;; As a convenience, let's alias a few common terms
         ;; to their appropriate counterpart. Use cspice_eqstr
         ;; 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 cspice_eqstr call.
         ;;
 
         if ( cspice_eqstr( alias, "meter") ) then begin
 
               ;;
               ;; First, a 'meter' by any other name is a
               ;; 'METER' and smells as sweet ...
               ;;
               alias = "METERS"
         endif
 
         if ( cspice_eqstr( alias, "klicks"    ) OR $
              cspice_eqstr( alias, "kilometers") OR $
              cspice_eqstr( alias, "kilometer" )     ) then begin
 
               ;;
               ;; ... 'klicks' and 'KILOMETERS' and 'KILOMETER'
               ;; identifies 'KM'....
               ;;
               alias = "KM"
         endif
 
         if ( cspice_eqstr( alias, "secs") ) then begin
 
               ;;
               ;; ... 'secs' to 'SECONDS'.
               ;;
               alias = "SECONDS"
         endif
 
         if ( cspice_eqstr( alias, "miles") ) then begin
 
               ;;
               ;; ... 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.
               ;;
               alias = "STATUTE_MILES"
         endif
 
         ;;
         ;; Much better. Now return. If the input matched
         ;; none of the aliases, this routine did nothing.
         ;;
 
      END
 
 
 
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_N0060
      From Units : klicks
      From Value : 3
      To Units   : miles
             1.8641136 STATUTE_MILES
 
 
   Now we know. Three kilometers equals 1.864 miles.
 
   Pheidippides ran 26.2 miles from the Marathon Plain to Athens. How far
   in kilometers?
 
 
      Convert demo program compiled against CSPICE Toolkit CSPICE_N0060
      From Units : miles
      From Value : 26.2
      To Units   : km
             42.164813 km
 
 
 
Programming Task
--------------------------------------------------------
 
   Write a program to output Icy constants and use those constants to
   calculate some rudimentary values.
 
 
Code Solution
--------------------------------------------------------
 
 
      PRO CONST
 
         ;;
         ;; All the function have the same calling sequence:
         ;;
         ;;    VALUE = function_name()
         ;;
         ;;    some_procedure( function_name() )
         ;;
         ;;    print, function_name()
         ;;
         ;; First a simple example using the seconds per day
         ;; constant...
         ;;
         print,   $
         FORMAT = $
         '("Number of (S)econds (P)er (D)ay           : ", F19.12)',$
                                                          cspice_spd()
 
         ;;
         ;; ...then show the value of degrees per radian, 180/Pi...
         ;;
         print,   $
         FORMAT = $
         '("Number of (D)egrees (P)er (R)adian        : ", F19.16)',$
                                                          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
         ;;
         print,   $
         FORMAT = $
         '("Number of (R)adians (P)er (D)egree        : ", F19.16)',$
                                                          cspice_rpd()
 
         ;;
         ;; What's the value for the astrophysicist's favorite
         ;; physical constant (in a vacuum)?
         ;;
         print,   $
         FORMAT = $
         '("Speed of light in KM per second           : ", F19.12)',$
                                                      cspice_clight()
 
         ;;
         ;; How long (in Julian days) from the J2000 epoch to the
         ;; J2100 epoch?
         ;;
         print, "Number of days between epochs J2000 and     "
         print, $
         FORMAT = $
         '("  J2100                                   : ", F19.12)',$
                                      cspice_j2100() - cspice_j2000()
 
         ;;
         ;; Redo the calculation returning seconds...
         ;;
         print, "Number of seconds between epochs J2000 "
         print,   $
         FORMAT = $
         '("   and J2100                              : ", F19.5)',$
                   cspice_spd() * (cspice_j2100() - cspice_j2000() )
 
         ;;
         ;; ...then tropical years.
         ;;
         print,  "Number of tropical years between epochs     "
         print, $
         FORMAT = $
         '("  J2000 and J2100                         : ", F19.12)',$
                                 ( cspice_spd() / cspice_tyear() )  $
                              * (cspice_j2100() - cspice_j2000() )
 
         ;;
         ;; Finally, how can I convert a radian value to degrees.
         ;;
         print,   $
         FORMAT = $
         '("Number of degrees in Pi/2 radians of arc  : ", F19.16)',$
                                       cspice_halfpi() * cspice_dpr()
 
         ;;
         ;; and degrees to radians.
         ;;
         print,   $
         FORMAT = $
         '("Number of radians in 250 degrees of arc   : ", F19.16)',$
                                                 250.D * cspice_rpd()
 
      END
 
 
 
Run the code example
 
 
      Number of (S)econds (P)er (D)ay           :  86400.000000000000
      Number of (D)egrees (P)er (R)adian        : 57.2957795130823229
      Number of (R)adians (P)er (D)egree        :  0.0174532925199433
      Speed of light in KM per second           : 299792.457999999984
      Number of days between epochs J2000 and
        J2100                                   :  36525.000000000000
      Number of seconds between epochs J2000
         and J2100                              :    3155760000.00000
      Number of tropical years between epochs
        J2000 and J2100                         :    100.002135902909
      Number of degrees in Pi/2 radians of arc  : 90.0000000000000000
      Number of radians in 250 degrees of arc   :  4.3633231299858242
 
 
