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 pl2psv_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
       pl2psv_c ( Plane to point and spanning vectors )

       void pl2psv_c ( ConstSpicePlane  * plane,
                       SpiceDouble        point[3],
                       SpiceDouble        span1[3],
                       SpiceDouble        span2[3]  )
#### Abstract
       Return a point and two orthogonal spanning vectors that generate
       a specified plane.
#### Required_Reading
       PLANES
#### Keywords
       GEOMETRY
       MATH
       PLANE
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       plane      I   A SPICE plane.
       point,
       span1,
       span2      O   A point in the input plane and two vectors
                      spanning the input plane.
#### Detailed_Input
       plane       is a SPICE plane.
#### Detailed_Output
       point,
       span1,
       span2       are, respectively, a point and two orthogonal spanning
                   vectors that generate the geometric plane represented by
                   `plane'. The geometric plane is the set of vectors

                      point   +   s * span1   +   t * span2

                   where `s' and `t' are real numbers. `point' is the closest
                   point in the plane to the origin; this point is always a
                   multiple of the plane's normal vector. `span1' and `span2'
                   are an orthonormal pair of vectors. `point', `span1', and
                   `span2' are mutually orthogonal.
#### Parameters
       None.
#### Exceptions
       Error free.

       1)  The input plane MUST have been 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 )

           Otherwise, the results of this routine are unpredictable.
#### Files
       None.
#### Particulars
       CSPICE geometry routines that deal with planes use the `plane'
       data type to represent input and output planes. This data type
       makes the routine interfaces simpler and more uniform.

       The CSPICE routines that produce SPICE planes from data that
       define a plane are:

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

       The CSPICE routines that convert SPICE planes to data that
       define a plane are:

          pl2nvc_c ( Plane to normal vector and constant )
          pl2nvp_c ( Plane to normal vector and point    )
          pl2psv_c ( Plane to point and spanning vectors )
#### Examples
       1) Project a vector `v' orthogonally onto a plane defined by
          `point', `span1', and `span2'. `proj' is the projection we want; it
          is the closest vector in the plane to `v'.

             psv2pl_c ( point,  span1, span2, &plane );
             vprjp_c  ( &v,    &plane, &proj         );

       2) Find the intersection of a plane and the unit sphere. This
          is a geometry problem that arises in computing the
          intersection of a plane and a triaxial ellipsoid. The
          CSPICE routine inedpl_c computes this intersection, but this
          example does illustrate how to use this routine.

             /.
             The geometric plane of interest will be represented
             by the SPICE plane plane in this example.

             The intersection circle will be represented by the
             vectors center, v1, and v2; the circle is the set
             of points

                center  +  cos(theta) v1  +  sin(theta) v2,

             where theta is in the interval (-pi, pi].

             The logical variable found indicates whether the
             intersection is non-empty.

             The center of the intersection circle will be the
             closest point in the plane to the origin. This
             point is returned by pl2psv_c. The distance of the
             center from the origin is the norm of center.
             ./

             pl2psv_c  ( &plane, center, span1, span2 );

             dist = vnorm_c ( center )

             /.
             The radius of the intersection circle will be

                     ____________
                 _  /          2
                  \/  1 - dist

             since the radius of the circle, the distance of the
             plane from the origin, and the radius of the sphere
             (1) are the lengths of the sides of a right triangle.

             ./

             found = ( dist <= 1.0 );

             if ( found )
             {
                radius = sqrt ( 1.0 - pow(dist,2) );

                vscl_c ( radius, span1, v1 );
                vscl_c ( radius, span2, v2 ) ;
             }

       3) Apply a linear transformation represented by the matrix `m' to
          a plane represented by the normal vector `n' and the constant C.
          Find a normal vector and constant for the transformed plane.

             /.
             Make a SPICE plane from n and c, and then find a
             point in the plane and spanning vectors for the
             plane.  n need not be a unit vector.
             ./
             nvc2pl_c ( n,       c,     &plane         );
             pl2psv_c ( &plane,  point,  span1,  span2 );

             /.
             Apply the linear transformation to the point and
             spanning vectors. All we need to do is multiply
             these vectors by m, since for any linear
             transformation T,

                   T ( point  +  t1 * span1     +  t2 * span2 )

                =  T (point)  +  t1 * T(span1)  +  t2 * T(span2),

             which means that T(point), T(span1), and T(span2)
             are a point and spanning vectors for the transformed
             plane.
             ./

             mxv_c ( m, point, tpoint );
             mxv_c ( m, span1, tspan1 );
             mxv_c ( m, span2, tspan2 );

             /.
             Make a new SPICE plane tplane from the
             transformed point and spanning vectors, and find a
             unit normal and constant for this new plane.
             ./

             psv2pl_c ( tpoint,   tspan1,  tspan2,   &tplane );
             pl2nvc_c ( &tplane,  tn,      &tc               );
#### Restrictions
       None.
#### 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.0.1, 24-AUG-2021 (JDR)

           Edited the header to comply with NAIF standard. Added example #1.

       -CSPICE Version 1.0.0, 05-MAR-1999 (NJB)
#### Index_Entries
       plane to point and spanning vectors
#### Link to routine pl2psv_c source file pl2psv_c.c

    Fri Dec 31 18:41:10 2021