Procedure

     FRAME ( Build a right handed coordinate frame )

     SUBROUTINE FRAME ( X, Y, Z )

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

Declarations

     IMPLICIT NONE

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

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

     Then call FRAME with the arguments 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

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 1.3.0, 03-JUL-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard. Improved
        argument descriptions.

    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) (IMU)