PINPOINT User's Guide =========================================================================== Revisions -------------------------------------------------------- December 2002 Initial release of the User's Guide. Summary -------------------------------------------------------- This program provides SPICE users with a mechanism for creating SPK files for landmarks on the surface of celestial bodies. More generally, this utility can be used to create an ephemeris for any object that has a constant offset relative to some other ephemeris object in some reference frame recognized by the SPICE frames subsystem. Usage -------------------------------------------------------- The program expects the following command line arguments: pinpoint -def defns -spk spkfile [-pck txtpck] [flags] where defns is the name of a file that defines the names and locations of landmarks. spkfile is the name of the SPK file to create. txtpck is the name of a text PCK kernel that is needed if you specify landmarks in terms of latitude, longitude and altitude. This argument is optional in some cases. The program prompts for any required item that is not supplied on the command line. Batch Mode As discussed above, pinpoint normally requests information needed that has not been supplied on the command line. When you use the program interactively, this is often a friendlier response than issuing an error message if some value is left out. However, if you are using this utility in a script that cannot respond to user requests, you will want to repress the normal prompting behavior of pinpoint. To do this add the flag "-batch" to the other values supplied on the command line. pinpoint -def defns -spk spkfile [-pck txtpck] -batch If some required input is not supplied, the program simply stops. No prompts for input are issued and no SPK file is created. Information Modes The program also supplies general information about how to use it, the current version. The following illustrate the various information modes. help : pinpoint -h[elp] version: pinpoint -v[ersion] usage : pinpoint -usage Particulars -------------------------------------------------------- Pinpoint creates a binary SPK file for a objects that have constant positions relative to some object in some reference frame. Normally, you will use pinpoint to create an SPK file for landmarks or station locations. To create the SPK file you need to create a landmark definitions file (defns in the Usage section). The definitions take the form of KEYWORD = VALUE. The KEYWORD = VALUE format used in the definition file is the same format as used by any text kernel. Inputs You list the names of your landmarks via the variable: SITES This is an array of character strings giving the names of the various sites. The names should have no embedded spaces and be less than 24 characters in length. For example SITES = ( 'GOLDSTONE', 'CANBERRA', 'MADRID' ) For each NAMEd site you need to supply the following variables _FRAME = a reference frame available via NAMFRM _IDCODE = the idcode to associate with the name. Following our previous example you would specify: GOLDSTONE_FRAME = 'IAU_EARTH' GOLDSTONE_IDCODE = 399001 CANBERRA_FRAME = 'IAU_EARTH' CANBERRA_IDCODE = 399002 MADRID_FRAME = 'IAU_EARTH' MADRID_IDCODE = 399003 You define the position of the object in the reference frame via one of the following two variables. _XYZ = X, Y, and Z components of the object in km. _LATLON = Latitude, Longitude, Altitude in "Gaussian" coordinates in degrees and km. Again, following up our previous example you might have: GOLDSTONE_XYZ = ( -2353.623, -4641.344, 3667.062 ) CANBERRA_XYZ = ( -4451.074, 2676.822, -3691.361 ) MADRID_XYZ = ( 4849.091, -360.177, 4115.114 ) If you supply latitude-longitude form of coordinates you will need to supply a PCK kernel for the bodies on which the sites are located. Unless you specify otherwise the position of the object will be relative to the center of the reference frame. This is almost always what you want. However, occasionally you may want the position to be relative to some object other than the center of the reference frame. To explicitly specify relative position, supply the variable: _CENTER = NAIF ID code of the relative body. In our example, we want the relative body to be the center of the earth. This is the default, but to explicitly specify it we supply the variables: GOLDSTONE_CENTER = 399 CANBERRA_CENTER = 399 MADRID_CENTER = 399 You may also define the bounds for the segment associated with a landmark. (Default bounds are from 1950 Jan 1 ET to 2050 Jan 1 ET.) _BOUNDS = start and stop time in Ephemeris seconds past J2000. This is usually most easily input via the the @yyyy-mon-dd-hh:mm:ss format Example: GOLDSTONE_BOUNDS = ( @1972-JAN-1, @2100-JAN-1 ) CANBERRA_BOUNDS = ( @1972-JAN-1, @2100-JAN-1 ) MADRID_BOUNDS = ( @1972-JAN-1, @2100-JAN-1 ) Examples -------------------------------------------------------- DSS 12 and DSS 13 Locations The following definitions file can be used to create an SPK containing locations of the DSS 12 and DSS 13: This paragraph is placeholder comments accompanying an example PINPOINT definitions file. These comments along with the actual definitions from the section below will be copied into the comment area of the output SPK file. In real applications a set of detailed comments describing the origin, accuracy, applicability, etc. of the data below as well as the producer contact information should be provided instead of these ``placeholder comments'' to ensure the SPK's use-ability/trace-ability in the future. \begindata SITES = ( 'DSS_12', 'DSS_13' ) DSS_12_CENTER = 399 DSS_12_FRAME = 'EARTH_FIXED' DSS_12_IDCODE = 399012 DSS_12_XYZ = ( -2350.443812, -4651.980837, +3665.630988 ) DSS_13_CENTER = 399 DSS_13_FRAME = 'EARTH_FIXED' DSS_13_IDCODE = 399013 DSS_13_XYZ = ( -2351.112452, -4655.530771, +3660.912823 ) \begintext Since XYZ-style position definition is used in the file, PCK file name does not have to be provided on the command line and PINPOINT can be run with just two command line arguments: > pinpoint -def pinpoint_ex1.defs -spk dss_12_13.bsp MER-A Landing Site EP55A2 Location The following definitions file can be used to create an SPK containing location of the MER-A landing site EP55A2 (areographic coordinates: Lon = 175.298 degrees East, Lat = -14.806408 degrees North, Alt w.r.t. IAU 2000 Mars ellipsoid = -2.595 km): This paragraph is placeholder comments accompanying an example PINPOINT definitions file. These comments along with the actual definitions from the section below will be copied into the comment area of the output SPK file. In real applications a set of detailed comments describing the origin, accuracy, applicability, etc. of the data below as well as the producer contact information should be provided instead of these ``placeholder comments'' to ensure the SPK's use-ability/trace-ability in the future. \begindata SITES = ( 'LS' ) LS_CENTER = 499 LS_FRAME = 'IAU_MARS' LS_IDCODE = -253900 LS_LATLON = ( -14.806408 175.298000 -2.595 ) LS_BOUNDS = ( @2001-JAN-01, @2100-JAN-01 ) \begintext Since the position is given as LON/LAT, a PCK file name should be provided on the command line along with the definitions and spk file names: > pinpoint -def pinpoint_ex2.defs \ -spk mera_EP55A2.bsp \ -pck mars_iau2000_v0.tpc