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
pxform_c

 Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input Detailed_Output Parameters Exceptions Files Particulars Examples Restrictions Literature_References Author_and_Institution Version Index_Entries

Procedure

pxform_c ( Position Transformation Matrix )

void pxform_c ( ConstSpiceChar   * from,
ConstSpiceChar   * to,
SpiceDouble        et,
SpiceDouble        rotate )

Abstract

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

FRAMES

FRAMES

Brief_I/O

VARIABLE  I/O  DESCRIPTION
--------  ---  --------------------------------------------------
from       I   Name of the frame to transform from.
to         I   Name of the frame to transform to.
et         I   Epoch of the rotation matrix.
rotate     O   A rotation matrix.

Detailed_Input

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

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

et          is the epoch in ephemeris seconds past the epoch of J2000
(TDB) at which the position transformation matrix `rotate'
should be evaluated.

Detailed_Output

rotate      is the matrix that transforms position vectors from
the reference frame `from' to the frame `to' at epoch `et'.
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.

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 `from' or `to' input string pointers is null,
the error SPICE(NULLPOINTER) is signaled.

4)  If any of the `from' or `to' input strings has zero length,
the error SPICE(EMPTYSTRING) is signaled.

None.

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
CSPICE routine pxfrm2_c computes this type of frame
transformation.

Examples

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

#include "SpiceUsr.h"
.
.
.
bodvcd_c ( 399, radii, 3, &n, abc );

equatr   =  abc;
polar    =  abc;
f        =  ( equatr - polar ) / equatr;

georec_c ( long,        lat,      0.0,   equatr,   f,   epos );
pxform_c ( "IAU_EARTH", "J2000",  et,    rotate              );
mxv_c    (  rotate,   epos,     jpos                         );

The position jpos is the desired J2000 position of the station.

None.

None.

Author_and_Institution

C.H. Acton          (JPL)
N.J. Bachman        (JPL)
J. Diaz del Rio     (ODC Space)
B.V. Semenov        (JPL)
W.L. Taber          (JPL)
E.D. Wright         (JPL)

Version

-CSPICE Version 1.0.5, 10-AUG-2021 (JDR) (NJB)

Edited the header to comply with NAIF standard.

Added entries #3 and #4 to -Exceptions section. Updated the
-Particulars section to mention pxfrm2_c.

-CSPICE Version 1.0.4, 27-FEB-2008 (BVS)

-CSPICE Version 1.0.3, 24-OCT-2005 (NJB)

computation; this was corrected. Reference to bodvar_c was
replaced with reference to bodvcd_c.

-CSPICE Version 1.0.2, 07-JAN-2004 (EDW)

Trivial typo correction to example section.

-CSPICE Version 1.0.1, 29-JUL-2003 (NJB) (CHA)