vprjpi_c

Index Page vprjpi_c
A B C D E F G H I J K L M N O P Q R S T U V W X
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
       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 CSPICE plane
                      containing the vector, and a CSPICE 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 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.

       2)  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
            CSPICE 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
       None.
#### Literature_References
       [1] `Calculus and Analytic Geometry', Thomas and Finney.
#### Author_and_Institution
       N.J. Bachman   (JPL)
#### Version
       -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

    Thu Apr 16 08:59:34 2009