Index Page
cspice_srfc2s
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_SRFC2S translates a surface ID code, together with a body
   ID code, to the corresponding surface name. If no such name exists,
   return a string representation of the surface ID code.

   For important details concerning this module's function, please refer to
   the CSPICE routine srfc2s_c.

I/O


   Given:

      code     is an integer code for a surface associated with a body.

      bodyid   is an integer code for the body associated with the
               surface designated by `code'. The combination of `code'
               and `bodyid' is to be mapped to a surface name.

   the call:

      cspice_srfc2s, code, bodyid, srfstr, isname

   returns:

      srfstr   the name of the surface identified by `code', for the
               body designated by `bodyid', if an association exists
               between this pair of ID codes and a surface name.

               If `code' has more than one translation, then the most
               recently defined surface name corresponding to `code' is
               returned. `srfstr' will have the exact format (case and
               embedded blanks) used in the definition of the
               name/code association.

               If the input pair of codes does not map to a surface
               name, `srfstr' is set to the string representation of
               `code'.

      isname   is a logical flag that is SPICETRUE if a surface name
               corresponding to the input ID codes was found and
               SPICEFALSE otherwise. When `isname' is SPICEFALSE, the
               output string `srfstr' contains a string representing the
               integer `code'.

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   Supposed a text kernel has been loaded that contains
   the following assignments:

      NAIF_SURFACE_NAME += ( 'MGS MOLA  64 pixel/deg',
                             'MGS MOLA 128 pixel/deg',
                                'PHOBOS GASKELL Q512'     )
      NAIF_SURFACE_CODE += (   1,   2,    1 )
      NAIF_SURFACE_BODY += ( 499, 499,  401 )

   Translate each surface and body ID code pair to the
   associated surface name. Also perform a translation
   for a surface ID having no matching name.

   Use the meta-kernel shown below to define the required SPICE
   kernel variables.

         KPL/MK
   
         File: srfc2s_t1.tm
   
         This meta-kernel is intended to support operation of SPICE
         example programs. The file contents shown here should not be
         assumed to contain adequate or correct versions of data
         required by SPICE-based user applications.
   
   
         \begindata
   
         NAIF_SURFACE_NAME += ( 'MGS MOLA  64 pixel/deg',
                                'MGS MOLA 128 pixel/deg',
                                'PHOBOS GASKELL Q512'     )
         NAIF_SURFACE_CODE += (   1,   2,    1 )
         NAIF_SURFACE_BODY += ( 499, 499,  401 )
   
         \begintext


      PRO SRFC2S_T
      
         bodyid = [  499L, 401, 499, 499, -1 ]
         surfid = [  1L,   1,   2,   3,  1  ]
         tf     = [ 'false', 'true' ]
         meta   = 'srfc2s_t1.tm';
      
         cspice_furnsh, meta
      
         for i= 0, n_elements( bodyid )-1L do begin
      
            cspice_srfc2s, surfid[i], bodyid[i], srfnam, isname
      
            print, 'surface ID       = ', surfid[i]
            print, 'body ID          = ', bodyid[i]
            print, 'name found       = ', tf[ long(isname) ]
            print, 'surface string   = ', srfnam
            print
      
         endfor
      
         ;;
         ;; It's always good form to unload kernels after use,
         ;; particularly in IDL due to data persistence.
         ;;
         cspice_kclear
      
      END

   IDL outputs:

      surface ID       =            1
      body ID          =          499
      name found       = true
      surface string   = MGS MOLA  64 pixel/deg
      
      surface ID       =            1
      body ID          =          401
      name found       = true
      surface string   = PHOBOS GASKELL Q512
      
      surface ID       =            2
      body ID          =          499
      name found       = true
      surface string   = MGS MOLA 128 pixel/deg
      
      surface ID       =            3
      body ID          =          499
      name found       = false
      surface string   = 3
      
      surface ID       =            1
      body ID          =           -1
      name found       = false
      surface string   = 1

Particulars


   Surfaces are always associated with bodies (which usually are
   ephemeris objects). For any given body, a mapping between surface
   names and surface ID codes can be established.

   Bodies serve to disambiguate surface names and ID codes: the set
   of surface names and surface ID codes for a given body can be
   thought of as belonging to a name space. A given surface ID code
   or surface name may be used for surfaces of multiple bodies,
   without conflict.

   Associations between surface names and ID codes are always made
   via kernel pool assignments; there are no built-in associations.

   cspice_srfc2s is one of four related subroutines:

      cspice_srfs2c    Surface string and body string to surface ID code
      cspice_srfscc    Surface string and body ID code to surface ID code
      cspice_srfc2s    Surface ID code and body ID code to surface string
      cspice_srfcss    Surface ID code and body string to surface string

   cspice_srfs2c, cspice_srfc2s, cspice_srfscc, and cspice_srfcss perform
   translations between surface strings and their corresponding
   integer ID codes.

   Refer to naif_ids.req for details concerning adding new surface
   name/code associations at run time by loading text kernels.

Required Reading


   ICY.REQ
   DSK.REQ
   NAIF_IDS.REQ

Version


   -Icy Version 1.0.0, 15-DEC-2016, ML (JPL), EDW (JPL)

Index_Entries


   surface ID code and body ID code to surface string



Wed Apr  5 17:58:04 2017