tangpt_c |

Table of contents## Proceduretangpt_c ( Ray-ellipsoid tangent point ) void tangpt_c ( ConstSpiceChar * method, ConstSpiceChar * target, SpiceDouble et, ConstSpiceChar * fixref, ConstSpiceChar * abcorr, ConstSpiceChar * corloc, ConstSpiceChar * obsrvr, ConstSpiceChar * dref, ConstSpiceDouble dvec [3], SpiceDouble tanpt [3], SpiceDouble * alt, SpiceDouble * range, SpiceDouble srfpt [3], SpiceDouble * trgepc, SpiceDouble srfvec [3] ) ## AbstractCompute, for a given observer, ray emanating from the observer, and target, the "tangent point": the point on the ray nearest to the target's surface. Also compute the point on the target's surface nearest to the tangent point. The locations of both points are optionally corrected for light time and stellar aberration. The surface shape is modeled as a triaxial ellipsoid. ## Required_ReadingABCORR CK FRAMES NAIF_IDS PCK SCLK SPK TIME ## KeywordsELLIPSOID GEOMETRY RAY ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- method I Computation method. target I Name of target body. et I Epoch in ephemeris seconds past J2000 TDB. fixref I Body-fixed, body-centered target body frame. abcorr I Aberration correction. corloc I Aberration correction locus: "TANGENT POINT" or "SURFACE POINT". obsrvr I Name of observing body. dref I Reference frame of ray direction vector. dvec I Ray direction vector. tanpt O "Tangent point": point on ray nearest to surface. alt O Altitude of tangent point above surface. range O Distance of tangent point from observer. srfpt O Point on surface nearest to tangent point. trgepc O Epoch associated with correction locus. srfvec O Vector from observer to surface point `srfpt'. ## Detailed_Inputmethod is a short string providing parameters defining the computation method to be used. `method' is currently restricted to the value "ELLIPSOID" This value indicates that the target shape is modeled as a triaxial ellipsoid. `method' is case-insensitive, and leading and trailing blanks in `method' are not significant. 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. If the target is identified by name rather than ID code, the target name must be recognized by SPICE. Radii defining a triaxial ellipsoid target shape model must be available in the kernel pool. See the -Files section below. et is the epoch associated with the observer, expressed as ephemeris seconds past J2000 TDB. `et' is the epoch at which radiation is received by the observer, when an observation is made, or in the case of transmission from the observer, at which radiation is emitted. `et' is the epoch at which the state of the observer relative to the solar system barycenter is computed. When aberration corrections are not used, `et' is also the epoch at which the state and orientation of the target body are computed. When aberration corrections are used, 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 aberration correction locus and the observer. The sign applied to `lt' depends on the selected correction. See the descriptions of `abcorr' and `corloc' below for details. fixref is the name of a body-fixed reference frame centered on the target body. `fixref' may be any such frame supported by the SPICE system, including built-in frames (documented in frames.req) and frames defined by a loaded frame kernel (FK). The string `fixref' is case-insensitive, and leading and trailing blanks in `fixref' are not significant. The output points `tanpt' and `srfpt', and the observer-to-surface point vector `srfvec' will be expressed relative to this reference frame. abcorr indicates the aberration corrections to be applied when computing the target's position and orientation. See the description of the aberration correction locus `corloc' for further details on how aberration corrections are applied. For remote sensing applications, where the apparent tangent or surface point seen by the observer is desired, normally one of the corrections "CN+S" or "NONE" should be selected. For applications involving transmission from the observer, normally "XCN+S" or "NONE" should be selected. Light-time-only corrections can be useful for testing but generally don't accurately model geometry applicable to remote sensing observations or signal transmission. The supported options are described below. `abcorr' may be any of the following: "NONE" Compute outputs without applying aberration corrections. "NONE" may be suitable when the magnitudes of the aberration corrections are negligible. Let `lt' represent the one-way light time between the observer and the aberration correction locus specified by `corloc'. The following values of `abcorr' apply to the "reception" case in which radiation departs from the aberration correction locus at the light-time corrected epoch et-lt and arrives at the observer's location at `et': "LT" Correct for one-way light time between the aberration correction locus and the observer, using a Newtonian formulation. This correction yields the position of the aberration correction locus at the moment it emitted radiation 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 several iterations but does not guarantee convergence. 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 aberration correction locus solution obtained with the "LT" option to account for the observer's velocity relative to the solar system barycenter. These corrections yield the apparent aberration correction locus. "CN" Converged Newtonian light time correction. In solving the light time equation, the "CN" correction iterates until either the solution converges or a large iteration limit is reached. Both the position and orientation 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 some cases this routine will execute more slowly when a converged solution is computed. For reception-case applications where aberration corrections are applied, this option should be used, unless the magnitudes of the corrections are negligible. The following values of `abcorr' apply to the "transmission" case in which radiation *departs* from the observer's location at `et' and arrives at the aberration correction locus at the light-time corrected epoch et+lt: "XLT" "Transmission" case: correct for one-way light time between the aberration correction locus and the observer, using a Newtonian formulation. This correction yields the position of the aberration correction locus at the moment it receives radiation 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 "XLT" option uses several iterations but does not guarantee convergence. 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 aberration correction locus solution obtained with the "XLT" option to account for the observer's velocity relative to the solar system barycenter. Stellar aberration is computed for transmitted, rather than received, radiation. These corrections yield the analog for the transmission case of the apparent aberration correction locus. "XCN" "Transmission" case: converged Newtonian light time correction. In solving the light time equation, the "XCN" correction iterates until either the solution converges or a large iteration limit is reached. Both the position and rotation of the target body are corrected for light time. "XCN+S" "Transmission" case: converged Newtonian light time and stellar aberration corrections. This option produces a solution that is at least as accurate at that obtainable with the "XLT+S" option. Whether the "XCN+S" solution is substantially more accurate depends on the geometry of the participating objects and on the accuracy of the input data. In some cases this routine will execute more slowly when a converged solution is computed. For transmission-case applications where aberration corrections are applied, this option should be used, unless the magnitudes of the corrections are negligible. Case and embedded blanks are not significant in `abcorr'. For example, the string "Cn + s" is valid. corloc specifies the aberration correction "locus," which is the fixed point in the frame designated by `fixref' for which light time and stellar aberration corrections are computed. Differential aberration effects across the surface of the target body are not considered by this routine. When aberration corrections are used, the effective positions of the observer and target, and the orientation of the target, are computed according to the corrections determined for the aberration correction locus. The light time used to determine the position and orientation of the target body is that between the aberration correction locus and the observer. The stellar aberration correction applied to the position of the target is that computed for the aberration correction locus. The descriptions below apply only when aberration corrections are used. The values and meanings of `corloc' are: "TANGENT POINT" Compute corrections at the "tangent point," which is the point on the ray, defined by `dref' and `dvec', nearest to the target's surface. "SURFACE POINT" Compute corrections at the point on the target's surface nearest to the tangent point. Case and leading and trailing blanks are not significant in `corloc'. obsrvr is the name of the observing body. This is typically a spacecraft or a surface point on an extended ephemeris object. `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 "MOON" and "301" are legitimate strings that indicate the Moon is the observer. If the observer is identified by name rather than ID code, the observer name must be recognized by SPICE. See the -Files section below. dref is the name of the reference frame relative to which the ray direction vector is expressed. This may be any frame supported by the SPICE system, including built-in frames (documented in the Frames Required Reading) and frames defined by a loaded frame kernel (FK). The string `dref' is case-insensitive, and leading and trailing blanks in `dref' are not significant. When `dref' designates a non-inertial frame, the orientation of the frame is evaluated at an epoch dependent on the frame's center and, if the center is not the observer, on the selected aberration correction. See the description of the direction vector `dvec' for details. dvec is a ray direction vector emanating from the observer. The tangent point on the ray and the point on the target body's surface nearest to the tangent point are sought. `dvec' is specified relative to the reference frame designated by `dref'. Non-inertial reference frames are treated as follows: if the center of the frame is at the observer's location, the frame's orientation is evaluated at `et'. If the frame's center is located elsewhere, then letting `ltcent' be the one-way light time between the observer and the central body associated with the frame, the orientation of the frame is evaluated at et-ltcent, et+ltcent, or `et' depending on whether the requested aberration correction is, respectively, for received radiation, transmitted radiation, or is omitted. `ltcent' is computed using the method indicated by `abcorr'. ## Detailed_Outputtanpt is the "tangent point": the point on the ray defined by `dref' and `dvec' nearest to the target body's surface. `tanpt' is a vector originating at the target body's center, expressed in the reference frame designated by `fixref', the orientation of which is evaluated at `trgepc' (see description below). Units are km. If the ray intersects the surface, `tanpt' is the nearest point of intersection to the observer. If the ray points away from the surface---that is, if the angle between the ray and the outward normal at the target surface point nearest to the observer, computed using the specified aberration corrections, is less than or equal to 90 degrees---then `tanpt' is set to the position of the observer relative to the target center. `tanpt' is computed using the aberration corrections specified by `abcorr' and `corloc'. When the aberration correction locus is set to "TANGENT POINT", and the position of `tanpt' is corrected for aberration as specified by `abcorr', the resulting point will lie on the input ray. alt is the altitude of the tangent point above the target body's surface. This is the distance between `tanpt' and `srfpt'. Units are km. If the ray intersects the surface, `alt' is set to the exact double precision value 0.0. `alt' may be used as an indicator of whether a ray-surface intersection exists. range is the distance between the observer and the tangent point. Units are km. If the ray points away from the surface (see the description of `tanpt' above), `range' is set to the exact double precision value 0.0. `range' may be used as an indicator of whether this geometric condition exists. srfpt is the point on the target body's surface nearest to the tangent point. `srfpt' is a vector originating at the target body's center, expressed in the reference frame designated by `fixref', the orientation of which is evaluated at `trgepc' (see description below). Units are km. `srfpt' is computed using the aberration corrections specified by `abcorr' and `corloc'. When the aberration correction locus is set to "SURFACE POINT", and the position of `srfpt' is corrected for aberration as specified by `abcorr', the resulting point will lie on the ray emanating from the observer and pointing in the direction of `srfvec'. If the ray intersects the surface, `srfpt' is the point of intersection nearest to the observer. If the ray points away from the surface (see the description of `tanpt' above), `srfpt' is set to the target surface point nearest to the observer. trgepc is the epoch associated with the aberration correction locus. `trgepc' is defined as follows: letting `lt' be the one-way light time between the observer and the aberration correction locus, `trgepc' is the epoch et-lt, et+lt, or `et' depending on whether the requested aberration correction is, respectively, for received radiation, transmitted radiation, or omitted. `lt' is computed using the method indicated by `abcorr'. `trgepc' is expressed as seconds past J2000 TDB. The name `trgepc', which stands for "target epoch," is used for compatibility with other SPICE high-level geometry routines. Note that the epoch it designates is not associated with the target body's center. srfvec is the vector from the observer's position at `et' to the surface point `srfpt', where the position of `srfpt' is corrected for aberrations as specified by `abcorr' and `corloc'. `srfvec' is expressed in the target body-fixed reference frame designated by `fixref', evaluated at `trgepc'. Units are km. One can use the CSPICE function vnorm_c to obtain the distance between the observer and `srfpt': 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' and `corloc', can be computed via the call: vsub_c ( srfpt, srfvec, obspos ); To transform the vector `srfvec' from the 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 ); ## ParametersNone. ## Exceptions1) If the specified aberration correction is unrecognized, an error is signaled by a routine in the call tree of this routine. 2) If `method' is not equivalent to "ELLIPSOID", when case and blanks are ignored in the comparison, the error SPICE(NOTSUPPORTED) is signaled by a routine in the call tree of this routine. 3) If `corloc' is not equivalent to either "TANGENT POINT" or "SURFACE POINT", when case and blanks are ignored, the error SPICE(NOTSUPPORTED) is signaled by a routine in the call tree of this routine. 4) If the direction vector `dvec' is the zero vector, the error SPICE(ZEROVECTOR) is signaled by a routine in the call tree of this routine. 5) If either the target or observer input strings cannot be converted to an integer ID code, the error SPICE(IDCODENOTFOUND) is signaled by a routine in the call tree of this routine. 6) If `obsrvr' and `target' map to the same NAIF integer ID code, the error SPICE(BODIESNOTDISTINCT) is signaled by a routine in the call tree of this routine. 7) If triaxial radii of the target body have not been loaded into the kernel pool prior to a call to this routine, an error is signaled by a routine in the call tree of this routine. 8) If the number of radii associated with the target body is not three, the error SPICE(INVALIDCOUNT) is signaled by a routine in the call tree of this routine. 9) If the input target body-fixed frame `fixref' is not recognized, the error SPICE(NOFRAME) is signaled by a routine in the call tree of this routine. A frame name may fail to be recognized because a required frame specification kernel has not been loaded; another cause is a misspelling of the frame name. 10) If the input frame `fixref' is not centered at the target body, the error SPICE(INVALIDFRAME) is signaled by a routine in the call tree of this routine. 11) If the reference frame designated by `dref' is not recognized by the SPICE frame subsystem, the error SPICE(NOFRAME) is signaled by a routine in the call tree of this routine. 12) If insufficient ephemeris data have been loaded prior to calling ## FilesAppropriate kernels must be loaded by the calling program before this routine is called. 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. - Target orientation data: rotation data for the target body must be loaded. These may be provided in a text or binary PCK file, or by a CK file. The following data may be required: - SPK data: if aberration corrections are used, and if the ray frame `dref' is non-inertial, ephemeris data for that frame's center must be loaded. The state of that object relative to the solar system barycenter must be calculable from the available ephemeris data. - Frame specifications: 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. Similarly, the frame definition required to map between the frame designated by `dref' and the target body-fixed frame must be available. Typically the definitions of frames not already built-in to SPICE are supplied by loading a frame kernel. - Ray frame orientation data: if the frame to which `dref' refers is non-inertial, PCK or CK data for the frame's orientation are required. If the frame is fixed to a spacecraft instrument or structure, at least one CK file will be needed to permit transformation of vectors between that frame and both the J2000 and the target body-fixed frames. - Ray direction data: if the ray direction is defined by a vector expressed in a spacecraft reference frame, an IK may be required to provide the coordinates of the ray's direction in that frame. - SCLK data: if a CK file is needed, an associated SCLK kernel is required to enable conversion between encoded SCLK (used to time-tag CK data) and barycentric dynamical time (TDB). - Leapseconds data: if SCLK data are needed, a leapseconds kernel usually is needed as well. - Body name-ID mappings: if the target or observer name is not built into the SPICE software, the mapping between the name and the corresponding ID code must be present in the kernel pool. Such mappings are usually introduced by loading a frame kernel or other text kernel containing them. In all cases, kernel data are normally loaded once per program run, NOT every time this routine is called. ## ParticularsGiven an observer, the direction vector of a ray emanating from the observer, and an extended target body represented by a triaxial ellipsoid, ## ExamplesThe numerical results shown for these examples 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) The following program computes tangent and surface points for the MAVEN IUVS instrument. The observer is the MAVEN spacecraft; the target body is Mars. The ray direction is that of the boresight of the MAVEN IUVS instrument. The aberration corrections used in this example are often suitable for remote sensing observations: converged Newtonian light time and stellar aberration "reception" corrections. In some cases it is reasonable to omit aberration corrections; see the second and third example programs below for demonstrations of the effects of different aberration correction choices. In this example, the aberration correction locus is the tangent point, meaning that converged light time and stellar aberration corrections are computed for that point. The epoch `trgepc' is used to compute the light time-corrected target position and orientation, and the stellar aberration correction applicable to the tangent point is applied to the observer-target position vector, in order to model apparent observation geometry. Three geometric cases are covered by this example: - The "normal" case, in which the ray defined by the MAVEN IUVS boresight passes over Mars at low altitude. In the example code, there are two computations that fall into this category. - The "intercept" case, in which the ray intersects Mars. - The "look away" case, in which the elevation of the ray's direction vector, measured from the local level plane at the sub-spacecraft point, is greater than or equal to 0. The aberration corrections used to compute the sub-observer point for this case are those applicable to the aberration correction locus. Use the meta-kernel shown below to load the required SPICE kernels. KPL/MK File name: tangpt_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. All kernels referenced by this meta-kernel are available from the MAVEN SPICE PDS archive. The names and contents of the kernels referenced by this meta-kernel are as follows: File name Contents --------- -------- mar097s.bsp Mars satellite ephemeris maven_iuvs_v11.ti MAVEN IUVS instrument information maven_orb_rec_201001_210101_v1.bsp MAVEN s/c ephemeris mvn_v09.tf MAVEN frame specifications mvn_app_rel_201005_201011_v01.bc MAVEN Articulated Payload Platform attitude mvn_iuvs_rem_201001_201231_v01.bc MAVEN IUVS instrument internal mirror attitude mvn_sc_rel_201005_201011_v01.bc MAVEN s/c attitude mvn_sclkscet_00086.tsc MAVEN SCLK coefficients naif0012.tls Leapseconds pck00010.tpc Planet and satellite orientation and radii \begindata KERNELS_TO_LOAD = ( 'mar097s.bsp', 'maven_iuvs_v11.ti', 'maven_orb_rec_201001_210101_v1.bsp', 'maven_v09.tf', 'mvn_app_rel_201005_201011_v01.bc', 'mvn_iuvs_rem_201001_201231_v01.bc', 'mvn_sc_rel_201005_201011_v01.bc', 'mvn_sclkscet_00086.tsc', 'naif0012.tls', 'pck00010.tpc' ) \begintext End of meta-kernel Example code begins here. /. Program tangpt_ex1 ./ #include <stdio.h> #include <string.h> #include "SpiceUsr.h" int main( ) { /. Parameters ./ #define META "tangpt_ex1.tm" #define TIMFMT "YYYY-MM-DD HR:MN:SC.###### UTC ::RND" #define FRNMLN 33 #define LNSIZE 73 #define NCASE 3 #define NTIMES 4 #define ROOM 12 #define SHPLEN 26 #define TIMLEN 36 /. Local variables ./ SpiceChar * abcorr; SpiceChar casenm [LNSIZE]; SpiceChar fixref [FRNMLN]; SpiceChar * locus; SpiceChar * obsrvr; SpiceChar rayfrm [FRNMLN]; SpiceChar shape [SHPLEN]; SpiceChar * target; SpiceChar timstr [TIMLEN]; SpiceDouble alt; SpiceDouble bounds [ROOM][3]; SpiceDouble et; SpiceDouble range; SpiceDouble raydir [3]; SpiceDouble srfpt [3]; SpiceDouble srfvec [3]; SpiceDouble tanpt [3]; SpiceDouble trgepc; SpiceInt i; SpiceInt nvec; /. Initial values ./ SpiceChar cases [NCASE][LNSIZE] = { "Ray slightly above limb", "Intercept", "Look-away" }; SpiceChar * insnam = "MAVEN_IUVS"; SpiceChar utctim [NTIMES][TIMLEN] = { "2020-10-11 16:01:43.000000 UTC", "2020-10-11 16:17:43.000000 UTC", "2020-10-11 16:49:07.000000 UTC", "2020-10-11 17:12:08.000000 UTC" }; /. Load kernels. ./ furnsh_c ( META ); printf( "\n" ); printf( "Instrument: %s\n", insnam ); printf( "\n" ); /. Get the instrument reference frame name and the instrument boresight direction in the instrument frame. ./ getfvn_c ( insnam, ROOM, SHPLEN, FRNMLN, shape, rayfrm, raydir, &nvec, bounds ); /. Initialize inputs to ## Restrictions1) This routine is applicable only to computations for which radiation paths can be modeled as straight lines. 2) This routine does not account for differential aberration corrections across the target body surface: when aberration corrections are used, the entire target ellipsoid's position and orientation are modified by the corrections that apply at the aberration correction locus. 3) A cautionary note: if aberration corrections are used, and if `dref' is the target body-fixed frame, the epoch at which that frame is evaluated is offset from `et' by the light time between the observer and the *center* of the target body. This light time normally will differ from the light time between the observer and the tangent or surface point. Consequently the orientation of the target body-fixed frame at `trgepc' will not match that of the target body-fixed frame at the epoch associated with `dref'. As a result, various derived quantities may not be as expected: for example, `srfvec' would not be parallel to `dvec'. In many applications the errors arising from this frame discrepancy may be insignificant; however a safe approach is to always use as `dref' a frame other than the target body-fixed frame. ## Literature_ReferencesNone. ## Author_and_InstitutionM. Costa Sitja (JPL) ## Version-CSPICE Version 1.0.0, 28-OCT-2021 (MCS) ## Index_Entriesfind ray-ellipsoid tangent point find nearest point to ray on ellipsoid |

Fri Dec 31 18:41:14 2021