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 vprjpi_c
Table of contents
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
       vprjpi_c ( Vector projection onto plane, inverted )

       void vprjpi_c ( ConstSpiceDouble    vin    [3],
                       ConstSpicePlane   * projpl,
                       ConstSpicePlane   * invpl,
                       SpiceDouble         vout   [3],
                       SpiceBoolean      * found       )
#### Abstract
       Find the vector in a specified plane that maps to a specified
       vector in another plane under orthogonal projection.
#### Required_Reading
       PLANES
#### Keywords
       GEOMETRY
       MATH
       PLANE
       VECTOR
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       vin        I   The projected vector.
       projpl     I   Plane containing `vin'.
       invpl      I   Plane containing inverse image of `vin'.
       vout       O   Inverse projection of `vin'.
       found      O   Flag indicating whether `vout' could be calculated.
#### Detailed_Input
       vin,
       projpl,
       invpl       are, respectively, a 3-vector, a SPICE plane
                   containing the vector, and a SPICE plane
                   containing the inverse image of the vector under
                   orthogonal projection onto `projpl'.
#### Detailed_Output
       vout        is the inverse orthogonal projection of `vin'. This
                   is the vector lying in the plane `invpl' whose
                   orthogonal projection onto the plane `projpl' is
                   `vin'. `vout' is valid only when `found' (defined below)
                   is SPICETRUE. Otherwise, `vout' is undefined.

       found       indicates whether the inverse orthogonal projection
                   of `vin' could be computed. `found' is SPICETRUE if so,
                   SPICEFALSE otherwise.
#### Parameters
       None.
#### Exceptions
       1)  If the normal vector of either 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 the geometric planes defined by `projpl' and `invpl' are
           orthogonal, or nearly so, the inverse orthogonal projection
           of `vin' may be undefined or have magnitude too large to
           represent with double precision numbers. In either such
           case, `found' will be set to SPICEFALSE.

       3)  Even when `found' is SPICETRUE, `vout' may be a vector of extremely
           large magnitude, perhaps so large that it is impractical to
           compute with it. It's up to you to make sure that this
           situation does not occur in your application of this routine.
#### Files
       None.
#### Particulars
       Projecting a vector orthogonally onto a plane can be thought of
       as finding the closest vector in the plane to the original vector.
       This "closest vector" always exists; it may be coincident with the
       original vector. Inverting an orthogonal projection means finding
       the vector in a specified plane whose orthogonal projection onto
       a second specified plane is a specified vector. The vector whose
       projection is the specified vector is the inverse projection of
       the specified vector, also called the "inverse image under
       orthogonal projection" of the specified vector. This routine
       finds the inverse orthogonal projection of a vector onto a plane.

       Related routines are vprjp_c, which projects a vector onto a plane
       orthogonally, and vproj_c, which projects a vector onto another
       vector orthogonally.
#### Examples
       1)   Suppose

               vin    =  ( 0.0, 1.0, 0.0 ),

            and that projpl has normal vector

               projn  =  ( 0.0, 0.0, 1.0 ).

            Also, let's suppose that invpl has normal vector and constant

               invn   =  ( 0.0, 2.0, 2.0 )
               invc   =    4.0.

            Then vin lies on the y-axis in the x-y plane, and we want to
            find the vector vout lying in invpl such that the orthogonal
            projection of vout the x-y plane is vin. Let the notation
            < a, b > indicate the inner product of vectors a and b.
            Since every point x in invpl satisfies the equation

               <  x,  (0.0, 2.0, 2.0)  >  =  4.0,

            we can verify by inspection that the vector

               ( 0.0, 1.0, 1.0 )

            is in invpl and differs from vin by a multiple of projn. So

               ( 0.0, 1.0, 1.0 )

            must be vout.

            To find this result using CSPICE, we can create the
            SPICE planes projpl and invpl using the code fragment

               nvp2pl_c  ( projn,  vin,  &projpl );
               nvc2pl_c  ( invn,   invc, &invpl  );

            and then perform the inverse projection using the call

               vprjpi_c ( vin, &projpl, &invpl, vout );

            vprjpi_c will return the value

               vout = ( 0.0, 1.0, 1.0 );
#### Restrictions
       1)  It is recommended that the input planes be created by one of
           the CSPICE routines

              nvc2pl_c ( Normal vector and constant to plane )
              nvp2pl_c ( Normal vector and point to plane    )
              psv2pl_c ( Point and spanning vectors to plane )

           In any case each input plane must have a unit length normal
           vector and a plane constant consistent with the normal
           vector.
#### 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)
#### Version
       -CSPICE Version 1.1.1, 25-AUG-2021 (JDR) (NJB)

           Edited the header to comply with NAIF standard.

           Added entry #1 to -Exceptions section, and entry #1 to -Restrictions.

       -CSPICE Version 1.1.0, 05-APR-2004 (NJB)

           Computation of LIMIT was re-structured to avoid
           run-time underflow warnings on some platforms.

       -CSPICE Version 1.0.0, 05-MAR-1999 (NJB)
#### Index_Entries
       vector projection onto plane inverted
#### Link to routine vprjpi_c source file vprjpi_c.c

    Fri Dec 31 18:41:15 2021