xfmsta_c |

Table of contents## Procedurexfmsta_c ( Transform state between coordinate systems ) void xfmsta_c ( ConstSpiceDouble istate[6], ConstSpiceChar * icosys, ConstSpiceChar * ocosys, ConstSpiceChar * body, SpiceDouble ostate[6] ) ## AbstractTransform a state between coordinate systems. ## Required_ReadingNone. ## KeywordsCONVERSION COORDINATE EPHEMERIS STATE ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- istate I Input state. icosys I Current (input) coordinate system. ocosys I Desired (output) coordinate system. body I Name or NAIF ID of body with which coordinates are associated (if applicable). ostate O Converted output state. ## Detailed_Inputistate is a state vector in the input `icosys' coordinate system representing position and velocity. All angular measurements must be in radians. Note: body radii values taken from the kernel pool are used when converting to or from geodetic or planetographic coordinates. It is the user's responsibility to verify the distance inputs are in the same units as the radii in the kernel pool, typically kilometers. icosys is the name of the coordinate system that the input state vector `istate' is currently in. `icosys' may be any of the following: "RECTANGULAR" "CYLINDRICAL" "LATITUDINAL" "SPHERICAL" "GEODETIC" "PLANETOGRAPHIC" Leading spaces, trailing spaces, and letter case are ignored. For example, " cyLindRical " would be accepted. ocosys is the name of the coordinate system that the state should be converted to. Please see the description of `icosys' for details. body is the name or NAIF ID of the body associated with the planetographic or geodetic coordinate system. If neither of the coordinate system choices are geodetic or planetographic, `body' is ignored. It may be a blank string. Examples of accepted body names or IDs are: "Earth" "399" Leading spaces, trailing spaces, and letter case are ignored. ## Detailed_Outputostate is the state vector that has been converted to the output coordinate system `ocosys'. ## ParametersNone. ## Exceptions1) If either the input or output coordinate system is not recognized, the error SPICE(COORDSYSNOTREC) is signaled by a routine in the call tree of this routine. 2) If the input body name cannot be converted to a NAIF ID (applies to geodetic and planetographic coordinate systems), the error SPICE(IDCODENOTFOUND) is signaled by a routine in the call tree of this routine. 3) If the input state `istate' is not valid, meaning the position but not the velocity is along the Z-axis, the error SPICE(INVALIDSTATE) is signaled by a routine in the call tree of this routine. Note: If both the input position and velocity are along the Z-axis and the output coordinate system is not rectangular, the velocity can still be calculated even though the Jacobian is undefined. This case will not signal an error. An example of the input position and velocity along the Z-axis is below. Term Value ----- ------ x 0 y 0 z z dx/dt 0 dy/dt 0 dz/dt dz_dt 4) If either the input or output coordinate system is geodetic or planetographic and at least one of the body's radii is less than or equal to zero, the error SPICE(INVALIDRADIUS) is signaled by a routine in the call tree of this routine. 5) If either the input or output coordinate system is geodetic or planetographic and the difference of the equatorial and polar radii divided by the equatorial radius would produce numeric overflow, the error SPICE(INVALIDRADIUS) is signaled by a routine in the call tree of this routine. 6) If the product of the Jacobian and velocity components may lead to numeric overflow, the error SPICE(NUMERICOVERFLOW) is signaled by a routine in the call tree of this routine. 7) If radii for `body' are not found in the kernel pool, an error is signaled by a routine in the call tree of this routine. 8) If the size of the `body' radii kernel variable is not three, an error is signaled by a routine in the call tree of this routine. 9) If any of the three `body' radii is less-than or equal to zero, an error is signaled by a routine in the call tree of this routine. 10) If body's equatorial radii are not equal and either the input or output coordinate system is geodetic or planetographic, the error SPICE(NOTSUPPORTED) is signaled by a routine in the call tree of this routine. 11) If any of the `icosys', `ocosys' or `body' input string pointers is null, the error SPICE(NULLPOINTER) is signaled. 12) If any of the `icosys', `ocosys' or `body' input strings has zero length, the error SPICE(EMPTYSTRING) is signaled. ## FilesSPK, PCK, CK, and FK kernels may be required. If the input or output coordinate systems are either geodetic or planetographic, a PCK providing the radii of the body name `body' must be loaded via furnsh_c. Kernel data are normally loaded once per program run, NOT every time this routine is called. ## ParticularsInput Order ----------- The input and output states will be structured by the following descriptions. For rectangular coordinates, the state vector is the following in which `x', `y', and `z' are the rectangular position components and `dx', `dy', and `dz' are the time derivatives of each position component. istate = ( x, y, z, dx, dy, dz ) For cylindrical coordinates, the state vector is the following in which `r' is the radius, `long' is the longitudes, `z' is the height, and `dr', `dlong', and `dz' are the time derivatives of each position component. istate = ( r, long, z, dr, dlong, dz ) For latitudinal coordinates, the state vector is the following in which `r' is the radius, `long' is the longitude, `lat' is the latitude, and `dr', `dlong', and `dlat' are the time derivatives of each position component. istate = ( r, long, lat, dr, dlong, dlat ) For spherical coordinates, the state vector is the following in which `r' is the radius, `colat' is the colatitude, `long' is the longitude, and `dr', `dcolat', and `dlong' are the time derivatives of each position component. istate = ( r, colat, long, dr, dcolat, dlong ) For geodetic coordinates, the state vector is the following in which `long' is the longitude, `lat' is the latitude, `alt' is the altitude, and `dlong', `dlat', and `dalt' are the time derivatives of each position component. istate = ( long, lat, alt, dlong, dlat, dalt ) For planetographic coordinates, the state vector is the following in which `long' is the longitude, `lat' is the latitude, `alt' is the altitude, and `dlong', `dlat', and `dalt' are the time derivatives of each position component. istate = ( long, lat, alt, dlong, dlat, dalt ) Input Boundaries ---------------- There are intervals the input angles must fall within if the input coordinate system is not rectangular. These intervals are provided below. Input variable Input meaning Input interval [rad] -------------- ------------- ------------------------ long Longitude 0 <= long < 2*pi lat Latitude -pi/2 <= lat <= pi/2 colat Colatitude 0 <= colat <= pi ## ExamplesThe numerical results shown for these examples may differ across platforms. The results depend on the SPICE kernels used as input, the compiler and supporting libraries, and the machine specific arithmetic implementation. 1) Find the apparent state of Phoebe as seen by CASSINI in the J2000 frame at 2004 Jun 11 19:32:00. Transform the state from rectangular to latitudinal coordinates. For verification, transform the state back from latitudinal to rectangular coordinates. Use the meta-kernel shown below to load the required SPICE kernels. KPL/MK File name: xfmsta_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 --------- -------- pck00010.tpc Planet orientation and radii naif0012.tls Leapseconds 041014R_SCPSE_01066_04199.bsp CASSINI, planetary and Saturn Satellite ephemeris \begindata KERNELS_TO_LOAD = ( 'naif0012.tls', '041014R_SCPSE_01066_04199.bsp', 'pck00010.tpc' ) \begintext End of meta-kernel Example code begins here. /. Program xfmsta_ex1 ./ #include <stdio.h> #include "SpiceUsr.h" int main() { /. Constants ./ #define METAKR "xfmsta_ex1.tm" /. Local variables `et' is the ephemeris time (TDB) corresponding to the observation. ./ SpiceDouble et; SpiceDouble lt; /. `state_rec' is the state of Phoebe with respect to CASSINI in rectangular coordinates. `state_lat' is the state transformed in latitudinal coordinates. `state_rec2' is the state transformed back into rectangular coordinates from latitudinal. ./ SpiceDouble state_rec [6]; SpiceDouble state_lat [6]; SpiceDouble state_rec2 [6]; /. The required kernels must be loaded. ./ furnsh_c ( METAKR ); /. Calculate the state at 2004 Jun 11 19:32:00 UTC. ./ str2et_c ( "2004-JUN-11-19:32:00", &et ); /. Calculate the apparent state of Phoebe as seen by Cassini in the J2000 frame. ./ spkezr_c ( "phoebe", et, "iau_phoebe", "lt+s", "cassini", state_rec, < ); /. Transform the state from rectangular to latitudinal. Notice that since neither the input nor output coordinate frames are 'geodetic' or 'planetographic', the input for the body name is a blank string. ./ ## RestrictionsNone. ## Literature_ReferencesNone. ## Author_and_InstitutionJ. Diaz del Rio (ODC Space) S.C. Krening (JPL) B.V. Semenov (JPL) ## Version-CSPICE Version 1.2.0, 01-NOV-2021 (JDR) Updated -Exceptions section with description of missing exceptions and its format to comply with NAIF standard. Changed argument names "input_state", "input_coord_sys", "output_coord_sys" and "output_state" to "istate", "icosys", "ocosys" and "ostate" for consistency with other functions. Edits to the header to comply with NAIF standard. Added missing begintext tag in example's meta-kernel. Updated Examples' kernels set to use PDS archived data. -CSPICE Version 1.1.0, 09-FEB-2017 (BVS) BUG FIX: the routine no longer allows converting to and from geodetic and planetographic coordinates for bodies with unequal equatorial radii. Previously it arbitrarily picked the first and the third radii to compute body's flattening coefficient. -CSPICE Version 1.0.0, 30-JAN-2011 (SCK) ## Index_Entriesstate transformation between coordinate systems convert state |

Fri Dec 31 18:41:15 2021