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

Procedure
Abstract
Required_Reading
Keywords
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version
Index_Entries

Procedure

   void dskxsi_c ( SpiceBoolean         pri,
                   ConstSpiceChar     * target,
                   SpiceInt             nsurf,
                   ConstSpiceInt        srflst [],
                   SpiceDouble          et,
                   ConstSpiceChar     * fixref,
                   ConstSpiceDouble     vertex [3],
                   ConstSpiceDouble     raydir [3],
                   SpiceInt             maxd,
                   SpiceInt             maxi,
                   SpiceDouble          xpt    [3],
                   SpiceInt           * handle,
                   SpiceDLADescr      * dladsc,
                   SpiceDSKDescr      * dskdsc,
                   SpiceDouble          dc     [],
                   SpiceInt             ic     [],
                   SpiceBoolean       * found      )

Abstract

 
   Compute a ray-surface intercept using data provided by  
   multiple loaded DSK segments. Return information about  
   the source of the data defining the surface on which the 
   intercept was found: DSK handle, DLA and DSK descriptors, 
   and DSK data type-dependent parameters. 
 

Required_Reading

 
   CK 
   DSK 
   FRAMES 
   PCK 
   SPK 
   TIME 
 

Keywords

 
   GEOMETRY 
   INTERCEPT 
   SURFACE 
   TOPOGRAPHY 
 

Brief_I/O

 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   pri        I   Data prioritization flag.  
   target     I   Target body name. 
   nsurf      I   Number of surface IDs in list. 
   srflst     I   Surface ID list. 
   et         I   Epoch, expressed as seconds past J2000 TDB. 
   fixref     I   Name of target body-fixed reference frame. 
   vertex     I   Vertex of ray. 
   raydir     I   Direction vector of ray. 
   maxd       I   Size of DC array.
   maxi       I   Size of IC array.
   xpt        O   Intercept point. 
   handle     O   Handle of segment contributing surface data. 
   dladsc     O   DLA descriptor of segment. 
   dskdsc     O   DSK descriptor of segment. 
   dc         O   Double precision component of source info. 
   ic         O   Integer component of source info. 
   found      O   Found flag.  
   SPICE_DSKXSI_DCSIZE
              P    Required size of DC array.
   SPICE_DSKXSI_ICSIZE
              P    Required size of IC array.

Detailed_Input

 
   pri        is a logical flag indicating whether to perform 
              a prioritized or unprioritized DSK segment search. 
              In an unprioritized search, no segment masks another: 
              data from all specified segments are used to   
              define the surface of interest. 
 
              The search is unprioritized if and only if `pri'  
              is set to SPICEFALSE. In the N0066 SPICE Toolkit, this 
              is the only allowed value. 
 
 
   target     is the name of the target body on which a surface 
              intercept is sought. 
 
 
   nsurf, 
   srflst     are, respectively, a count of surface ID codes in a list
              and an array containing the list. Only DSK segments for
              the body designated by `target' and having surface IDs in
              this list will be considered in the intercept
              computation. If the list is empty, all DSK segments for
              `target' will be considered.
 
 
   et         is the epoch of the intersection computation, expressed
              as seconds past J2000 TDB. This epoch is used only for
              DSK segment selection. Segments used in the intercept
              computation must include `et' in their time coverage
              intervals.
 
 
   fixref     is the name of a body-fixed, body-centered reference 
              frame associated with the target. The input ray vectors 
              are specified in this frame, as is the output intercept 
              point. 
     
              The frame designated by `fixref' must have a fixed 
              orientation relative to the frame of any DSK segment 
              used in the computation. 
 
 
   vertex, 
   raydir     are, respectively, the vertex and direction vector of 
              the ray to be used in the intercept computation.  
 
              Both the vertex and ray's direction vector must be 
              represented in the reference frame designated by 
              `fixref'. The vertex is considered to be an offset from 
              the target body. 

   maxd,
   maxi       are, respectively, the declared sizes of the arrays
              `dc' and `ic'. `maxd' must be at least 
             
                 SPICE_DSKXSI_DCSIZE
       
              while `maxi' must be at least 

                 SPICE_DSKXSI_ICSIZE

              See the Parameters section for details.
    

Detailed_Output

 
 
   xpt        is the intercept of the input ray on the surface  
              specified by the inputs 
 
                 pri 
                 target 
                 nsurf 
                 srflst 
                 et 
 
              if such an intercept exists. If the ray intersects the 
              surface at multiple points, the one closest to the 
              ray's vertex is selected. 
 
              `xpt' is defined if and only if `found' is SPICETRUE. 
 
              Units are km. 
 
 
   handle, 
   dladsc, 
   dskdsk     are, respectively, the DSK file handle, DLA descriptor, 
              and DSK descriptor of the DSK file and segment that  
              contributed the surface data on which the intercept  
              was found. 
 
              These outputs are defined if and only if `found' is 
              SPICETRUE. 
 
   dc, 
   ic         are, respectively, double precision and integer arrays 
              that may contain additional information associated 
              with the segment contributing the surface data on 
              which the intercept was found. The information is  
              DSK data type-dependent. 
 
                 For DSK type 2 segments 
 
                    ic[0] is the intercept plate ID. 
                    `dc' is unused. 
                 
              These outputs are defined if and only if `found' is 
              SPICETRUE. 
 
 
   found      is a logical flag that is set to SPICETRUE if and only if 
              and intercept was found. 
 
 

Parameters

 
   See the header file  
 
      SpiceDSK.h
 
   for declarations of size parameters for the output arguments 
 
      dc 
      ic 
 
   See the header files 
 
      SpiceDLA.h
      SpiceDSK.h 
 
   for declarations of DLA and DSK descriptor sizes and 
   documentation of the contents of these descriptors. 
 
   See the header file 
 
      SpiceDtl.h 
 
   for the values of tolerance parameters used by default by the 
   ray-surface intercept algorithm. These are discussed in in the 
   Particulars section below. 
 

Exceptions

 
   1)  If the input prioritization flag `pri' is set to SPICETRUE, 
       the error SPICE(NOPRIORITIZATION) is signaled. 
    
   2)  If the input body name `target' cannot be mapped to an 
       ID code, the error SPICE(IDCODENOTFOUND) is signaled. 
 
   3)  If the input frame name `fixref' cannot be mapped to an 
       ID code, the error SPICE(IDCODENOTFOUND) is signaled. 
 
   4)  If the frame center associated with `fixref' cannot be 
       retrieved, the error SPICE(NOFRAMEINFO) is signaled. 
 
   5)  If the frame center associated with `fixref' is not 
       the target body, the error SPICE(INVALIDFRAME) is signaled. 
 
   6)  Any errors that occur during the intercept computation 
       will be signaled by routines in the call tree of this 
       routine. 

   7)  If `maxd' is less than SPICE_DSKXIS_DCSIZE or `maxi' is less 
       than SPICE_DSKXSI_ICSIZE, the error SPICE(ARRAYTOOSMALL) will 
       be signaled.

   8)  If any input string argument pointer is null, the error
       SPICE(NULLPOINTER) will be signaled.

   9)  If any input string argument is empty, the error
       SPICE(EMPTYSTRING) will be signaled.

Files

   
   Appropriate kernels must be loaded by the calling program before 
   this routine is called. 
 
   The following data are required: 
 
      - SPK data: ephemeris data for the positions of the centers 
        of DSK reference frames relative to the target body are 
        required if those frames are not centered at the target 
        body center. 
 
        Typically ephemeris data are made available by loading one 
        or more SPK files via furnsh_c. 
 
      - DSK data: DSK files containing topographic data for the 
        target body must be loaded. If a surface list is specified, 
        data for at least one of the listed surfaces must be loaded. 
 
      - Frame data: if a frame definition is required to convert 
        DSK segment data to the body-fixed frame designated by 
        `fixref', the target, that definition must be available in the 
        kernel pool. Typically the definitions of frames not already 
        built-in to SPICE are supplied by loading a frame kernel. 
 
      - CK data: if the frame to which `fixref' refers is a CK frame, 
        and if any DSK segments used in the computation have a 
        different frame, at least one CK file will be needed to 
        permit transformation of vectors between that frame and both 
        the J2000 and the target body-fixed frames. 
 
      - SCLK data: if a CK file is needed, an associated SCLK 
        kernel is required to enable conversion between encoded SCLK 
        (used to time-tag CK data) and barycentric dynamical time 
        (TDB). 
 
   In all cases, kernel data are normally loaded once per program 
   run, NOT every time this routine is called.  
 
 

Particulars

 
 
   This is the lowest-level public interface for computing 
   ray-surface intercepts, where the surface is modeled using 
   topographic data provided by DSK files. The highest-level 
   interface for this purpose is sincpt_c. 
 
   In cases where the data source information returned by this 
   routine are not needed, the routine dskxv_c may be more suitable. 
 
   This routine works with multiple DSK files. It places no 
   restrictions on the data types or coordinate systems of the DSK 
   segments used in the computation. DSK segments using different 
   reference frames may be used in a single computation. The only 
   restriction is that any pair of reference frames used directly or 
   indirectly are related by a constant rotation. 
 
   This routine enables calling applications to identify the source of
   the data defining the surface on which an intercept was found. The
   file, segment, and segment-specific information such as a DSK type 2
   plate ID are returned.
 
   This routine can be used for improved efficiency in situations  
   in which multiple ray-surface intercepts are to be performed 
   using a constant ray vertex. 
 
 
   Using DSK data 
   ============== 
 
      DSK loading and unloading 
      ------------------------- 
 
      DSK files providing data used by this routine are loaded by 
      calling furnsh_c and can be unloaded by calling unload_c or 
      kclear_c. See the documentation of furnsh_c for limits on numbers 
      of loaded DSK files. 
 
      For run-time efficiency, it's desirable to avoid frequent 
      loading and unloading of DSK files. When there is a reason to 
      use multiple versions of data for a given target body---for 
      example, if topographic data at varying resolutions are to be 
      used---the surface list can be used to select DSK data to be 
      used for a given computation. It is not necessary to unload 
      the data that are not to be used. This recommendation presumes 
      that DSKs containing different versions of surface data for a 
      given body have different surface ID codes. 
 
 
      DSK data priority 
      ----------------- 
 
      A DSK coverage overlap occurs when two segments in loaded DSK 
      files cover part or all of the same domain---for example, a 
      given longitude-latitude rectangle---and when the time 
      intervals of the segments overlap as well. 
 
      When DSK data selection is prioritized, in case of a coverage 
      overlap, if the two competing segments are in different DSK 
      files, the segment in the DSK file loaded last takes 
      precedence. If the two segments are in the same file, the 
      segment located closer to the end of the file takes 
      precedence. 
 
      When DSK data selection is unprioritized, data from competing 
      segments are combined. For example, if two competing segments 
      both represent a surface as sets of triangular plates, the 
      union of those sets of plates is considered to represent the 
      surface.  
 
      Currently only unprioritized data selection is supported. 
      Because prioritized data selection may be the default behavior 
      in a later version of the routine, the presence of the `pri' 
      argument is required. 
 
 
      Round-off errors and mitigating algorithms 
      ------------------------------------------ 
 
      When topographic data are used to represent the surface of a 
      target body, round-off errors can produce some results that 
      may seem surprising. 
 
      Note that, since the surface in question might have mountains, 
      valleys, and cliffs, the points of intersection found for 
      nearly identical sets of inputs may be quite far apart from 
      each other: for example, a ray that hits a mountain side in a 
      nearly tangent fashion may, on a different host computer, be 
      found to miss the mountain and hit a valley floor much farther 
      from the observer, or even miss the target altogether. 
       
      Round-off errors can affect segment selection: for example, a 
      ray that is expected to intersect the target body's surface 
      near the boundary between two segments might hit either 
      segment, or neither of them; the result may be 
      platform-dependent. 
 
      A similar situation exists when a surface is modeled by a set 
      of triangular plates, and the ray is expected to intersect the 
      surface near a plate boundary. 
       
      To avoid having the routine fail to find an intersection when 
      one clearly should exist, this routine uses two "greedy" 
      algorithms: 
      
         1) If the ray passes sufficiently close to any of the  
            boundary surfaces of a segment (for example, surfaces of 
            maximum and minimum longitude or latitude), that segment 
            is tested for an intersection of the ray with the 
            surface represented by the segment's data. 
 
            This choice prevents all of the segments from being 
            missed when at least one should be hit, but it could, on 
            rare occasions, cause an intersection to be found in a 
            segment other than the one that would be found if higher 
            precision arithmetic were used. 
             
         2) For type 2 segments, which represent surfaces as  
            sets of triangular plates, each plate is expanded very 
            slightly before a ray-plate intersection test is 
            performed. The default plate expansion factor is  
 
               1 + XFRACT 
 
            where XFRACT is declared in  
 
               SpiceDtl.h 
 
            For example, given a value for XFRACT of 1.e-10, the 
            sides of the plate are lengthened by 1/10 of a micron 
            per km. The expansion keeps the centroid of the plate 
            fixed. 
 
            Plate expansion prevents all plates from being missed 
            in cases where clearly at least one should be hit. 
 
            As with the greedy segment selection algorithm, plate 
            expansion can occasionally cause an intercept to be 
            found on a different plate than would be found if higher 
            precision arithmetic were used. It also can occasionally 
            cause an intersection to be found when the ray misses 
            the target by a very small distance.  
 

Examples

 
   The numerical results shown for these examples may differ across 
   platforms. The results depend on the SPICE kernels used as 
   input, the compiler and supporting libraries, and the machine  
   specific arithmetic implementation.  
     
   1) Compute surface intercepts of rays emanating from a set of 
      vertices distributed on a longitude-latitude grid. All 
      vertices are outside the target body, and all rays point 
      toward the target's center. 

      Check intercepts against expected values. Indicate the 
      number of errors, the number of computations, and the 
      number of intercepts found. 
 
      Use the meta-kernel shown below to load example SPICE 
      kernels. 

          KPL/MK

          File: dskxsi_ex1.tm

          This meta-kernel is intended to support operation of SPICE
          example programs. The kernels shown here should not be
          assumed to contain adequate or correct versions of data
          required by SPICE-based user applications.

          In order for an application to use this meta-kernel, the
          kernels referenced here must be present in the user's
          current working directory.

          The names and contents of the kernels referenced
          by this meta-kernel are as follows:

             File name                        Contents
             ---------                        --------
             phobos512.bds                    DSK based on
                                              Gaskell ICQ Q=512
                                              plate model
          \begindata

             PATH_SYMBOLS    = 'GEN'
             PATH_VALUES     = '/ftp/pub/naif/generic_kernels'

             KERNELS_TO_LOAD = ( '$GEN/dsk/phobos/phobos512.bds' )

          \begintext

  
   Example code begins here. 
 

      /.
      Multi-segment spear program.

      This program expects all loaded DSKs
      to represent the same body and surface.

      Syntax: spear <meta-kernel>
      ./

      #include <stdio.h>
      #include <stdlib.h>
      #include "SpiceUsr.h"

      int main( int argc,  char **argv )
      {
         /.
         Local constants 
         ./ 
         #define  DTOL           1.0e-14
         #define  FILSIZ         256
         #define  FRNMLN         33
         #define  BDNMLN         37
         #define  TYPLEN         5
         #define  INTLEN         12
         #define  MAXN           100000
         #define  MAXSRF         100
         #define  MAXD           SPICE_DSKXSI_DCSIZE
         #define  MAXI           SPICE_DSKXSI_ICSIZE

         /.
         Local variables
         ./
         SpiceBoolean            found;

         SpiceChar               dsk1   [FILSIZ];
         SpiceChar               fixref [FRNMLN];
         SpiceChar               source [FILSIZ];
         SpiceChar               filtyp [TYPLEN];
         SpiceChar               target [BDNMLN];

         SpiceDLADescr           dladsc;
         SpiceDLADescr           xptDLAdsc;

         SpiceDSKDescr           dskdsc;
         SpiceDSKDescr           xptDSKdsc;

         SpiceDouble             d;
         SpiceDouble             dc    [1];
         static SpiceDouble      dirarr[MAXN][3];
         SpiceDouble             et;
         SpiceDouble             lat;
         SpiceDouble             latcrd[3];
         SpiceDouble             latstp;
         SpiceDouble             lon;
         SpiceDouble             lonstp;
         SpiceDouble             polmrg;
         SpiceDouble             r;
         SpiceDouble             radius;
         SpiceDouble             vlat;
         SpiceDouble             vlon;
         SpiceDouble             vrad;
         static SpiceDouble      vtxarr[MAXN][3];
         static SpiceDouble      xpt   [3];
         SpiceDouble             xyzhit[3];

         SpiceInt                bodyid;
         SpiceInt                framid;
         SpiceInt                handle;
         SpiceInt                i;
         SpiceInt                ic    [1];
         SpiceInt                nderr;
         SpiceInt                nhits;
         SpiceInt                nlstep;
         SpiceInt                nrays;
         SpiceInt                nsurf;
         static SpiceInt         srflst [MAXSRF];
         SpiceInt                surfid;
         SpiceInt                xpthan;



         chkin_c ( "spear" );

         /.
         Get meta-kernel name from the command line. 
         ./
         if ( argc != 2 )
         {
            printf ( "Command syntax:  spear <meta-kernel>\n" );
            exit(1);
         }

         /.
         Load the meta-kernel. 
         ./
         furnsh_c ( argv[1] );

         /.
         Get a handle for one of the loaded DSKs,
         then find the first segment and extract
         the body and surface IDs. 
         ./
         kdata_c ( 0,    "DSK",  FILSIZ, TYPLEN,  FILSIZ,
                   dsk1, filtyp, source, &handle, &found );
         if ( !found )
         {
            sigerr_c ( "SPICE(NOINFO)" );
         }

         dlabfs_c ( handle, &dladsc, &found );

         if ( !found )
         {
            sigerr_c ( "SPICE(NOSEGMENT)" );
         }

         dskgd_c ( handle, &dladsc, &dskdsc );

         bodyid = dskdsc.center;
         surfid = dskdsc.surfce;
         framid = dskdsc.frmcde;

         bodc2n_c ( bodyid, BDNMLN, target, &found );

         if ( !found )
         {
            setmsg_c ( "Cannot map body ID # to a name." );
            errint_c ( "#", bodyid                       );
            sigerr_c ( "SPICE(BODYNAMENOTFOUND)"         );
         }

         frmnam_c ( framid, FRNMLN, fixref );

         if ( eqstr_c( fixref, " " ) )
         {
            setmsg_c ( "Cannot map frame ID # to a name." );
            errint_c ( "#", framid                        );
            sigerr_c ( "SPICE(BODYNAMENOTFOUND)"          );
         }

         /.
         Set the magnitude of the ray vertices. Use a large
         number to ensure the vertices are outside of
         any realistic target.
         ./
         r = 1.0e10;

         /.
         Spear the target with rays pointing toward
         the origin.  Use a grid of ray vertices
         located on a sphere enclosing the target.

         The variable `polmrg' ("pole margin") can
         be set to a small positive value to reduce
         the number of intercepts done at the poles.
         This may speed up the computation for
         the multi-segment case, since rays parallel
         to the Z axis will cause all segments converging
         at the pole of interest to be tested for an
         intersection.
         ./     

         polmrg =    0.5;
         latstp =    1.0;
         lonstp =    2.0;

         nhits  =    0;
         nderr  =    0;

         lon    = -180.0;
         lat    =   90.0;
         nlstep =    0;
         nrays  =    0;

         /.
         Generate rays. 
         ./
         while ( lon < 180.0 )
         {
            while ( nlstep <= 180 )
            {
               if ( lon == 180.0 )
               {
                  lat = 90.0 - nlstep*latstp;
               }
               else
               {
                  if ( nlstep == 0 )
                  {
                     lat =  90.0 - polmrg;
                  }
                  else if ( nlstep == 180 )
                  {
                     lat = -90.0 + polmrg;
                  }
                  else
                  {
                     lat =  90.0 - nlstep*latstp;
                  }
               }

               latrec_c ( r,             lon*rpd_c(), 
                          lat*rpd_c(),   vtxarr[nrays] );

               vminus_c ( vtxarr[nrays], dirarr[nrays] );

               ++ nrays;
               ++ nlstep;      
            }

            lon   += lonstp;
            lat    = 90.0;
            nlstep = 0;
         }

         /.
         Assign surface ID list. 

         Note that, if we knew that all files had the desired
         surface ID, we could set `nsurf' to 0 and omit the
         initialization of the surface ID list.
         ./
         nsurf     = 1;
         srflst[0] = surfid;

         printf ( "Computing intercepts...\n" );

         for ( i = 0;  i < nrays;  i++ )
         {
            /.
            Find the surface intercept of the ith ray. 
            ./

            dskxsi_c ( SPICEFALSE, target,     nsurf,      srflst,
                       et,         fixref,     vtxarr[i],  dirarr[i], 
                       MAXD,       MAXI,       xpt,        &xpthan, 
                       &xptDLAdsc, &xptDSKdsc, dc,         ic,      
                       &found                                       );

            if ( found )
            {

               /.
               Record that a new intercept was found. 
               ./
               ++ nhits;

               /.
               Check results. 


               Compute the latitude and longitude of         
               the intercept. Make sure these agree
               well with those of the vertex.
               ./
               reclat_c ( xpt, latcrd, latcrd+1, latcrd+2 );
               radius = latcrd[0];

               /.
               Recover the vertex longitude and latitude.
               ./
               reclat_c ( vtxarr[i], &vrad, &vlon, &vlat  );
               latrec_c ( radius,     vlon,  vlat, xyzhit );

               d = vdist_c( xpt, xyzhit );

               if ( d/r > DTOL )
               {
                  printf ( "===========================\n" );
                  printf ( "Lon = %f;  Lat = %f\n",
                           lon, lat                        );
                  printf ( "Bad intercept\n"               );
                  printf ( "Distance error = %e\n", d      );
                  printf ( "xpt    = (%e %e %e)\n",
                           xpt[0], xpt[1], xpt[2] );
                  printf ( "xyzhit = (%e %e %e)\n",
                           xyzhit[0], xyzhit[1], xyzhit[2] );
                  /.
                  Display the intercept segment's plate ID if
                  applicable.
                  ./
                  if ( xptDSKdsc.dtype == 2 )
                  {
                     printf ( "Plate ID = %d\n", (int)ic[0] );
                  }

         
                  ++ nderr;
               }
            }
            else
            {
               /.
               Missing the target entirely is a fatal error.

               This is true only for this program, not in
               general. For example, if the target shape is
               a torus, many rays would miss the target.
               ./
               printf ( "===========================\n" );
               printf ( "Lon = %f;  Lat = %f\n",
                        lon, lat                        );
               printf ( "No intercept\n"                );
               exit( 1 );
            }
         }
         printf ( "Done.\n\n" );

         printf( "nrays = %d\n", (int)nrays );
         printf( "nhits = %d\n", (int)nhits );
         printf( "nderr = %d\n", (int)nderr );

         return ( 0 );
      }  
 

   When this program was executed on a PC/Linux/gcc 64-bit  
   platform, using the meta-kernel shown above, the output was: 
 

      Computing intercepts...
      Done.

      nrays = 32580
      nhits = 32580
      nderr = 0

 

Restrictions

 
   1)  The frame designated by `fixref' must have a fixed 
       orientation relative to the frame of any DSK segment 
       used in the computation. This routine has no  
       practical way of ensuring that this condition is met; 
       so this responsibility is delegated to the calling 
       application. 
     

Literature_References

 
   None. 
 

Author_and_Institution

 
   N.J. Bachman    (JPL) 
 

Version

 
   -CSPICE Version 1.0.0, 04-APR-2017 (NJB)

Index_Entries

 
   dsk ray-surface intercept with source information 
   dsk ray-surface intercept with handle and descriptors 
 
Wed Apr  5 17:54:32 2017