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 Icy. NAIF implemented the SPICE plane data type in IDL as a structure with the fields
normal: (3array double) constant: (scalar double)'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 Icy 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 cspice_pl2nvp (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
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 cspice_nvc2pl:
cspice_nvc2pl, n, c, plane Construct a plane from a normal vector and a point
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 cspice_nvp2pl:
cspice_nvp2pl, n, p, plane Construct a plane from a point and spanning vectors
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 cspice_psv2pl:
cspice_psv2pl, p, v1, v2, plane Access plane data elements
The Icy 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 cspice_pl2nvc:
cspice_pl2nvc, plane, n, cThe 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 cspice_pl2nvp:
cspice_pl2nvp, 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 cspice_pl2psv:
cspice_pl2psv, 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
cspice_pl2nvc, n, c, plane cspice_pl2nvc, plane, n, c cspice_nvp2pl, p, n, plane cspice_pl2nvp, plane, p, n cspice_psv2pl, v1, v2, p, plane cspice_pl2psv, plane, v1, v2, pdo 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 cspice_pl2nvc, cspice_pl2nvp, and cspice_pl2psv 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
cspice_nvc2pl, n, c, plane cspice_pl2nvp, 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
p = p + x cspice_nvp2pl, n, p, plane cspice_pl2nvp, plane, n, pNow, `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.
cspice_nvc2pl, n, c, plane cspice_pl2psv, plane, point, v1, v2Apply 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.
cspice_mxv, m, point, tpoint cspice_mxv, m, v1, tv1 cspice_mxv, m, v2, tv2Construct a new SPICE plane `tplane' from the transformed point and spanning vectors, and find a unit normal and constant for this new plane.
cspice_psv2pl, tpoint, tv1, tv2, tplane cspice_pl2nvc, 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 = [ p[0]/a^2, p[1]/b^2, p[2]/c^2 ] cspice_nvc2pl, n, 1.d, planeThe limb is the intersection of the limb plane and the ellipsoid. To find the intersection, we use the Icy routine cspice_inedpl (Intersection of ellipsoid and plane):
cspice_inedpl, a, b, c, plane, ellipse, found`ellips' is a SPICE `ellipse', a data type analogous to the SPICE plane. We can use the Icy routine cspice_el2cgv (Ellipse to center and generating vectors) to find the limb's center, semimajor axis, and semiminor axis:
cspice_el2cgv, ellips, center, smajor, sminor Header examples
Use of ellipses with planes
Summary of routines
cspice_inedpl Intersection of ellipsoid and plane cspice_inelpl Intersection of ellipse and plane cspice_inrypl Intersection of ray and plane cspice_nvc2pl Normal vector and constant to plane cspice_nvp2pl Normal vector and point to plane cspice_pjelpl Project ellipse onto plane cspice_pl2nvc Plane to normal vector and constant) cspice_pl2nvp Plane to normal vector and point cspice_pl2psv Plane to point and spanning vectors cspice_psv2pl Point and spanning vectors to plane cspice_vprjp Vector projection onto plane cspice_vprjpi Vector projection onto plane, inverted Appendix: Document Revision History2012 JAN 23, EDW (JPL)
2008 JAN 17, BVS (JPL)
2002 DEC 12, NAIF (JPL)
