sumspice

Overview

This program allows the user to update a cube's labels, spaceraft attitude (pointing) and position with the information found in a corresponding Gaskell SUMFILE. SUMFILEs are a product of Gaskell's stereo photoclinometry (SPC) digital elevation model (DEM) generation process. SUMFILEs are generated for each file included in the processing to generate the DEM.

Part of the SPC DEM processing flow is to control all the images. The SUMFILE is a direct product from the SPIC control process that (typically) corresponds to a single file. The SUMFILE contains updates to pointing attitude and spacecraft position, among other things. The contents of the SUMFILE and their purpose are described below.

The objective of this program is to (optionally) apply timing changes (as seen in Hayabusa 1 images), pointing and spacecraft updates directly to ISIS cubes. This provides ISIS users the ability to apply consistent control to ISIS images that have corresponding SUMFILEs and use the DEM generated from the SPC process for orthorectiifed cartographic mapping processes in ISIS. This includes creating CK and SPK kernels from the result of this application for more widely distributed use of SPC results.

Here is an example of the contents of a Gaskell SPC SUMFILE (NOTE: Line numbers are not part of the SUMFILE but are annotated here for documentation purposes which follows):

  1   W46908480918
  2   2014 NOV 12 17:20:03.128
  3     2048  2048   500 65535                                       NPX, NLN, THRSH
  4       0.1356800000D+03    0.1044000000D+04    0.9380000000D+03   MMFL, CTR
  5      -0.9665063720D+01    0.1326644487D+02   -0.6673084308D+01   SCOBJ
  6      -0.6442479111D+00   -0.1829032409D-01    0.7645979944D+00   CX
  7       0.5935707119D+00    0.6184779444D+00    0.5149357652D+00   CY
  8      -0.4823053379D+00    0.7855892670D+00   -0.3875965231D+00   CZ
  9       0.7254908676D+00   -0.3292717307D+00    0.6043534796D+00   SZ
 10     74.07410   0.00000   0.00000   0.00000  74.07410   0.00000   K-MATRIX
 11     0.00000D+00    0.00000D+00    0.00000D+00    0.00000D+00   DISTORTION
 12     0.1007758363D-02    0.1482813397D-02    0.8902614968D-03   SIGMA_VSO
 13     0.3071768580D-04    0.3093941486D-04    0.1565302183D-04   SIGMA_PTG
 14 LANDMARKS
 15 AO0001   2049.39    668.15
 16 AO0002   2020.70    644.81
 17 AO0003   2035.17    708.66
 18 BD0009   1902.39    884.05
 19 BD0010   1891.13    909.86
 20    ...
 21 EK0022    675.73   1371.97
 22 EQ0088    721.76    738.13
 23 FI0002    727.77    220.40
 24 LIMB FITS
 25 END FILE
    

The lines of a Gaskell SUMFILEs are described as:

• Line 1: An ID for the SUMFILE (occasionally, but not always, the image name).
• Line 2: The potentially corrected start, center or stop time in UTC for the image.
• Line 3: The number of pixels, the number of lines, the lower DN threshold, and the upper DN threshold.
• Line 4: The focal length (in mm), followed by the pixel center and the line center (i.e. boresight/optical axis).
• Line 5: The vector from the spacecraft to the object center (i.e. the spacecraft position in body fixed coordinates).
• Line 6: The pixel (x) unit vector, in body fixed coordinates.
• Line 7: The line (y) unit vector, in body fixed coordinates.
• Line 8: The boresight (z) unit vector, in body fixed coordinates.
• Line 9: The sun direction unit vector, in body fixed coordinates.
• Line 10: The k matrix
• Line 11: Used to contain distortion information, but it is always zero now.
• Line 12: The formal spacecraft position uncertainty , ie. the sigma VSO.
• Line 13: The formal spacecraft orientation uncertainty , ie. the sigma PTG.
• Line 14-23: A list of landmarks containing the ID, pixel sample center, and pixel line center.
• Line 24+: A list of limb fits containing the landmark-on-limb centers.
• Line 25: Last line of a Gaskell SUMFILE ends with the END FILE statement.

Usage

sumspice has been used to apply Gaskell SPC control to Hayabusa Itokawa AMICA images. There is up to 12 seconds of uncertainty in the start times of these images. The Hayabusa team improved the start time with brute force comparisons of the position of Itokawa in the AMICA field of view. The SUMFILEs contained the correction of the start time. Unfortunately, the PDS archive of the AMICA data has not been updated with the new start times. This was the motivation behind adding support for the start time adjustment.

The basic processing options are to update the start times (UPDATE=TIMES) and pointing (CK) (UPDATE=POINTING) and spacecraft position (SPK) (UPDATE=POSITION) data in the ISIS label/file with that contained in the SUMFILE. Both the pointing and spacecraft position can be updated in the same run (UPDATE=SPICE). And, finally, it may be useful to start over by resetting the times to their original values - UPDATE=RESET provides this option (and removes the SumTimeHistory and disables SPICE requiring a rerun of spiceinit.

To apply the complete functionality of sumspice, the start time must be updated first if required. Note that it is rather uncommon the start time will need to be updated. If it needed/desired, the UPDATE=TIMES option will recompute the SpacecraftClockStartTime, which is used primarily by most camera models for best accuracy of image acquisition times. This option will force a rerun of spiceinit after observation times are updated mainly to reestablish the body orientation and solar illumination angles for the new start time. This option will reassign computed values, relative to the SUMFILE reference time (see SUMTIMES) to SpacecraftClockStartCount, SpacecraftClockStopCount, StartTime and StopTime label keywords. Most camera models use at least one of these values to establish observation times. These times are used to associate the correct ephemeris data from SPICE kernels.

The update of pointing attitude and spacecraft position requires spiceinit to be applied to the image. This operation will update the InstrumentPointing and InstrumentPosition Tables in the label of the ISIS cube with the contents of the Gaskell SUMFILE. Note that SUMFILEs contain vectors in body-fixed format, so you must ensure the proper PCK is used with the image. NAIF routines are used to apply any required transformations to retain the integrity of the data. Once the fidelity of the updates are confirmed, new CK and SPK kernels can be created using the ISIS ckwriter and spkwriter applications, respectively.

Activity Tracking

sumspice does supply some aid in tracking its activity in the ISIS label. When timing is updated, there is a group called SumTimeHistory that is created upon the first operation pertaining to changes that were made to the timing keywords (typically) in the Instrument group in the ISIS label. Four keywords are affected by timing operations in sumspice. These are SpacecraftClockStartCount, SpacecraftClockStopCount, StartTime, and StopTime. The first two keywords, SpacecraftClockStartCount and pacecraftClockStopCount, are in the form of spacecraft clock, or SCLK, format. Manipulation of these two keywords requires the existance of an ISIS camera model to determine the appropriate SCLK NAIF id for conversion from UTC (as stored in the SUMFILE, line 2) to SCLK. The later two keywords, StartTime, and StopTime, are conversions of the times to UTC. These keywords are only updated if they exist in the Instrument group in the ISIS label.

When any of these keywords are updated in the ISIS label, previous values are recorded in the SumTimeHistory group created upon the first run of sumspice that modifies these keywords. Any subsequent run of sumspice that modifies times have previous values appended to the corresponding keywords, thus creating an running history of timing operations and enabling the UPDATE=RESET option to retain original timing values if needed. Using the reset option removes the SumTimeHistory group. Here is an example of the SumTimeHistory group after an update.

  Group = SumTimeHistory
    # SUMFILE(s) used to update the SCLK timing in the instrument group (SPC).
    SUMFILE                   = N2395699394
    SpacecraftClockStartCount = 2395694888 <1/32sec>
    SpacecraftClockStopCount  = 2395695365 <1/32sec>
    StartTime                 = 2005-09-21T10:44:07
    StopTime                  = 2005-09-21T10:44:07
  End_Group
    

Note that the TOLOG file, if specified, will also contain a record of the activities that were applied, including the timing values resulting from these operations.

When updating pointing or spacecraft position, a keyword named SUMFILE is added to the InstrumentPointing and InstrumentPosition tables, respectively that records the name of the SUMFILE used to update the ephemeris data in those objects. When spiceinit is run, this table is replaced, thus removing the keyword, indicating original SPICE data is contained in those objects.

SUMTIME Considerations

Regarding the SUMFILE reference time, the SUMTIME parameter is provided for the user to specify that the UTC time in the SUMFILE represents the start, mid or end time of the image exposure time. The following table provides known reference times contained in SUMFILEs for spacecraft/instruments. Knowing the correct reference contained in the SUMFILE is critical to determine the correct SUMFILE for a given ISIS cube and updating the ISIS labels with the time and ephemeris data contained therein.

SUMFILE SUMTIME References

Spacecraft	Instrument	Reference
Hayabusa 1	AMICA	Start
Dawn	FC	Center (Note: Dawn FC has a 193 ms delay from start time)
OSIRIS-REx	OCAMS (MapCam, SamCam, PolyCam)	Center
MESSENGER	MDIS	Center

Processing Sequences

Here is an example that shows the commonly used command sequence for the Hayabusa AMICA instrument. This process will update times and ephemeris data, which includes pointing and spacecraft position.

# First transfer the SUMFILE timing to the ISIS cube labels
sumspice from=st_2395699394_v.lev0.cub sumfile=N2395699394.SUM  update=times sumtime=start  tolog=haya_amica.log

# Now rerun spiceinit as a timing update forces this
spiceinit   from=st_2395699394_v.lev0.cub shape=user model='$hayabusa/kernels/dsk/hay_a_amica_5_itokawashape_v1_0_512q.bds'

# Finally, apply the pointing and spacecraft position update in a single run
sumspice from=st_2395699394_v.lev0.cub sumfile=N2395699394.SUM  update=spice sumtime=start  tolog=haya_amica.log
      

Description

The name of a single input cube whose labels will be updated using a Gaskell SUMFILE. Note: Use the FROMLIST parameter instead of this one if there are multiple cubes to process.

Type	cube
File Mode	input
Default	None
Exclusions	FROMLIST
Filter	*.cub

Description

A text file containing a list of input cubes whose labels will be updated using Gaskell SUMFILEs. Note: Use the FROM parameter instead of this one if there is only one cube to process.

Type	filename
File Mode	input
Default	None
Exclusions	FROM

Description

The name of a single Gaskell SUMFILE containing time and SPICE information. Note: Use the SUMFILELIST parameter instead of this one if the exact SUMFILE that should be used to update the cube(s) is unknown or if there are more than one.

Type	filename
File Mode	input
Default	None
Exclusions	SUMFILELIST
Filter	*.SUM

Description

A text file containing a list of Gaskell SUMFILEs that each contain time and SPICE information. Note: Use the SUMFILE parameter instead of this one if the desired SUMFILE is known for the given cube(s).

Type	filename
File Mode	input
Default	None
Exclusions	SUMFILE
Filter	*.lis

Description

If a name is provided, the results of each cube file is written to the specified file.

Type	filename
File Mode	output
Default	None
Filter	*.log

Description

This parameter is provided to explicity specify what the time in the SUMFILE represents. Typically, this is the start time (default) but not always. The user must make this determination.

This may be important when searching for the SUMFILE associated with the ISIS cube when using the times from each source. sumspice will make adjustments based upon this value and the exposure duration as found in the ISIS cube file label.

Type	string
Default	CENTER
Option List:	Option Brief Description START Time contained in SUMFILE refers to start time The UTC time stored in the SUMFILE refers to the start time of the observation. CENTER Time contained in SUMFILE refers to center of the exposure time The UTC time stored in the SUMFILE refers to the center of the exposure time of the observation. STOP Time contained in SUMFILE refers to end of the exposure time The UTC time stored in the SUMFILE refers to the stop time of the observation. This option is not common but may be used so is added for completeness.

Description

Determines which elements of the ISIS cube to update with the appropriate SUMFILE contents. Note that there are input requirements for each option. if a SUMFILELIST was provided, the program will search for the file in the given list whose time is within the specified TIMEDIFF tolerance and is the closest to the SpacecraftClockStartCount in the cube. If multiple files in the SUMFILELIST have the same time, this program will choose to use the first one in the list with the closest time. If no SUMFILE is found within this tolerance, a warning will be printed to the output log and the program will exit without updating the input cube.

Type	string
Default	SPICE
Option List:	Option Brief Description NONE Essentailly a NOOP, but does determine cube/SUMFILE pairings If the NONE option is selected, the program will only determine which SUMFILE applies to each cube. This option is useful as a dryrun to ensure the pairings are good. You can also get a useful output log in TOLOG that will provide timing information. TIMES Update the start and end times in the ISIS cube label. If the TIMES option is selected, the program will update the UTC StartTime/EndTIme and SpacecraftClockStartCount/SpacecraftClockStopCount ISIS cube Instrument group. The UTC on the second line of the SUMFILE will replace the StartTime value in the cube's Instrument group. The ExposureDuration in the label is then used to find the new StopTime. These new start/stop time values are used to determine the new SpacecraftClockStartCount and the new SpacecraftClockStopCount. The original values of these keywords and the SUMFILE used to update the keywords will be saved in the cube's Archive group. Note that this option will effectively require spiceinit to be ran after it completes. sumspice forces this by disabling existing geometry (by removing the NaifKeywords object and some keywords in the Kernels group). Changing start times will change positions of the spacecraft and target body. A rerun of spiceinit will update these relative positions. This step should be applied prior to using any other option of this application. SPICE Update the InstrumentPosition and InstrumentPointing tables in the cube file If the SPICE option is selected, the program will search for the SumFile keyword in the cube's Archive group. If no such keyword exists or if the SumFile saved to the labels is not found in the given SUMFILELIST, a warning will be printed to the output log and the program will exit without updating the SPICE tables. Otherwise, the spacecraft position and pointing information will be updated using the information provided in the matching SUMFILE. This option is equivalent to running both the POINTING and POSITION option. POINTING Update the InstrumentPointing tables in the cube file. If the POINTING option is selected, the program will update only the spacecraft pointing SPICE information with the data contained in the SUMFILE. The file must have be ran through spiceint previous and the SPICE data must be attached as a Table in the ISIS cube (i.e., spiceint must have ATTACH=TRUE) POSITION Update the InstrumentPosition tables in the cube file If the POSITION option is selected, the program will update only the spacecraft position SPICE information with the data contained in the SUMFILE. The file must have be ran through spiceint previous and the SPICE data must be attached as a Table in the ISIS cube (i.e., spiceint must have ATTACH=TRUE) RESET Resets the timing to original times This option has been added to essentially reset the timing adjustments that were made back to the original values. This is to prevent one having to start over completely with a new version of the file. This will preserve any processing that has taken place. This option will use the keywords in the SumtimeHistory group that record all timing sumspice operations that have taken place on the file to reset all existing keywords in the Instrument group related to observation timing. The final act of this option will also remove the SumtimeHistory group and disable SPICE operations until a run of spiceinit is made.

Description

This value is always considered to specify the time differential when looking for matching SUMFILES. This tolerance is used when both the SUMFILE and SUMFILELIST are given to constrain the difference in observation times contained in the cube label and the SUMFILE. If no value is provided, then the default behavior is to choose the SUMFILE that has the closest time as specified in SUMTIME to the corresponding time contained in cube label, assertained in conjunction with the camera model.

Note that it is critical to provided a tolerance value here if known (e.g., ~12 seconds for Hayabusa/AMICA) so that the correct SUMFILE is determined.

Type	double
Internal Default	INFINITY

Description

In some cases, additional kernels may be required in order to compute some of the data acquired from the NAIF toolkit. If the ISIS labels do not contain sufficient kernels, this parameter can specify a NAIF meta kernel, or a single kernel of any supported NAIF type that will be loaded prior to any computations. These kernels remain loaded for all files and for the entirety of the runtime of this application. See SPICE Kernel Required Reading for additional information about NAIF meta kernels.

Type	filename
File Mode	input
Default	None
Filter	*.meta *.tm