GetSpots

GetSpots identifies those times, listed in sclkfile, when the boresight of instrumenttype intersects the surface of Bennu less than distance milliradians from the center of individual facets in the OBJ file described in objfile. Needed spice files for this calculation are listed in spicemetakernel.
At the time a three-dimensional map is made, a designated DSK file will be used to create an OBJ file that act as a framework on which a map will be made. (This is done with the utility mkobj.) The OBJ file identifies a set of vertices (in body centered Cartesian coordinates) and groups these vertices to identify facets. Facet numbers correspond to their ordinal position in the list of facet identifications. An ancillary file locates the center of each facet in latitude (deg), longitude (deg), and range (km) from center of figure.
Mapmakers may wish to assign a value to a facet based on an algorithmic combination of one or more observations that are in the proximity of the facet. In order to do this, they need to understand which observations are candidates for their analysis. Knowing the distance and position angle of the observation relative to the center of the facet is the discriminator for determining which observations are candidates, and GetSpots provides this information.
For all observations taken by OSIRIS-REx, the unique value of a counter on the spacecraft when the observation was made is known. This is called the sclk ("sklock") value. SPICE files provide spacecraft ephemeris and orientation, Bennu position, orientation, and shape, and instrument boresight and orientations. When combined with the sclk value, the intersection of the boresight on the surface of Bennu can be calculated.
A simple text file of sclk values (one per line) acts as input to getspots. GetSpots can determine which boresight values corresponding to the sclk values do not exceed the maximum distance criteria for each facet, along with the position angle of the spot, and the fraction of the facet covered by the spot. The position angle is valued from 0 to 359 degrees North being 0 with east being 90 degrees. Spots that do not completely intersect the surface of Bennu are flagged. Any additional information on the input line following the sclk value is echoed to the output unchanged, allowing other data useful in the subsequent analysis to be carried along in the output.

INPUTS

spicemetakernel is a spice metakernel listing all required spice files (DSK, SPK, PCK, etc.) needed to perform the analysis. Only files needed for this analysis are in the metakernel (e.g. no ambiguity about which file to use.) Required contents of this metakernel is TBD.
instrumenttype is a code that specifies the boresight and field of view of the instrument to use in the analysis. This must be one of "OLA", "OTES", "OVIRS", "POLYCAM", "MAPCAM", "SAMCAM", or "NAVCAM".
distance is the maximum distance of the instrument boresight from the center of the facet expressed in milliradians.
sclkfile is a text file that contains the sclk values for one or more times of observation by an instrument. Leading whitespace is ignored. One or more whitespace characters must separate the sclkvalue from the rest of the line. The format is as follows:

 BEGIN
 sclkvalue [otherdata]
 sclkvalue [otherdata]
 .
 .
 END

Where:

sclkvalue is a string (format TBD)
[otherdata] includes all additional data (including whitespace) in the line up to, but not including, the linefeed character.

OUTPUT

All output is written to standard output.
Output is a text file, with each line terminated by linefeeds.

 F1
 sclkvalue dist pos frac flag inc ems phs [otherdata]
 sclkvalue dist pos frac flag inc ems phs [otherdata]
 ..
 F2
 sclkvalue dist pos frac flag inc ems phs [otherdata]
 sclkvalue dist pos frac flag inc ems phs [otherdata]
 F3
 F4
 ..
 FN
 END

Where:

FN is a facet identifier that identifies facet number N. Each sclkvalue that meets the distance criteria for facet number N is listed sequentially after the facet identifier. If no sclk values meet the distance criteria, then no values are listed, and the next facet identifier follows on the next line. sclkvalue is the sclk exactly as it appeared in the input file.
dist is a real number that describes the distance of the spot from the center of the facet in units of milliradians.
pos is the position angle of the center of the instrument boresight intersection on the surface measured in degrees from North, with East being 90 degrees.
frac is a real number greater than or equal to 0.0 and less than or equal to 100.0 that describes the fraction of the facet covered by the spot. If the value is 0.0, then the spot does not cover any portion of the facet. If the value is 100.0 then the facet is entirely covered by the spot.
flag is 1 if any portion of the spot does not intersect the surface of Bennu, otherwise it is 0.
inc is the incidence angle in degrees
ems is the emission angle in degrees
phs is the phase angle in degrees
[otherdata] is all textual data on the line following the sclk value, up to the linefeed, unchanged.

NAME

SYNOPSIS

DESCRIPTION

INPUTS

OUTPUT