Index Page
cspice_pxform
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_PXFORM returns the matrix that transforms position
   vectors from one specified frame to another at a specified epoch.

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

I/O


   Given:

      from   the scalar string name of a reference frame in which
             a position is known.

      to     the scalar string name of a reference frame in which
             it is desired to represent the position.

      et     the double precision scalar or N-vector of epochs in
             ephemeris seconds past the epoch of J2000 (TDB) at which
             the position transformation matrix should be evaluated.

   the call:

      cspice_pxform, from, to, et, rotate

   returns:

      rotate   a double precision 3x3 matrix or 3x3xN array that
               transforms  dates 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 position vector from one reference
   to another:

   either returning DOUBLE ARRAY [1,3]

      to_pos = rotate ## from_pos

   or the classic IDL format returning DOUBLE ARRAY[3]

      to_pos = transpose(rotate) # from_pos

   or using the Icy 3x3 matrix, 3-vector multiplication routine
   returning DOUBLE ARRAY[3]:

      cspice_mxv, rotate, from_pos, to_pos

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.

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

         KPL/MK

         File name: standard.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
            ---------                     --------
            de421.bsp                     Planetary ephemeris
            pck00009.tpc                  Planet orientation and
                                          radii
            naif0009.tls                  Leapseconds

         \begindata

            KERNELS_TO_LOAD = ( 'de421.bsp',
                                'pck00009.tpc',
                                'naif0009.tls'  )

         \begintext

   Example(1):

      ;;
      ;; Suppose that you have geodetic coordinates of a station on the
      ;; surface of Earth and you need the inertial (J2000)
      ;; position of this station.  The following code fragment
      ;; illustrates how to transform the geodetic position of the
      ;; station to a J2000 position.
      ;;

      ;;
      ;; 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 = 'July 4 2005'
      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, epos

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

      ;;
      ;; Transform the Cartesian position vector from "IAU_EARTH"
      ;; to "J2000."
      ;;
      jpos = transpose(rotate) # epos

      ;;
      ;; Output the transformed vector.
      ;;
      print, "Cartesian coordinates in J2000 frame at epoch: "
      print, "   ", jpos

   IDL outputs:

      Cartesian coordinates in J2000 frame at epoch:
             4040.9563       3416.4007       3548.8791


   Example(2):

      ;;
      ;; Output the right ascension and declination of the earth's pole
      ;; in the J2000 frame approximately every month for the time
      ;; interval January 1, 1990 to January 1, 2010 (UTC).
      ;;
      ;;
      ;; Load a standard kernel set.
      ;;
      cspice_furnsh, 'standard.tm'

      ;;
      ;; 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]

      ;;
      ;; Set the conversion constant "radians to degrees."
      ;;
      r2d = cspice_dpr()

      ;;
      ;; Convert the 240-vector of 'et' to an array of corresponding
      ;; transformation matrices (dimensions (3,3,240) ).
      ;;
      cspice_pxform, 'IAU_EARTH', 'J2000', et, mat

      ;;
      ;; Extract the pole vector from the transformation matrix,
      ;; convert to RA and DEC expressed in degrees.
      ;;

      ;;
      ;; The last column in each matrix is the pole vector (z = (0,0,1))
      ;; of the earth in IAU expressed in J2000.
      ;;
      ;; Recall, IDL notation places column indices first, and IDL uses
      ;; zero based indexing, so [2,*,*] represents the third column of
      ;; the matrices.
      ;;
      pole = mat[2,*,*]

      ;;
      ;; Pole returns as a 1x3x240 array. We need a 3x240 matrix which.
      ;; requires a reduction in rank. Conceptually, a 1x3x240 array
      ;; equates to a 3x240, but not functionally.
      ;;
      ;; A transpose creates a 240x3 matrix. Rank reduced by one.
      ;;
      pole = transpose( pole )

      ;;
      ;; Another transpose converts the 240x3 into a 3x240
      ;; ready for use in cspice_radrec.
      ;;
      pole = transpose( pole )
      cspice_recrad, pole, radius, ra, dec

      ;;
      ;; Output the ephemeris time and the corresponding
      ;; angular values (in degrees).  'ra' and 'dec' return
      ;; as double precision 240-vectors.
      ;;
      ra  = ra  * r2d
      dec = dec * r2d

      for I= 0, 239 do begin
         print, et[I], ra[I], dec[I]
      endfor

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

   IDL outputs:

      A partial output centered on et = 0:

                         ...

      -18408540.       180.00374       89.996751
      -15778739.       180.00320       89.997215
      -13148939.       180.00267       89.997679
      -10519139.       180.00214       89.998143
      -7889339.4       180.00160       89.998608
      -5259539.4       180.00107       89.999072
      -2629739.3       180.00053       89.999536
       60.683927       360.00000       90.000000
       2629860.7       359.99947       89.999536
       5259660.7       359.99893       89.999072
       7889460.8       359.99840       89.998607
       10519261.       359.99786       89.998143
       13149061.       359.99733       89.997679
       15778861.       359.99679       89.997215
       18408661.       359.99626       89.996751

                         ...

Particulars


   None.

Required Reading


   ICY.REQ
   ROTATION.REQ
   FRAMES.REQ

Version


   -Icy Version 1.1.2, 03-JAN-2012, EDW (JPL)

      Edits to Example section, proper description of "standard.tm"
      meta kernel.

   -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

      Also corrected a typo, "cspice_mxv" in I/O
      instead of "cspice_mxm."

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

       Added capability to process vector 'et' as
       input returning a 3x3xN 'rotate' array.

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

Index_Entries


   Find a position transformation matrix




Wed Apr  5 17:58:03 2017