Procedure

     REFCHG (Reference frame Change)

     SUBROUTINE REFCHG ( FRAME1, FRAME2, ET, ROTATE )

Abstract

     Return the transformation matrix from one
     frame to another.

Required_Reading

     None.

Keywords

     FRAMES

Declarations

     IMPLICIT NONE

     INCLUDE              'errhnd.inc'
     INCLUDE              'frmtyp.inc'

     INTEGER               FRAME1
     INTEGER               FRAME2
     DOUBLE PRECISION      ET
     DOUBLE PRECISION      ROTATE ( 3, 3 )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     FRAME1     I   the frame id-code for some reference frame
     FRAME2     I   the frame id-code for some reference frame
     ET         I   an epoch in TDB seconds past J2000.
     ROTATE     O   a rotation matrix

Detailed_Input

     FRAME1   is the frame id-code in which some positions
              are known.

     FRAME2   is the frame id-code for some frame in which you
              would like to represent positions.

     ET       is the epoch at which to compute the transformation
              matrix. This epoch should be in TDB seconds past
              the ephemeris epoch of J2000.

Detailed_Output

     ROTATE   is a 3 x 3 rotation matrix that can be used to
              transform positions relative to the frame
              corresponding to frame FRAME2 to positions relative
              to the frame FRAME2. More explicitly, if POS is
              the position of some object relative to the
              reference frame of FRAME1 then POS2 is the position
              of the same object relative to FRAME2 where POS2 is
              computed via the subroutine call below

                 CALL MXV ( ROTATE, POS, POS2 )

Parameters

     None.

Exceptions

     1)  If either of the reference frames is unrecognized, the error
         SPICE(UNKNOWNFRAME) is signaled.

     2)  If the auxiliary information needed to compute a non-inertial
         frame is not available, an error is signaled
         by a routine in the call tree of this routine.

Files

     None.

Particulars

     This routine allows you to compute the rotation matrix
     between two reference frames.

Examples

     Suppose that you have a position POS1 at epoch ET
     relative to  FRAME1 and wish to determine its representation
     POS2 relative to FRAME2. The following subroutine calls
     would suffice to make this rotation.

        CALL REFCHG ( FRAME1, FRAME2, ET,   ROTATE )
        CALL MXV    ( ROTATE, POS1,   POS2 )

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 2.1.0, 08-OCT-2021 (JDR) (NJB)

        Bug fix: added calls to FAILED after each call to
        FRINFO and to ROTGET.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 2.0.0, 14-DEC-2008 (NJB)

        Upgraded long error message associated with frame
        connection failure.

    SPICELIB Version 1.2.0, 26-APR-2004 (NJB)

        Another typo was corrected in the long error message, and
        in a comment.

    SPICELIB Version 1.1.0, 23-MAY-2000 (WLT)

        A typo was corrected in the long error message.

    SPICELIB Version 1.0.0, 09-JUL-1998 (WLT)