Index Page
cspice_spkapo
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_SPKAPO returns the position 3-vector of a target
   body relative to an observer, optionally corrected for
   light time and stellar aberration, given the geometric
   state 6-vector of the observer relative to the Solar System
   Barycenter.

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

I/O


   Given:

      targ      scalar integer SPICE ID of the target body (the
                observed body).

      et        scalar double precision ephemeris time (ET) epoch
                for the observation of interest.

      ref       scalar string name of the reference frame in
                which to output the position 3-vector.

      sobs      double precision geometric (uncorrected) state 6-vector
                of the observer relative to the solar system barycenter
                at epoch 'et'.

      abcorr    scalar string name of the aberration correction
                to apply to 'sobs'.

                'abcorr' may be any of the following:

                   'NONE'     Apply no correction. Return the
                              geometric state of the target
                              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-ltime 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 state 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. 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
                              state obtained with the 'LT' option to
                              account for the observer's velocity
                              relative to the solar system
                              barycenter. The result is the apparent
                              state 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+ltime:

                   'XLT'      "Transmission" case:  correct for
                              one-way light time using a Newtonian
                              formulation. This correction yields the
                              state 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
                              state obtained with the 'XLT' option to
                              account for the observer's velocity
                              relative to the solar system
                              barycenter. The position component of
                              the computed target state 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.

                Case and leading and trailing blanks are not
                significant in the string 'abcorr'.

   the call:

      cspice_spkapo, targ, et, ref, sobs, abcorr, ptarg, ltime

   returns:

      ptarg   the double precision 3-vector describing the position
              of target 'targ' with respect to the observer
              with aberration correction 'abcorr' in reference
              frame 'ref'.

      ltime   the double precision scalar describing the one-way
              light-time between the observer and 'targ'.

              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.

   Note: NAIF recommends the use of cspice_spkpos instead of
   cspice_spkapo to calculate observer to target position vectors.

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.


      ;;
      ;; Define the needed parameters.
      ;;
      MARS   = 499
      MOON   = 301
      EPOCH  = 'Jan 1 2004 5:00 PM'
      REF    = 'J2000'
      ABCORR = 'LT+S'

      ;;
      ;; Load a meta kernel listing a leapseconds kernel.
      ;;
      cspice_furnsh, 'standard.tm'

      ;;
      ;; Convert the time string to ephemeris time J2000.
      ;;
      cspice_str2et, EPOCH, et

      ;;
      ;; Compute the geometric state of the Moon wrt the
      ;; the Solar System barycenter.
      ;;
      cspice_spkssb, MOON, et, REF, state

      ;;
      ;; Apply an aberration correction for a position vector
      ;; of the MOON as seen from Mars.
      ;;
      cspice_spkapo, MARS, et, REF, state, ABCORR, pos_vec, ltime

      print, 'Position vector of : ' + string(MARS)
      print, '...as seen from    : ' + string(MOON)
      print, '...in frame        : ' + REF
      print, '...at time         : ' + EPOCH
      print, '...with correction : ' + ABCORR
      print, '...equals (KM)     : ', pos_vec

   IDL outputs:

      Position vector of :      499
      ...as seen from    :      301
      ...in frame        : J2000
      ...at time         : Jan 1 2004 5:00 PM
      ...with correction : LT+S
      ...equals (KM)     :  1.6453447e+08  25121995.  11145412.

   The cspice_spkpos call equivalent to the preceding code:

      cspice_spkpos, 'MARS', et, REF, ABCORR, 'MOON', pos_vec, ltime

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.0.4, 01-APR-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.0.3, 10-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.0.2, 07-NOV-2013 (EDW)

      Improvement of I/O section descriptions. Added aberration 
      algorithm explanation to Particulars section.

   -Icy Version 1.0.1, 23-SEP-2008, EDW (JPL)

      Eliminated error in English.

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

Index_Entries


   apparent position from spk file
   get apparent position




Wed Apr  5 17:58:03 2017