spkwriter

spkwriter produces NAIF compatible SPICE SPK kernels from one or more ISIS cube files. The cube files must have been initialized with the spiceinit program. They may also have undergone pointing adjustments by jigsaw or some other (bundle) adjustment application.

The contents of the SPK kernels are extracted from the ISIS InstrumentPosition Table (BLOB) in the ISIS file. These Tables are created by the spiceinit application and its contents further modified by ISIS pointing (bundle) adjustments. The contents may not be in a state that can be written directly to the kernel. They must be converted (e.g., rotated/transformed) into the proper reference frames utilized by each mission/instrument. These frames are defined uniquely in each instrument camera model.

Users may provide one or more ISIS cube files to the application. Each file is written to the SPK kernel as its own segment. The ProductId from the ISIS label is used as the NAIF SEGMENT ID. This information, along with other information pertaining to the ISIS file and image data, are recorded in the kernel comment section. A general description of the SPK kernel contents is provided by the application and the user can provide additional comments in a files specified by the COMFILE parameter. Should the user provide a comments file, those comments will be added to the kernel file in a user comment section contained in the default header provided by this application.

Each image is checked for overlap in start/end time ranges involving the same ephemeris body and target. Any files that have common time coverages are identified and reported. Furthermore, the user may select with the OVERLAP parameter how to treat occurances of overlapping time ranges. It seems highly likely that images with common time coverage is a conflict and an error should be generated and the output SPK kernel is not created. However, if the user chooses, they can be treated as warnings and the TO output SPK kernel will be generated in this case. It is up to the user to determine if this is intended/valid behavior.

Provided in every SPK kernel file created is the complete list of all the SPICE kernels, DEMs and extras loaded by spiceinit. In order to ensure the same geometric properties when using this kernel, the same kernels listed for the ISIS file segment must be supplied in any subsequent run of spiceinit. The PolyDergree is the degree of the polynomial used when writing each individual segment to the NAIF SPK kernel. The CamVersion value listed refers to the version of the ISIS camera model in use at the time the SPK data was created. Any subsequent code changes to the ISIS camera model may result in different geometric properties of the image.

The following is an example of the contents of the comment section in an output SPK kernel created by this application:

 ****************************************************************************
   USGS ISIS (spkwriter) Generated SPK Kernel
   Created By:   kbecker
   Date Created: 2011-04-07T22:32:24
 ****************************************************************************
 
 Position Data in the File
 -----------------------------------------------------------------------
 
       This file contains time ordered array of geometric states 
       (kilometers) and rates of change (kilometers/second) of body
       relative to center, specified relative to frame.
 
 
 Status
 -----------------------------------------------------------------------
 
       This kernel was generated for the purposes of storing C-Smithed
       position updates that may have been generated from ISIS processing
       techniques (controlled imaging, jitter analysis, etc...).  These
       SPK kernels are intended to mimick SPKs provided by individual
       missions (or NAV teams).
 

 Pedigree
 -----------------------------------------------------------------------
 
       This file was generated by an automated process.  The ISIS
       application spkwriter was used to read SPK kernel data
       contained within an ISIS cube file.  It then writes it as an
       individual segment in the SPK.  Hence, a list of files can be
       written to a single SPK kernel.  However, mixing the instruments
       contained in a single SPK kernel is discouraged.
 
 
 Angular Rates
 -----------------------------------------------------------------------
 
       This kernel typically contains state vectors of rates of change
       as a function of time but may only contain position vectors.  The
       ephemeris given is for the body moving relative to the center of
       motion.
 
 
 Usage Note
 -----------------------------------------------------------------------
 
       To make use of this file in a typical SPICE based application,
       users must supply at least a leapseconds kernel. This file is
       necessary for time-based conversions.  They should be the same
       kernels that were originally used to initialize the image.
 
       Segments in this file are actually individual ISIS files where the
       internally cached SPICE data is extracted and transformed into the
       appropriate content to satisfy NAIF's SPICE kernel storage
       requirements.  The contents of this kernel are summarized below.
  
        
User Comments
 -----------------------------------------------------------------------
 
         NONE

 Segment (by file) Summary
 -----------------------------------------------------------------------
 
       The follow sections describe each segment in this SPK kernel.  Each
       segment is a file in the input list.  When running ISIS spiceinit,
       the kernels listed for each file should be supplied to ensure proper
       geometry can be reproduced accurately.
 

-----------------------------------------------------------------------
  File:        viking.cub
  Segment ID:  084A14 (ProductId)
  StartTime:   1976-09-13T13:19:51.309
  EndTime:     1976-09-13T13:19:51.315
  Target Body: Body -27, VO1
  Center Body: Body 499, MARS
  RefFrame:    B1950
  Records:     3
  HasVV:       YES
  PolyDegree:  1
  CamVersion:  1
  Kernels:     
    $base/kernels/spk/de405.bsp
    $viking1/kernels/spk/viking1a.bsp
    $viking1/kernels/ck/vo1_sedr_ck2.bc
    $viking1/kernels/fk/vo1_v10.tf
    $base/kernels/pck/pck00009.tpc
    $viking1/kernels/iak/vikingAddendum003.ti
    $base/kernels/lsk/naif0009.tls
    $viking1/kernels/sclk/vo1_fict.tsc
    $viking1/kernels/sclk/vo1_fsc.tsc
    $base/dems/molaMarsPlanetaryRadius0005.cub
    viking.bsp
      

To extract the contents of the SPICE SPK kernel it is recommended you use the SPICE commnt utility. The form of the command to extract the contents is commnt -r PSP_001446_1790_RED2_0.bc. This SPICE utility can be downloaded from NAIF's web site from one of the supported operating system archtectures at ftp://naif.jpl.nasa.gov/pub/naif/utilities.

The SUMMARY parameter is provided as a file name that will contain the comments section of the output SPK kernel file. This can be used in addition to or in lieu of the TO parameter. Getting the contents of the comment section of the NAIF SPK SPICE kernel in the TO file requires the NAIF utility program, commnt .

To use the newly created SPK SPICE kernel in the ISIS environment, you use the spiceinit program providing, at a minimum, the SPK kernel created by spkwriter in the SPK parameter. The basic command would be:

spiceinit from=PSP_001446_1790_RED2_0.cub SPK=PSP_001446_1790_RED2_0.bsp

This would be the best case scenario should all the other kernels listed in the comments be selected. If they are not the same, then you will need to resort to explicitly providing all of them in the spiceinit command line. Here is the command using the above list for PSP_001446_1790_RED2_0:

spiceinit from=PSP_001446_1790_RED2_0.cub
LS='$base/kernels/lsk/naif0009.tls'
PCK='$base/kernels/pck/pck00009.tpc'
TSPK='$base/kernels/spk/de405.bsp'
IK='$mro/kernels/ik/mro_hirise_v11.ti'
SCLK='$mro/kernels/sclk/MRO_SCLKSCET.00041.65536.tsc'
CK=PSP_001446_1790_RED2_0.bc
FK='$mro/kernels/fk/mro_v14.tf'
SPK='$mro/kernels/spk/mro_psp1.bsp'
IAK='$mro/kernels/iak/hiriseAddendum006.ti'
SHAPE=USER
MODEL='$base/dems/molaMarsPlanetaryRadius0004.cub'

The other important thing to note is that when you provide explicit filenames in spiceinit parameters, you typically will be required to give the full path the file. If you do not do this, then camera models cannot properly initialize because it will always look for the file in the current directory. An example command should be spiceinit from=viking.cub EXTRA=$PWD/viking.bsp

See the NAIF website for more information .

Description

Use this option to create a NAIF SPICE kernel from a single ISIS cube. It can be used in conjunction with the FROMLIST option.

Type	filename
File Mode	input
Internal Default	None
Filter	*.cub

Description

This file contains a list of ISIS cubes that will be used to generate SPICE kernels from. Each file is expected to be a level 0 image that has at least had spiceinit run on it. The relevant SPICE positions and velocities are extracted from each file, translated to appropriate coordinates compatible with established mission criteria and written to the specified SPICE kernel file. WARNING- Data from missions with multiple cameras imaging concurrently should not be put into the same kernel unless the concurrent images were treated as a single observation in the bundle adjustment. For instance, a left and right camera imaging concurrently could be considered to be a single observation. If these images are not treated as a single observation in the bundle adjustment, they will likely have different positions/velocities for the same time coverage. In this case two runs of spkwriter would be necessary: one run using only left images and the other run using only right images.

Type	filename
File Mode	input
Internal Default	None
Filter	*.lis

Description

Name of the output NAIF SPK SPICE kernel that will be generated from the input file list. This format will be consistant with the selected NAIF spice kernel format. The kernels should be directly usable as a source for spiceinit on files that fall within the time segments of the input file list.

Type	filename
File Mode	output
Internal Default	None
Filter	*.bsp

Description

SPKTYPE allows the user to specify which type of kernel to create. Valid values are 1 to 18 for SPK kernels. However, at this time, only a limited number of the available types are supported. The primary reason we do not support other types is that many of the other types do not apply to ISIS cube epheremis. Please see the NAIF SPK reference document for additional information regarding NAIF SPK kernel types.

Type	integer
Default	13
Option List:	Option Brief Description 9 Lagrange Interpolation -- Unequal Time Steps The ninth SPK data type represents a continuous ephemeris using a discrete set of states and a Lagrange interpolation method. The epochs (also called `time tags') associated with the states need not be evenly spaced. For a request epoch not corresponding to the time tag of some state, the data type defines a state by interpolating each component of a set of states whose epochs are `centered' near the request epoch. Further details can be found here. 13 Hermite Interpolation -- Unequal Time Steps The thirteenth SPK data type represents a continuous ephemeris using a discrete set of states and a sliding window Hermite interpolation method. The epochs, also called "time tags," associated with the states need not be evenly spaced. For any request epoch, the data type defines a state by interpolating a set of consecutive states, or "window," centered as closely as possible to the request epoch. Interpolated position values are obtained for each coordinate by fitting a Hermite polynomial to the window's set of position and velocity values for that coordinate; interpolated velocity is obtained by differentiating the interpolating polynomials. Further details can be found here.

Description

This file is optional and its contents will be added to the output SPK SPICE kernel file specified by the TO parameter. It may contain additional information that users will be able to see using the NAIF SPICE commnt utility. The command to use to extract the comment from the SPICE kernel file is commnt -r spk_kernel.bsp where spk_kernel.bsp is a NAIF SPK SPICE kernel file.

Type	filename
File Mode	input
Internal Default	None
Filter	*.txt

Description

This file will contain the summarization and documentation that describes contents of the SPK kernel. This can be provided in addition to or in lieu of the output SPK kernel parameter TO. Each segment is sorted by start time of the image. This is the same ordering as the SPK kernel.

Type	filename
File Mode	output
Internal Default	None
Filter	*.txt

Description

This option allows the user to specify how images that contain start/end time overlaps are treat. Users can specify this condition as an error or a warning. Specification of ERROR will result in program termination and no output SPK file is generated. WARNING will log the images with overlaps and the output TO SPK kernel is still generated.

Type	string
Default	ERROR
Option List:	Option Brief Description ERROR Do not allow time overlaps in output SPK kernel This option will treat images that have time overlaps as an error. The output TO SPK kernel will not be generated if this option is specifed and an error is generated. WARNING Allow time overlaps in output SPK kernel This option will treat images that have time overlaps as a warning. The output TO SPK kernel is generated if this option is specifed but the overlapping images are reported in the log file.