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_spkezp

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


Abstract


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

I/O


   Given:

      targ     the NAIF ID code for a target body.

               help, targ
                  LONG = Scalar

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

      et       the ephemeris time, expressed as seconds past J2000 TDB, at
               which the position of the target body relative to the observer
               is to be computed.

               help, et
                  DOUBLE = Scalar

               `et' refers to time at the observer's location.

      ref      the name of the reference frame relative to which the output
               position vector should be expressed.

               help, ref
                  STRING = Scalar

               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. See
               the description of the output position vector `ptarg'
               for details.

      abcorr   indicates the aberration corrections to be applied to the
               position of the target body to account for one-way light time
               and stellar aberration.

               help, abcorr
                  STRING = Scalar

               See the discussion in the -Particulars section for
               recommendations on how to choose aberration corrections.

               `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-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 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
                             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
                             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 computed target
                             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.

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

      obs      the NAIF ID code for the observing body.

               help, obs
                  LONG = Scalar

   the call:

      cspice_spkezp, targ, et, ref, abcorr, obs, ptarg, ltime

   returns:

      ptarg    a Cartesian 3-vector representing the position of the target
               body relative to the specified observer.

               help, ptarg
                  DOUBLE = Array[3]

               `ptarg' is corrected for the specified aberrations, and is
               expressed with respect to the reference frame specified by
               `ref'. The three components of `ptarg' represent the x-, y- and
               z-components of the target's position.

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

               Units are always km.

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

      ltime    the one-way light time between the observer and target in
               seconds.

               help, ltime
                  DOUBLE = Scalar

               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.

Parameters


   None.

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.

   1) Return the position vector of Mars (499) as seen from
      Earth (399) in the J2000 frame using aberration
      correction LT+S (light time plus stellar aberration)
      at the epoch July 4, 2003 11:00 AM PST.

      Use the meta-kernel shown below to load the required SPICE
      kernels.


         KPL/MK

         File name: spkezp_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
            ---------                     --------
            de421.bsp                     Planetary ephemeris
            pck00009.tpc                  Planet orientation and
                                          radii
            naif0009.tls                  Leapseconds

         \begindata

            KERNELS_TO_LOAD = ( 'de421.bsp',
                                'pck00009.tpc',
                                'naif0009.tls'  )

         \begintext

         End of meta-kernel


      Example code begins here.


      PRO spkezp_ex1

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

         ;;
         ;; Define parameters for a position lookup:
         ;;
         target   = 499
         epoch    = 'July 4, 2003 11:00 AM PST'
         frame    = 'J2000'
         abcorr   = 'LT+S'
         observer = 399

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

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

         ;;
         ;; Output...
         ;;
         print, 'The position of    : ', target
         print, 'As observed from   : ', observer
         print, 'In reference frame : ', frame
         print, 'At epoch           : ', epoch
         print
         print, FORMAT='(A,3F18.6)', 'R   (km): ', ptarg
         print
         print, 'Light time (s) between observer and target: ', ltime

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


      The position of    :      499
      As observed from   :      399
      In reference frame : J2000
      At epoch           : July 4, 2003 11:00 AM PST

      R   (km):    73822235.331161  -27127919.178593  -18741306.284864

      Light time (s) between observer and target:        269.68988


Particulars


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

Exceptions


   1)  If name of target or observer cannot be translated to its NAIF
       ID code, the error SPICE(IDCODENOTFOUND) is signaled by a
       routine in the call tree of this routine.

   2)  If the reference frame `ref' is not a recognized reference
       frame, the error SPICE(UNKNOWNFRAME) is signaled by a routine
       in the call tree of this routine.

   3)  If the loaded kernels provide insufficient data to compute the
       requested position vector, an error is signaled by a routine
       in the call tree of this routine.

   4)  If an error occurs while reading an SPK or other kernel file,
       the error  is signaled by a routine in the call tree
       of this routine.

   5)  If any of the required attributes of the reference frame `ref'
       cannot be determined, the error SPICE(UNKNOWNFRAME2) is
       signaled by a routine in the call tree of this routine.

   6)  If any of the input arguments, `targ', `et', `ref', `abcorr'
       or `obs', is undefined, an error is signaled by the IDL error
       handling system.

   7)  If any of the input arguments, `targ', `et', `ref', `abcorr'
       or `obs', is not of the expected type, or it does not have the
       expected dimensions and size, an error is signaled by the Icy
       interface.

   8)  If any of the output arguments, `ptarg' or `ltime', is not a
       named variable, an error is signaled by the Icy interface.

Files


   This routine computes positions using SPK files that have been loaded
   into the SPICE system, normally via the kernel loading interface routine
   cspice_furnsh. See the routine cspice_furnsh and the SPK and KERNEL
   Required Reading for further information on loading (and unloading)
   kernels.

   If the output position `ptarg' is to be expressed relative to a
   non-inertial frame, or if any of the ephemeris data used to
   compute `ptarg' are expressed relative to a non-inertial frame in
   the SPK files providing those data, additional kernels may be
   needed to enable the reference frame transformations required to
   compute the position. Normally these additional kernels are PCK
   files or frame kernels. Any such kernels must already be loaded
   at the time this routine is called.

Restrictions


   None.

Required_Reading


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

Literature_References


   None.

Author_and_Institution


   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.0.4, 10-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard. Added example's
       problem statement and meta-kernel. Reformatted example's output
       and added call to cspice_kclear.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       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.3, 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.0.2, 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.0.1, 07-NOV-2013 (EDW)

       Added aberration algorithm explanation to -Particulars section.

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

Index_Entries


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



Fri Dec 31 18:43:07 2021