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

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_SPKPOS returns the position of a target body relative 
   to an observing body, optionally corrected for light time 
   (planetary aberration) and stellar aberration.

   For important details concerning this module's function, please refer to
   the CSPICE routine spkpos_c.

I/O

   
   Given:
   
      targ      the scalar string name of a target body.
                Optionally, you may supply the integer ID code 
                for the object as an integer string, i.e. both 
                'MOON' and '301' are legitimate strings that 
                indicate the Moon is the target body.

                The target and observer define a position vector 
                whose position component points from the observer 
                to the target.

      et        the scalar or N-array of double precision ephemeris
                time, expressed as seconds past J2000 TDB, at which 
                position of the target body relative to the observer
                the is to be  computed, 'et' refers to time at the 
                observer's location.

      ref       the scalar string name of the reference frame relative
                to which the output position vector should be
                expressed. This may be any frame supported by the SPICE
                system, including built-in frames (documented in the
                Frames Required Reading) and frames defined by a loaded
                frame kernel (FK). 
 
                When 'ref' designates a non-inertial frame, the 
                orientation of the frame is evaluated at an epoch  
                dependent on the selected aberration correction. 

      abcorr    a scalar string that indicates the aberration corrections to
                apply to the position of the target body to account  
                for one-way light time and stellar aberration.

                'abcorr' may be any of the following: 
  
                   'NONE'     Apply no correction. Return the  
                              geometric position of the target body  
                              relative to the observer.  

                The following values of 'abcorr' apply to the
                "reception" case in which photons depart from the
                target's location at the light-time corrected epoch
                et-lt and *arrive* at the observer's location at
                'et':

                   'LT'       Correct for one-way light time (also 
                              called "planetary aberration") using a 
                              Newtonian formulation. This correction 
                              yields the position of the target at the 
                              moment it emitted photons arriving at 
                              the observer at 'et'. 

                              The light time correction uses an
                              iterative solution of the light time 
                              equation (see Particulars for details). 
                              The solution invoked by the "LT" option 
                              uses one iteration. 

                   'LT+S'     Correct for one-way light time and 
                              stellar aberration using a Newtonian 
                              formulation. This option modifies the 
                              position obtained with the "LT" option to 
                              account for the observer's velocity 
                              relative to the solar system 
                              barycenter. The result is the apparent 
                              position of the target---the position and 
                              velocity of the target as seen by the 
                              observer. 

                   'CN'       Converged Newtonian light time
                              correction. In solving the light time
                              equation, the 'CN' correction iterates
                              until the solution converges (three
                              iterations on all supported platforms).
                              Whether the 'CN+S' solution is
                              substantially more accurate than the
                              'LT' solution depends on the geometry
                              of the participating objects and on the
                              accuracy of the input data. In all
                              cases this routine will execute more
                              slowly when a converged solution is
                              computed. See the Particulars section
                              below for a discussion of precision of
                              light time corrections.

                   'CN+S'     Converged Newtonian light time
                              correction and stellar aberration
                              correction.


                The following values of 'abcorr' apply to the 
                "transmission" case in which photons *depart* from 
                the observer's location at 'et' and arrive at the 
                target's location at the light-time corrected epoch 
                et+lt: 

                   'XLT'      "Transmission" case:  correct for 
                              one-way light time using a Newtonian 
                              formulation. This correction yields the 
                              position of the target at the moment it 
                              receives photons emitted from the 
                              observer's location at 'et'. 

                   'XLT+S'    "Transmission" case:  correct for 
                              one-way light time and stellar 
                              aberration using a Newtonian 
                              formulation  This option modifies the 
                              position obtained with the "XLT" option to 
                              account for the observer's velocity 
                              relative to the solar system 
                              barycenter. The position indicates the 
                              direction that photons emitted from the 
                              observer's location must be "aimed" to 
                              hit the target. 
  
                   'XCN'      "Transmission" case:  converged  
                              Newtonian light time correction. 
  
                   'XCN+S'    "Transmission" case: converged Newtonian
                              light time correction and stellar
                              aberration correction.
  
                Neither special nor general relativistic effects are 
                accounted for in the aberration corrections applied 
                by this routine. 
  
                Both letter case and embedded blanks are not significant 
                in the 'abcorr' string. 

      obs       the scalar string name of a observing body. 
                Optionally, you may supply the integer ID code 
                for the object as an integer string, i.e. both 
                'MOON' and '301' are legitimate strings that 
                indicate the Moon is the observing body.
   
   the call:
   
      cspice_spkpos, targ, et, ref, abcorr, obs, ptarg, ltime
   
   returns:
   
      ptarg   a double precision 3-array or double precision 3xN array
              of Cartesian position vector(s)representing the position 
              and velocity of the target body relative to the 
              specified observer at 'et'. 'starg' is corrected for 
              the specified aberrations 'abcorr'.
              
              The three components of a 3-array 'ptarg' represent 
              the x-, y- and z-components of the target's position as
              measure in kilometers.

              The position component of 'ptarg' points from the 
              observer's location at 'et' to the aberration-corrected 
              location of the target. Note that the sense of the 
              position vector is independent of the direction of 
              radiation travel implied by the aberration 
              correction.

              Non-inertial frames are treated as follows: letting 
              'ltcent' be the one-way light time between the observer 
              and the central body associated with the frame, the 
              orientation of the frame is evaluated at et-ltcent, 
              et+ltcent, or 'et' depending on whether the requested
              aberration correction is, respectively, for received
              radiation, transmitted radiation, or is omitted. 'ltcent'
              is computed using the method indicated by 'abcorr'.


              The 3xN form of 'ptarg' returns as ptarg[6,N]. Retrieve
              the ith position vector via:
              
                 pos_i = pos[*,i]
   
      ltime   the double precision scalar or N-array of one-way 
              light time(s) between the observer and target
              in seconds; if the target position is corrected 
              for aberrations, then 'ltime' is the one-way 
              light time between the observer and the light
              time corrected target location.

              Please note, CSPICE documentation and source code 
              uniformly uses the variable name 'lt' to designate
              the light-time between an observer and target. IDL 
              uses 'lt' as the less-than numeric comparison 
              operator and so does not allow 'lt' as a variable name. 
              Therefore, Icy documentation uses the name 'ltime' 
              for the light-time value. 

              'ptarg' and 'ltime' return with the same measure of 
              vectorization (N) as 'et'.

   The cspice_spkpos routine performs the same operation as cspice_spkezp
   with the exception that cspice_spkpos expects arguments 'targ' and 
   'obs' to pass as strings, whereas cspice_spkezp expects the arguments
   as integers. cspice_spkpos also accepts the string form of the integer 
   NAIF IDs as inputs to 'ptarg' and 'obs', e.g.

      targ = 'Mars'
      obs  = 'Earth'

   or (remember, string representation of the integers)

      targ = '499'
      obs  = '399'

Examples


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

      ;;
      ;; Load a set of kernels: an SPK file, a PCK
      ;; file and a leapseconds file. Use a meta
      ;; kernel for convenience.
      ;;
      cspice_furnsh, 'standard.tm'

      ;;
      ;; Define parameters for a position lookup:
      ;;
      ;; Return the position vector of Mars as seen from
      ;; Earth in the J2000 frame using aberration
      ;; correction LT+S (light time plus stellar aberration)
      ;; at the epoch July 4, 2003 11:00 AM PST.
      ;;
      target   = 'Mars'
      epoch    = 'July 4, 2003 11:00 AM PST'
      frame    = 'J2000'
      abcorr   = 'LT+S'
      observer = 'Earth'

      ;;
      ;; Convert the epoch to ephemeris time.
      ;;
      cspice_str2et, epoch, et

      ;;
      ;; Look-up the position for the defined parameters.
      ;;
      cspice_spkpos, target, et, frame, abcorr, observer, $
                     ptarg, ltime

      ;;
      ;; Output...
      ;;
      print, 'Scalar:'
      print, 'The position of    : ', target
      print, 'As observed from   : ', observer
      print, 'In reference frame : ', frame
      print, 'At epoch           : ', epoch

      ;;
      ;; The first three entries of 'ptarg' contain the
      ;; X, Y, Z position components.
      ;;
      print, 'R (kilometers)     : ', ptarg[0:2]
      print
      print, 'Light time (secs) between observer and target: ', ltime
      print

      ;;
      ;; Create a vector of et's, starting at 'epoch'
      ;; in steps of 100000 ephemeris seconds.
      ;;
      SIZE   = 5
      vec_et = dindgen( SIZE )*100000.D + et

      ;;
      ;; Look up the 'ptarg' vectors and light time values
      ;; 'lt'  corresponding to the vector of input
      ;; ephemeris time 'vec_et'.
      ;;
      cspice_spkpos, target  , vec_et, frame, abcorr, $
                     observer, ptarg , ltime

      print, 'Vector'
      cspice_et2utc, vec_et, 'C', 3, vec_epoch
   
      ;;
      ;; When called with a vector 'et', cspice_spkpos returns
      ;; 'ptarg' as an 3xN matrix. Extract the ith position from
      ;; the matrix as:
      ;;
      ;;   ptarg_i = ptarg[*,i] 
      ;;
      for i=0, 4 do begin

         print, 'At epoch (UTC)     : ', vec_epoch[i]
         print, 'R (kilometers)     : ', (ptarg[*,i])[0:2]
         print, 'Light time (secs)  : ', ltime[i]
         print, ' between observer'
         print, ' and target'
         print

      endfor

      ;;
      ;; It's always good form to unload kernels after use,
      ;; particularly in IDL due to data persistence.
      ;;
      cspice_kclear
   
   IDL outputs:
   
      Scalar:
      The position of    : Mars
      As observed from   : Earth
      In reference frame : J2000
      At epoch           : July 4, 2003 11:00 AM PST
      R (kilometers)     :   73822235.      -27127919.      -18741306.
      Light time (secs)  :   269.68988
       between observer
       and target

      Vector
      At epoch (UTC)     : 2003 JUL 04 19:00:00.000
      R (kilometers)     :   73822235.      -27127919.      -18741306.
      Light time (secs)  :   269.68988
       between observer
       and target

      At epoch (UTC)     : 2003 JUL 05 22:46:40.000
      R (kilometers)     :   73140185.      -26390525.      -18446763.
      Light time (secs)  :   266.56404
       between observer
       and target

      At epoch (UTC)     : 2003 JUL 07 02:33:20.000
      R (kilometers)     :   72456240.      -25681031.      -18163339.
      Light time (secs)  :   263.48035
       between observer
       and target

      At epoch (UTC)     : 2003 JUL 08 06:20:00.000
      R (kilometers)     :   71771127.      -24999259.      -17890947.
      Light time (secs)  :   260.43952
       between observer
       and target

      At epoch (UTC)     : 2003 JUL 09 10:06:40.000
      R (kilometers)     :   71085544.      -24345021.      -17629491.
      Light time (secs)  :   257.44220
       between observer
       and target

Particulars


   Please refer to the Aberation Corrections Required Reading (ABCORR.REQ)
   for detailed information describing the nature and calculation of the
   applied corrections.

Required Reading


   ICY.REQ
   ABCORR.REQ
   SPK.REQ
   NAIF_IDS.REQ 
   FRAMES.REQ 
   TIME.REQ 

Version


   -Icy Version 1.1.5, 22-DEC-2015 (EDW)

       Corrected typo in Version section. The 07-NOV-2013
       version entry lacked a version ID.
       
       Particulars updated to refer to Aberration Corrections
       Required Reading document.

   -Icy Version 1.1.4, 07-JUL-2014 (NJB)(EDW)

       Discussion of light time corrections was updated. Assertions
       that converged light time corrections are unlikely to be
       useful were removed.

   -Icy Version 1.1.3, 07-NOV-2013 (EDW)

      Added aberration algorithm explanation to Particulars section.

   -Icy Version 1.1.2, 22-DEC-2008, EDW (JPL)

      Header edits performed to improve argument descriptions.
      These descriptions should now closely match the descriptions
      in the corresponding CSPICE routine.

   -Icy Version 1.1.1, 29-SEP-2007, EDW (JPL)
      
      Replaced the comment fragment in the I/O section
      
         "return with the same order"
         
      with
      
         "return with the same measure of vectorization"

   -Icy Version 1.1.0, 12-SEP-2004, EDW (JPL)

       Added capability to process vector 'et' input
       returning a matrix 'ptarg' and vector 'ltime'
       on output.

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

Index_Entries

 
   using names get target position relative to an observer 
   position relative to observer corrected for aberrations 
   read ephemeris data 
   read trajectory data 
 



Wed Apr  5 17:58:03 2017