nearpt_c |

Table of contents## Procedurenearpt_c ( Nearest point on an ellipsoid ) void nearpt_c ( ConstSpiceDouble positn[3], SpiceDouble a, SpiceDouble b, SpiceDouble c, SpiceDouble npoint[3], SpiceDouble * alt ) ## AbstractLocate the point on the surface of an ellipsoid that is nearest to a specified position. Also return the altitude of the position above the ellipsoid. ## Required_ReadingNone. ## KeywordsELLIPSOID GEOMETRY ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- positn I Position of a point in bodyfixed frame. a I Length of semi-axis parallel to x-axis. b I Length of semi-axis parallel to y-axis. c I Length on semi-axis parallel to z-axis. npoint O Point on the ellipsoid closest to positn. alt O Altitude of positn above the ellipsoid. ## Detailed_Inputpositn 3-vector giving the position of a point with respect to the center of an ellipsoid. The vector is expressed in a body-fixed reference frame. The semi-axes of the ellipsoid are aligned with the x, y, and z-axes of the body-fixed frame. a is the length of the semi-axis of the ellipsoid that is parallel to the x-axis of the bodyfixed coordinate system. b is the length of the semi-axis of the ellipsoid that is parallel to the y-axis of the bodyfixed coordinate system. c is the length of the semi-axis of the ellipsoid that is parallel to the z-axis of the bodyfixed coordinate system. ## Detailed_Outputnpoint is the nearest point on the ellipsoid to `positn'. `npoint' is a 3-vector expressed in the body-fixed reference frame. alt is the altitude of `positn' above the ellipsoid. If `positn' is inside the ellipsoid, `alt' will be negative and have magnitude equal to the distance between `npoint' and `positn'. ## ParametersNone. ## Exceptions1) If any of the axis lengths `a', `b' or `c' are non-positive, the error SPICE(BADAXISLENGTH) is signaled by a routine in the call tree of this routine. 2) If the ratio of the longest to the shortest ellipsoid axis is large enough so that arithmetic expressions involving its squared value may overflow, the error SPICE(BADAXISLENGTH) is signaled by a routine in the call tree of this routine. 3) If any of the expressions a * abs( positn[0] ) / m^2 b * abs( positn[1] ) / m^2 c * abs( positn[2] ) / m^2 where `m' is the minimum of { a, b, c }, is large enough so that arithmetic expressions involving these sub-expressions may overflow, the error SPICE(INPUTSTOOLARGE) is signaled by a routine in the call tree of this routine. 4) If the axes of the ellipsoid have radically different magnitudes, for example if the ratios of the axis lengths vary by 10 orders of magnitude, the results may have poor precision. No error checks are done to identify this problem. 5) If the axes of the ellipsoid and the input point `positn' have radically different magnitudes, for example if the ratio of the magnitude of `positn' to the length of the shortest axis is 1.e25, the results may have poor precision. No error checks are done to identify this problem. ## FilesNone. ## ParticularsMany applications of this routine are more easily performed using the higher-level CSPICE routine subpnt_c. This routine is the mathematical workhorse on which subpnt_c relies. This routine solves for the location, N, on the surface of an ellipsoid nearest to an arbitrary location, P, relative to that ellipsoid. ## ExamplesExample 1. The code fragment below illustrates how you can use CSPICE to compute the sub-earth point on the moon. /. Load the ephemeris, leapseconds and physical constants files first. We assume the names of these files are stored in the character variables SPK, LSK and PCK. ./ furnsh_c ( SPK ); furnsh_c ( LSK ); furnsh_c ( PCK ); /. Get the apparent position of the Moon as seen from Earth. Look up this position vector in the moon body-fixed frame IAU_MOON. The orientation of the IAU_MOON frame will be computed at epoch et-lt. ./ spkpos_c ( "moon", et, "IAU_MOON", "lt+s", "earth, trgpos, < ); /. Negate the moon's apparent position to obtain the position of the earth in the moon's body-fixed frame. ./ vminus_c ( trgpos, evec ); /. Get the lengths of the principal axes of the moon. Transfer the elements of the array radii to the variables a, b, c to enhance readability. ./ bodvcd_c ( 399, "RADII", 3, &dim, radii ); vupack_c ( radii, &a, &b, &c ); /. Finally get the point `subpnt' on the surface of the moon closest to the earth --- the sub-earth point. ./ ## Restrictions1) See the -Exceptions header section above. ## Literature_ReferencesNone. ## Author_and_InstitutionC.H. Acton (JPL) N.J. Bachman (JPL) J. Diaz del Rio (ODC Space) E.D. Wright (JPL) ## Version-CSPICE Version 2.0.0, 01-NOV-2021 (NJB) (JDR) (EDW) Edit to logic to reduce unneeded operations when error or projection vectors equal zero. Addition of details concerning the "ellipsoid near point" problem and solution. Edited the header to comply with NAIF standard. -CSPICE Version 1.3.2, 17-NOV-2005 (NJB) (EDW) The -Exceptions and -Restrictions header sections were updated. A reference to bodvar_c in the header was changed to a reference to bodvcd_c. -CSPICE Version 1.3.1, 28-JUL-2003 (NJB) (CHA) Various header corrections were made. -CSPICE Version 1.3.0, 21-OCT-1998 (NJB) Made input vector const. -CSPICE Version 1.2.0, 15-FEB-1998 (EDW) Minor corrections to header. -CSPICE Version 1.2.0, 08-FEB-1998 (NJB) Removed local variables used for temporary capture of outputs. -CSPICE Version 1.0.0, 25-OCT-1997 (NJB) Based on SPICELIB Version 1.1.0, 27-NOV-1990 (WLT) ## Index_Entriesdistance from point to ellipsoid nearest point on an ellipsoid |

Fri Dec 31 18:41:10 2021