Procedure

   frame_c ( Build a right handed coordinate frame ) 

   void frame_c ( SpiceDouble x[3],
                  SpiceDouble y[3],
                  SpiceDouble z[3] )

Abstract

   Build a right handed orthonormal frame (x,y,z) from a
   3-dimensional input vector, where the X-axis of the resulting
   frame is parallel to the original input vector.

Required_Reading

   None.

Keywords

   AXES
   FRAME

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   x         I-O  Input vector. A parallel unit vector on output.
   y          O   Unit vector in the plane orthogonal to `x'.
   z          O   Unit vector given by the cross product <x,y>.

Detailed_Input

   x           is a 3-dimensional vector used to form the first vector
               of a right-handed orthonormal triple.

Detailed_Output

   x,
   y,
   z           are the 3-dimensional unit vectors that form a right
               handed orthonormal frame, where `x' is now a unit vector
               parallel to the original input vector in `x'. There are no
               special geometric properties connected to `y' and `z' (other
               than that they complete the right handed frame).

Parameters

   None.

Exceptions

   Error free.

   1)  If `x' on input is the zero vector the "standard" frame (ijk)
       is returned.

Files

   None.

Particulars

   Given an input vector x, this routine returns unit vectors x,
   y, and z such that xyz forms a right-handed orthonormal frame
   where the output x is parallel to the input x.

   This routine is intended primarily to provide a basis for
   the plane orthogonal to x. There are no special properties
   associated with y and z other than that the resulting xyz frame
   is right handed and orthonormal. There are an infinite
   collection of pairs (y,z) that could be used to this end.
   Even though for a given x, y and z are uniquely determined, users
   should regard the pair (y,z) as a random selection from this
   infinite collection.

   For instance, when attempting to determine the locus of points
   that make up the limb of a triaxial body, it is a straightforward
   matter to determine the normal to the limb plane. To find
   the actual parametric equation of the limb one needs to have
   a basis of the plane. This routine can be used to get a basis
   in which one can describe the curve and from which one can
   then determine the principal axes of the limb ellipse.

Examples

   In addition to using a vector to construct a right handed frame
   with the x-axis aligned with the input vector, one can construct
   right handed frames with any of the axes aligned with the input
   vector.

   For example suppose we want a right hand frame xyz with the
   z-axis aligned with some vector v. Assign v to z

         z[0] = v[0];
         z[1] = v[1];
         z[2] = v[2];

   Then call frame_c with the arguments x,y,z cycled so that z
   appears first.

         frame_c (z, x, y);

   The resulting xyz frame will be orthonormal with z parallel
   to the vector v.

   To get an xyz frame with y parallel to v perform the following

         y[0] = v[0];
         y[1] = v[1];
         y[2] = v[2];

         frame_c (y, z, x);

Restrictions

   None.

Literature_References

   None.

Author_and_Institution

   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)

Version

   -CSPICE Version 1.0.1, 03-JUL-2021 (JDR)

       Edited the header to comply with NAIF standard.

   -CSPICE Version 1.0.0, 26-MAR-1999 (NJB)

Index_Entries

   build a right handed coordinate frame