Procedure

      FRAME ( Build a right handed coordinate frame )
 
      SUBROUTINE FRAME ( X, Y, Z )
 

Abstract

      Given a vector X, this routine builds a right handed
      orthonormal frame X,Y,Z where the output X is parallel to
      the input X.

Required_Reading

     None.

Keywords

      AXES,  FRAME

Declarations

 
      DOUBLE PRECISION    X ( 3 )
      DOUBLE PRECISION    Y ( 3 )
      DOUBLE PRECISION    Z ( 3 )
 

Brief_I/O

      VARIABLE  I/O  DESCRIPTION
      --------  ---  ------------------------------------------------
      X         I/0  Input vector. A parallel unit vector on output.
      Y          O   Unit vector in the plane orthogonal to X.
      Z          O   Unit vector given by X x Y.

Detailed_Input

      X      This vector is used to form the first vector of a
             right-handed orthonormal triple.

Detailed_Output

      X,
      Y,
      Z      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(1) = V(1)
            Z(2) = V(2)
            Z(3) = V(3)

      Then call FRAME with the arguements X,Y,Z cycled so that Z
      appears first.

            CALL FRAME (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(1) = V(1)
            Y(2) = V(2)
            Y(3) = V(3)

            CALL FRAME (Y, Z, X)

Restrictions

      None.

Literature_References

      None.

Author_and_Institution

      W.L. Taber      (JPL)
      I.M. Underwood  (JPL)

Version

    SPICELIB Version 1.2.0, 02-SEP-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VHAT call.

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (WLT)