Index Page
mice_subpt
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


   MICE_SUBPT determines the coordinates of the sub-observer point
   on a target body at a particular epoch, optionally corrected
   for planetary (light time) and stellar aberration. The call also
   returns the observer's altitude above the target body.

I/O


   Given:

      method   a string providing parameters defining the 
               computation method to use.

               [1,c1] = size(method); char = class(method)

                  or

               [1,1] = size(method); cell = class(method)

               The choices are:

                  'Near point'       The sub-observer point is
                                     defined as the nearest point on
                                     the target relative to the
                                     observer.

                  'Intercept'        The sub-observer point is
                                     defined as the target surface
                                     intercept of the line
                                     containing the observer and the
                                     target's center.

               In both cases, the intercept computation treats the
               surface of the target body as a triaxial ellipsoid.
               The ellipsoid's radii must be available in the kernel
               pool.

               Neither case nor white space are significant in
               'method'.  For example, the string ' NEARPOINT' is
               valid.

      target   the name of the observed target body. 'target'
               is case-insensitive, and leading and trailing blanks in
               'target' are not significant. Optionally, you may supply
               a string containing the integer ID code for the object.
               For example both 'MOON' and '301' are legitimate strings
               that indicate the moon is the target body.

               [1,c2] = size(target); char = class(target)

                  or

               [1,1] = size(target); cell = class(target)

               This routine assumes that the target body is modeled by
               a tri-axial ellipsoid, and that a PCK file containing
               its radii has been loaded into the kernel pool via
               cspice_furnsh.

      et       the epoch(s), expressed as seconds past J2000 TDB, of the
               observer: 'et' is the epoch at which the observer's state 
               is computed.

               [1,n] = size(et); double = class(et)

               When aberration corrections are not used, 'et' is also
               the epoch at which the position and orientation of
               the target body are computed.

               When aberration corrections are used, 'et' is the epoch
               at which the observer's state relative to the solar
               system barycenter is computed; in this case the
               position and orientation of the target body are
               computed at et-lt or et+lt, where 'lt' is the one-way
               light time between the sub-observer point and the
               observer, and the sign applied to 'lt' depends on the
               selected correction. See the description of 'abcorr'
               below for details.

      abcorr   the aberration correction to apply
               when computing the observer-target state and the
               orientation of the target body.

               [1,c3] = size(abcorr); char = class(abcorr)

                  or

               [1,1] = size(abcorr); cell = class(abcorr)

               For remote sensing applications, where the apparent
               sub-observer point seen by the observer is desired,
               normally either of the corrections

                     'LT+S'
                     'CN+S'

               should be used. These and the other supported options
               are described below. 'abcorr' may be any of the
               following:

                     'NONE'     Apply no correction. Return the
                                geometric sub-observer point on the
                                target body.

               Let 'lt' represent the one-way light time between the
               observer and the sub-observer point (note: NOT
               between the observer and the target body's center).
               The following values of 'abcorr' apply to the
               "reception" case in which photons depart from the
               sub-observer point'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 location of sub-observer
                                point 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.

                                Both the target position as seen by the
                                observer, and rotation of the target
                                body, are corrected for light time.

                     '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
                                sub-observer point 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. Both the
                                position and rotation of the target
                                body are corrected for light time.

                     'CN+S'     Converged Newtonian light time and
                                stellar aberration corrections. This
                                option produces a solution that is at
                                least as accurate at that obtainable
                                with the 'LT+S' option. Whether the 'CN+S'
                                solution is substantially more accurate
                                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.

               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
               sub-observer point 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
                                sub-observer location at the moment it
                                receives photons emitted from the
                                observer's location 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.

                                Both the target position as seen by the
                                observer, and rotation of the target
                                body, are corrected for light time.

                     'XLT+S'    "Transmission" case: correct for
                                one-way light time and stellar
                                aberration using a Newtonian
                                formulation  This option modifies the
                                sub-observer point obtained with the
                                'XLT' option to account for the
                                observer's velocity relative to the
                                solar system barycenter.

                     'XCN'      Converged Newtonian light time
                                correction. This is the same as XLT
                                correction but with further iterations
                                to a converged Newtonian light time
                                solution.

                     'XCN+S'    "Transmission" case: converged
                                Newtonian light time and stellar
                                aberration corrections.

      obsrvr   the scalar string name of the observing body. The
               observing body is an ephemeris object: it typically
               is a spacecraft, the earth, or a surface point on the
               earth. 'obsrvr' is case-insensitive, and leading and
               'obsrvr' are not significant. Optionally, you may
               trailing blanks in supply a string containing the integer
               ID code for the object. For example both 'MOON' and '301'
               are legitimate strings that indicate the Moon is the
               observer.

               [1,c4] = size(obsrvr); char = class(obsrvr)

                  or

               [1,1] = size(obsrvr); cell = class(obsrvr)

   the call:

      [spoint] = mice_subpt( method, target, et, abcorr, obsrvr)

   returns:

      spoint   the structure(s) containing the results of the calculation.

               [1,n] = size(spoint); struct = class(spoint)

               Each structure consists of the fields:

                  'pos'   the array(s) defining the sub-observer point
                          on the target body.
        
                          [3,1] = size(spoint(i).pos)
                          double = class(spoint(i).pos(i))

                          The sub-observer point is defined either as the 
                          point on the target body that is closest to the 
                          observer, or the target surface intercept of the 
                          line from the observer to the target's center; 
                          the input argument 'method' selects the 
                          definition to be used.

                          The body-fixed frame, which is time-dependent, is
                          evaluated at 'et' if 'abcorr' is 'NONE'; otherwise
                          the frame is evaluated at et-lt, where 'lt' is the
                          one-way light time from target to observer.

                          The state of the target body is corrected for
                          aberration as specified by 'abcorr'; the corrected
                          state is used in the geometric computation.  As
                          indicated above, the rotation of the target is
                          retarded by one-way light time if 'abcorr'
                          specifies that light time correction is to be done.

                  'alt'   the values(s) of the altitude(s) of  'obsrvr' above
                          'target'.

                          [1,1] = size(spoint(i).alt)
                          double = class(spoint(i).alt)

                          When 'method' specifies a "near point" computation,
                          'alt' is truly altitude in the standard geometric
                          sense:  the length of a segment dropped from the
                          observer to the target's surface, such that the
                          segment is perpendicular to the surface at the
                          contact point 'spoint'.

                          When 'method' specifies an "intercept" computation,
                          'alt' is still the length of the segment from the
                          observer to the surface point 'spoint', but this
                          segment in general is not perpendicular to
                          the surface.

      'spoint' returns with the same vectorization measure, N, as 'et'.

      Note, if needed, the user can extract the field data from vectorized
      'spoint' structures into separate arrays.

      Extract the N 'pos' field data to a 3XN array 'position':

         position = reshape( [spoint(:).pos], 3, [] )

      Extract the N 'alt' field data to a 1XN array 'altitude':

         altitude = reshape( [point(:).alt], 1, [] )

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.

   Example(1):

      %
      % Find the sub point position of the moon on the earth at
      % a given time using the "near point" then the "intercept"
      % options.
      %
      % Load the meta kernel listing the needed SPK, PCK, LSK
      % kernels.
      %
      cspice_furnsh( 'standard.tm' )

      %
      % Calculate the location of the sub point of the moon as
      % seen from Earth at epoch JAN 1, 2006. Apply light time
      % correction to return apparent position.
      %
      et = cspice_str2et( 'JAN 1, 2006' );

      %
      % First use option 'Near Point'
      %
      [point1] = mice_subpt( 'near point', 'earth', et, 'lt+s', 'moon');

      %
      % Now use option 'Intercept'
      %
      [point2] = mice_subpt( 'intercept', 'earth', et, 'lt+s', 'moon');

      %
      % Calculate the Euclidean distance between the two locations
      % and the angular separation between the position vectors.
      %
      dist = norm( point1.pos - point2.pos);
      sep  = cspice_vsep(point1.pos, point2.pos )*cspice_dpr;

      txt = sprintf( 'Distance between locations            (km): %8.5f', ...
                                                                       dist);
      disp( txt )

      txt = sprintf( 'Angular separation between locations (deg): %8.5f', ...
                                                                       sep );
      disp( txt )

      %
      % It's always good form to unload kernels after use,
      % particularly in MATLAB due to data persistence.
      %
      cspice_kclear

   MATLAB outputs:

      Distance between locations            (km): 16.70963
      Angular separation between locations (deg):  0.15020

   Example(2):

      %
      % Find the sub body position of the moon on the earth at
      % at epoch JAN 1, 2006 and for the next 12 months. Use the
      % 'near point' option to calculate the physically
      % closest point between the two bodies.
      %
      % Load the meta kernel listing the needed SPK, PCK, LSK
      % kernels.
      %
      cspice_furnsh( 'standard.tm' )

      %
      % Convert the calendar string to ephemeris time.
      %
      et0 = cspice_str2et( 'JAN 1, 2006' );

      %
      % Fill an array with epochs, start with the epoch above then
      % epochs in steps on one month ( thirty days in seconds)
      %
      et  = [0:12]*cspice_spd*30. + et0;

      %
      % Calculate the nearpoint of the moon with respect to earth at
      % the epochs defined in 'et'.
      %
      [point] = mice_subpt( 'near point', 'earth', et, 'lt+s', 'moon');

      %
      % Convert the subpoint coordinates to lat/lon expressed in degrees with
      % the radius.
      %
      % Extract from the 'point' structure the 3XN array of position data.
      %
      position = reshape( [point(:).pos], 3, [] )

      [radius, longitude, latitude] = cspice_reclat(position);
      longitude                     = longitude * cspice_dpr;
      latitude                      = latitude  * cspice_dpr;

      %
      % Convert the 'et' epochs to calendar format.
      %
      utc = cspice_et2utc( et, 'C', 3 );

      for i=1:13
         txt = sprintf( 'Moon subpoint epoch: %s', utc(i,:) );
         disp( txt )

         txt = sprintf( '              (deg): longitude %8.4f', longitude(i) );
         disp( txt )

         txt = sprintf( '              (deg): latitude  %8.4f', latitude(i) );
         disp( txt )
         disp( ' ' )

      end

      %
      % It's always good form to unload kernels after use,
      % particularly in MATLAB due to data persistence.
      %
      cspice_kclear

   MATLAB outputs:

                 ... partial output ...

      Moon subpoint epoch: 2006 JUL 30 00:00:00.001
                    (deg): longitude -127.7548
                    (deg): latitude   -0.1948

      Moon subpoint epoch: 2006 AUG 29 00:00:00.001
                    (deg): longitude -128.2727
                    (deg): latitude  -15.0349

      Moon subpoint epoch: 2006 SEP 28 00:00:00.002
                    (deg): longitude -123.9021
                    (deg): latitude  -25.9738

      Moon subpoint epoch: 2006 OCT 28 00:00:00.001
                    (deg): longitude -113.7475
                    (deg): latitude  -27.7753

      Moon subpoint epoch: 2006 NOV 27 00:00:00.001
                    (deg): longitude -104.0459
                    (deg): latitude  -17.9194

      Moon subpoint epoch: 2006 DEC 27 00:00:00.000
                    (deg): longitude -98.2728
                    (deg): latitude   -0.5411

Particulars


   A sister version of this routine exists named cspice_subpt that returns
   the structure field data as separate arguments.

Required Reading


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

   MICE.REQ
   FRAMES.REQ
   PCK.REQ
   SPK.REQ
   TIME.REQ

Version


   -Mice Version 1.0.1, 12-JAN-2015, EDW (JPL)

       Edited I/O section to conform to NAIF standard for Mice documentation.

   -Mice Version 1.0.0, 16-DEC-2005, EDW (JPL)

Index_Entries


   sub-observer point


Wed Apr  5 18:00:37 2017