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
