Main Page
Other Stuff (IDL)

Table of Contents


   Other Stuff (IDL)
      Overview
      Note About HTML Links
      References
         Tutorials
         Required Readings
         The Permuted Index
         Icy API Documentation
      Kernels Used
      Icy Modules Used

   NAIF Documentation
         Required Reading and Users Guides
         HTML format documentation
         Library Source Code Documentation
         API Documentation
      Text kernels
         Text kernel format

   Lesson 1: Kernel Management with the Kernel Subsystem
      Task Statement
      Learning Goals
      Code Solution
         First, create a meta text kernel:
         Now the solution source code:
         Run the code example

   Lesson 2: The Kernel Pool
      Task Statement
      Learning Goals
      Code Solution
         Run the code example
      Related Routines

   Lesson 3: Coordinate Conversions
      Task Statement
      Learning Goals
      Code Solution
         Run the code example
      Related Routines

   Lesson 4: Advanced Time Manipulation Routines
      Task Statement
      Learning Goals
      Code Solution
         Run the code example

   Lesson 5: Error Handling
      Task Statement
      Learning Goals
      Code Solution
         Run the code example

   Lesson 6: Windows, and Cells
      Programming task
      Learning Goals
      Code Solution
         Run the code example
      Related Routines

   Lesson 7: Utility and Constants Routines
      Task Statement
      Learning Goals
      Code Solution
         Run the code example
      Task Statement
      Code Solution
         Run the code example
      Related Routines




Top

Other Stuff (IDL)





March 01, 2023

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.



Top

Overview




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



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, if not done already by installing the lessons package under the Toolkit's ``doc/html'' directory, create a subdirectory called ``lessons'' under the ``doc/html'' directory of the ``icy/'' tree and copy this document to that subdirectory before loading it into a Web browser.



Top

References




This section lists SPICE documents referred to in this lesson.

Of these documents, the ``Tutorials'' contains the highest level descriptions with the least number of details while the ``Required Reading'' documents contain much more detailed specifications. The most complete specifications are provided in the ``API Documentation''.



Top

Tutorials



The following SPICE tutorials serve as references for the discussions in this lesson:

 
   Name              Lesson steps/routines it describes
   ----------------  -----------------------------------------------
   concepts          Concepts of space geometry and time
   intro_to_kernels  Using kernels, meta-kernels
   time              Time systems, conversions and formats
   lsk_and_sclk      LSK and SCLK
   derived_quant     "high-level" observation geometry computations
   other_functions   Intro to some SPICE "low level" computations
   exceptions        built-in mechanism for trapping/handling errors
 
These tutorials are available from the NAIF server at JPL:

   https://naif.jpl.nasa.gov/naif/tutorials.html


Top

Required Readings



The Required Reading documents are provided with the Toolkit and are located under the ``icy/doc'' directory in the Icy installation tree.

   Name             Lesson steps/routines that it describes
   ---------------  -----------------------------------------
   kernel.req       Loading SPICE kernels
   time.req         Time conversion
   windows.req      The SPICE window data type
   icy.req          The Icy API


Top

The Permuted Index



Another useful document distributed with the Toolkit is the permuted index. It is located under the ``icy/doc'' directory in the IDL installation tree.

This text document provides a simple mechanism by which users can discover which Icy procedures perform functions of interest, as well as the names of the source files that contain these procedures.




Top

Icy API Documentation



An Icy routine's specification is found in the HTML API documentation page located under ``icy/doc/html/icy''.

For example, the document

   icy/doc/html/icy/cspice_str2et.html
describes the cspice_str2et routine.



Top

Kernels Used




The following kernels are used in examples provided in this lesson:

   #  FILE NAME    TYPE DESCRIPTION
   -- ------------ ---- ------------------------------------------------
   1  naif0008.tls LSK  Generic LSK
   2  de405s.bsp   SPK  Planet Ephemeris SPK
   3  pck00008.tpc PCK  Generic PCK
These SPICE kernels are included in the lesson package.



Top

Icy Modules Used




This section provides a complete list of the procedures and kernels that are suggested for usage in each of the exercises in this lesson. (You may wish to not look at this list unless/until you ``get stuck'' while working on your own.)

   CHAPTER EXERCISE   FUNCTIONS      NON-VOID       KERNELS
   ------- ---------  -------------  -------------  ----------
      1    kpool      cspice_furnsh                 1-3
                      cspice_ktotal
                      cspice_kdata
                      cspice_unload
                      cspice_kclear
 
      2    kervar     cspice_furnsh                 1-3
                      cspice_gnpool
                      cspice_dtpool
                      cspice_gdpool
                      cspice_gcpool
                      cspice_kclear
 
      3    coord      cspice_furnsh  cspice_dpr     1-3
                      cspice_str2et
                      cspice_bodvrd
                      cspice_spkpos
                      cspice_recrad
                      cspice_reclat
                      cspice_recsph
                      cspice_recgeo
 
      4    xtic       cspice_furnsh  cspice_jyear   1
                      cspice_str2et
                      cspice_timout
                      cspice_tpictr
                      cspice_tsetyr
                      cspice_kclear
 
      5    aderr      cspice_furnsh  cspice_eqstr   1-3
                      cspice_spkezr
                      cspice_kclear
 
      6    win        cspice_furnsh  cspice_card    1-3
                      cspice_str2et  cspice_size
                      cspice_wninsd
                      cspice_wnvald
                      cspice_wnintd
                      cspice_wnfetd
                      cspice_et2utc
                      cspice_wnsumd
                      cspice_kclear
 
      7    units      cspice_prsdp   cspice_tkvrsn
                      cspice_convrt  cspice_eqstr
 
           xconst                    cspice_spd
                                     cspice_dpr
                                     cspice_rpd
                                     cspice_clight
                                     cspice_j2100
                                     cspice_j2000
                                     cspice_tyear
                                     cspice_halfpi
Refer to the Icy HTML API documentation pages located under ``icy/doc/html/icy'' for detailed interface specifications of these procedures.



Top

NAIF Documentation





The technical complexity of the various SPICE subsystems mandates an extensive, user-friendly documentation set. The set differs somewhat depending on your choice of development language but provides the same information with regards to SPICE operation. The sources for a user needing information concerning SPICE are:

    -- 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 Icy subsystems:

   abcorr.req
   cells.req
   ck.req
   cspice.req
   daf.req
   das.req
   dla.req
   dsk.req
   ek.req
   ellipses.req
   error.req
   frames.req
   gf.req
   icy.req
   kernel.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 Icy tools:

   brief.ug
   chronos.ug
   ckbrief.ug
   commnt.ug
   convert.ug
   dskbrief.ug
   dskexp.ug
   frmdiff.ug
   inspekt.ug
   mkdsk.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:

      ../icy/doc/


Top

HTML format documentation



The Icy distributions include HTML versions of Required Readings and Users Guides, accessible from the HTML documentation directory:

     ../icy/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 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:

      ../icy/src/
Find the CSPICE library source code in:

      ../icy/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 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


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 cspice_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

Lesson 1: Kernel Management with the Kernel Subsystem







Top

Task Statement




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.



Top

Learning 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

Code Solution






Top

First, create a meta text kernel:



You can use two versions of a meta kernel with code examples (kpool.tm) in this lesson. Either a kernel with explicit path information:

   KPL/MK
 
   \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:

   KPL/MK
 
      Define the paths to the kernel directory. Use the PATH_SYMBOLS
      as aliases to the paths.
 
      The names and contents of the kernels referenced by this
      meta-kernel are as follows:
 
         File Name        Description
         ---------------  ------------------------------
         naif0008.tls     Generic LSK.
         de405s.bsp       Planet Ephemeris SPK.
         pck00008.tpc     Generic PCK.
 
 
   \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:



   PRO KPOOL
 
      ;;
      ;; Assign the path name of the meta kernel to META.
      ;;
      META = 'kpool.tm'
 
      ;;
      ;; Load the meta kernel then use KTOTAL to interrogate the SPICE
      ;; kernel subsystem.
      ;;
      cspice_furnsh, META
      cspice_ktotal, 'ALL', count
      print, FORMAT='(A,I1)', '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, FORMAT='(A,I1)', '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, FORMAT='(A,I1)', 'Kernel count after meta unload: ', $
                              count
 
      ;;
      ;; Done. Unload the kernels.
      ;;
      cspice_kclear
 
 
   END


Top

Run the code example



First we see the number of all loaded kernels returned from the cspice_ktotal call.

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

   Kernel count after load:        4
   File   kpool.tm
   Type   META
   Source
 
   File   kernels/lsk/naif0008.tls
   Type   TEXT
   Source kpool.tm
 
   File   kernels/spk/de405s.bsp
   Type   SPK
   Source kpool.tm
 
   File   kernels/pck/pck00008.tpc
   Type   TEXT
   Source kpool.tm
 
   Kernel count after one unload:  3
   Kernel count after meta unload: 0


Top

Lesson 2: The Kernel Pool







Top

Task Statement




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

Learning 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 (kervar.tm) containing PCK-type data, kernels to load, and example time strings:

   KPL/MK
 
      Name the kernels to load. Use path symbols.
 
      The names and contents of the kernels referenced by this
      meta-kernel are as follows:
 
         File Name        Description
         ---------------  ------------------------------
         naif0008.tls     Generic LSK.
         de405s.bsp       Planet Ephemeris SPK.
         pck00008.tpc     Generic PCK.
 
 
   \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
 
   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
 
The main references for pool routines are found in the API documentation for the particular routines.



Top

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, 'kervar.tm'
 
      ;;
      ;; 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. 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)
      ;;
 
      cspice_gnpool, tmplate, START, N_ITEMS, STRLEN, cvals, found
 
      if ( found) then begin
         print, FORMAT='(A,I1)',                        $
                'Number 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=0L, (n_elements(cvals)-1L) 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
         print, cvals[i]
         print, FORMAT='(A,I1,2A)', ' Number items: ', 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 m=0L, (n_elements(dvars)-1L) do begin
 
                     print, FORMAT='(A,F20.6)', '  Numeric value: ',$
                                                 dvars[m]
 
                  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=0L, (n_elements(cvars)-1L) do begin
 
                     print, '  String value: ', cvars[j]
 
                  endfor
 
               end
 
         endcase
 
      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
      print, 'EXAMPLE_TIMES'
 
      for j=0L, (n_elements(dvars)-1L) do begin
 
         print, FORMAT='(A,F20.6)', '  Time value:    ', dvars[j]
 
      endfor
 
      ;;
      ;; Done. Unload the kernels.
      ;;
      cspice_kclear
 
   END


Top

Run the code example



The program runs and first reports the number of kernel pool variables matching the 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.

   Number variables matching template: 6
 
   BODY699_RING1_1
    Number 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
    Number 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
    Number 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_NAME
    Number items: 1   Of type: C
     String value: Encke Gap
 
   BODY699_RING2_NAME
    Number items: 1   Of type: C
     String value: Cassini Division
 
   BODY699_RING1_NAME
    Number items: 1   Of type: C
     String value: A Ring
 
   EXAMPLE_TIMES
     Time value:        134094896.789000
     Time value:        134094896.789000
     Time value:        134094896.789753
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.



Top

Related Routines




    -- cspice_gipool retrieves integer values from the kernel subsystem.



Top

Lesson 3: Coordinate Conversions







Top

Task Statement




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

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



Top

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, 'coord.tm'
 
      ;;
      ;; 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, FORMAT='(A,F20.6)', '    Range: ', range
      print, FORMAT='(A,F20.6)', '    RA   : ', ra * cspice_dpr()
      print, FORMAT='(A,F20.6)', '    DEC  : ', dec* cspice_dpr()
 
      ;;
      ;; ...latitudinal coordinates...
      ;;
      cspice_reclat,  pos, range, lon, lat
      print, '   Latitudinal'
      print, FORMAT='(A,F20.6)', '    Rad  : ', range
      print, FORMAT='(A,F20.6)', '    Lon  : ', lon * cspice_dpr()
      print, FORMAT='(A,F20.6)', '    Lat  : ', lat * cspice_dpr()
 
      ;;
      ;; ...spherical coordinates use the colatitude,
      ;; the angle from the Z axis.
      ;;
      cspice_recsph,  pos, range, colat, lon
      print, '   Spherical'
      print, FORMAT='(A,F20.6)', '    Rad  : ', range
      print, FORMAT='(A,F20.6)', '    Lon  : ', lon   * cspice_dpr()
      print, FORMAT='(A,F20.6)', '    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, FORMAT='(A,F20.6)', '    Rad  : ', range
      print, FORMAT='(A,F20.6)', '    Lon  : ', lon * cspice_dpr()
      print, FORMAT='(A,F20.6)', '    Lat  : ', lat * cspice_dpr()
 
      ;;
      ;; ...spherical coordinates...
      ;;
      cspice_recsph,  pos, range, colat, lon
      print, '   Spherical'
      print, FORMAT='(A,F20.6)', '    Rad  : ', range
      print, FORMAT='(A,F20.6)', '    Lon  : ', lon   * cspice_dpr()
      print, FORMAT='(A,F20.6)', '    Colat: ', colat * cspice_dpr()
 
      ;;
      ;; ...finally, convert the position to geodetic coordinates.
      ;;
      cspice_recgeo,  pos, rad[0], flat, lon, lat, range
      print, '   Geodetic'
      print, FORMAT='(A,F20.6)', '    Rad  : ', range
      print, FORMAT='(A,F20.6)', '    Lon  : ', lon * cspice_dpr()
      print, FORMAT='(A,F20.6)', '    Lat  : ', lat * cspice_dpr()
      print
 
   END


Top

Run the code example



Input "Feb 3 2002 TDB" 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.986950
       Lat  :            -4.989675
Spherical.

      Spherical
       Rad  :        369340.815193
       Lon  :            70.986950
       Colat:            94.989675
Geodetic. The cartographic lat/lon.

      Geodetic
       Rad  :        362962.836755
       Lon  :            70.986950
       Lat  :            -4.990249
 


Top

Related Routines






Top

Lesson 4: Advanced Time Manipulation Routines







Top

Task Statement




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.



Top

Learning Goals




Introduce the routines used for advanced manipulation of time strings. Understand the concept of ephemeris time (ET) as used in Icy.



Top

Code Solution




Caution: Be sure to assign sufficient string lengths for time formats/pictures.

   PRO XTIC
 
      ;;
      ;; Assign the META variable to the name of the meta-kernel
      ;; that contains the LSK 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';
      META     = 'xtic.tm';
      AMBIGSTR = 'Mar 15, 79 12:34:56';
      STRLEN   = 81
 
      ;;
      ;; Load the meta-kernel.
      ;;
      cspice_furnsh, META
      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, FORMAT='(A,F20.6)', '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
 
 
      ;;
      ;; Confirm the tpictr_c call succeeded. Report the error string
      ;; if not.
      ;;
      if ( ~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, FORMAT='(A,F20.6)', 'Years between evaluations:  ', $
                                 (et2 - et1)/cspice_jyear()
 
      ;;
      ;; Reset the default year to 1969.
      ;;
      cspice_tsetyr, 1969
 
      ;;
      ;; Done. Unload the kernels.
      ;;
      cspice_kclear
 
   END


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







Top

Task Statement




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

Learning Goals




Learn how to write a program that has the capability to recover from expected SPICE errors.

The Icy 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 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.



Top

Code Solution




   PRO ADERR
 
      ;;
      ;; Set initial parameters.
      ;;
      SPICETRUE = 1B
      SPICEFALSE= 0B
      doloop    = SPICETRUE;
 
      ;;
      ;; Load the data we need for state evaluation.
      ;;
      cspice_furnsh, 'aderr.tm'
 
      ;;
      ;; 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 :", 3(X,F20.6))', state[0:2]
               print, FORMAT = '( "V :", 3(X,F20.6))', state[3:5]
               print, FORMAT = '( "LT: ",    F20.6)',  ltime
               print
 
            endelse
 
           catch, /cancel
 
         endelse
 
      endwhile
 
      ;;
      ;; Done. Unload the kernels.
      ;;
      cspice_kclear
 
   END


Top

Run the code example



Now run the code with various inputs to observe behavior. Begin the run using known astronomical bodies, e.g. "Moon", "Mars", "Pluto barycenter" and "Puck". 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.616595       -266693.402359        -76095.647558
   V :             0.643439            -0.666066            -0.301310
   LT:             1.342311
 
   Target: Mars
   R :     234536077.419136    -132584383.595569     -63102685.706191
   V :            30.961373            28.932996            13.113031
   LT:           923.001080
 
   Target: Pluto barycenter
   R :   -1451304742.838526   -4318174144.406321    -918251433.587357
   V :            35.079843             3.053138            -0.036762
   LT:         15501.258293
 
   Target: Puck
   ICY_M_SPICE_ERROR
   CSPICE_SPKEZR: SPICE(SPKINSUFFDATA):
                     [spkezr_c->SPKEZR->SPKEZ->SPKACS->SPKAPS->SPKLTC
                    ->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.
                     (CSPICE_N0067)
 
   Target:
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, this time for "Casper"

   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' (CSPICE_N0067)
 
   Target:
An easy to understand error. The SPICE system does not contain information on a body named 'Casper.'

Another look-up, this time, "Venus".

   Target: Venus
   R :     -80970027.540532    -139655772.573898     -53860125.958201
   V :            31.166910           -27.001056           -12.316514
   LT:           567.655074
 
   Target:
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.



Top

Lesson 6: Windows, and Cells







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

Learning Goals




This lesson introduces the concepts of the SPICE 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.



Top

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, 'win.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.
      ;;
      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=0L, (MAXSIZ/2L) -1L 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, FORMAT='("No. data values in sched           : ",I2)', $
                                                 cspice_card(sched)
      print, FORMAT='("Space available for values in sched: ",I2)', $
                                                 cspice_size(sched)
 
      print
      print, 'Time intervals meeting defined criterion.'
 
      for i=0L, (cspice_card(sched)/2L)-1L 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, FORMAT='(I2,4A)', 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, FORMAT='("o Total measure of sched    : ",F16.6)', meas
      print, FORMAT='("o Average measure of sched  : ",F16.6)', avg
      print, 'o Standard deviation of '
      print, FORMAT='("  the measures in sched     : ",F16.6)',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, FORMAT='("o Index of shortest interval: ",I2)', small/2L
      print, FORMAT='("o Index of longest interval : ",I2)', large/2L
 
 
      ;;
      ;; Done. Unload the kernels.
      ;;
      cspice_kclear
 
   END


Top

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.000   2003 JAN 02 04:43:29.000
    1  2003 JAN 05 12:00:00.000   2003 JAN 05 12:45:00.000
    2  2003 JAN 06 00:30:00.000   2003 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.000009
   o Average measure of sched  :      8660.000003
   o Standard deviation of
     the measures in sched     :      5958.550217
   o Index of shortest interval:  1
   o Index of longest interval :  0


Top

Related Routines




    -- cspice_wncomd determines the compliment of a window with respect to a defined interval.

    -- 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_wnincd determines if an interval exists within a window.

    -- cspice_wnreld compares two windows. Comparison operations available, equality '=', inequality '<>', subset '<=' and '>=', proper subset '<' and '>'.



Top

Lesson 7: Utility and Constants Routines







Top

Task Statement




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

Learning Goals




Icy provides several routines to perform commonly needed tasks. Among these:

    -- convert values between unit expressions

    -- determine the equality of strings

    -- indicate whether a file exists

    -- identify the toolkit version

Icy also includes a set of functions that return constant values often used in astrodynamics, time calculations, and geometry.



Top

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, FORMAT='(F12.6,2A)', 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


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_N0067
   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_N0067
   From Units : miles
   From Value : 26.2
   To Units   : km
      42.164813 km


Top

Task Statement




Write a program to output Icy constants and use those constants to calculate some rudimentary values.



Top

Code Solution




   PRO XCONST
 
      ;;
      ;; 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


Top

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


Top

Related Routines




    -- cspice_exists returns a boolean indicating the existence of a file.

    -- 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_pi : double precision value of Pi

    -- cspice_jyear : seconds per Julian year (365.25 Julian days)