cspice_term_pl02 |
|||

## AbstractDeprecated: This routine has been superseded by the CSPICE routine cspice_termpt. This routine is supported for purposes of backward compatibility only. CSPICE_TERM_PL02 computes a set of points on the umbral or penumbral terminator of a specified target body, where the target body's surface is represented by a triangular plate model contained in a type 2 DSK segment. ## I/OGiven: handle 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. [1,1] = size(handle); int32 = class(handle) dladsc the DLA descriptor of a DSK segment representing the surface of a target body. [SPICE_DLA_DSCSIZ,1] = size(dladsc) int32 = class(dladsc) trmtyp a string indicating the type of terminator to compute: umbral or penumbral. The umbral terminator is the boundary of the portion of the target surface in total shadow. The penumbral terminator is the boundary of the portion of the surface that is completely illuminated. Note that in astronomy references, the unqualified word "terminator" refers to the umbral terminator. Here, the unqualified word refers to either type of terminator. [1,c1] = size(trmtyp); char = class(trmtyp) or [1,1] = size(trmtyp); cell = class(trmtyp) To compute the terminator points, this routine first computes a set of points on the terminator of the indicated type on the surface of a reference ellipsoid for the target body. Each such point defines the direction of a ray emanating from the target center and associated with a terminator point on the actual surface defined by the plate model. The outermost surface intercept of each such ray is a considered to be a terminator point of the surface defined by the plate model. Possible values of `trmtyp' are 'UMBRAL' 'PENUMBRAL' Case and leading or trailing blanks in `trmtyp' are not significant. source the name of the body acting as a light source. `source' 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 'SUN' and '10' are legitimate strings that indicate the Sun is the light source. [1,c2] = size(source); char = class(source) or [1,1] = size(source); cell = class(source) This routine assumes that a kernel variable representing the light source's radii is present in the kernel pool. Normally the kernel variable would be defined by loading a PCK file. The shape of the light source is always modeled as a sphere, regardless of whether radii defining a triaxial ellipsoidal shape model are available in the kernel pool. The maximum radius of the body is used as the radius of the sphere. target 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. [1,c3] = size(target); char = class(target) or [1,1] = size(target); cell = class(target) This routine assumes that a kernel variable representing the target's radii is present in the kernel pool. Normally the kernel variable would be defined by loading a PCK file. et the epoch of participation of the observer, expressed as ephemeris seconds past J2000 TDB: `et' is the epoch at which the observer's position is computed. [1,1] = 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 and position of the light source are computed. When aberration corrections are used, `et' is the epoch at which the observer's position 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 target body's center and the observer, and the sign applied to `lt' depends on the selected correction. See the description of `abcorr' below for details. fixfrm the name of the reference frame relative to which the output terminator points are expressed. This must a body-centered, body-fixed frame associated with the target. The frame's axes must be compatible with the triaxial ellipsoidal shape model associated with the target body (normally provide via a PCK): this routine assumes that the first, second, and third axis lengths correspond, respectively, to the x, y, and z-axes of the frame designated by `fixfrm'. [1,c4] = size(fixfrm); char = class(fixfrm) or [1,1] = size(fixfrm); cell = class(fixfrm) `fixfrm' may refer to a built-in frame (documented in the Frames Required Reading) or a frame defined by a loaded frame kernel (FK). The orientation of the frame designated by `fixfrm' is evaluated at epoch of participation of the target body. See the descriptions of `et' and `abcorr' for details. abcorr indicates the aberration correction to be applied when computing the observer-target position, the orientation of the target body, and the target- source position vector. [1,c5] = size(abcorr); char = class(abcorr) or [1,1] = size(abcorr); cell = class(abcorr) `abcorr' may be any of the following. 'NONE' Apply no correction. Compute the terminator points using the position of the light source and target, and the orientation of the target, at `et'. Let `lt' represent the one-way light time 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 target body's center 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 the terminator points at the approximate time they emitted photons arriving at the observer at `et' (the difference between light time to the target center and light time to the terminator points is ignored). The light time correction uses an iterative solution of the light time equation. The solution invoked by the 'LT' option uses one iteration. The target position as seen by the observer, the position of the light source as seen from the target at et-lt, and the 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 positions obtained with the 'LT' option to account for the observer's velocity relative to the solar system barycenter. This correction also applies to the position of the light source relative to the target. The result is the apparent terminator 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. The position and rotation of the target body and the position of the light source relative to the target are corrected for light time. 'CN+S' Converged Newtonian light time and stellar aberration corrections. obsrvr 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. [1,c6] = size(obsrvr); char = class(obsrvr) or [1,1] = size(obsrvr); cell = class(obsrvr) npoints the number of terminator points to compute. the call: [trgepc, obspos, termpts, plateids] = ... ## ExamplesAny 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. Compute sets of umbral and penumbral terminator points on Phobos as seen from Mars. Perform a consistency check using the solar incidence angle at each point, where the solar incidence angle is computed using both a reference ellipsoid and the actual plate model surface and surface normal. We expect to see a solar incidence angle of approximately 90 degrees. Since the solar incidence angle is measured between the local outward normal and the direction to the Sun, the solar incidence angle at an umbral or penumbral terminator point should be, respectively, greater than or less than 90 degrees by approximately the angular radius of the Sun as seen from each terminator point. In the following example program, the file phobos_3_3.dsk is a DSK file containing a type 2 segment that provides a plate model representation of the surface of Phobos. The file mar097.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. pck00010.tpc is a planetary constants kernel file containing radii and rotation model constants. naif0010.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: KPL/MK \begindata KERNELS_TO_LOAD = ( 'naif0010.tls' 'pck00010.tpc' 'mar097.bsp' ) \begintext function term_pl02_t % % Constants % NPOINTS = 3; NTYPES = 2; TIMLEN = 40; ILUM_METHOD = 'ELLIPSOID'; TOL = 1.d-12; UTCSTR = '2007 FEB 9 00:00:00 UTC'; % % Initial values % target = 'Phobos'; fixfrm = 'IAU_PHOBOS'; abcorr = 'CN+S'; fixfrm = 'IAU_PHOBOS'; obsrvr = 'Mars'; trmtypes = { 'Umbral', 'Penumbral' }; utcstr = '2007 FEB 9 00:00:00 UTC'; % % Prompt for the name of a meta-kernel specifying % all of the other kernels we need. Load the % metakernel. % meta = input( 'Enter meta-kernel name > ','s'); cspice_furnsh( meta ) % % Prompt for the name of a DSK file. % dsk = input( 'Enter DSK name > ','s'); % % Open the DSK file for read access. % We use the DAS-level interface for % this function. % handle = cspice_dasopr( dsk ); % % Begin a forward search through the % kernel, treating the file as a DLA. % In this example, it's a very short % search. % [dladsc, found] = cspice_dlabfs( handle ); if ~found % % We arrive here only if the kernel % contains no segments. This is % unexpected, but we're prepared for it. % fprintf( 'No segments found in DSK file %s\n', dsk ) return end % % If we made it this far, `dladsc' is the % DLA descriptor of the first segment. % % Now compute sub-points using both computation % methods. We'll vary the aberration corrections % and the epochs. % et = cspice_str2et( UTCSTR ); timstr = cspice_timout( et, ... 'YYYY-MON-DD HR:MN:SC.### ::TDB(TDB)' ); fprintf( '\n\n' ) fprintf( ' Observer: %s\n', obsrvr ) fprintf( ' Target: %s\n', target ) fprintf( ' Observation epoch: %s\n', timstr ) fprintf( ' Aberration correction: %s\n', abcorr ) fprintf( ' Body-fixed frame: %s\n', fixfrm ) % % Look up the radii of the Sun. We'll use these as % part of a computation to check the solar incidence % angles at the terminator points. % sunRadii = cspice_bodvrd( 'SUN', 'RADII', 3 ); % % Now compute grids of terminator points using both % terminator types. % for typidx = 1:NTYPES % % Select the terminator type. % trmtyp = trmtypes( typidx ); fprintf( '\n Terminator type: %s\n', char(trmtyp) ) % % Compute the terminator point set. % [trgepc, obpos, termpts, plateids] = ... ## ParticularsIn this routine, we use the term "umbral terminator" to denote the curve usually called the "terminator": this curve is the boundary of the portion of the target body's surface that lies in total shadow. We use the term "penumbral terminator" to denote the boundary of the completely illuminated portion of the surface. Boundaries of illuminated regions on an arbitrary surface are often complicated point sets: boundaries of shadows of mountains and craters, if present, all contribute to the overall set. To make the terminator computation tractable, we simplify the problem by using a reference ellipsoid for guidance. We compute a set of terminator points on the reference ellipsoid for the target body, then use those points to define the latitudes and longitudes of terminator points on the surface defined by the specified triangular shape model. As such, the set of terminator points found by this routine is just an approximation. Below we discuss the computation of terminator points on the target body's reference ellipsoid. This routine assumes a spherical light source. Light rays are assumed to travel along straight lines; refraction is not modeled. Points on the reference ellipsoid at which the entire cap of the light source is visible are considered to be completely illuminated. Points on the ellipsoid at which some portion (or all) of the cap of the light source are blocked are considered to be in partial (or total) shadow. In general, the terminator on an ellipsoid is a more complicated curve than the limb (which is always an ellipse). Aside from various special cases, the terminator does not lie in a plane. However, the condition for a point X on the ellipsoid to lie on the terminator is simple: a plane tangent to the ellipsoid at X must also be tangent to the light source. If this tangent plane does not intersect the vector from the center of the ellipsoid to the center of the light source, then X lies on the umbral terminator; otherwise X lies on the penumbral terminator. ## Required ReadingFor important details concerning this module's function, please refer to the CSPICE routine term_pl02. MICE.REQ ABCORR.REQ DSK.REQ PCK.REQ SPK.REQ TIME.REQ ## Version-Mice Version 1.0.0, 25-JUL-2016, NJB, EDW (JPL) ## Index_Entriesfind terminator on plate model find terminator on triangular shape model find terminator on dsk type_2 shape model find umbral terminator on plate model find umbral terminator on triangular shape model find umbral terminator on dsk type_2 shape model find penumbral terminator on plate model find penumbral terminator on triangular shape model find penumbral terminator on dsk type_2 shape model |

Wed Apr 5 18:00:35 2017