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_inrypl

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


Abstract


   CSPICE_INRYPL finds the intersection of a ray and a plane.

I/O


   Given:

      vertex   a double precision 3-vector defining the vertex position of a
               ray.

               help, vertex
                  DOUBLE = Array[3]

      dir      a double precision 3-vector defining the direction of a ray from
               `vertex'.

               help, dir
                  DOUBLE = Array[3]

      plane    a scalar SPICE plane structure.

               help, plane
                  STRUCT = CSPICE_PLANE

               The structure has the fields:

                 normal:   [3-array double]
                 constant: [scalar double]

   the call:

      cspice_inrypl, vertex, dir, plane, nxpts, xpt

   returns:

      nxpts   a scalar integer flag indicating the number of intersection
              points between the ray and `plane':

                 0     No intersection.

                 1     One point of intersection. Note that
                       this case may occur when the ray's
                       vertex is in the plane.

                -1     An infinite number of points of
                       intersection; the ray lies in the plane.

               help, nxpts
                  LONG = Scalar

      xpt      a double precision 3-vector defining the point of intersection
               of the input ray and `plane', when one point of intersection
               exists.

               help, xpt
                  DOUBLE = Array[3]

               If the ray lies in the plane, `xpt' is set equal to `vertex'.

               If no intersection exists, `xpt' returns as the zero vector.

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) Determine the intersection between the Saturn ring plane and
      a look direction as seen from a position in the Saturn
      body-fixed frame. For this extremely simplistic example,
      we take the equatorial plane as the ring plane.

      Use the PCK kernel below to load the required triaxial
      ellipsoidal shape model and orientation data for Saturn.

         pck00008.tpc


      Example code begins here.


      PRO inrypl_ex1

         ;;
         ;; Load a PCK.
         ;;
         cspice_furnsh, 'pck00008.tpc'

         ;;
         ;; Retrieve the triaxial radii of Saturn (699)
         ;;
         cspice_bodvrd, 'SATURN', 'RADII', 3, radii

         ;;
         ;; Define a position in the IAU_SATURN frame at three equatorial
         ;; radius out along the x axis, a half radius above the
         ;; equatorial plane. For this example, we'll assume 'vertex'
         ;; represents the light-time corrected position of a vehicle
         ;; to the Saturn ring plane.
         ;;
         vertex = [ 3.d0 * radii[0], 0.d0, radii[2] *.5d0 ];

         ;;
         ;; Define a look vector in the y-z plane from 'vertex'.
         ;;
         ;;   'vertex'
         ;;      *______ y
         ;;     /|\
         ;;    / | \  30 degrees
         ;;   /  |  \
         ;;  x  -z  'dir'
         ;;
         dir = [ 0.d,                       $
                 cos( 30.d *cspice_rpd() ), $
                -sin( 30.d *cspice_rpd() )  $
               ]

         ;;
         ;; Define the equatorial plane as a SPICE plane. The Z
         ;; axis is normal to the plane, the origin lies in the
         ;; plane.
         ;;
         normal = [ 0.d, 0.d, 1.d]
         point  = [ 0.d, 0.d, 0.d]
         cspice_nvp2pl , normal, point, plane

         ;;
         ;; Determine the intersection point of 'dir' and 'plane', if
         ;; such an intersection exists.
         ;;
         cspice_inrypl, vertex, dir, plane, nxpts, xpt

         ;;
         ;; Do we have an intersection?
         ;;
         if ( nxpts eq 1 ) then begin
            print, FORMAT='(A,3F13.5)', 'Vector intersects plane at:', $
                                        xpt
         endif

         ;;
         ;; No intersection
         ;;
         if ( nxpts eq 0 ) then begin
            print, 'No intersection between vector and plane.'
         endif

         ;;
         ;; No intersection
         ;;
         if ( nxpts eq -1 ) then begin
            print, 'Vector lies in plane, degenerate case.'
         endif

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

      END


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


      Vector intersects plane at: 180804.00000  47080.60505      0.00000


Particulars


   The intersection of a ray and plane in three-dimensional space
   can be a the empty set, a single point, or the ray itself.

Exceptions


   1)  If the ray's direction vector is the zero vector, the error
       SPICE(ZEROVECTOR) is signaled by a routine in the call tree of
       this routine. `nxpts' and `xpt' are not modified.

   2)  If the ray's vertex is further than cspice_dpmax() / 3 from the
       origin, the error SPICE(VECTORTOOBIG) is signaled by a routine
       in the call tree of this routine. `nxpts' and `xpt' are not
       modified.

   3)  If the input plane is further than cspice_dpmax() / 3 from the
       origin, the error SPICE(VECTORTOOBIG) is signaled by a routine
       in the call tree of this routine. `nxpts' and `xpt' are not
       modified.

   4)  The input plane should be created by one of the Icy
       routines

          cspice_nvc2pl
          cspice_nvp2pl
          cspice_psv2pl

       Invalid input planes will cause unpredictable results.

   5)  In the interest of good numerical behavior, in the case
       where the ray's vertex is not in the plane, this routine
       considers that an intersection of the ray and plane occurs
       only if the distance between the ray's vertex and the
       intersection point is less than cspice_dpmax() / 3.

       If `vertex' is not in the plane and this condition is not
       met, then `nxpts' is set to 0 and `xpt' is set to the zero
       vector.

   6)  If any of the input arguments, `vertex', `dir' or `plane', is
       undefined, an error is signaled by the IDL error handling
       system.

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

   8)  If any of the output arguments, `nxpts' or `xpt', is not a
       named variable, an error is signaled by the Icy interface.

Files


   None.

Restrictions


   None.

Required_Reading


   ICY.REQ
   PLANES.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.0.1, 01-JUN-2021 (JDR)

       Edited the header to comply with NAIF standard.

       Added example's problem statement and required PCK. Reformatted
       example's output. Added cspice_kclear to example.

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

       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, 16-JUN-2003 (EDW)

Index_Entries


   intersection of ray and plane



Fri Dec 31 18:43:05 2021