Procedure

     FRMCHG (Frame Change)

     SUBROUTINE FRMCHG ( FRAME1, FRAME2, ET, XFORM )

Abstract

     Return the state 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      XFORM ( 6, 6 )

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.
     XFORM      O   a state transformation matrix

Detailed_Input

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

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

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

Detailed_Output

     XFORM    is a 6 x 6 state transformation matrix that can
              be used to transform states relative to the frame
              corresponding to frame FRAME2 to states relative
              to the frame FRAME2. More explicitly, if STATE
              is the state of some object relative to the reference
              frame of FRAME1 then STATE2 is the state of the
              same object relative to FRAME2 where STATE2 is
              computed via the subroutine call below

                 CALL MXVG ( XFORM, STATE, 6, 6, STATE2 )

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 state transformation matrix
     between two reference frames.

     The currently supported reference frames are IAU bodyfixed frames
     and inertial reference frames.

Examples

     Example 1. Suppose that you have a state STATE1 at epoch ET
     relative to  FRAME1 and wish to determine its representation
     STATE2 relative to FRAME2. The following subroutine calls
     would suffice to make this transformation.

        CALL FRMCHG ( FRAME1, FRAME2, ET,   XFORM )
        CALL MXVG   ( XFORM,  STATE1, 6, 6, STATE2 )



     Example 2. Suppose that you have the angular velocity, W, of some
     rotation relative to FRAME1 at epoch ET and that you wish to
     express this angular velocity with respect to FRAME2. The
     following subroutines will suffice to perform this computation.

        CALL FRMCHG ( FRAME1, FRAME2, ET, STXFRM )

     Recall that a state transformation matrix has the following form.


            -               -
           |                 |
           |    R        0   |
           |                 |
           |                 |
           |   dR            |
           |   --        R   |
           |   dt            |
           |                 |
            -               -


     The velocity of an arbitrary point P undergoing rotation with the
     angular velocity W is W x P

     Thus the velocity of P in FRAME2 is:


        dR
        --  P    +    R*(W x P )
        dt

           dR  t
     =  (  -- R  R P   +  R*(W x P)  )            ( 1 )
           dt


           dR  t                                              t
     But   -- R  is skew symmetric  (simply differentiate  R*R to see
           dt
                    dR  t
     this ).  Hence -- R R P  can be written as Ax(R*P) for some fixed
                    dt

     vector A. Moreover the vector A can be read from the upper

                            dR  t
     triangular portion of  -- R  .  So that equation (1) above can
                            dt

     be re-written as

         dR  t
     = ( -- R  R*P   +  R*(WxP)  )
         dt

     = Ax(R*P) + R*W x R*P

     = ( [A+R*W] x R*P )


     From this final expression it follows that in FRAME2 the angular
     velocity vector is given by [A+R*W].

     The code below implements these ideas.

        CALL FRMCHG ( FRAME1, FRAME2, ET, STXFRM )


        DO I = 1, 3
           DO J = 1, 3

              RT  ( I, J ) = STXFRM ( I,   J )
              DRDT( I, J ) = STXFRM ( I+3, J )

           END DO
        END DO

        CALL MXMT ( DRDT, R, AMATRIX )

        Read the angular velocity of R from the skew symmetric matrix

         dR  t
         -- R
         dt

        Recall that if A has components A1, A2, A3 then the matrix
        corresponding to the cross product linear mapping is:

            -               -
           |   0  -A3    A2  |
           |                 |
           |  A3   0    -A1  |
           |                 |
           | -A2   A1    0   |
            -               -

        A(1) = -AMATRIX(2,3)
        A(2) =  AMATRIX(1,3)
        A(3) = -AMATRIX(1,2)

        CALL MXV  ( R, W1,  W  )
        CALL VADD ( A, W,   W2 )

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 FRMGET.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 2.0.1, 16-JAN-2014 (NJB)

        Corrected equation 1 in header comments. Corrected
        numerous spelling errors in comments.

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

        Upgraded long error message associated with frame
        connection failure.

    SPICELIB Version 1.1.0, 25-JUL-1996 (WLT)

        Bug Fix:

        The previous edition of the routine had a bug in the
        first pass of the DO WHILE that looks for a frame
        in the chain of frames associated with FRAME2 that is
        in common with the chain of frames for FRAME1.

        On machines where variables are created as static
        variables, this error could lead to finding a frame
        when a legitimate path between FRAME1 and FRAME2
        did not exist.

    SPICELIB Version 1.0.1, 06-MAR-1996 (WLT)

        An typo was fixed in the Brief I/O section. It used
        to say TDT instead of the correct time system TDB.

    SPICELIB Version 1.0.0, 28-SEP-1994 (WLT)