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

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_PXFORM returns the matrix that transforms position
   vectors from one specified frame to another at a specified epoch.

I/O


   Given:

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

               help, from
                  STRING = Scalar

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

               help, to
                  STRING = Scalar

      et       the epoch in ephemeris seconds past the epoch of J2000 (TDB),
               or an N-vector of epochs, at which the position transformation
               matrix `rotate' should be evaluated.

               help, et
                  DOUBLE = Scalar   or   DOUBLE = Array[N]

   the call:

      cspice_pxform, from, to, et, rotate

   returns:

      rotate   the matrix, or an N-vector of matrices, that transforms position
               vectors from the reference frame `from' to the frame `to' at
               epoch `et'.

               help, rotate
                  DOUBLE = Array[3,3]   or   DOUBLE = Array[3,3,N]

               If (x, y, z) is a position relative to the frame `from' then
               the vector ( x', y', z') is the same position relative to the
               frame `to' at epoch `et'. Here the vector ( x', y', z' ) is
               defined by the equation:

                  .-   -.     .-        -.   .-  -.
                  | x'  |     |          |   | x  |
                  | y'  |  =  |  rotate  |   | y  |
                  | z'  |     |          |   | z  |
                  `-   -'     `-        -'   `-  -'

Parameters


   None.

Examples


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

   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 example
      illustrates how to transform the geodetic position of the
      station to a J2000 position.

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


         KPL/MK

         File name: pxform_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
            ---------                     --------
            pck00009.tpc                  Planet orientation and
                                          radii
            naif0009.tls                  Leapseconds

         \begindata

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

         \begintext

         End of meta-kernel


      Example code begins here.


      PRO pxform_ex1

         ;;
         ;; Load the PCK and LSK kernels.
         ;;
         cspice_furnsh, 'pxform_ex1.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

      END


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


      Cartesian coordinates in J2000 frame at epoch:
                4040.9563       3416.4007       3548.8791


   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, 1991 (UTC).

      Use the meta-kernel from the first example.

      Example code begins here.


      PRO pxform_ex2

         ;;
         ;;
         ;; Load kernels.
         ;;
         cspice_furnsh, 'pxform_ex1.tm'

         ;;
         ;; Define the time bounds for the time interval,
         ;; 12 months,  convert to ephemeris time J2000.
         ;;
         utc_bounds = [ '1 Jan 1990', '1 Jan 1991' ]
         cspice_str2et, utc_bounds, et_bounds

         ;;
         ;; Step in units of a month.
         ;;
         step = (et_bounds[1] - et_bounds[0]) / 12.d

         ;;
         ;; Create an array of 12 ephemeris times starting at
         ;; et_bounds[0] in intervals of 'step'.
         ;;
         et = dindgen(12)*step + et_bounds[0]

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

         ;;
         ;; Convert the 12-vector of 'et' to an array of corresponding
         ;; transformation matrices (dimensions (3,3,12) ).
         ;;
         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 1x3x12 array. We need a 3x12 matrix which.
         ;; requires a reduction in rank. Conceptually, a 1x3x12 array
         ;; equates to a 3x12, but not functionally.
         ;;
         ;; A transpose creates a 12x3 matrix. Rank reduced by one.
         ;;
         pole = transpose( pole )

         ;;
         ;; Another transpose converts the 12x3 into a 3x12
         ;; 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 12-vectors.
         ;;
         ra  = ra  * r2d
         dec = dec * r2d

         for I= 0, 11 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_kclear

      END


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


        -3.1557594e+08       180.06410       89.944300
        -3.1294794e+08       180.06357       89.944764
        -3.1031994e+08       180.06303       89.945228
        -3.0769194e+08       180.06250       89.945692
        -3.0506394e+08       180.06196       89.946155
        -3.0243594e+08       180.06143       89.946619
        -2.9980794e+08       180.06090       89.947083
        -2.9717994e+08       180.06036       89.947547
        -2.9455194e+08       180.05983       89.948011
        -2.9192394e+08       180.05930       89.948475
        -2.8929594e+08       180.05876       89.948938
        -2.8666794e+08       180.05823       89.949402


Particulars


   This routine provides the user level interface to computing
   position transformations from one reference frame to another.

   Note that the reference frames may be inertial or non-inertial.
   However, the user must take care that sufficient SPICE kernel
   information is loaded to provide a complete position
   transformation path from the `from' frame to the `to' frame.

   A common type of reference frame transformation is one from one
   time-dependent frame to another, where the orientations of the
   frames are computed at different epochs. For example, a remote
   sensing application may compute the transformation from a target
   body-fixed frame, with its orientation evaluated at the epoch of
   photon emission, to a spacecraft instrument frame, with its
   orientation evaluated at the epoch of photon reception. The
   Icy routine cspice_pxfrm2 computes this type of frame
   transformation.

   To perform a transformation of a position vector from one reference
   frame 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

Exceptions


   1)  If sufficient information has not been supplied via loaded
       SPICE kernels to compute the transformation between the
       two frames, an error is signaled by a routine
       in the call tree of this routine.

   2)  If either frame `from' or `to' is not recognized, the error
       SPICE(UNKNOWNFRAME) is signaled by a routine in the call tree
       of this routine.

   3)  If any of the input arguments, `from', `to' or `et', is
       undefined, an error is signaled by the IDL error handling
       system.

   4)  If any of the input arguments, `from', `to' or `et', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy interface.

   5)  If the output argument `rotate' is not a named variable, an
       error is signaled by the Icy interface.

Files


   None.

Restrictions


   None.

Required_Reading


   ICY.REQ
   ROTATION.REQ
   FRAMES.REQ

Literature_References


   None.

Author_and_Institution


   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.1.3, 13-AUG-2021 (JDR) (NJB)

       Edited header to comply with NAIF standard. Reduced
       the time interval and ephemeris epochs used as input in code
       example #2.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Updated -I/O to extend "rotate" description and -Particulars
       to mention cspice_pxfrm2.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

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

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

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

       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)

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

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

Index_Entries


   Find a position transformation matrix



Fri Dec 31 18:43:06 2021