Index Page
cspice_dskxsi
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_DSKXSI computes 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.

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

I/O


   Given:

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

   the call:

      cspice_dskxsi, pri, target, nsurf, srflst, et, fixref, vertex, $
                     raydir, xpt, handle, dladsc, dskdsc, dc, ic, found

   returns:

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

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

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

      found      is a logical flag that is set to true if and only if
                 and intercept was found.

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.

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

      PRO DSKXSI_T, meta

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

         ;;
         ;; IcyUser globally defines DSK parameters.
         ;; For more information, please see DSKIcyUser.m and
         ;; DSKIcyUser02.m.
         ;;
         @IcyUser

         DTOL  = 1.0D-14
         MAXN  = 100000L
         dirarr = dblarr( 3, MAXN )
         vtxarr = dblarr( 3, MAXN )
         SPICEFALSE = 0L

         ;;
         ;; Get meta-kernel name from the command line.
         ;;
         cspice_furnsh, meta


         ;;
         ;; Get a handle for one of the loaded DSKs,
         ;; then find the first segment and extract
         ;; the body and surface IDs.
         ;;
         cspice_kdata, 0, 'DSK', file, filtyp, source, handle, found

         if ( ~found ) then begin
            cspice_kclear
            message, 'SPICE(NOINFO)'
         end

         cspice_dlabfs, handle, dladsc, found

         if ( ~found ) then begin
            cspice_kclear
            message, 'SPICE(NOSEGMENT)'
         end

         cspice_dskgd, handle, dladsc, dskdsc

         bodyid = long( dskdsc[SPICE_DSK_CTRIDX] )
         surfid = long( dskdsc[SPICE_DSK_SRFIDX] )
         framid = long( dskdsc[SPICE_DSK_FRMIDX] )

         cspice_bodc2n, bodyid, target, found

         if ( ~found ) then begin

            cspice_kclear
            txt = 'SPICE(BODYNAMENOTFOUND): ' + $
                  'Cannot map body ID ' + string(bodyid) + ' to a name.'

            message, txt
         end

         cspice_frmnam, framid, fixref

         if (fixref eq ' ')  then begin

            cspice_kclear
            txt = 'SPICE(BODYNAMENOTFOUND): ' + $
                  'Cannot map frame ID ' + string(framid) + ' to a name.'

            message, txt
         end

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

         ;;
         ;; 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.5d
         latstp =    1.0d
         lonstp =    2.0d

         nhits  =    0
         nderr  =    0

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

         ;;
         ;; Generate rays.
         ;;
         while ( lon lt 180.d ) do begin

            while ( nlstep le 180.d ) do begin

               if ( lon eq 180.d ) then begin

                  lat = 90.d - nlstep*latstp

               endif else begin

                  if ( nlstep eq 0 ) then begin
                     lat =  90.d - polmrg
                  endif else if ( nlstep eq 180.d ) then begin
                     lat = -90.d + polmrg
                  endif else begin
                     lat =  90.d - nlstep*latstp
                  endelse

               endelse

               cspice_latrec, r, lon*cspice_rpd(), lat*cspice_rpd(), arr
               vtxarr[*,nrays] = arr

               nrays  = nrays  + 1
               nlstep = nlstep + 1

            endwhile

            lon    = lon + lonstp
            lat    = 90.d
            nlstep = 0

         endwhile

         dirarr = -vtxarr

         ;;
         ;; 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    = lonarr(1)
         srflst[0] = surfid

         print, 'Computing intercepts...'

         for i = 0, (nrays-1) do begin

            ;;
            ;; Find the surface intercept of the ith ray.
            ;;
            cspice_dskxsi, SPICEFALSE, target, nsurf, srflst, 0.d, fixref,   $
                           vtxarr[*,i], dirarr[*,i], xpt, xpthan, xptDLAdsc, $
                           xptDSKdsc, dc, ic, found

            if ( found ) then begin

               ;;
               ;; Record that a new intercept was found.
               ;;
               nhits = nhits + 1

               ;;
               ;; Check results.
               ;;
               ;;
               ;; Compute the latitude and longitude of
               ;; the intercept. Make sure these agree
               ;; well with those of the vertex.
               ;;
               cspice_reclat, xpt, radius, lon, lat

               ;;
               ;; Recover the vertex longitude and latitude.
               ;;
               cspice_reclat, vtxarr[*,i], vrad, vlon, vlat
               cspice_latrec, radius,      vlon, vlat, xyzhit

               d = cspice_vdist( xpt, xyzhit )

               if ( d/r gt DTOL ) then begin

                  print, '==========================='
                  print, 'Lon = ' + string(lon) + '  Lat = ' + string(lat)
                  print, 'Bad intercept'
                  print, 'Distance error = ', d
                  print, 'xpt    = ', xpt
                  print, 'xyzhit = ', xyzhit

                  ;;
                  ;; Display the intercept segment's plate ID if
                  ;; applicable.
                  ;;
                  if ( xptDSKdsc(SPICE_DSK_TYPIDX) eq 2 ) then begin
                     print, 'Plate ID = ', ic[0]
                  endif

                  nderr = nderr + 1
               endif

            endif else begin

               ;;
               ;; 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.
               ;;
               print, '==========================='
               print, 'Lon = ' + string(lon) + '  Lat = ' + string(lat)

               cspice_kclear
               message,  'No intercept'

            endelse


         endfor

         print, 'Done.'

         print, 'nrays = ', nrays
         print, 'nhits = ', nhits
         print, 'nderr = ', nderr

         ;;
         ;; It's always good form to unload kernels after use,
         ;; particularly in IDL due to data persistence.
         ;;
         cspice_kclear

      END

   IDL outputs:

      IDL> dskxsi_t, 'dskxsi_t.tm'
      Computing intercepts...
      Done.
      nrays =    32580
      nhits =    32580
      nderr =        0

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

   In cases where the data source information returned by this
   routine are not needed, the routine cspice_dskxv 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 cspice_furnsh and can be unloaded by calling cspice_unload or
      cspice_kclear. See the documentation of cspice_furnsh 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 + SPICE_DSK_XFRACT

            where SPICE_DSK_XFRACT is declared in

               DSKtol.pro

            For example, given a value for SPICE_DSK_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.

Required Reading


   ICY.REQ
   DAS.REQ
   DSK.REQ

Version


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

Index_Entries


   dsk ray-surface intercept with source information
   dsk ray-surface intercept with handle and descriptors



Wed Apr  5 17:58:00 2017