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
    

• 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.

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