Planes Required Reading 
Table of ContentsPlanes Required Reading Abstract Introduction References Plane Data Type Description Plane routines Constructing planes Construct a plane from a normal vector and constant Construct a plane from a normal vector and a point Construct a plane from a point and spanning vectors Access plane data elements Examples Converting between representations of planes Translating planes Applying linear transformations to planes Finding the limb of an ellipsoid Header examples Use of ellipses with planes Summary of routines Appendix: Document Revision History 2012 JAN 23, EDW (JPL) 2008 JAN 17, BVS (JPL) 2002 DEC 12, NAIF (JPL) Planes Required Reading
Abstract
Introduction
References
Plane Data Type Description
< X, Y >denote the inner product of the vectors X and Y, then the relationship
< X, N > = Cholds for all vectors X in the plane. C is the distance of the plane from the origin. The vector
C * Nis the closest point in the plane to the origin. For planes that do not contain the origin, the vector N points from the origin toward the plane. The internal design of the plane data type is not part of its specification. The design is an implementation choice based on the programming language and so the design may change. Users should not write code based on the current implementation; such code might fail when used with a future version of CSPICE. NAIF implemented the SPICE plane data type in C as a structure with the fields
SpiceDouble normal [3]; SpiceDouble constant;'normal' contains the unit normal vector N; 'constant' contains the plane constant C. Plane routinesConstructing planes
The information stored in SPICE planes is not necessarily the input information you supply to a planemaking routine. SPICE planes use a single, uniform internal representation for planes, no matter what data you use to create them. As a consequence, when you create a SPICE plane and then break it apart into data that define a plane, the returned data will not necessarily be the data you originally supplied, though they define the same geometric plane as the data you originally supplied. This `loss of information' may seem to be a liability at first but turns out to be a convenience in the end: the CSPICE routines that break apart SPICE planes into various representations return outputs that are particularly useful for many geometric computations. In the case of the routine pl2nvp_c (Plane to normal vector and point), the output normal vector is always a unit vector, and the output point is always the closest point in the plane to the origin. The normal vector points from the origin toward the plane, if the plane does not contain the origin. You can convert any of the following representations of planes to a SPICE plane:
< X, N > = C.
< X  P, N > = 0.
P + s * V1 + t * V2,
Construct a plane from a normal vector and constant
Let `n', `c' and `plane' be declared by
SpiceDouble n[3]; SpiceDouble c; SpicePlane plane;After `n' and `c' have been assigned values, you can construct a SPICE plane that represents the plane having normal `n' and constant `c' by calling nvc2pl_c:
nvc2pl_c ( n, c, &plane ); Construct a plane from a normal vector and a point
Declare `n', `p', and `plane' as:
SpiceDouble n[3]; SpiceDouble p[3]; SpicePlane plane;After `n' and `p' have been assigned values, you can construct a SPICE plane that represents the plane containing point `p' and having normal `n' by calling nvp2pl_c:
nvp2pl_c ( n, p, &plane ); Construct a plane from a point and spanning vectors
Let `p', `v1', `v2', and `plane' be declared by
ConstSpiceDouble point[3]; ConstSpiceDouble span1[3]; ConstSpiceDouble span2[3]; SpicePlane plane;After `p', `v1', and `v2' have been assigned values, you can construct a SPICE plane that represents the plane spanned by the vectors V1 and V2 and containing the point P by calling psv2pl_c:
psv2pl_c ( p, v1, v2, &plane ); Access plane data elements
The CSPICE routines that break planes apart into data that define geometric planes are
To find a unit normal vector `n' and a plane constant `c' that define `plane', use pl2nvc_c:
pl2nvc_c ( &plane, n, &c );The constant `c' is the distance of the plane from the origin. The vector
C * Nwill be the closest point in the plane to the origin. To find a unit normal vector `n' and a point `p' that define `plane', use pl2nvp_c:
pl2nvp_c ( &plane, n, p );`p' will be the closest point in the plane to the origin. The unit normal vector `n' will point from the origin toward the plane. To find a point `p' and two spanning vectors `v1' and `v2' that define `plane', use pl2psv_c:
pl2psv_c ( &plane, p, v1, v2 );`p' will be the closest point in the plane to the origin. The vectors `v1' and `v2' are mutually orthogonal unit vectors and are also orthogonal to `p'. It is important to note that the xxx2PL and PL2xxx routines are not exact inverses of each other. The pairs of calls
nvc2pl_c ( n, c, &plane ) pl2nvc_c ( &plane, n, &c ) nvp2pl_c ( p, n, &plane ) pl2nvp_c ( plane p, n ) psv2pl_c ( v1, v2, p, &plane ) pl2psv_c ( &plane, v1, v2, p )do not necessarily preserve the input arguments supplied to the xxx2PL routines. This is because the uniform internal representation of SPICE planes causes them to `forget' what data they were created from; all sets of data that define the same geometric plane have the same internal representation in SPICE planes. In general, the routines pl2nvc_c, pl2nvp_c, and pl2psv_c are used in routines that accept planes as input arguments. In this role, they simplify the routines that call them, because the calling routines no longer check the input planes' validity. ExamplesConverting between representations of planes
nvc2pl_c ( n, c, &plane ); pl2nvp_c ( &plane, n, point ); Translating planes
T(X) = X + A for all vectors Xwhere A is a constant vector. While it's not difficult to directly apply a translation map to a plane, using SPICE plane routines provides the convenience of automatically computing the closest point to the origin in the translated plane. Suppose a plane is defined by the point `p' and the normal vector `n', and you wish to translate it by the vector `x'. That is, you wish to find data defining the plane that results from adding `x' to every vector in the original plane. You can do this with the code fragment
vadd_c ( p, x, p ); (Vector addition) nvp2pl_c ( n, p, &plane ); pl2nvp_c ( &plane, n, p );Now, `p' is the closest point in the translated plane to the origin. Applying linear transformations to planes
Let T be represented by the matrix M. If Y is a point in the transformed plane, then 1 M Y is a point in the original plane, so 1 < N, M Y > = C. But 1 T 1 < N, M Y > = N M Y 1 T T = ( ( M ) N ) Y 1 T = < ( M ) N, Y > So 1 T ( M ) N, C are, respectively, a normal vector and constant for the transformed plane.We can solve the problem using the following code fragments. Make a SPICE plane from `n' and `c', and then find a point in `plane' and spanning vectors for `plane'. `n' need not be a unit vector.
nvc2pl_c ( n, c, &plane ) pl2psv_c ( &plane, point, v1, v2 )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 * V1 + t2 * V2 ) = T (POINT) + t1 * T (V1) + t2 * T (V2),which means that T(POINT), T(V1), and T(V2) are a a point and spanning vectors for the transformed plane.
mxv_c ( m, point, tpoint ); mxv_c ( m, v1, tv1 ); mxv_c ( m, v2, tv2 );Construct 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, tv1, tv2, &tplane ); pl2nvc_c ( &tplane, tn, tc ); Finding the limb of an ellipsoid
We'll work in bodyfixed coordinates, which is to say that the ellipsoid is centered at the origin and has axes aligned with the x, y and z axes. Suppose that the semiaxes of the ellipsoid has lengths A, B, and C, and call our observation point
P = ( p1, p2, p3 ).Then every point
X = ( x1, x2, x3 )on the limb satisfies
< P  X, N > = 0where N a surface normal vector at X. In particular, the gradient vector
2 2 2 ( x1/A , x2/B , x3/C )is a surface normal, so X satisfies
0 = < P  X, N > 2 2 2 = < P  X, (x1/A , x2/B , x3/C ) > 2 2 2 2 2 2 = < P, (x1/A , x2/B , x3/C ) >  < X, (x1/A , x2/B , x3/C ) > 2 2 2 = < (p1/A , p2/B , p3/C ), X >  1So the limb plane has normal vector
2 2 2 N = ( p1/A , p2/B , p3/C )and constant 1. We can create a SPICE plane representing the limb with the code fragment
n(0) = p(0) / pow(a,2) n(1) = p(1) / pow(b,2) n(2) = p(2) / pow(c,2) nvc2pl_c ( n, 1., &plane );The limb is the intersection of the limb plane and the ellipsoid. To find the intersection, we use the CSPICE routine inedpl_c (Intersection of ellipsoid and plane):
inedpl_c ( a, b, c, &plane, &ellips, &found );`ellips' is a SPICE `ellipse', a data type analogous to the SPICE plane. We can use the CSPICE routine el2cgv_c (Ellipse to center and generating vectors) to find the limb's center, semimajor axis, and semiminor axis:
el2cgv_c ( &ellips, center, smajor, sminor ); Header examples
Use of ellipses with planes
Summary of routines
inedpl_c Intersection of ellipsoid and plane inelpl_c Intersection of ellipse and plane inrypl_c Intersection of ray and plane nvc2pl_c Normal vector and constant to plane nvp2pl_c Normal vector and point to plane pjelpl_c Project ellipse onto plane pl2nvc_c Plane to normal vector and constant) pl2nvp_c Plane to normal vector and point pl2psv_c Plane to point and spanning vectors psv2pl_c Point and spanning vectors to plane vprjp_c Vector projection onto plane vprjpi_c Vector projection onto plane, inverted Appendix: Document Revision History2012 JAN 23, EDW (JPL)
2008 JAN 17, BVS (JPL)
2002 DEC 12, NAIF (JPL)
