Procedure

     CKFXFM ( CK frame, find state transformation )

     SUBROUTINE CKFXFM ( INST, ET, XFORM, REF, FOUND )

Abstract

     Find the state transformation matrix from a C-kernel (CK) frame
     with the specified frame class ID (CK ID) to the base frame of
     the highest priority CK segment containing orientation and
     angular velocity data for this CK frame at the time requested.

Required_Reading

     CK

Keywords

     POINTING

Declarations

     IMPLICIT NONE

     INTEGER               INST
     DOUBLE PRECISION      ET
     DOUBLE PRECISION      XFORM  ( 6, 6 )
     INTEGER               REF
     LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     INST       I   Frame class ID (CK ID) of a CK frame.
     ET         I   Epoch measured in seconds past J2000 TDB.
     XFORM      O   Transformation from CK frame to frame REF.
     REF        O   Frame ID of the base reference.
     FOUND      O   .TRUE. when requested pointing is available.

Detailed_Input

     INST     is the unique frame class ID (CK ID) of the CK frame for
              which data is being requested.

     ET       is the epoch for which the state transformation is
              desired. ET should be given in seconds past the epoch of
              J2000 TDB.

Detailed_Output

     XFORM    is a state transformation matrix that converts states
              relative to the CK frame given by its frame class ID,
              INST, to states relative to the base frame given by its
              frame ID, REF.

              Thus, if a state S has components x, y, z, dx, dy, dz in
              the CK frame, then S has components x', y', z', dx',
              dy', dz' in the base frame REF.

                 .-   -.     .-         -. .-  -.
                 |  x' |     |           | |  x |
                 |  y' |     |           | |  y |
                 |  z' |     |           | |  z |
                 | dx' |  =  |   XFORM   | | dx |
                 | dy' |     |           | | dy |
                 | dz' |     |           | | dz |
                 `-   -'     `-         -' `-  -'


     REF      is the ID code of the base reference frame to which
              XFORM will transform states.

     FOUND    is .TRUE. if a record was found to satisfy the pointing
              request. FOUND will be .FALSE. otherwise.

Parameters

     None.

Exceptions

     1)  If no CK files were loaded prior to calling this routine, an
         error is signaled by a routine in the call tree of this
         routine.

     2)  If no SCLK correlation data needed to read CK files were
         loaded prior to calling this routine, an error is signaled by
         a routine in the call tree of this routine.

     3)  If the input time ET cannot be converted to an encoded SCLK
         time, using SCLK data associated with INST, an error is
         signaled by a routine in the call tree of this routine.

Files

     CKFXFM searches through loaded CK files to locate a segment that
     can satisfy the request for state transformation data for the CK
     frame with the specified frame class ID at time ET. You must load
     a CK file containing such data before calling this routine. You
     must also load SCLK and possibly LSK files needed to convert the
     input ET time to the encoded SCLK time with which the orientation
     data stored inside that CK is tagged.

Particulars

     CKFXFM searches through loaded CK files to satisfy a pointing
     request. Last-loaded files are searched first, and individual
     files are searched in backwards order, giving priority to
     segments that were added to a file later than the others.

     The search ends when a segment is found that can give pointing
     for the specified CK frame at the request time.

     Only segments with angular velocities are considered by this
     routine.

     This routine uses the CKMETA routine to determine the SCLK ID
     used to convert the input ET time to the encoded SCLK time used
     to look up pointing data in loaded CK files.

Examples

     The numerical results shown for this example may differ across
     platforms. The results depend on the SPICE kernels used as
     input, the compiler and supporting libraries, and the machine
     specific arithmetic implementation.

     1) Use CKFXFM to compute the angular rate of rotation for the Mars
        Global Surveyor (MGS) spacecraft frame, 'MGS_SPACECRAFT',
        relative to the inertial frame used as the base frame in CK
        files containing MGS spacecraft orientation at 2003-JUL-25
        13:00:00. The frame class ID (CK ID) for the 'MGS_SPACECRAFT'
        frame is -94000.

        Use the meta-kernel shown below to load the required SPICE
        kernels.


           KPL/MK

           File name: ckfxfm_ex1.tm

           This meta-kernel is intended to support operation of SPICE
           example programs. The kernels shown here should not be
           assumed to contain adequate or correct versions of data
           required by SPICE-based user applications.

           In order for an application to use this meta-kernel, the
           kernels referenced here must be present in the user's
           current working directory.

           The names and contents of the kernels referenced
           by this meta-kernel are as follows:

              File name                     Contents
              ---------                     --------
              naif0012.tls                  Leapseconds
              mgs_sclkscet_00061.tsc        MGS SCLK coefficients
              mgs_sc_ext12.bc               MGS s/c bus attitude

           \begindata

           KERNELS_TO_LOAD = ( 'naif0012.tls',
                               'mgs_sclkscet_00061.tsc',
                               'mgs_sc_ext12.bc' )

           \begintext

           End of meta-kernel


        Example code begins here.


              PROGRAM CKFXFM_EX1
              IMPLICIT NONE

        C
        C     SPICELIB functions.
        C
              DOUBLE PRECISION      VNORM

        C
        C     Local parameters.
        C
              CHARACTER*(*)         EPOCH
              PARAMETER           ( EPOCH  = '2003-JUL-25 13:00:00' )

              INTEGER               INST
              PARAMETER           ( INST   = -94000 )

        C
        C     Local variables.
        C
              DOUBLE PRECISION      AV     ( 3    )
              DOUBLE PRECISION      ET
              DOUBLE PRECISION      ROT    ( 3, 3 )
              DOUBLE PRECISION      XFORM  ( 6, 6 )

              INTEGER               REF

              LOGICAL               FOUND

        C
        C     Load the required LSK, SCLK and CK. Use a
        C     meta-kernel for convenience.
        C
              CALL FURNSH ( 'ckfxfm_ex1.tm' )

        C
        C     First convert the time to seconds past J2000.
        C
              CALL STR2ET ( EPOCH, ET )

        C
        C     Now, look up the state transformation from the MGS
        C     spacecraft frame specified by its frame class ID
        C     (CK ID) to a base reference frame (returned by
        C     CKFXFM), at ET.
        C
              CALL CKFXFM ( INST, ET, XFORM, REF, FOUND )

        C
        C     Next determine the angular velocity of the
        C     transformation.
        C
              CALL XF2RAV ( XFORM, ROT, AV )

        C
        C     The angular rate of change (in radians/second) is just
        C     the magnitude of AV.
        C
              WRITE(*,'(A,F20.16)') 'Angular rate of change (rad/s):',
             .                       VNORM ( AV )

              END


        When this program was executed on a Mac/Intel/gfortran/64-bit
        platform, the output was:


        Angular rate of change (rad/s):  0.0008907319999591

Restrictions

     1)  A CK file must be loaded prior to calling this routine.

     2)  LSK and SCLK files needed for time conversions must be loaded
         prior to calling this routine.

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 2.3.0, 13-DEC-2021 (JDR) (BVS) (NJB)

        Edited the header to comply with NAIF standard and modern
        SPICE CK and frames terminology. Added complete code example
        based on existing fragments. Added initialization of local
        variable SFND.

    SPICELIB Version 2.2.0, 17-FEB-2000 (WLT)

        The routine now checks to make sure convert ET to TICKS
        and that at least one C-kernel is loaded before trying
        to look up the transformation.

    SPICELIB Version 2.1.0, 09-MAR-1999 (NJB)

        A call to SCE2T has been replaced by a call to SCE2C.

    SPICELIB Version 2.0.0, 28-JUL-1997 (WLT)

        The previous edition did not correctly compute the derivative
        block of the state transformation matrix.

        The routine incorrectly computed the state transformation
        matrix using the rotation from INST to REF together with
        the angular velocity from REF to INST. Now it computes
        the state transformation matrix from REF to INST and then
        inverts the result to get the correct matrix.

        Moved the assignment of FOUND to just before the check
        of the SPICELIB function RETURN. That way if the routine
        exits immediately via a check of the function RETURN(),
        FOUND will have an appropriate value.

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