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_xfmsta

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


Abstract


   CSPICE_XFMSTA transforms a state between coordinate systems.

I/O


   Given:

      istate   a state vector in the input `icosys' coordinate system
               representing position and velocity.

               help, istate
                  DOUBLE = Array[6]   or   DOUBLE = Array[6,N]

               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   the name of the coordinate system that the input state vector
               `istate' is currently in.

               help, icosys
                  STRING = Scalar

               `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   the name of the coordinate system that the state should be
               converted to.

               help, ocosys
                  STRING = Scalar

               Please see the description of `icosys' for details.

      body     the name or NAIF ID of the body associated with the
               planetographic or geodetic coordinate system.

               help, body
                  STRING = Scalar

               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.

   the call:

      cspice_xfmsta, istate, icosys, ocosys, body, ostate

   returns:

      ostate   the state vector that has been converted to the output
               coordinate system `ocosys'.

               help, ostate
                  DOUBLE = Array[6]   or   DOUBLE = Array[6,N]

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) 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.


      PRO xfmsta_ex1

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

         ;;
         ;; Calculate the state at 2004 Jun 11 19:32:00 UTC.
         ;;
         cspice_str2et, '2004-JUN-11-19:32:00', et

         ;;
         ;; Calculate the apparent state of Phoebe as seen by
         ;; CASSINI in the J2000 frame.
         ;;
         cspice_spkezr, 'phoebe', et, 'iau_phoebe', 'lt+s', 'cassini', $
                         state_rec, ltime

         ;;
         ;; 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.
         ;;
         cspice_xfmsta, state_rec, 'rectangular', 'latitudinal', ' ', $
                        state_lat
         ;;
         ;; Transform the state back to rectangular from latitudinal. The
         ;; result should be very close to `state_rec'.
         ;;
         cspice_xfmsta, state_lat, 'latitudinal', 'rectangular', ' ', $
                        state_rec2

         ;;
         ;; Report the results.
         ;;
         print, 'Phoebe as seen by Cassini - rectangular'
         print, '  Position ', state_rec[0:2]
         print, '  Velocity ', state_rec[3:5]
         print, 'Phoebe as seen by Cassini - latitudinal'
         print, '  Position ', state_lat[0:2]
         print, '  Velocity ', state_lat[3:5]
         print, 'Verification: Phoebe as seen by Cassini - rectangular'
         print, '  Position ', state_rec2[0:2]
         print, '  Velocity ', state_rec2[3:5]

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


      Phoebe as seen by Cassini - rectangular
        Position       -2059.2713      -942.12833      -95.837672
        Velocity        3.9101130      -4.2281390      -1.5265612
      Phoebe as seen by Cassini - latitudinal
        Position        2266.5809      -2.7125146    -0.042295536
        Velocity       -1.7304619    0.0024161897  -0.00070642182
      Verification: Phoebe as seen by Cassini - rectangular
        Position       -2059.2713      -942.12833      -95.837672
        Velocity        3.9101130      -4.2281390      -1.5265612


   2) Transform a given state from cylindrical to planetographic
      coordinates with respect to Earth.

      Use the PCK kernel below to load the required triaxial
      ellipsoidal shape model and orientation data for the Earth.

         pck00010.tpc


      Example code begins here.


      PRO xfmsta_ex2

         ;;
         ;; Initialize the cylindrical state.
         ;;
         state_cyl = [1, 0.5, 0.5, 0.2, 0.1, -0.2]

         ;;
         ;; Load kernels.
         ;;
         cspice_furnsh, 'pck00010.tpc'

         ;;
         ;; Transform the state from cylindrical to planetographic.
         ;; Note that since one of the coordinate systems is
         ;; planetographic, the body name must be input.
         ;;
         cspice_xfmsta, state_cyl, 'cylindrical', 'planetographic', $
                        'earth', state_plan

         ;;
         ;; Transform the state back to cylindrical from planetographic.
         ;; The result should be very close to 'state_cyl'.
         ;;
         cspice_xfmsta, state_plan, 'planetographic', 'cylindrical', $
                        'earth', state_cyl2

         ;;
         ;; Report the results.
         ;;
         print, 'Cylindrical State'
         print, '  Position ', state_cyl[0:2]
         print, '  Velocity ', state_cyl[3:5]
         print, 'Planetographic State'
         print, '  Position ', state_plan[0:2]
         print, '  Velocity ', state_plan[3:5]
         print, 'Verification: Cylindrical State'
         print, '  Position ', state_cyl2[0:2]
         print, '  Velocity ', state_cyl2[3:5]

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


      Cylindrical State
        Position       1.00000     0.500000     0.500000
        Velocity      0.200000     0.100000    -0.200000
      Planetographic State
        Position       0.50000000       1.5477216      -6356.2404
        Velocity       0.10000000   -0.0047222685     -0.19533224
      Verification: Cylindrical State
        Position        1.0000000      0.50000000      0.50000000
        Velocity       0.20000000      0.10000000     -0.20000000


Particulars


   Input 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

Exceptions


   1)  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 input arguments, `istate', `icosys', `ocosys' or
       `body', is undefined, an error is signaled by the IDL error
       handling system.

   12) If any of the input arguments, `istate', `icosys', `ocosys' or
       `body', is not of the expected type, or it does not have the
       expected dimensions and size, an error is signaled by the Icy
       interface.

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

Files


   SPK, 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 cspice_furnsh.

   Kernel data are normally loaded once per program run, NOT every
   time this routine is called.

Restrictions


   None.

Required_Reading


   ICY.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   S.C. Krening        (JPL)

Version


   -Icy Version 1.1.0, 01-NOV-2021 (JDR)

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections. Changed
       argument names "input_state", "input_coord_sys", "output_coord_sys" and
       "output_state" to "istate", "icosys", "ocosys" and "ostate" for
       consistency with other procedures.

       Edited the header to comply with NAIF standard. Corrected output
       argument description.

       Updated Examples' kernels set to use PDS archived data.

       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.0.0, 30-JAN-2012 (SCK)

Index_Entries


   state transformation between coordinate systems
   convert state



Fri Dec 31 18:43:09 2021