subpt_c

Index Page subpt_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void subpt_c ( ConstSpiceChar       * method,
                      ConstSpiceChar       * target,
                      SpiceDouble            et,
                      ConstSpiceChar       * abcorr,
                      ConstSpiceChar       * obsrvr,
                      SpiceDouble            spoint [3],
                      SpiceDouble          * alt         )
#### Abstract
       Deprecated: This routine has been superseded by the CSPICE
       routine subpnt_c. This routine is supported for purposes of
       backward compatibility only.

       Compute the rectangular coordinates of the sub-observer point on
       a target body at a particular epoch, optionally corrected for
       planetary (light time) and stellar aberration.  Return these
       coordinates expressed in the body-fixed frame associated with the
       target body.  Also, return the observer's altitude above the
       target body.
#### Required_Reading
       FRAMES
       PCK
       SPK
       TIME
#### Keywords
       GEOMETRY
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       method     I   Computation method.
       target     I   Name of target body.
       et         I   Epoch in ephemeris seconds past J2000 TDB.
       abcorr     I   Aberration correction.
       obsrvr     I   Name of observing body.
       spoint     O   Sub-observer point on the target body.
       alt        O   Altitude of the observer above the target body.
#### Detailed_Input
       method      is a short string specifying the computation method
                   to be used.  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      is the name of the 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.

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

       et          is the epoch in ephemeris seconds past J2000 at which
                   the sub-observer point on the target body is to be
                   computed.

       abcorr      indicates the aberration corrections to be applied
                   when computing the observer-target state.  `abcorr'
                   may be any of the following.

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

                      "LT"       Correct for planetary (light time)
                                 aberration.  Both the state and rotation
                                 of the target body are corrected for
                                 light time.

                      "LT+S"     Correct for planetary (light time) and
                                 stellar aberrations. Both the state and
                                 rotation of the target body are
                                 corrected for light time.

                      "CN"       Converged Newtonian light time
                                 corrections.  This is the same as LT
                                 corrections but with further iterations
                                 to a converged Newtonian light time
                                 solution.  Given that relativistic
                                 effects may be as large as the higher
                                 accuracy achieved by this computation,
                                 this is correction is seldom worth the
                                 additional computations required unless
                                 the user incorporates additional
                                 relativistic corrections.  Both the
                                 state and rotation of the target body
                                 are corrected for light time.

                      "CN+S"     Converged Newtonian light time
                                 corrections and stellar aberration.
                                 Both the state and rotation of the
                                 target body are corrected for light
                                 time.

       obsrvr      is the name of the observing body.  This is typically a
                   spacecraft, the earth, or a surface point on the earth.
                   `obsrvr' is case-insensitive, and leading and trailing
                   blanks in `obsrvr' are not significant. Optionally, you
                   may supply a string containing the integer ID code for
                   the object.  For example both "EARTH" and "399" are
                   legitimate strings that indicate the earth is the
                   observer.
#### Detailed_Output
       spoint      is the sub-observer point on the target body at `et'
                   expressed relative to the body-fixed frame of the
                   target body.

                   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         is the "altitude" of the observer above the target
                   body.  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.
#### Parameters
       None.
#### Exceptions
       If any of the listed errors occur, the output arguments are
       left unchanged.

       1) If the input argument `method' is not recognized, the error
          SPICE(DUBIOUSMETHOD) is signaled.

       2) If either of the input body names `target' or `obsrvr' cannot be
          mapped to NAIF integer codes, the error SPICE(IDCODENOTFOUND)
          is signaled.

       3) If `obsrvr' and `target' map to the same NAIF integer ID codes, the
          error SPICE(BODIESNOTDISTINCT) is signaled.

       4) If frame definition data enabling the evaluation of the state
          of the target relative to the observer in target body-fixed
          coordinates have not been loaded prior to calling subpt_c, the
          error will be diagnosed and signaled by a routine in the call
          tree of this routine.

       5) If the specified aberration correction is not recognized, the
          error will be diagnosed and signaled by a routine in the call
          tree of this routine.

       6) If insufficient ephemeris data have been loaded prior to
          calling subpt_c, the error will be diagnosed and signaled by a
          routine in the call tree of this routine.

       7) If the triaxial radii of the target body have not been loaded
          into the kernel pool prior to calling subpt_c, the error will be
          diagnosed and signaled by a routine in the call tree of this
          routine.

       8) The target must be an extended body:  if any of the radii of
          the target body are non-positive, the error will be diagnosed
          and signaled by routines in the call tree of this routine.

       9) If PCK data supplying a rotation model for the target body
          have not been loaded prior to calling subpt_c, the error will be
          diagnosed and signaled by a routine in the call tree of this
          routine.
#### Files
       Appropriate SPK, PCK, and frame data must be available to
       the calling program before this routine is called.  Typically
       the data are made available by loading kernels; however the
       data may be supplied via subroutine interfaces if applicable.

       The following data are required:

          - SPK data:  ephemeris data for target and observer must be
            loaded.  If aberration corrections are used, the states of
            target and observer relative to the solar system barycenter
            must be calculable from the available ephemeris data.
            Typically ephemeris data are made available by loading one
            or more SPK files via furnsh_c.

          - PCK data:  triaxial radii for the target body must be loaded
            into the kernel pool.  Typically this is done by loading a
            text PCK file via furnsh_c.

          - Further PCK data:  rotation data for the target body must
            be loaded.  These may be provided in a text or binary PCK file.
            Either type of file may be loaded via furnsh_c

          - Frame data:  if a frame definition is required to convert
            the observer and target states to the body-fixed frame of
            the target, that definition must be available in the kernel
            pool.  Typically the definition is supplied by loading a
            frame kernel via furnsh_c.

       In all cases, kernel data are normally loaded once per program
       run, NOT every time this routine is called.
#### Particulars
       subpt_c computes the sub-observer point on a target body.
       (The sub-observer point is commonly called the sub-spacecraft
       point when the observer is a spacecraft.)  subpt_c also
       determines the altitude of the observer above the target body.

       There are two different popular ways to define the sub-observer
       point:  "nearest point on target to observer" or "target surface
       intercept of line containing observer and target."  These
       coincide when the target is spherical and generally are distinct
       otherwise.

       When comparing sub-point computations with results from sources
       other than SPICE, it's essential to make sure the same geometric
       definitions are used.
#### Examples
       The numerical results shown for this example may differ across
       platforms.  The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, and the machine
       specific arithmetic implementation.

       In the following example program, the file

          spk_m_031103-040201_030502.bsp

       is a binary SPK file containing data for Mars Global Surveyor,
       Mars, and the Sun for a time interval bracketing the date

           2004 JAN 1 12:00:00 UTC.

       pck00007.tpc is a planetary constants kernel file containing
       radii and rotation model constants.  naif0007.tls is a
       leapseconds kernel.

       Find the sub-observer point of the Mars Global Surveyor (MGS)
       spacecraft on Mars for a specified time.  Perform the computation
       twice, using both the "intercept" and "near point" options.

          #include <stdio.h>
          #include "SpiceUsr.h"

          int main ()
          {
             #define  METHODLEN      25

             SpiceChar               method [2][METHODLEN] =
                                     {
                                        "Intercept", "Near point"
                                     };

             SpiceDouble             alt;
             SpiceDouble             et;
             SpiceDouble             lat;
             SpiceDouble             lon;
             SpiceDouble             radius;
             SpiceDouble             spoint [3];

             SpiceInt                i;

             /.
             Load kernel files.
             ./
             furnsh_c ( "naif0007.tls"                   );
             furnsh_c ( "pck00007.tpc"                   );
             furnsh_c ( "spk_m_031103-040201_030502.bsp" );

             /.
             Convert the UTC request time to ET (seconds past J2000 TDB).
             ./
             str2et_c ( "2004 JAN 1 12:00:00", &et );

             /.
             Compute sub-spacecraft point using light time and stellar
             aberration corrections.  Use the "target surface intercept"
             definition of sub-spacecraft point on the first loop
             iteration, and use the "near point" definition on the
             second.
             ./

             for ( i = 0;  i < 2;  i++ )
             {
                subpt_c ( method[i],
                          "MARS",     et,      "LT+S",
                          "MGS",      spoint,  &alt    );

                /.
                Convert rectangular coordinates to planetocentric
                latitude and longitude.  Convert radians to degrees.
                ./
                reclat_c ( spoint, &radius, &lon, &lat );

                lon *= dpr_c ();
                lat *= dpr_c ();

                /.
                Write the results.
                ./

                printf ( "\n"
                         "Computation method:  %s\n"
                         "\n"
                         "   Radius                   (km)  =  %25.15e\n"
                         "   Planetocentric Latitude  (deg) =  %25.15e\n"
                         "   Planetocentric Longitude (deg) =  %25.15e\n"
                         "   Altitude                 (km)  =  %25.15e\n"
                         "\n",
                         method[i],
                         radius,
                         lat,
                         lon,
                         alt                                             );
             }

             return ( 0 );
          }

       When this program is executed, the output will be:

          Computation method:  Intercept

             Radius                   (km)  =      3.387970765126046e+03
             Planetocentric Latitude  (deg) =     -3.970227239033073e+01
             Planetocentric Longitude (deg) =     -1.592266633611679e+02
             Altitude                 (km)  =      3.731735060549094e+02

          Computation method:  Near point

             Radius                   (km)  =      3.387984503271711e+03
             Planetocentric Latitude  (deg) =     -3.966593293571449e+01
             Planetocentric Longitude (deg) =     -1.592266633611679e+02
             Altitude                 (km)  =      3.731666361282019e+02
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       C.H. Acton     (JPL)
       N.J. Bachman   (JPL)
       J.E. McLean    (JPL)
#### Version
       -CSPICE Version 1.0.3, 07-FEB-2008 (NJB)

            Abstract now states that this routine is deprecated.

       -CSPICE Version 1.0.2, 22-JUL-2004 (NJB)

           Updated header to indicate that the `target' and `observer'
           input arguments can now contain string representations of
           integers.

       -CSPICE Version 1.0.1, 27-JUL-2003 (NJB) (CHA)

           Various header corrections were made.  The example program
           was upgraded to use real kernels, and the program's output is
           shown.

       -CSPICE Version 1.0.0, 31-MAY-1999 (NJB) (JEM)
#### Index_Entries
       sub-observer point
#### Link to routine subpt_c source file subpt_c.c

    Thu Apr 16 08:59:19 2009