Procedure

     FRMGET ( Frame get transformation )

     SUBROUTINE FRMGET ( INFRM, ET, XFORM, OUTFRM, FOUND )

Abstract

     Find the transformation from a user specified frame to
     another frame at a user specified epoch.

Required_Reading

     FRAMES

Keywords

     FRAMES

Declarations

     IMPLICIT NONE

     INCLUDE              'frmtyp.inc'

     INTEGER               INFRM
     DOUBLE PRECISION      ET
     DOUBLE PRECISION      XFORM ( 6, 6 )
     INTEGER               OUTFRM
     LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     INFRM      I   The integer code for a SPICE reference frame.
     ET         I   An epoch in seconds past J2000.
     XFORM      O   A state transformation matrix.
     OUTFRM     O   The frame that XFORM transforms INFRM to.
     FOUND      O   .TRUE. if a frame transformation can be found.

Detailed_Input

     INFRM    is the SPICE ID-code for some reference frame.

     ET       is an epoch in ephemeris seconds past J2000 at
              which the user wishes to retrieve a state
              transformation matrix.

Detailed_Output

     XFORM    is a 6x6 matrix that transforms states relative to
              INFRM to states relative to OUTFRM. (Assuming such a
              transformation can be found.)

     OUTFRM   is the SPICE ID-code of a reference frame. The 6x6
              matrix XFORM transforms states relative to INFRM to
              states relative to OUTFRM. The state transformation
              is achieved by multiplying XFORM on the right by a
              state relative to INFRM. This is easily accomplished
              via the subroutine call shown below.

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

     FOUND    is a logical flag indicating whether or not a
              transformation matrix could be found from INFRM to
              some other frame. If a transformation matrix cannot
              be found OUTFRM will be set to zero, FOUND will be
              set to .FALSE. and XFORM will be returned as the zero
              matrix.

Parameters

     See include file.

Exceptions

     1)  If a transformation matrix cannot be located, then FOUND will
         be set to .FALSE., OUTFRM will be set to zero and XFORM will
         be set to the zero 6x6 matrix.

     2)  If the class of the requested frame is not recognized the
         exception, the error SPICE(UNKNOWNFRAMETYPE) is signaled.

Files

     LSK, SCLK, PCK, FK, SPK, and/or CK kernels may need to be loaded
     to provide the needed frame definition and transformation data.

Particulars

     This is a low level routine used for determining a chain of state
     transformation matrices from one frame to another.

Examples

     See FRMCHG.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 5.0.0, 15-MAR-2021 (NJB) (JDR)

        **Updated shadow routines ZZFRMGT0 and ZZFRMGT1, as must be
          done each time this routine is updated.**

        Support for switch frames was added. VERSN is now
        initialized via a DATA statement. Corrected long error
        message to use the term "class" rather than "class id-code."

        Edited the header to comply with NAIF standard.

    SPICELIB Version 4.0.0, 05-JAN-2014 (BVS)

        To prevent operations with un-initialized DP numbers, wrapped
        IF ( .NOT. FAILED() ) ... END IF around output matrix
        transposition/re-assignment operations in all branches where
        the routine returning the matrix might fail.

        Added zero-ing out the output matrix in cases of a failed or
        .NOT. FOUND transformation look ups.

    SPICELIB Version 3.0.0, 18-DEC-2004 (NJB)

        Added the new frame type 'DYN' to the list of frame
        types recognized by FRMGET.

    SPICELIB Version 2.0.0, 03-APR-1997 (WLT)

        Added the new frame type 'TK' to the list of frame
        types recognized by FRMGET. In addition the routine
        now checks FAILED after "getting" the frame transformation.

    SPICELIB Version 1.0.0, 20-OCT-1994 (WLT)