Index Page subsol_pl02

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 subsol_pl02 ( SpiceInt               handle,
                          ConstSpiceDLADescr   * dladsc,
                          ConstSpiceChar       * method,
                          ConstSpiceChar       * target,
                          SpiceDouble            et,
                          ConstSpiceChar       * abcorr,
                          ConstSpiceChar       * obsrvr,
                          SpiceDouble            spoint [3],
                          SpiceDouble          * dist,
                          SpiceInt             * plateID     )

#### Abstract

       Deprecated: This routine has been superseded by the CSPICE routine
       subslr_c. This routine is supported for purposes of backward
       compatibility only.

       Compute the rectangular coordinates of the sub-solar point on a
       target body at a particular epoch, optionally corrected for light
       time and stellar aberration.  The target body's surface is
       represented by a triangular plate model contained in a type 2 DSK
       segment. Return the sub-solar point's coordinates expressed in the
       body-fixed frame associated with the target body.  Also, return the
       observer's distance from the sub-solar point.

#### Required_Reading

       FRAMES
       PCK
       SPK
       TIME

#### Keywords

       GEOMETRY

#### Brief_I/O

       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       handle     I   DSK handle.
       dladsc     I   DLA descriptor of target body segment.
       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-solar point on the target body.
       dist       O   Distance of observer from sub-solar point.
       plateID    O   DSK plate ID of sub-solar point.

#### Detailed_Input

       handle      is the DAS file handle of a DSK file open for read
                   access.  This kernel must contain a type 2 segment that
                   provides a plate model representing the entire surface
                   of the target body.

       dladsc      is the DLA descriptor of a DSK segment representing the
                   surface of the target body.

       method      is a short string specifying the computation method
                   to be used.  The choices are:

                      "Intercept"        The sub-solar point is defined as
                                         the plate model surface intercept
                                         of the ray starting at the Sun and
                                         passing through the target's
                                         center.

                      "Ellipsoid
                       near point"       The sub-solar point is defined as
                                         the plate model surface intercept
                                         of the ray starting at the Sun and
                                         passing through the nearest point
                                         to the observer on a reference
                                         ellipsoid associated with the
                                         target body.

                                         This option requires that the
                                         reference ellipsoid's radii be
                                         available in the kernel pool.

                   Neither case nor white space are significant in the
                   string "method".  For example, the string

                      "  ellipsoidNEARPOINT"

                   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's surface is
                   represented by a plate model, and that a DSK file
                   containing the plate model has been loaded via dasopr_c.

       et          is the epoch, represented  as seconds past J2000 TDB, at
                   which the sub-solar point on the target body is to be
                   computed.  When aberration corrections are used, `et'
                   refers to the epoch at which radiation is received at
                   the observer.

       abcorr      indicates the aberration corrections to be applied to
                   the position and orientation of the target body and the
                   position of the Sun to account for one-way light time
                   and stellar aberration.  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.  Use the geometric
                                 positions of the Sun and target body
                                 relative to the observer; evaluate the
                                 target body's orientation at `et'.

                   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
                                 uses the position and orientation of the
                                 target at the moment it emitted photons
                                 arriving at the observer at `et'.  The
                                 position of the Sun relative to the
                                 target is corrected for the one-way light
                                 time from the Sun to the target.

                                 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 positions
                                 obtained with the "LT" option to account
                                 for the observer's velocity relative to
                                 the solar system barycenter (note the
                                 target plays the role of "observer" in the
                                 computation of the aberration-corrected
                                 target-Sun vector). The result is the
                                 sub-solar point computed using apparent
                                 position and orientation of the target as
                                 seen by the observer and the apparent
                                 position of the Sun as seen by the target.

                      "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).

                                 The "CN" correction typically does not
                                 substantially improve accuracy because the
                                 errors made by ignoring relativistic
                                 effects may be larger than the improvement
                                 afforded by obtaining convergence of the
                                 light time solution. The "CN" correction
                                 computation also requires a significantly
                                 greater number of CPU cycles than does the
                                 one-iteration light time correction.

                      "CN+S"     Converged Newtonian light time
                                 and stellar aberration corrections.

       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-solar point on the target body expressed
                   relative to the body-fixed reference frame of the target
                   body.

                   The definition of sub-solar point depends on the
                   selected computation method.  See the description of the
                   input argument `method' for details.

                   The target 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 position and orientation of the target body and the
                   position of the Sun are corrected for aberration as
                   specified by `abcorr'; the corrected positions and
                   orientation are used in the computation of `spoint'.

       dist        is the distance between the observer and the sub-solar
                   point.  The observer is presumed to be outside the
                   target body, so `dist' is always non-negative.

       plateID     is the integer ID code of the plate on which the
                   sub-solar point is located.  This ID code can be
                   use to look up data associated with the plate, such
                   as the plate's vertices or outward normal vector.

#### 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 subsol_pl02, 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 subsol_pl02, the error will be diagnosed and signaled by a
          routine in the call tree of this routine.

       7) If a DSK providing a DSK type 2 plate model has not been
          loaded prior to calling subsol_pl02, the error will be
          diagnosed and signaled by a routine in the call tree of this
          routine.

       8) If the computation method is "near point" and radii of
          the target body have not been loaded into the kernel pool, 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 subsol_pl02, the error will be
          diagnosed and signaled by a routine in the call tree of this
          routine.

       10) If the segment associated with the input DLA descriptor does not
           contain data for the designated target, the error
           SPICE(TARGETMISMATCH) is signaled.

       11) If the segment associated with the input DLA descriptor is not
           of data type 2, the error SPICE(WRONGDATATYPE) is signaled.

       12) If the sub-solar point cannot be computed because the ray from
           the observer to the aim point designated by `method' fails to
           intersect the target surface as defined by the plate model, the
           error SPICE(NOINTERCEPT) is signaled.

       13) Use of transmission-style aberration corrections is not
           permitted.  If abcorr specified such a correction, the
           error SPICE(NOTSUPPORTED) is signaled.

       14) The observer is presumed to be outside the target body; no
           checks are made to verify this.

       15) If any input string pointer is null, the error SPICE(NULLPOINTER)
           will be signaled.

       16) If any input string has length zero, the error SPICE(EMPTYSTRING)
           will be signaled.

#### Files

       Appropriate DSK, 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:

          - DSK data:  a DSK file containing a plate model representing the
            target body's surface must be loaded. This kernel must contain
            a type 2 segment that contains data for the entire surface of
            the target body.

          - SPK data:  ephemeris data for target, observer, and Sun 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 if the "Near Point" method is selected.
            Typically these data are made available 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

       subsol_pl02 computes the sub-solar point on a target body.
       subsol_pl02 also determines the distance of the observer from the
       sub-solar point.

       Sub-point Definitions
       =====================

       This routine offers two ways of defining the sub-solar point:

          - The "intercept" method. In general, this definition
            calls for defining a ray emanating from the Sun and
            passing through the center of the target body.  The intercept
            on the first plate (the one closest to the observer) hit by this
            ray is the sub-point.

          - The "ellipsoid near point" method.  When a target's surface is
            modeled by a set of triangular plates, the notion of "dropping
            a perpendicular segment to the surface," which makes sense for
            convex surfaces, becomes problematic:  there need not be any
            plate whose normal vector is parallel to a segment from the Sun
            to some point on that plate, or there could be more than one
            such plate.  If such a plate exists, it might be located
            anywhere on the visible surface---not necessarily "below" the
            Sun.

            To work around these problems, the ellipsoid near point method
            uses a reference ellipsoid to define a preliminary sub-solar
            point: this is the unique point on the ellipsoid's surface at
            which the outward surface normal points toward the Sun.  Then
            the plate model sub-solar point is defined as the plate
            intercept closest to the Sun of a ray emanating from the Sun
            and passing through the preliminary sub-solar point on the
            ellipsoid.

       For a large target such as Mars, or for any target whose reference
       ellipsoid deviates significantly from spherical, the results
       obtained using the two sub-point definitions can be quite different.
       The example program provided below demonstrates this fact; Phobos is
       the target body in this case.  Some analysis on the user's part will
       be needed to select the "best" definition for a given application.

       When comparing sub-solar point computations with results from
       sources other than SPICE, it's essential to make sure the same
       geometric definitions are used.

       Aberration Corrections
       ======================

       Below, we indicate the aberration corrections to use for some
       common applications:

          1) Compute the sub-solar point using the apparent direction
             and orientation of a target. This is the most common case for
             a remote-sensing observation.  When the observer's altitude
             is more than one target radius above the surface:

                Use "LT+S":  apply both light time and stellar
                aberration corrections.

             Note that when the observer is close to the target surface,
             this choice may yield inaccurate results, since light time is
             measured between the observer and the target center.  When the
             observer has altitude of less than one target radius above the
             surface, aberration corrections should be omitted, so in this
             case abcorr should be set to:

                "NONE"

             Note that this selection calls for using the geometric position
             of the Sun.

          2) Use a geometric position vector and uncorrected target
             orientation as low-accuracy estimates for an application where
             execution speed is critical.

                Use "NONE".

       See the header of the CSPICE routine spkezr_c for a detailed
       discussion of aberration corrections.

#### 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

          phobos.3.3.bds

       is a DSK file containing a type 2 segment that provides a plate model
       representation of the surface of Phobos.  The file

          mar085.bsp

       is a binary SPK file containing data for Phobos, the Earth, and the
       Sun for a time interval bracketing the date

          2006 NOV 3 00:00:00 UTC.

       pck00009.tpc is a planetary constants kernel file containing radii
       and rotation model constants.  naif0009.tls is a leapseconds kernel.

       All of the kernels other than the DSK file should be loaded via
       a meta-kernel.  An example of the contents of such a kernel is:

           \begindata

              KERNELS_TO_LOAD = ( 'naif0009.tls'
                                  'pck00009.tpc'
                                  'mar085.bsp' )
           \begintext

       Find the sub-solar point on Phobos as seen from Earth for a
       specified sequence of times. Perform the computation twice, using
       both the "intercept" and "ellipsoid near point" options. Compute the
       corresponding sub-solar point values using an ellipsoidal surface
       for comparison.

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

          int main()
          {
             /.
             Local parameters
             ./
             #define  FILSIZ         256
             #define  NCORR          2
             #define  NSAMP          3
             #define  NMETHOD        2
             #define  TOL            ( 1.e-12 )
             #define  CORLEN         15
             #define  METHLEN        81
             #define  TIMLEN         41

             /.
             Local variables
             ./
             SpiceBoolean            found;

             SpiceChar             * abcorr;
             SpiceChar             * abcorrs[ NCORR ]   =
                                     {
                                        "NONE",
                                        "LT+S"
                                     };

             SpiceChar               dsk     [ FILSIZ  ];

             SpiceChar             * emethod;
             SpiceChar             * emethods[ NMETHOD ] =
                                     {
                                        "Intercept",
                                        "Near point"
                                     };

             SpiceChar               meta    [ FILSIZ  ];

             SpiceChar             * method;
             SpiceChar             * methods [ NMETHOD ] =
                                     {
                                        "Intercept",
                                        "Ellipsoid near point"
                                     };

             SpiceChar             * obsrvr = "Earth";
             SpiceChar             * target = "Phobos";
             SpiceChar               timstr [ TIMLEN ];

             SpiceDLADescr           dladsc;

             SpiceDouble             dist;
             SpiceDouble             elat;
             SpiceDouble             elon;
             SpiceDouble             erad;
             SpiceDouble             et0;
             SpiceDouble             et;
             SpiceDouble             f;
             SpiceDouble             radii  [3];
             SpiceDouble             re;
             SpiceDouble             rp;
             SpiceDouble             stepsize ;
             SpiceDouble             xlat;
             SpiceDouble             xlon;
             SpiceDouble             xpt    [3];
             SpiceDouble             xr;

             SpiceInt                coridx;
             SpiceInt                handle;
             SpiceInt                i;
             SpiceInt                midx;
             SpiceInt                n;
             SpiceInt                plid;

             /.
             Prompt for the name of a meta-kernel specifying
             all of the other kernels we need.  Load the
             metakernel.
             ./
             prompt_c ( "Enter meta-kernel name > ", FILSIZ, meta );
             furnsh_c ( meta );

             /.
             Prompt for the name of the DSK to read.
             ./
             prompt_c ( "Enter DSK name         > ", FILSIZ, dsk );

             /.
             Look up radii of the target; compute flattening
             coefficient.
             ./
             bodvrd_c ( target, "RADII", 3, &n, radii );

             re = radii[0];
             rp = radii[2];
             f  = ( re - rp ) / re;

             /.
             Open the DSK file for read access.
             We use the DAS-level interface for
             this function.
             ./
             dasopr_c ( dsk, &handle );

             /.
             Begin a forward search through the
             kernel, treating the file as a DLA.
             In this example, it's a very short
             search.
             ./
             dlabfs_c ( handle, &dladsc, &found );

             if ( !found  )
             {
                /.
                We arrive here only if the kernel
                contains no segments.  This is
                unexpected, but we're prepared for it.
                ./
                setmsg_c ( "No segments found in DSK file #.");
                errch_c  ( "#",  dsk                         );
                sigerr_c ( "SPICE(NODATA)"                   );
             }

             /.
             If we made it this far, DLADSC is the
             DLA descriptor of the first segment.

             Now compute sub-solar points using both computation
             methods.  We'll vary the aberration corrections
             and the epochs.
             ./
             et0      = 0.0;
             stepsize = 1.e6;

             for ( i = 0;  i < NSAMP;  i++  )
             {
                /.
                Set the computation time for the ith
                sample.
                ./
                et = et0 + i*stepsize;

                timout_c ( et,
                           "YYYY-MON-DD "
                           "HR:MN:SC.### ::TDB(TDB)",
                           TIMLEN,
                           timstr                    );

                printf ( "\n\nObservation epoch:  %s\n",
                         timstr                      );

                for ( coridx = 0;  coridx < NCORR;  coridx++  )
                {
                   /.
                   Select the aberration correction.
                   ./
                   abcorr = abcorrs[coridx];
                   printf ( "\n"
                            "   abcorr = %s\n", abcorr  );

                   for ( midx = 0;  midx < NMETHOD;  midx++  )
                   {
                      /.
                      Select the computation method.
                      ./
                      method  = methods [midx];
                      emethod = emethods[midx];

                      printf (  "\n"
                                "       Method = %s\n", method  );

                      /.
                      Compute the sub-solar point using a plate model
                      representation of the target's surface.
                      ./
                      subsol_pl02 ( handle, &dladsc, method,
                                    target, et,      abcorr,
                                    obsrvr, xpt,     &dist,   &plid );

                      /.
                      Represent the intercept in latitudinal
                      coordinates.
                      ./
                      reclat_c ( xpt, &xr, &xlon, &xlat );

                      printf (
                      "         Sub-solar point on plate model surface:\n"
                      "             Planetocentric Longitude (deg):  %f\n"
                      "             Planetocentric Latitude  (deg):  %f\n"
                      "             Radius                    (km):  %f\n"
                      "             Observer distance         (km):  %f\n",
                      xlon * dpr_c(),
                      xlat * dpr_c(),
                      xr,
                      dist                                                 );

                      /.
                      Compute the sub-solar point using an ellipsoidal
                      representation of the target's surface.  (The
                      routine subsol_c doesn't return distance.)
                      ./
                      subsol_c ( emethod, target, et,  abcorr,
                                 obsrvr,  xpt                 );

                      /.
                      Represent the intercept in latitudinal
                      coordinates.
                      ./
                      reclat_c ( xpt, &erad, &elon, &elat );

                      printf (
                      "         Sub-solar point on ellipsoid surface:\n"
                      "             Planetocentric Longitude (deg):  %f\n"
                      "             Planetocentric Latitude  (deg):  %f\n"
                      "             Radius                    (km):  %f\n",
                      elon * dpr_c(),
                      elat * dpr_c(),
                      erad                                                 );
                   }
                }
             }

             /.
             Close the kernel.  This isn't necessary in a stand-
             alone program, but it's good practice in subroutines
             because it frees program and system resources.
             ./
             dascls_c ( handle );

             return ( 0 );
          }

       When this program was executed on a PC/Linux/gcc platform,
       the output for the first epoch (the rest of the output
       is not shown due to its large volume) was:

          Enter meta-kernel name > meta
          Enter DSK name         > phobos.3.3.bds

          Observation epoch:  2000-JAN-01 12:00:00.000 (TDB)

             abcorr = NONE

                 Method = Intercept
                   Sub-solar point on plate model surface:
                       Planetocentric Longitude (deg):  102.413905
                       Planetocentric Latitude  (deg):  -24.533127
                       Radius                    (km):  11.612325
                       Observer distance         (km):  276700026.660260
                   Sub-solar point on ellipsoid surface:
                       Planetocentric Longitude (deg):  102.413905
                       Planetocentric Latitude  (deg):  -24.533127
                       Radius                    (km):  10.819463

                 Method = Ellipsoid near point
                   Sub-solar point on plate model surface:
                       Planetocentric Longitude (deg):  107.297077
                       Planetocentric Latitude  (deg):  -17.050888
                       Radius                    (km):  11.571591
                       Observer distance         (km):  276700027.335171
                   Sub-solar point on ellipsoid surface:
                       Planetocentric Longitude (deg):  107.488961
                       Planetocentric Latitude  (deg):  -16.739508
                       Radius                    (km):  11.116793

             abcorr = LT+S

                 Method = Intercept
                   Sub-solar point on plate model surface:
                       Planetocentric Longitude (deg):  114.623420
                       Planetocentric Latitude  (deg):  -24.533628
                       Radius                    (km):  11.411417
                       Observer distance         (km):  276710249.495398
                   Sub-solar point on ellipsoid surface:
                       Planetocentric Longitude (deg):  114.623420
                       Planetocentric Latitude  (deg):  -24.533628
                       Radius                    (km):  10.983515

                 Method = Ellipsoid near point
                   Sub-solar point on plate model surface:
                       Planetocentric Longitude (deg):  123.445345
                       Planetocentric Latitude  (deg):  -15.622318
                       Radius                    (km):  11.239869
                       Observer distance         (km):  276710250.760758
                   Sub-solar point on ellipsoid surface:
                       Planetocentric Longitude (deg):  123.267795
                       Planetocentric Latitude  (deg):  -15.815465
                       Radius                    (km):  11.479807

#### Restrictions

       1) This routine assumes that the origin of the body-fixed reference
          frame associated with the target body is located in the interior
          of that body.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman   (JPL)
       J.E. McLean    (JPL)

#### Version

       -CSPICE Version 2.0.0, 23-JUL-2016 (NJB)

           Bug fix: the DSK segment's surface ID code is no longer
           required to match that of the target. The segment's
           center ID must match.

           Added failed_c calls.

           Include file references have been updated.

       -Beta Version 1.3.0, 30-APR-2014 (NJB) (BVS)

           Adding missing "return" statement after chkout_c call
           in branch for bad input method string.

           Now includes dsk_proto.h.

           Last update was 07-APR-2014 (BVS)

           Changed FRAME to FRAMES in the Required_Reading section.

       -Beta Version 1.2.0, 14-MAY-2010 (NJB)

           Updated for compatibility with new DSK design.

       -Beta Version 1.1.0, 09-FEB-2007 (NJB)

           Bug fix:  type of local variable fDLADescr was changed to SpiceInt.

       -Beta Version 1.0.0, 06-NOV-2006 (NJB)

#### Index_Entries

       sub-solar point

#### Link to routine subsol_pl02 source file subsol_pl02.c

    Wed Apr  5 17:54:45 2017