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_vprjp

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


Abstract


   CSPICE_VPRJP projects orthogonally a vector onto a specified plane.

I/O


   Given:

      vin      a double precision 3-vector to orthogonally project onto a
               specified plane.

               help, vin
                  DOUBLE = Array[3]

      plane    a SPICE plane structure that represents the geometric plane onto
               which to project `vin'.

               help, plane
                  STRUCT = CSPICE_PLANE

               The structure has the fields:

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

               The normal vector component of a SPICE plane has unit length.

   the call:

      cspice_vprjp, vin, plane, vout

   returns:

      vout     a double precision 3-vector resulting from the orthogonal
               projection of `vin' onto `plane'.

               help, vout
                  DOUBLE = Array[3]

               `vout' is the closest point in the specified plane to `vin'.

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 closest point in the ring plane of a planet to a
      spacecraft located at a point (in body-fixed coordinates).


      Example code begins here.


      PRO vprjp_ex1

         ;;
         ;; Set the spacecraft location and define the normal
         ;; vector as the normal to the equatorial plane, and
         ;; the origin at the body/ring center.
         ;;
         scpos = [-29703.16955d0, 879765.72163d0, -137280.21757d0]

         norm = [0.d0, 0.d0, 1.d0]

         orig = [0.d0, 0.d0, 0.d0]

         ;;
         ;; Create the plane structure.
         ;;
         cspice_nvp2pl, norm, orig, ringpl

         ;;
         ;; Project the position vector onto the ring plane.
         ;;
         cspice_vprjp, scpos, ringpl, proj

         print, 'Projection of S/C position onto ring plane:'
         print, format='(3F17.5)', proj

      END


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


      Projection of S/C position onto ring plane:
           -29703.16955     879765.72163          0.00000


Particulars


   Projecting a vector `vin' orthogonally onto a plane can be thought of
   as finding the closest vector in the plane to `vin'. This "closest
   vector" always exists; it may be coincident with the original
   vector.

   Two related routines are cspice_vprjpi, which inverts an orthogonal
   projection of a vector onto a plane, and cspice_vproj, which projects
   a vector orthogonally onto another vector.

Exceptions


   1)  If the normal vector of the input plane does not have unit
       length (allowing for round-off error), the error
       SPICE(NONUNITNORMAL) is signaled by a routine in the call tree
       of this routine.

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

   3)  If any of the input arguments, `vin' 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.

   4)  If the output argument `vout' is not a named variable, an
       error is signaled by the Icy interface.

Files


   None.

Restrictions


   1)  It is recommended that the input plane be created by one of
       the Icy routines

          cspice_nvc2pl ( Normal vector and constant to plane )
          cspice_nvp2pl ( Normal vector and point to plane    )
          cspice_psv2pl ( Point and spanning vectors to plane )

       In any case the input plane must have a unit length normal
       vector and a plane constant consistent with the normal
       vector.

Required_Reading


   ICY.REQ
   PLANES.REQ

Literature_References


   [1]  G. Thomas and R. Finney, "Calculus and Analytic Geometry,"
        7th Edition, Addison Wesley, 1988.

Author_and_Institution


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

Version


   -Icy Version 1.1.0, 27-AUG-2021 (JDR) (NJB)

       Added error check for non-unit plane normal vector.

       Edited the header to comply with NAIF standard. Modified code example
       to produce formatted output and use actual data.

       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.1, 23-NOV-2010 (EDW)

       Improved the -Particulars and -I/O sections. The section now meets NAIF
       standard for Icy headers.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries


   vector projection onto plane



Fri Dec 31 18:43:09 2021