illum_plid_pl02 |

Table of contents## Procedureillum_plid_pl02 (illumination angles using type 2 DSK) void illum_plid_pl02 ( SpiceInt handle, ConstSpiceDLADescr * dladsc, ConstSpiceChar * target, SpiceDouble et, ConstSpiceChar * abcorr, ConstSpiceChar * obsrvr, SpiceDouble spoint [3], SpiceInt plid, SpiceDouble * trgepc, SpiceDouble srfvec [3], SpiceDouble * phase, SpiceDouble * solar, SpiceDouble * emissn, SpiceBoolean * visible, SpiceBoolean * lit ) ## AbstractDeprecated: This routine has been superseded by the CSPICE routine illumf_c. This routine is supported for purposes of backward compatibility only. Compute the illumination angles---phase, solar incidence, and emission---at a specified point on a target body at a particular epoch, optionally corrected for light time and stellar aberration. Return logical flags indicating whether the surface point is shadowed or occulted by the target body. The target body's surface is represented by a triangular plate model contained in a type 2 DSK segment. The ID of the plate on which the point is located must be provided by the caller. ## Required_ReadingFRAMES PCK SPK TIME ## KeywordsGEOMETRY ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- handle I DSK handle. dladsc I DLA descriptor of target body segment. 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 I Body-fixed coordinates of a target surface point. plid I ID of plate on which surface point is located. trgepc O Target surface point epoch. srfvec O Vector from observer to target surface point. phase O Phase angle at the surface point. solar O Solar incidence angle at the surface point. emissn O Emission angle at the surface point. visible O Visibility flag (SPICETRUE = visible). lit O Illumination flag (SPICETRUE = illuminated). ## Detailed_Inputhandle 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. 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 using 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 illumination angles are 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 that the illumination angles are 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. spoint is a surface point on the target body, expressed in rectangular body-fixed (body equator and prime meridian) coordinates. `spoint' need not be visible from the observer's location at time `et'. plid is the integer ID of the plate on which `spoint' is located. If `spoint' was found by calling any of the routines dskx02_c subpt_pl02 subsol_pl02 `plid' is the plate ID returned by the called routine. ## Detailed_OutputAll outputs are computed using the body-fixed, body-centered reference frame of the DSK segment identified by `handle' and `dladsc'. This frame is referred to below as `fixref'. The frame ID of `fixref' may be obtained by calling dskgd_c, as is shown in the Examples section below. The orientation of the frame `fixref' is evaluated at the epoch `trgepc'. trgepc is the "surface point epoch." `trgepc' is defined as follows: letting `lt' be the one-way light time between the observer and the input surface point `spoint', `trgepc' is either the epoch et-lt or `et' depending on whether the requested aberration correction is, respectively, for received radiation or omitted. `lt' is computed using the method indicated by `abcorr'. `trgepc' is expressed as seconds past J2000 TDB. srfvec is the vector from the observer's position at `et' to the aberration-corrected (or optionally, geometric) position of `spoint', where the aberration corrections are specified by `abcorr'. `srfvec' is expressed in the target body-fixed reference frame designated by `fixref', evaluated at `trgepc'. The components of `srfvec' are given in units of km. One can use the CSPICE function vnorm_c to obtain the distance between the observer and `spoint': dist = vnorm_c ( srfvec ); The observer's position `obspos', relative to the target body's center, where the center's position is corrected for aberration effects as indicated by `abcorr', can be computed via the call: vsub_c ( spoint, srfvec, obspos ); To transform the vector `srfvec' from a reference frame `fixref' at time `trgepc' to a time-dependent reference frame `ref' at time `et', the routine pxfrm2_c should be called. Let `xform' be the 3x3 matrix representing the rotation from the reference frame `fixref' at time `trgepc' to the reference frame `ref' at time `et'. Then `srfvec' can be transformed to the result `refvec' as follows: pxfrm2_c ( fixref, ref, trgepc, et, xform ); mxv_c ( xform, srfvec, refvec ); phase is the phase angle at `spoint', as seen from `obsrvr' at time `et'. This is the angle between the spoint-obsrvr vector and the spoint-sun vector. Units are radians. The range of `phase' is [0, pi]. solar is the solar incidence angle at `spoint', as seen from `obsrvr' at time `et'. This is the angle between the surface normal vector at `spoint' and the spoint-sun vector. Units are radians. The range of `solar' is [0, pi]. Note that if the target surface is non-convex, a solar incidence angle less than pi/2 radians does not imply the surface point is illuminated. See the description of `lit' below. emissn is the emission angle at `spoint', as seen from `obsrvr' at time `et'. This is the angle between the surface normal vector at `spoint' and the spoint-observer vector. Units are radians. The range of `emissn' is is [0, pi]. See Particulars below for a detailed discussion of the definitions of these angles. Note that if the target surface is non-convex, an emission angle less than pi/2 radians does not imply the surface point is visible to the observer. See the description of `visible' below. visible is a logical flag indicating whether the surface point is visible to the observer. `visible' takes into account whether the target surface occults `spoint', regardless of the emission angle at `spoint'. `visible' is returned with the value SPICETRUE if `spoint' is visible; otherwise it is SPICEFALSE. lit is a logical flag indicating whether the surface point is illuminated; the point is considered to be illuminated if the vector from the point to the center of the sun doesn't intersect the target surface. `lit' takes into account whether the target surface casts a shadow on `spoint', regardless of the solar incidence angle at `spoint'. `lit' is returned with the value SPICETRUE if `spoint' is illuminated; otherwise it is SPICEFALSE. ## ParametersNone. ## ExceptionsIf any of the listed errors occur, the output arguments are left unchanged. 1) If `plid' is not a valid plate ID, an error is signaled by a routine in the call tree of this routine. 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 the target body-fixed frame have not been loaded prior to calling ## FilesAppropriate 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: 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. ## ParticularsThe term "illumination angles" refers to following set of angles: solar incidence angle Angle between the surface normal at the specified surface point and the vector from the surface point to the Sun. emission angle Angle between the surface normal at the specified surface point and the vector from the surface point to the observer. phase angle Angle between the vectors from the surface point to the observing body and from the surface point to the Sun. The diagram below illustrates the geometric relationships defining these angles. The labels for the solar incidence, emission, and phase angles are "s.i.", "e.", and "phase". * Sun surface normal vector ._ _. |\ /| Sun vector \ phase / \ . . / . . \ ___ / . \/ \/ _\ s.i./ . / \ / . | e. \ / * <--------------- * surface point on viewing vector target body location to viewing (observer) location Note that if the target-observer vector, the target normal vector at the surface point, and the target-sun vector are coplanar, then phase is the sum of incidence and emission. This is rarely true; usually phase angle < solar incidence angle + emission angle All of the above angles can be computed using light time corrections, light time and stellar aberration corrections, or no aberration corrections. The way aberration corrections are used is described below. Care must be used in computing light time corrections. The guiding principle used here is "describe what appears in an image." Observer-target body surface point vector ----------------------------------------- Let `et' be the epoch at which an observation or remote sensing measurement is made, and let et - lt ("lt" stands for "light time") be the epoch at which the photons received at `et' were emitted from the body (we use the term "emitted" loosely here). The correct observer-target vector points from the observer's location at `et' to the surface point location at et - lt. The target-observer vector points in the opposite direction. Since light time corrections are not anti-symmetric, the correct target-observer vector CANNOT be found by negating the light time corrected position of the observer as seen from the target body. Target body's orientation ------------------------- Using the definitions of `et' and `lt' above, the target body's orientation at et-lt is used. The surface normal is dependent on the target body's orientation, so the body's orientation model must be evaluated for the correct epoch. Target body -- Sun vector ------------------------- All surface features on the target body will appear in a measurement made at `et' as they were at the target at epoch et-lt. In particular, lighting on the target body is dependent on the apparent location of the Sun as seen from the target body at et-lt. So, a second light time correction is used in finding the apparent location of the Sun. Stellar aberration corrections, when used, are applied as follows: Observer-target body vector --------------------------- In addition to light time correction, stellar aberration is used in computing the apparent target surface point position as seen from the observer's location at time `et'. This apparent position defines the observer-target surface point vector. Target body-Sun vector ---------------------- The target body-Sun vector is the apparent position of the Sun, corrected for light time and stellar aberration, as seen from the target body at time et-lt. Note that the target body's position is not affected by the stellar aberration correction applied in finding its apparent position as seen by the observer. Once all of the vectors, as well as the target body's orientation, have been computed with the proper aberration corrections, the element of time is eliminated from the computation. The problem becomes a purely geometric one and is described by the diagram above. ## ExamplesThe 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. 1) Find the illumination angles at both the sub-observer point and sub-solar point on Phobos as seen from Mars for a specified sequence of times. Perform each computation twice, using both the "intercept" and "ellipsoid near point" options for the sub-observer point and sub-solar point computations. Compute the corresponding illumination angles using an ellipsoidal surface for comparison. (Note that the surface points on the plate model generally will not lie on the ellipsoid's surface, so the emission and solar incidence angles won't generally be zero at the sub-observer and sub-solar points, respectively.) Use the meta-kernel shown below to load the required SPICE kernels. KPL/MK File: illum_plid_pl02_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 --------- -------- mar097.bsp Mars satellite ephemeris pck00010.tpc Planet orientation and radii naif0010.tls Leapseconds \begindata KERNELS_TO_LOAD = ( 'mar097.bsp', 'pck00010.tpc', 'naif0010.tls' ) \begintext End of meta-kernel Use the DSK kernel below to provide the plate model representation of the surface of Phobos. phobos_3_3.bds Example code begins here. /. Program illum_plid_pl02_ex1 Find the illumination angles at both the sub-observer point and sub-solar point on Phobos as seen from Mars for a specified sequence of times. Perform each computation twice, using both the "intercept" and "ellipsoid near point" options for the sub-observer point and sub-solar point computations. Compute the corresponding illumination angles 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 #define FRNMLN 33 /. Local variables ./ SpiceBoolean found; SpiceBoolean lit; SpiceBoolean visible; SpiceChar * abcorr; SpiceChar * abcorrs[ NCORR ] = { "NONE", "CN+S" }; SpiceChar dsk [ FILSIZ ]; SpiceChar * emethod; SpiceChar * emethods[ NMETHOD ] = { "Intercept", "Near point" }; SpiceChar fixref [ FRNMLN ]; SpiceChar meta [ FILSIZ ]; SpiceChar * method; SpiceChar * methods [ NMETHOD ] = { "Intercept", "Ellipsoid near point" }; SpiceChar * obsrvr = "Mars"; SpiceChar * target = "Phobos"; SpiceChar timstr [ TIMLEN ]; SpiceDLADescr dladsc; SpiceDSKDescr dskdsc; SpiceDouble alt; SpiceDouble dist; SpiceDouble emissn; SpiceDouble esrfvc [3]; SpiceDouble et0; SpiceDouble etrgep; SpiceDouble et; SpiceDouble phase; SpiceDouble solar; SpiceDouble srfvec [3]; SpiceDouble stepsize; SpiceDouble trgepc; SpiceDouble xlat; SpiceDouble xlon; SpiceDouble xpt [3]; SpiceDouble xr; SpiceInt coridx; SpiceInt handle; SpiceInt i; SpiceInt midx; 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 ); /. 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. Get the DSK descriptor of the segment; from this descriptor we can obtain the ID of body-fixed frame associated with the segment. We'll need this frame later to compute illumination angles on the target body's reference ellipsoid. ./ dskgd_c ( handle, &dladsc, &dskdsc ); frmnam_c ( dskdsc.frmcde, FRNMLN, fixref ); if ( eqstr_c(fixref, " ") ) { setmsg_c ( "Frame ID code # could not be mapped to " "a frame name." ); errint_c ( "#", dskdsc.frmcde ); sigerr_c ( "SPICE(UNKNOWNFRAME)" ); } /. Now compute sub-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-observer point using a plate model representation of the target's surface. ./ subpt_pl02 ( handle, &dladsc, method, target, et, abcorr, obsrvr, xpt, &alt, &plid ); /. Compute the illumination angles at the sub-observer point. Also compute the light-of-sight visibility and shadowing flags. ./ ## Restrictions1) The solar illumination state indicated by the output argument `lit' is computed treating the sun as a point light source. Surface points that are illuminated by part of the sun's disc are classified as "lit" or not depending on whether the center of the sun is visible from those points. ## Literature_ReferencesNone. ## Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) ## Version-CSPICE Version 1.1.0, 26-OCT-2021 (JDR) (NJB) Bug fix: call to ljust_ is now followed by call to F2C_ConvertStr. Edited the Examples section to comply with NAIF standard. Fixed printf statements on example code as they violated ANSI-C 89 standard maximum string literal length of 509 characters. Index lines now state that this routine is deprecated. -CSPICE Version 1.0.0, 22-FEB-2017 (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. Include file references have been updated. Added failed_c calls. 02-SEP-2014 (NJB) Based on illum_pl02 Beta Version 1.3.0, 30-APR-2014 (NJB) (BVS) ## Index_EntriesDEPRECATED plate model point visibility and shadowing DEPRECATED illumination angles using DSK type 2 plate model DEPRECATED lighting angles using DSK type 2 plate model DEPRECATED phase angle using DSK type 2 plate model DEPRECATED emission angle using DSK type 2 plate model DEPRECATED solar incidence angle using DSK type 2 |

Fri Dec 31 18:41:08 2021