PINPOINT User's Guide =========================================================================== Last revised on 2021 DEC 13 by N. J. Bachman. Abstract -------------------------------------------------------- Create an SPK file and optionally, an FK file, for a set of objects having fixed locations or constant velocities relative to their respective centers of motion. Summary -------------------------------------------------------- This utility can be used to create an ephemeris for any object that has a constant position or constant velocity, relative to some other ephemeris object, in a reference frame recognized by the SPICE frames subsystem. Examples are landmarks on the surface of a celestial body, offsets between manipulator joints, an antenna phase center relative to a spacecraft center of mass, terrestrial communications stations, and planetary landers. NASA DSN stations are examples of objects having velocities modeled as non-zero constant values, relative to a terrestrial reference frame. An object for which an ephemeris is created thus becomes an ephemeris object within the SPICE context. In this document that ephemeris object is also called a ``site.'' PINPOINT can create an SPK file containing ephemerides for multiple sites; the file will have one segment for each site. This program can also create a frame kernel specifying topocentric frames associated with each site listed in the input definitions file. This feature is applicable only to sites on the surface of an object having an associated reference ellipsoid. If a frame kernel is created, reference frame specifications will be created for all sites in the definitions file. Usage -------------------------------------------------------- The program expects the following command line arguments: pinpoint -def defns -spk spkfile [-pck kerfile] [-fk fk] [flags] where defns is the name of a file that defines the names and locations of objects for which an ephemeris is to be created. spkfile is the name of the SPK file to create. kerfile is the name of a SPICE text kernel file. This file can be: a text PCK providing radii if you specify object locations in terms of latitude, longitude and altitude, or if you command the program to create an FK. an FK providing specifications of the frames used to define locations but not built into SPICE a meta-kernel that lists PCK(s), FK(s), and/or any other kinds of kernels that may be needed to provide radii, reference frame specifications, or body-name mappings. fk is the name of a topocentric frame specification kernel to be created. This argument is optional. If an FK is to be created, a PCK must be specified to provide radii of the reference ellipsoid for each central body associated with any site. The program prompts for any required item that is not supplied on the command line. Batch Mode As discussed above, PINPOINT normally prompts the user for needed information 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 suppress 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] [-fk fk] -batch If some required input is not supplied, the program simply stops. No prompts for input are issued and no SPK or FK file is created. Information Modes The program can supply general information about how to use it, and it can display the current version number. The following illustrate the various information modes. help : pinpoint -h[elp] version: pinpoint -v[ersion] usage : pinpoint -usage Creating a Definitions File -------------------------------------------------------- To create the SPK file (and FK) you need to create a landmark definitions file (defns in the Usage section). The definitions take the form of KEYWORD = VALUE. The requirements on the KEYWORD = VALUE format used in the definition file are the same as for any text kernel. All keywords must be in upper case. Inputs for Creating SPK Files List the names of your sites (such as landmarks or communications stations) using the variable: SITES This is an array of character strings giving the names of the various sites. The names must have no embedded spaces and be less than 24 characters in length. Each name must be delimited by single quotes. Site names must be in upper case. For example SITES = ( 'GOLDSTONE', 'CANBERRA', 'MADRID' ) For each named site you need to supply the following variables _FRAME = a reference frame known to SPICE (built-in or having a frame specification in the definitions file) _IDCODE = the integer body ID code to associate with the site name Using the example above you would specify: GOLDSTONE_FRAME = 'ITRF93' GOLDSTONE_IDCODE = 399001 CANBERRA_FRAME = 'ITRF93' CANBERRA_IDCODE = 399002 MADRID_FRAME = 'ITRF93' MADRID_IDCODE = 399003 In the assignments above, ITRF93 is the name of a terrestrial reference frame. The orientation of this frame relative to the J2000 reference frame is provided by binary PCK files. See the PCK Required Reading and Lunar-Earth PCK-FK tutorial (available on the NAIF web site) for details. Define the position of the site in the reference frame using one of the following two variables: _XYZ = Cartesian X, Y, and Z components of the object in km. _LATLON = Latitude, Longitude, Altitude in planetodetic coordinates, in units of degrees and km. Planetodetic coordinates have positive east longitude. Planetodetic latitude is defined using a reference ellipsoid. Latitude at a point P on the ellipsoid is the angle between the ellipsoid's outward normal vector at P and the equatorial plane. The latitude of a point P not on the ellipsoid is the latitude of the closest point to P on the ellipsoid. The altitude of P is its height above or below the ellipsoid. Following the 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 the latitude-longitude-altitude form of coordinates, you will need to supply a PCK kernel containing size and shape information for the bodies on which the sites are located. Supported shapes are bi-axial ellipsoids: spheres, oblate spheroids, or prolate spheroids. Objects having three distinct ellipsoid radii are accepted by this program, but are treated as though both equatorial radii are equal. It is strongly recommended that you use Cartesian coordinates for sites on such objects. Velocity data are optional; the velocity is assumed to be zero if no velocity data are provided. To define the velocity of the site in the reference frame used for the site's location, use the variable _DXYZ = X, Y, and Z velocity components of the object in meters/year (NOT km/s). For example, the velocity of the Goldstone communications antennas complex might be provided as: GOLDSTONE_DXYZ = ( -0.0191, 0.0061, -0.0047 ) When velocity data are provided, the epoch at which the site position applies must be specified using the kernel variable _EPOCH = TDB (Barycentric Dynamical Time) epoch at which the site position is that specified by _XYZ or _LATLON. The epoch is expressed in the format used in the leapseconds kernel. Example: @2000-JAN-1/12:00 The string must contain no embedded blanks and is not quoted. The string is assumed to represent TDB; no TDB marker may be added. For example, the epoch of the position of the Goldstone complex might be provided as: GOLDSTONE_EPOCH = @1993-JAN-1/00:00 Unless you specify otherwise, the position of the object will be relative to the center of the reference frame specified using the _FRAME keyword. 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 a central body relative to which the site's position and velocity are expressed, provide this assignment: _CENTER = NAIF ID code of the central body. In our example, we want the central body to be the center of the earth. This is the default, but we specify it explicitly for clarity. This is done using the assignments: GOLDSTONE_CENTER = 399 CANBERRA_CENTER = 399 MADRID_CENTER = 399 SPK files have a begin and end time associated with each segment. PINPOINT uses default time bounds from 1950 Jan 1 TDB to 2050 Jan 1 TDB. You may explicitly set time bounds for the segment associated with a site: _BOUNDS = start and stop time in seconds past J2000 TDB. This is usually most easily input using 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 ) Note that for a given site, only a single pair of begin and end times may be used. If you need to have multiple time spans for a given site (thus with a gap between each span), you'll need to make multiple runs of PINPOINT, creating multiple SPK files. You could subsequently merge those files for convenience. Inputs for Creating an Optional FK File To create an FK file, you must specify the inputs required to create an SPK file, as shown above. Additional inputs are required to specify topocentric frames associated with the site or sites listed in the definitions file. A single FK will be produced no matter how many sites are being processed. A topocentric frame associated with a site is centered at that site. Elsewhere in this discussion the term ``central body'' refers not to the site at the center of the topocentric frame, but to the extended body on whose surface the site is located. If you command PINPOINT to create a topocentric frame kernel, PINPOINT will attempt to specify a topocentric frame for each site listed in the definitions file. It's an error to provide topocentric frame specifications for some sites and not others. To create a topocentric frame kernel, you must specify on the command line a PCK file containing radii of reference ellipsoids for each central body. These ellipsoids are requited to have equal-length X and Y axes: they may be oblate spheroids, spheres, or prolate spheroids. You also must specify the orientation of two of the axes of each topocentric frame. PINPOINT will determine the direction of the third axis using the right-hand rule: the transformation from the topocentric frame to the central body's body-fixed, body-centered frame is always a rotation. For a site located anywhere except on the Z-axis of the body-centered, body-fixed reference frame designated by the _FRAME keyword, the topocentric frame's axes are specified by associating two of the optionally signed axis names '-X', '-Y', '-Z', 'X', 'Y', 'Z' with the local zenith (``up'' direction) and the north direction. This is done using the assignments _UP = _NORTH = Positive directions may optionally be prefixed with plus signs (+). Example: The axis orientations shown below for Goldstone are standard for topocentric frames associated with NASA DSN stations in frames kernels distributed by JPL's NAIF group. It is recommended that you follow this convention for earth-based communications stations. To create a frame centered at GOLDSTONE, with the Z axis pointing toward the zenith and the X axis pointing north, use the assignments: GOLDSTONE_UP = 'Z' GOLDSTONE_NORTH = 'X' Example: To create a frame centered at the landing site on Titan of the Cassini mission's Huygens probe, with the -Z axis pointing toward the zenith and the X axis pointing north, use the assignments: HUYGENS_UP = '-Z' HUYGENS_NORTH = 'X' Since the direction ``north'' is not defined on the Z axis of a body-fixed, body-centered frame, for sites on the Z axis, the topocentric axis pointing in the direction of the prime meridian is specified instead; this is accomplished using the assignment: _PRIME = Example: SANTAS_HOME_UP = 'Z' SANTAS_HOME_PRIME = 'X' By default PINPOINT will create topocentric frame specifications using automatically generated frame names and frame ID codes. Default frame names have the form _TOPO and default frame ID codes are generated by adding 1000000 to the body ID codes of the respective sites, for example: GOLDSTONE_TOPO 1399001 These defaults can be overridden using the assignments: _TOPO_FRAME = _TOPO_ID = For example, if we wished to set the Goldstone topocentric frame's ID code to -1399001, we would use the assignments: GOLDSTONE_TOPO_FRAME = 'GOLDSTONE_LOCAL_LEVEL' GOLDSTONE_TOPO_ID = -1399001 For each site having velocity data, PINPOINT will create a topocentric frame centered at the location of that site at the epoch specified by the required keyword _TOPO_EPOCH = The epoch on the right hand side must follow the same time format used for other epoch specifications (see discussion above). Example: GOLDSTONE_TOPO_EPOCH = @2005-JUL-15 Examples -------------------------------------------------------- DSS 12 and DSS 13 Locations The following definitions file can be used to create an SPK containing locations of the NASA DSS 12 and DSS 13 communications stations: This paragraph consists of 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 usability/traceability 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 To create a frame kernel for these sites that specifies topocentric frames whose Z axes point toward the zenith and whose X axes point north, extend the inputs above as follows: \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-12_UP = 'Z' DSS-12_NORTH = 'X' DSS-13_CENTER = 399 DSS-13_FRAME = 'EARTH_FIXED' DSS-13_IDCODE = 399013 DSS-13_XYZ = ( -2351.112452, -4655.530771, +3660.912823 ) DSS-13_UP = 'Z' DSS-13_NORTH = 'X' \begintext The command required to run PINPOINT must then specify both an input PCK file and the name of the FK to create, for example: > pinpoint -def pinpoint_ex1.defs -pck pck00010.tpc -spk dss_12_13.bsp -fk dss_12_13.tf 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 consists of 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 usability/traceability 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 Spacecraft Antennas The use of PINPOINT to create a fixed-offset SPK file for spacecraft antennas, such as an articulating high gain antenna, may be seen in the comment area of the structure SPK file made for the Mars Global Surveyor (MGS) antennas. This file is available from the PDS Archived SPICE Data Sets web pages of the NAIF node. In particular: http://naif.jpl.nasa.gov/pub/naif/pds/data/ mgs-m-spice-6-v1.0/mgsp_1000/data/spk/mgsstruct_hga.bsp To view the comments in this file, use the COMMNT utility program available in any SPICE Toolkit and also available from the ``SPICE Applications and Utilities'' link of the NAIF web pages.