Index Page
cspice_sxform
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_SXFORM returns the state transformation matrix from one 
   frame to another at a specified epoch. 

   For important details concerning this module's function, please refer to
   the CSPICE routine sxform_c.

I/O

   
   Given:
   
      from   the scalar string name of a reference frame in which
             a state is known 
             
      to     the scalar string name of a reference frame in which 
             it is desired to represent the state 
      
      et     the double precision scalar or N-vector of epochs in 
             ephemeris seconds past the epoch of J2000 (TDB) at which 
             the state transformation matrix should be evaluated.
   
   the call:
   
      cspice_sxform, from, to, et, xform
   
   returns:
   
      xform   a double precision, 6x6 or 6x6xN array state 
              transformation matrix that transforms states from the
              reference frame 'from' to the frame 'to' at epoch 'et'
   
   Recall the difference in CSPICE and IDL matrix representations.
   
   To perform a transformation of a state vector from one reference
   to another:
   
   either returning DOUBLE ARRAY [1,6]
   
      to_state = xform ## from_state
   
   or the classic IDL format returning DOUBLE ARRAY[6]
   
      to_state = transpose(xform) # from_state
   

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

      ;;
      ;; Suppose you have geodetic coordinates of a station on the
      ;; surface of Earth and that you need the inertial (J2000)
      ;; state of this station.  The following code fragment
      ;; illustrates how to transform the geodetic state of the 
      ;; station to a J2000 state. 
      ;;
   
      ;;
      ;; Load the SPK, PCK and LSK kernels.
      ;;
      cspice_furnsh, 'standard.tm'

      ;;
      ;; Define a geodetic longitude, latitude, altitude
      ;; coordinate set. These coordinates are defined in the
      ;; non-inertial, earth fixed frame "IAU_EARTH".
      ;;
      lon = 118.25d * cspice_rpd()
      lat = 34.05d  * cspice_rpd()
      alt = 0.d
   
      ;;
      ;; Define a UTC time of interest. Convert the 'utc' string
      ;; to ephemeris time J2000.
      ;;
      utc = 'January 1, 1990'
      cspice_str2et, utc, et

      ;;
      ;; Retrieve the equatorial and polar axis of the earth (body 399).
      ;;
      cspice_bodvrd, 'EARTH', 'RADII', 3, abc
      equatr =  abc[0]
      polar  =  abc[2]

      ;;
      ;; Calculate the flattening factor for earth.
      ;;
      f =  ( equatr - polar  ) / equatr

      ;;
      ;; Calculate the Cartesian coordinates on earth for the
      ;; location at 'lon', 'lat', 'alt'.
      ;;
      cspice_georec, lon, lat, alt, equatr, f, estate
   
      ;;
      ;; cspice_georec returned the position vector of the geodetic
      ;; coordinates, but we want the state vector. Since it is a fixed
      ;; location referenced in the "IAU_EARTH" frame, the location has
      ;; no velocity. We need to extend estate to a 6-vector, the final
      ;; three elements with value 0.d.
      ;;
      estate = [ temporary(estate)  , dblarr(3) ]

      ;;
      ;; Retrieve the transformation matrix from "IAU_EARTH"
      ;; to "J2000" at epoch 'et'.
      ;;
      cspice_sxform, 'IAU_EARTH', 'J2000', et, xform

      ;;
      ;; Transform the Cartesian state vector from "IAU_EARTH"
      ;; to "J2000."
      ;;
      jstate = transpose(xform) # estate

      print, 'Scalar'
      print, 'Cartesian position in J2000 frame at epoch: ', et
      print, '   ', jstate[0:2]

      print, 'Cartesian velocity in J2000 frame'
      print, '   ', jstate[3:5]
      print

      ;;
      ;; Return the state transformation matrices from "IAU_EARTH"
      ;; to "J2000" approximately every month for the time 
      ;; interval January 1, 1990 to January 1, 2010 (UTC).
      ;;
      ;;
      ;; Define the time bounds for the time interval,
      ;; 20 years,  convert to ephemeris time J2000.
      ;;
      utc_bounds = [ '1 Jan 1990', '1 Jan 2010' ]
      cspice_str2et, utc_bounds, et_bounds
   
      ;;
      ;; Step in units of a month. 20 years ~ 240 months.
      ;; 
      step = (et_bounds[1] - et_bounds[0]) / 240.d
   
      ;;
      ;; Create an array of 240 ephemeris times starting at
      ;; et_bounds[0] in intervals of 'step'.
      ;;
      et = dindgen(240)*step + et_bounds[0]

      ;;
      ;; Convert the 240-vector of 'et' to an array of corresponding
      ;; transformation matrices (dimensions (6,6,240) ).
      ;;
      cspice_sxform, 'IAU_EARTH', 'J2000', et, xform

      ;;
      ;; Show the dimensions of the 'xform'.
      ;;
      print, 'Vector'
      print, 'Type and dimension of xform:'
      help, xform
      print

      ;;
      ;; Apply the first and last of the transform matrices to the
      ;; 'estate' vector.
      ;;
      ;;
      ;; Transform the Cartesian state vector from "IAU_EARTH"
      ;; to "J2000" at et[0] (initial epoch).
      ;;
      jstate = transpose( xform(*,*,0) ) # estate

      print, 'Cartesian position in J2000 frame at epoch: ', et[0]
      print, '   ', jstate[0:2]

      print, 'Cartesian velocity in J2000 frame'
      print, '   ', jstate[3:5]
      print

      ;;
      ;; Same transformation, but at et[239] (final epoch).
      ;;
      jstate = transpose( xform(*,*,239) ) # estate

      print, 'Cartesian position in J2000 frame at epoch: ', et[239]
      print, '   ', jstate[0:2]

      print, 'Cartesian velocity in J2000 frame'
      print, '   ', jstate[3:5]

      ;;
      ;; It's always good form to unload kernels after use,
      ;; particularly in IDL due to data persistence.
      ;;
      cspice_unload, 'standard.tm'

   IDL outputs:

      Scalar
      Cartesian position in J2000 frame at epoch:   -3.1557594e+08
               -4131.4630      -3308.3707       3547.0215
      Cartesian velocity in J2000 frame
               0.24124981     -0.30101944   0.00023421585

      Vector
      Type and dimension of xform:
      XFORM           DOUBLE    = Array[6, 6, 240]

      Cartesian position in J2000 frame at epoch:   -3.1557594e+08
               -4131.4630      -3308.3707       3547.0215
      Cartesian velocity in J2000 frame
               0.24124981     -0.30101944   0.00023421585

      Cartesian position in J2000 frame at epoch:    3.1294626e+08
                4533.6204       2731.8593       3546.6738
      Cartesian velocity in J2000 frame
              -0.19921049      0.33034733   0.00019238768

Particulars


   None.

Required Reading


   ICY.REQ
   ROTATION.REQ
   FRAMES.REQ

Version


   -Icy Version 1.1.1, 18-MAY-2005, EDW (JPL)

      Corrected the expression for the flattening factor,
      from:
      
         f =  ( polar - equatr ) / equatr
         
      to
      
         f =  ( equatr - polar  ) / equatr

   -Icy Version 1.1.0, 26-OCT-2004, EDW (JPL)

       Added capability to process vector 'et' as
       input returning a 6x6xN 'xform' array.

   -Icy Version 1.0.0, 16-JUN-2003, EDW (JPL)

Index_Entries

 
   Find a state transformation matrix 
 



Wed Apr  5 17:58:04 2017