Procedure

     TWOVEC ( Two vectors defining an orthonormal frame )

     SUBROUTINE TWOVEC ( AXDEF, INDEXA, PLNDEF, INDEXP, MOUT )

Abstract

     Find the transformation to the right-handed frame having a
     given vector as a specified axis and having a second given
     vector lying in a specified coordinate plane.

Required_Reading

     None.

Keywords

     AXES
     FRAME
     ROTATION
     TRANSFORMATION

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION   AXDEF  (   3 )
     INTEGER            INDEXA
     DOUBLE PRECISION   PLNDEF (   3 )
     INTEGER            INDEXP
     DOUBLE PRECISION   MOUT   ( 3,3 )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  -------------------------------------------------
     AXDEF      I   Vector defining a principal axis.
     INDEXA     I   Principal axis number of AXDEF (X=1, Y=2, Z=3).
     PLNDEF     I   Vector defining (with AXDEF) a principal plane.
     INDEXP     I   Second axis number (with INDEXA) of principal
                    plane.
     MOUT       O   Output rotation matrix.

Detailed_Input

     AXDEF    is a vector defining one of the principle axes of a
              coordinate frame.

     INDEXA   is a number that determines which of the three
              coordinate axes contains AXDEF.

              If INDEXA is 1 then AXDEF defines the X axis of the
              coordinate frame.

              If INDEXA is 2 then AXDEF defines the Y axis of the
              coordinate frame.

              If INDEXA is 3 then AXDEF defines the Z axis of the
              coordinate frame.

     PLNDEF   is a vector defining (with AXDEF) a principal plane of
              the coordinate frame. AXDEF and PLNDEF must be
              linearly independent.

     INDEXP   is the second axis of the principal frame determined
              by AXDEF and PLNDEF.  INDEXA, INDEXP must be different
              and be integers from 1 to 3.

              If INDEXP is 1, the second axis of the principal
              plane is the X-axis.

              If INDEXP is 2, the second axis of the principal
              plane is the Y-axis.

              If INDEXP is 3, the second axis of the principal plane
              is the Z-axis.

Detailed_Output

     MOUT     is a rotation matrix that transforms coordinates given
              in the input frame to the frame determined by AXDEF,
              PLNDEF, INDEXA and INDEXP.

Parameters

     None.

Exceptions

     1)  If INDEXA or INDEXP is not in the set {1,2,3}, the error
         SPICE(BADINDEX) is signaled.

     2)  If INDEXA and INDEXP are the same, the error
         SPICE(UNDEFINEDFRAME) is signaled.

     3)  If the cross product of the vectors AXDEF and PLNDEF is zero,
         the error SPICE(DEPENDENTVECTORS) is signaled.

Files

     None.

Particulars

     Given two linearly independent vectors there is a unique
     right-handed coordinate frame having:

        AXDEF lying along the INDEXA axis.

        PLNDEF lying in the INDEXA-INDEXP coordinate plane.

     This routine determines the transformation matrix that transforms
     from coordinates used to represent the input vectors to the
     the system determined by AXDEF and PLNDEF. Thus a vector
     (x,y,z) in the input coordinate system will have coordinates

                     t
        MOUT* (x,y,z)

     in the frame determined by AXDEF and PLNDEF.

Examples

     The rotation matrix TICC from inertial to Sun-Canopus
     (celestial) coordinates is found by the call

        CALL TWOVEC (Sun vector, 3, Canopus vector, 1, TICC)

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 1.2.0, 06-JUL-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard. Removed
        unnecessary $Revisions section.

    SPICELIB Version 1.1.0, 31-AUG-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VSCL 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 (WMO) (WLT)