Abstract

   CSPICE_PLTNP finds the nearest point on a triangular plate to a
   given point.

I/O

   Given:

      point    an arbitrary point in 3-dimensional space.

               help, point
                  DOUBLE = Array[3]

      v1,
      v2,
      v3       3-vectors constituting the vertices of a triangular plate.

               help, v1
                  DOUBLE = Array[3]
               help, v2
                  DOUBLE = Array[3]
               help, v3
                  DOUBLE = Array[3]

               The plate is allowed to be degenerate: it may
               consist of a line segment or of a single point.

   the call:

      cspice_pltnp, point, v1, v2, v3, pnear, dist

   returns:

      pnear    the closest point on the plate to `point'.

               help, pnear
                  DOUBLE = Array[3]

               `pnear' is unique, since the plate is convex.

      dist     the distance between `point' and `pnear'.

               help, dist
                  DOUBLE = Scalar

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) Find the nearest point to the point (2,2,2) on a plate having
      vertices at the unit basis vectors that lie along the positive
      X, Y, and Z coordinate axes.


      Example code begins here.


      PRO pltnp_ex1

         point = [2.D, 2.0, 2.0]
         v1    = [1.D, 0.0, 0.0]
         v2    = [0.D, 1.0, 0.0]
         v3    = [0.D, 0.0, 1.0]

         cspice_pltnp, point, v1, v2, v3, pnear, dist


         print, 'Plate vertex 1 = ', v1
         print, 'Plate vertex 2 = ', v2
         print, 'Plate vertex 3 = ', v3
         print, 'Input point    = ', point
         print
         print, 'Near point     = ', pnear
         print, 'Distance       = ', dist

      END


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


      Plate vertex 1 =        1.0000000       0.0000000       0.0000000
      Plate vertex 2 =        0.0000000       1.0000000       0.0000000
      Plate vertex 3 =        0.0000000       0.0000000       1.0000000
      Input point    =        2.0000000       2.0000000       2.0000000

      Near point     =       0.33333333      0.33333333      0.33333333
      Distance       =        2.8867513

Particulars

   None.

Exceptions

   1)  The input plate is allowed to be degenerate: it may be
       a line segment or a single point.

   2)  If any of the input arguments, `point', `v1', `v2' or `v3', is
       undefined, an error is signaled by the IDL error handling
       system.

   3)  If any of the input arguments, `point', `v1', `v2' or `v3', 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, `pnear' or `dist', is not a
       named variable, an error is signaled by the Icy interface.

Files

   None.

Restrictions

   None.

Required_Reading

   DSK.REQ
   ICY.REQ

Literature_References

   None.

Author_and_Institution

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

Version

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

       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, 15-DEC-2016 (ML) (EDW)

Index_Entries

   nearest point on triangular plate