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

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_SRFSCC translates a surface string, together with a body ID code,
   to the corresponding surface ID code. The input surface string may
   contain a name or an integer ID code.

I/O


   Given:

      srfstr   a string designating a surface.

               help, srfstr
                  STRING = Scalar

               `srfstr' may contain a surface name or a string
               representation of the surface's integer ID code.

               If, for the body specified by `bodyid', multiple surface
               names are associated with one surface ID code, then any
               of these names may be used as the value of `srfstr'.

               Case and leading and trailing blanks in a surface name
               are not significant. Sequences of consecutive embedded
               blanks are considered equivalent to a single blank.
               For example, all of the strings below are considered
               to be equivalent:

                  'MGS MOLA 128 PIXEL/DEG'
                  'MGS MOLA 128 pixel/deg'
                  'MGS MOLA 128 PIXEL/DEG   '
                  'MGS MOLA 128    PIXEL/DEG'
                  '   MGS MOLA 128 PIXEL/DEG'

               However,

                  'MGSMOLA 128PIXEL/DEG'

               is not equivalent to the names above.


      bodyid   the integer ID code of the body associated with the surface
               designated by `srfstr'.

               help, bodyid
                  LONG = Scalar

   the call:

      cspice_srfscc, srfstr, bodyid, code, found

   returns:

      code     integer ID code of the surface designated by `srfstr', for
               the body designated by `bodyid', if for this body an
               association exists between the input surface string and a
               surface ID code.

               help, code
                  LONG = Scalar

               `code' is defined if and only if the output flag `found' is
               True

      found    a logical flag that is True if a surface code corresponding
               to the input surface string and body ID code was found.

               help, found
                  BOOLEAN = Scalar

               `found' is False otherwise.

Parameters


   None.

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.

   1) 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 string pair to the
      associated surface ID code. Also perform a translation
      for a surface name having no matching ID and for
      a body string having no matching body ID code.

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


         KPL/MK

         File: srfscc_ex1.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

         End of meta-kernel


      Example code begins here.


      PRO srfscc_ex1

         bodyid = [ 499L, 401, 499, 499, 401, 499, 499 ]
         srfstr = [ 'MGS MOLA  64 pixel/deg', $
                    'PHOBOS GASKELL Q512',    $
                    'MGS MOLA 128 pixel/deg', $
                    'MGS MOLA  64 pixel/deg', $
                    '1',   $
                    '2',   $
                    'ZZZ', $
                    '1' ]

         tf     = [ 'false', 'true' ]
         meta   = 'srfscc_ex1.tm'

         cspice_furnsh, meta

         for i= 0, n_elements( bodyid )-1 do begin

            surfid = -1

            cspice_srfscc, srfstr[i], bodyid[i], surfid, found

            print, 'surface string   = ', srfstr[i]
            print, 'body ID          = ' , bodyid[i]
            print, 'surface ID found = ', tf[ long(found) ]

            if (found) then print, 'surface ID       = ', surfid

            print

         end

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      surface string   = MGS MOLA  64 pixel/deg
      body ID          =          499
      surface ID found = true
      surface ID       =            1

      surface string   = PHOBOS GASKELL Q512
      body ID          =          401
      surface ID found = true
      surface ID       =            1

      surface string   = MGS MOLA 128 pixel/deg
      body ID          =          499
      surface ID found = true
      surface ID       =            2

      surface string   = MGS MOLA  64 pixel/deg
      body ID          =          499
      surface ID found = true
      surface ID       =            1

      surface string   = 1
      body ID          =          401
      surface ID found = true
      surface ID       =            1

      surface string   = 2
      body ID          =          499
      surface ID found = true
      surface ID       =            2

      surface string   = ZZZ
      body ID          =          499
      surface ID found = false


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

Exceptions


   1)  If the input surface string does not map to an ID code
       and does not represent an integer, the output `code' is
       undefined and the output `found' is set to False.

       This case is not treated as an error.

   2)  If any of the input arguments, `srfstr' or `bodyid', is
       undefined, an error is signaled by the IDL error handling
       system.

   3)  If any of the input arguments, `srfstr' or `bodyid', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy interface.

   4)  If any of the output arguments, `code' or `found', is not a
       named variable, an error is signaled by the Icy interface.

Files


   Surface name-to-ID mappings may be defined at run time by loading
   text kernels containing kernel variable assignments of the form

      NAIF_SURFACE_NAME += ( <surface name 1>, ... )
      NAIF_SURFACE_CODE += ( <surface code 1>, ... )
      NAIF_SURFACE_BODY += ( <body code 1>,    ... )

   Above, the ith elements of the lists on the assignments' right
   hand sides together define the ith surface name/ID mapping.

   The same effect can be achieved using assignments formatted as
   follows:

      NAIF_SURFACE_NAME += <surface name 1>
      NAIF_SURFACE_CODE += <surface code 1>
      NAIF_SURFACE_BODY += <body code 1>

      NAIF_SURFACE_NAME += <surface name 2>
      NAIF_SURFACE_CODE += <surface code 2>
      NAIF_SURFACE_BODY += <body code 2>

         ...

   Note the use of the

      +=

   operator; this operator appends to rather than overwrites the
   kernel variable named on the left hand side of the assignment.

Restrictions


   None.

Required_Reading


   ICY.REQ
   DSK.REQ
   NAIF_IDS.REQ

Literature_References


   None.

Author_and_Institution


   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)
   M. Liukis           (JPL)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.0.1, 01-NOV-2021 (JDR) (NJB)

       Updated description of "srfstr" to indicate that any
       surface name alias may be used.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Edited the header to comply with NAIF standard.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.0, 20-DEC-2016 (ML) (EDW)

Index_Entries


   surface string and body ID code to surface ID code



Fri Dec 31 18:43:08 2021