Table of contents
CSPICE_PXFORM returns the matrix that transforms position
vectors from one specified frame to another at a specified epoch.
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 |
`- -' `- -' `- -'
None.
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
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
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.
None.
None.
ICY.REQ
ROTATION.REQ
FRAMES.REQ
None.
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-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)
Find a position transformation matrix
|