SUBPT User's Guide =========================================================================== Last revised on 2008 FEB 07 by N. J. Bachman. Abstract -------------------------------------------------------- SUBPT is a cookbook program that demonstrates how to use CSPICE Toolkit routines to compute a sub-observer point. Summary -------------------------------------------------------- The SUBPT ``cookbook'' program illustrates the use of CSPICE Toolkit software for solving a typical geometrical problem --- computing the apparent sub-observer point on a target body using light time and stellar aberration corrections. The ``apparent sub-observer point'' is defined in this program to be the point on the target body that appears to be closest to the observer. The apparent sub-observer point may also be defined as the intercept on the target's surface of the ray emanating from the observer and passing through the apparent target body's center, but we don't demonstrate use of that definition here. See the header of the function subpnt_c for details. In order to compute the apparent location of the sub-observer point, we correct the position of the sub-observer point for both light time and stellar aberration, and we correct the orientation of the target body for light time. We consider ``light time'' to be the time it takes a photon to travel from the sub-observer point to the observer. If the light time is given the name LT, then the apparent position of the sub-observer point relative to the observer is defined by the vector from the sub-observer point's location (relative to the solar system barycenter) at ET-LT, minus the observer's location (again, relative to the solar system barycenter) at ET, where this difference vector is corrected for stellar aberration. See the header of the CSPICE function spkezr_c for more information on light time and stellar aberration corrections; see the header of the CSPICE routine subpnt_c for an explanation of how it applies aberration corrections. SUBPT demonstrates the use of the following high-level CSPICE functions: prompt_c Interactively prompt user for a string input furnsh_c Load SPICE kernels str2et_c Convert time string to ephemeris time subpnt_c Calculate the sub-point et2utc_c Convert ephemeris time to UTC string To run SUBPT, you need a binary SPK ephemeris file and knowledge of the bodies and the corresponding time intervals contained in that file. The utility program named BRIEF summarizes the contents and time coverage of a binary SPK file. Refer to NAIF IDs Required Reading (naif_ids.req) for a list of body names and integer codes. In addition to an SPK file, you also require access to leapsecond (LSK) and planetary constants (PCK) kernels. SUBPT prompts you for the NAIF IDs or string name of a target body and observing body, the name of the body-fixed reference frame associated with the target body, the UTC end-points of a time interval, and the number of evaluations to perform over the assigned time interval. The program then computes the planetocentric coordinates of the apparent sub-observer point on the target body, printing to the terminal screen for each time in the interval. Below, find a sample session using SUBPT to calculate the latitude and longitude of the nearest point on the Earth to the Sun through a single day. SUBPT can be used with any SPK file containing appropriate data. Please note: FORTRAN and C versions of the program can output numerical values in slightly different formats. It is assumed the kernel files used by SUBPT exist in the current directory (i.e. the directory from which your execute SUBPT). This particular session was run on an Intel box using the LINUX operating system. First, create the binary SPK kernel cook_01.bsp by running the CSPICE Toolkit TOBIN application on the transfer format file cook_01.tsp located in the CSPICE data directory. The program also requires a leapseconds kernel to run; an example leapseconds kernel, cook_01.tls exists within the same directory. Now, execute SUBPT: Welcome to SUBPT This program demonstrates the use of CSPICE in computing the apparent sub-observer point on a target body. The computations use light time and stellar aberration corrections. Enter the name of leapseconds kernel file: cook_01.tls Enter the name of a planetary constants kernel: cook_01.tpc Enter the name of a binary SPK file: cook_01.bsp Working ... Please wait. Enter the name for the observing body: sun Enter the name for a target body: earth Enter the name of the target body-fixed frame: iau_earth Enter the number of points to calculate: 24 Enter the beginning UTC time: jul 1 1990 Enter the ending UTC time: jul 2 1990 Planetocentric coordinates for the nearest point on the target body to the observing body (deg). Target body: earth Observing body: sun UTC Time Lat Lon ---------------------------------------------- 1990 JUL 01 00:00:00 23.00157 -176.92004 1990 JUL 01 01:02:36 22.99879 167.42991 1990 JUL 01 02:05:13 22.99600 151.77986 1990 JUL 01 03:07:49 22.99320 136.12981 1990 JUL 01 04:10:26 22.99039 120.47976 1990 JUL 01 05:13:02 22.98757 104.82970 1990 JUL 01 06:15:39 22.98473 89.17964 1990 JUL 01 07:18:15 22.98188 73.52958 1990 JUL 01 08:20:52 22.97902 57.87952 1990 JUL 01 09:23:28 22.97614 42.22946 1990 JUL 01 10:26:05 22.97325 26.57939 1990 JUL 01 11:28:41 22.97035 10.92932 1990 JUL 01 12:31:18 22.96744 -4.72075 1990 JUL 01 13:33:54 22.96451 -20.37082 1990 JUL 01 14:36:31 22.96157 -36.02090 1990 JUL 01 15:39:07 22.95862 -51.67097 1990 JUL 01 16:41:44 22.95566 -67.32105 1990 JUL 01 17:44:20 22.95268 -82.97114 1990 JUL 01 18:46:57 22.94969 -98.62122 1990 JUL 01 19:49:33 22.94669 -114.27131 1990 JUL 01 20:52:10 22.94368 -129.92140 1990 JUL 01 21:54:46 22.94065 -145.57149 1990 JUL 01 22:57:23 22.93761 -161.22158 1990 JUL 02 00:00:00 22.93456 -176.87168 Continue? (Enter Y or N): N