sincpt_c |

Table of contents## Proceduresincpt_c ( Surface intercept ) void sincpt_c ( ConstSpiceChar * method, ConstSpiceChar * target, SpiceDouble et, ConstSpiceChar * fixref, ConstSpiceChar * abcorr, ConstSpiceChar * obsrvr, ConstSpiceChar * dref, ConstSpiceDouble dvec [3], SpiceDouble spoint [3], SpiceDouble * trgepc, SpiceDouble srfvec [3], SpiceBoolean * found ) ## AbstractCompute, for a given observer and a ray emanating from the observer, the surface intercept of the ray on a target body at a specified epoch, optionally corrected for light time and stellar aberration. The surface of the target body may be represented by a triaxial ellipsoid or by topographic data provided by DSK files. This routine supersedes srfxpt_c. ## Required_ReadingCK DSK FRAMES NAIF_IDS PCK SCLK SPK TIME ## KeywordsGEOMETRY ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- method I Computation method. target I Name of target body. et I Epoch in TDB seconds past J2000 TDB. fixref I Body-fixed, body-centered target body frame. abcorr I Aberration correction flag. obsrvr I Name of observing body. dref I Reference frame of ray's direction vector. dvec I Ray's direction vector. spoint O Surface intercept point on the target body. trgepc O Intercept epoch. srfvec O Vector from observer to intercept point. found O Flag indicating whether intercept was found. ## Detailed_Inputmethod is a short string providing parameters defining the computation method to be used. In the syntax descriptions below, items delimited by brackets are optional. `method' may be assigned the following values: "ELLIPSOID" The intercept computation uses a triaxial ellipsoid to model the surface of the target body. The ellipsoid's radii must be available in the kernel pool. "DSK/UNPRIORITIZED[/SURFACES = <surface list>]" The intercept computation uses topographic data to model the surface of the target body. These data must be provided by loaded DSK files. The surface list specification is optional. The syntax of the list is <surface 1> [, <surface 2>...] If present, it indicates that data only for the listed surfaces are to be used; however, data need not be available for all surfaces in the list. If absent, loaded DSK data for any surface associated with the target body are used. The surface list may contain surface names or surface ID codes. Names containing blanks must be delimited by escaped double quotes, for example "SURFACES = \"Mars MEGDR 128 PIXEL/DEG\"" If multiple surfaces are specified, their names or IDs must be separated by commas. See the -Particulars section below for details concerning use of DSK data. Neither case nor white space are significant in `method', except within double-quoted strings. For example, the string " eLLipsoid " is valid. Within double-quoted strings, blank characters are significant, but multiple consecutive blanks are considered equivalent to a single blank. Case is not significant. So "Mars MEGDR 128 PIXEL/DEG" is equivalent to " mars megdr 128 pixel/deg " but not to "MARS MEGDR128PIXEL/DEG" 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. When the target body's surface is represented by a tri-axial ellipsoid, this routine assumes that a kernel variable representing the ellipsoid's radii is present in the kernel pool. Normally the kernel variable would be defined by loading a PCK file. et is the epoch of participation of the observer, expressed as ephemeris seconds past J2000 TDB: `et' is the epoch at which the observer's state 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 intercept point and the observer, and the sign applied to `lt' depends on the selected correction. See the description of `abcorr' 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 the Frames Required Reading) 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 intercept point `spoint' and the observer-to- intercept 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. For remote sensing applications, where the apparent surface intercept point seen by the observer is desired, normally the correction "CN+S" should be used. This and the other supported options are described below. `abcorr' may be any of the following: "NONE" Apply no correction. Return the geometric surface intercept point on the target body. Let `lt' represent the one-way light time between the observer and the surface intercept point (note: NOT 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 intercept point'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 yields the location of the surface intercept point at the moment it emitted photons 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 one iteration. 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 surface intercept obtained with the "LT" option to account for the observer's velocity relative to the solar system barycenter. These computations yield the apparent surface intercept point. "CN" Converged Newtonian light time correction. In solving the light time equation, the "CN" correction iterates until the solution converges. Both the position and rotation 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 all cases this routine will execute more slowly when a converged solution is computed. For reception-case applications involving intercepts near the target body limb, this option should be used. The following values of `abcorr' apply to the "transmission" case in which photons *depart* from the observer's location at `et' and arrive at the intercept point at the light-time corrected epoch et+lt: "XLT" "Transmission" case: correct for one-way light time using a Newtonian formulation. This correction yields the intercept location at the moment it receives photons 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 one iteration. 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 intercept obtained with the "XLT" option to account for the observer's velocity relative to the solar system barycenter. "XCN" Converged Newtonian light time correction. This is the same as "XLT" correction but with further iterations to a converged Newtonian light time solution. "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 all cases this routine will execute more slowly when a converged solution is computed. For transmission-case applications involving intercepts near the target body limb, this option should be used. Case and embedded blanks are not significant in `abcorr'. For example, the string "Cn + s" is valid. obsrvr is the name of the observing body. This is typically a spacecraft, the earth, or a surface point on the earth or on another extended object. The observer must be outside the target body. `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. dref is the name of the reference frame relative to which the ray's 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 intercept with the target body's surface of the ray defined by the observer and `dvec' is 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 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_Outputspoint is the surface intercept point on the target body of the ray defined by the observer and the direction vector. If the ray intersects the target body in multiple points, the selected intersection point is the one closest to the observer. The output argument `found' (see below) indicates whether an intercept was found. `spoint' is expressed in Cartesian coordinates, relative to the target body-fixed frame designated by `fixref'. The body-fixed target frame is evaluated at the intercept epoch `trgepc' (see description below). When light time correction is used, the duration of light travel between `spoint' to the observer is considered to be the one way light time. When both light time and stellar aberration corrections are used, `spoint' is computed such that, when the vector from the observer to `spoint' is corrected for light time and stellar aberration, the resulting vector lies on the ray defined by the observer's location and `dvec'. The components of `spoint' are given in units of km. trgepc is the "intercept epoch." `trgepc' is defined as follows: letting `lt' be the one-way light time between the observer and the intercept point, `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 TDB 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 ); The second example in the -Examples header section below presents a complete program that demonstrates this procedure. found is a logical flag indicating whether or not the ray intersects the target. If an intersection exists `found' will be returned as SPICETRUE. If the ray misses the target, `found' will be returned as SPICEFALSE. ## 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 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. 3) 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. 4) 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. 5) 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. 6) If the input argument `method' cannot be parsed, an error is signaled by either this routine or a routine in the call tree of this routine. 7) If the target and observer have distinct identities but are at the same location (for example, the target is Mars and the observer is the Mars barycenter), the error SPICE(NOSEPARATION) is signaled by a routine in the call tree of this routine. 8) 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. Ephemeris data are made available by loading one or more SPK files via furnsh_c. - PCK data: if the computation method is specified as "Ellipsoid," 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 body orientation data: these may be provided in a text or binary PCK file. In some cases, target body orientation may be provided by one more more CK files. In either case, data are made available by loading the files via furnsh_c. The following data may be required: - DSK data: if `method' indicates that DSK data are to be used, DSK files containing topographic data for the target body must be loaded. If a surface list is specified, data for at least one of the listed surfaces must be loaded. - Surface name-ID associations: if surface names are specified in `method', the association of these names with their corresponding surface ID codes must be established by assignments of the kernel variables NAIF_SURFACE_NAME NAIF_SURFACE_CODE NAIF_SURFACE_BODY Normally these associations are made by loading a text kernel containing the necessary assignments. An example of such assignments is NAIF_SURFACE_NAME += 'Mars MEGDR 128 PIXEL/DEG' NAIF_SURFACE_CODE += 1 NAIF_SURFACE_BODY += 499 - 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. 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. - CK data: if the frame to which `dref' refers 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. - 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). In all cases, kernel data are normally loaded once per program run, NOT every time this routine is called. ## ParticularsGiven a ray defined by a direction vector and the location of an observer, ## 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 surface intercept points on Mars for the boresight and FOV boundary vectors of the MGS MOC narrow angle camera. The intercepts are computed for a single observation epoch. Converged Newtonian light time and stellar aberration corrections are used. For simplicity, camera distortion is ignored. Intercepts are computed using both triaxial ellipsoid and topographic surface models. The topographic model is based on data from the MGS MOLA DEM megr90n000cb, which has a resolution of 4 pixels/degree. A triangular plate model was produced by computing a 720 x 1440 grid of interpolated heights from this DEM, then tessellating the height grid. The plate model is stored in a type 2 segment in the referenced DSK file. Use the meta-kernel shown below to load the required SPICE kernels. KPL/MK File: sincpt_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 --------- -------- de430.bsp Planetary ephemeris mar097.bsp Mars satellite ephemeris pck00010.tpc Planet orientation and radii naif0011.tls Leapseconds mgs_moc_v20.ti MGS MOC instrument parameters mgs_sclkscet_00061.tsc MGS SCLK coefficients mgs_sc_ext12.bc MGS s/c bus attitude mgs_ext12_ipng_mgs95j.bsp MGS ephemeris megr90n000cb_plate.bds Plate model based on MEGDR DEM, resolution 4 pixels/degree. \begindata KERNELS_TO_LOAD = ( 'de430.bsp', 'mar097.bsp', 'pck00010.tpc', 'naif0011.tls', 'mgs_moc_v20.ti', 'mgs_sclkscet_00061.tsc', 'mgs_sc_ext12.bc', 'mgs_ext12_ipng_mgs95j.bsp', 'megr90n000cb_plate.bds' ) \begintext End of meta-kernel Example code begins here. /. Program sincpt_ex1 ./ #include <stdio.h> #include <string.h> #include "SpiceUsr.h" #include "SpiceZmc.h" int main() { /. Local parameters ./ #define META "sincpt_ex1.tm" #define ABCLEN 20 #define LNSIZE 81 #define NAMLEN 33 #define TIMLEN 51 #define SHPLEN 81 #define NCORNR 4 #define NMETH 2 /. Local variables ./ SpiceBoolean found; SpiceChar * abcorr = "CN+S"; SpiceChar * camera = "MGS_MOC_NA"; SpiceChar dref [NAMLEN]; SpiceChar * fixref = "IAU_MARS"; SpiceChar * methds [NMETH] = { "Ellipsoid", "DSK/UNPRIORITIZED" }; SpiceChar * obsrvr = "MGS"; SpiceChar shape [SHPLEN]; SpiceChar * srftyp [NMETH] = { "Ellipsoid", "MGS/MOLA topography, 4 pixel/deg" }; SpiceChar * target = "Mars"; SpiceChar title [LNSIZE]; SpiceChar * utc = "2003 OCT 13 06:00:00 UTC"; SpiceDouble bounds [NCORNR][3]; SpiceDouble bsight [3]; SpiceDouble dist; SpiceDouble dvec [3]; SpiceDouble et; SpiceDouble lat; SpiceDouble lon; SpiceDouble radius; SpiceDouble spoint [3]; SpiceDouble srfvec [3]; SpiceDouble trgepc; SpiceInt camid; SpiceInt i; SpiceInt k; SpiceInt n; /. Load kernel files: ./ furnsh_c ( META ); /. Convert the UTC request time to ET (seconds past J2000, TDB). ./ str2et_c ( utc, &et ); /. Get the MGS MOC Narrow angle camera (MGS_MOC_NA) ID code. Then look up the field of view (FOV) parameters. ./ bodn2c_c ( camera, &camid, &found ); if ( !found ) { setmsg_c ( "Could not find ID code for " "instrument #." ); errch_c ( "#", camera ); sigerr_c ( "SPICE(NOTRANSLATION)" ); } /. getfov_c will return the name of the camera-fixed frame in the string `dref', the camera boresight vector in the array `bsight', and the FOV corner vectors in the array `bounds'. ./ getfov_c ( camid, NCORNR, SHPLEN, NAMLEN, shape, dref, bsight, &n, bounds ); printf ( "\n" "Surface Intercept Locations for Camera\n" "FOV Boundary and Boresight Vectors\n" "\n" " Instrument: %s\n" " Epoch: %s\n" " Aberration correction: %s\n", camera, utc, abcorr ); /. Now compute and display the surface intercepts for the boresight and all of the FOV boundary vectors. ./ for ( i = 0; i <= NCORNR; i++ ) { if ( i < NCORNR ) { sprintf ( title, "Corner vector %d", (int)(i+1) ); vequ_c ( bounds[i], dvec ); } else { strcpy ( title, "Boresight vector" ); vequ_c ( bsight, dvec ); } printf ( "\n" "%s\n", title ); sprintf ( title, " Vector in %s frame = ", dref ); printf ( "\n" "%s\n", title ); if ( i < NCORNR ) { printf ( " %18.10e %18.10e %18.10e\n", bounds[i][0], bounds[i][1], bounds[i][2] ); } else { printf ( " %18.10e %18.10e %18.10e\n", bsight[0], bsight[1], bsight[2] ); } printf ( "\n" " Intercept:\n" ); /. Compute the surface intercept point using the specified aberration corrections. Loop over the set of computation methods. ./ for ( k = 0; k < NMETH; k++ ) { ## Restrictions1) 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 intercept 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. 2) This routine must not be used for cases where the observer is inside the target body. This routine does not attempt to detect this condition. If the observer is a point on a target surface described by DSK data, care must be taken to ensure the observer is sufficiently far outside the target. The routine should not be used for surfaces for which "outside" cannot be defined. ## Literature_ReferencesNone. ## Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) S.C. Krening (JPL) B.V. Semenov (JPL) ## Version-CSPICE Version 2.0.1, 01-NOV-2021 (JDR) (NJB) Edited the header to comply with NAIF standard. Updated -Detailed_Input and -Restrictions sections to state that the observer must be outside the target body. -CSPICE Version 2.0.0, 05-APR-2017 (NJB) (SCK) (BVS) Updated to support use of DSKs. -CSPICE Version 1.0.2, 02-APR-2011 (NJB) (SCK) References to the new pxfrm2_c routine were added, which changed the Detailed Output section and the second example. Miscellaneous, minor header comment corrections were made. -CSPICE Version 1.0.1, 06-FEB-2009 (NJB) Typos in the Detailed Input section's description of `dref' were corrected. Incorrect frame name fixfrm was changed to fixref in documentation. In the header examples, meta-kernel names were updated to use the suffix ".tm" -CSPICE Version 1.0.0, 02-MAR-2008 (NJB) ## Index_Entriesfind surface intercept point find intersection of ray and target body surface find intercept of ray on target body surface |

Fri Dec 31 18:41:12 2021