ckwriter

ckwriter produces a NAIF compatible SPICE CK kernel 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 but this is not required.

The contents of the CK kernel are extracted from the ISIS InstrumentRotation Table (BLOB) in the ISIS file. This table is 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 (i.e., rotated) into the proper reference frames utilized by each mission/instrument. These frames are specified in each ISIS instrument-specific camera model implementation and will vary from mission to mission.

Users may provide one or more ISIS cube files to the application. Each file is written to the CK 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 is recorded in the kernel comment section. A general description of the CK kernel contents is provided by the application but the user can provide their own comment for the kernel if it is not sufficient in the COMFILE parameter.

Each image is checked for overlap in start/end time ranges. 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 CK kernel is not created. However, if the user chooses, they can be treated as warnings and the TO output CK kernel will be generated in this case. It is up to the user to determine if this is intended/valid behavior.

Provided in every CK 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 CamVersion value listed refers to the version of the ISIS camera model in use at the time the CK 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 the resulting CK kernel:

 ****************************************************************************
  USGS ISIS (ckwriter) Generated CK Kernel
  Created By:   kbecker
  Date Created: 2010-12-07T01:27:42
****************************************************************************
 
Orientation Data in the File
-----------------------------------------------------------------------
 
      This file contains orientation and potentially derived angular
      rates (where possible/specified).
 
 
Status
-----------------------------------------------------------------------
 
      This kernel was generated for the purpose of storing C-Smithed
      pointing updates generated through ISIS processing techniques
      (control nets, jitter analysis, etc...).  These CK kernels
      are intended to mimick CKs provided by individual mission
      (NAV teams).
 
Pedigree
-----------------------------------------------------------------------
 
      This file was generated by an automated process.  The ISIS
      application ckwriter was used to read CK kernel data
      contained within an ISIS cube file.  It then writes it as an
      individual segment in the CK.  Hence, a list of files can be
      written to a single CK kernel.  However, mixing the instruments
      contained in a single CK kernel is discouraged.
 
      Individual segments coming from files will have a single record
      written for the center of the exposure (time) for framing
      instruments or a record/image line for line scan instruments.
 
      Creating type 3 CK kernels must contain at least 3 records for
      framing instruments to avoid roundoff error for the center of the
      exposure time of an image.  Framing instruments should pad time
      using the spiceinit application options.
 
 
Angular Rates
-----------------------------------------------------------------------
 
      This kernel may or may not contain angular velocity vectors. Efforts
      are made to preserve and provide angular velocities where they
      originally existed.
 
 
Usage Note
-----------------------------------------------------------------------
 
      To make use of this file in a typical SPICE based application,
      you must supply a leapseconds kernel, a mission spacecraft clock
      kernel, and the instrument/spacecraft frame kernel.  These files
      provide the supporting ancillary data to properly query this
      C-kernel for attitude content.  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 CK 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:       PSP_001446_1790_RED2_0.cub
  ProductId:  PSP_001446_1790_RED2_0
  StartTime:  2006-11-17T03:27:53.211
  EndTime:    2006-11-17T03:27:54.912
  Instrument: HIRISE
  Target:     Mars
  InstrFrame: MRO_SPACECRAFT
  RefFrame:   MRO_MME_OF_DATE
  Records:    18
  HasAV:      YES
  CamVersion: 1
  Kernels:
    $mro/kernels/spk/mro_psp1.bsp
    $mro/kernels/ck/mro_sc_psp_061114_061120.bc
    $mro/kernels/fk/mro_v14.tf
    $base/kernels/spk/de405.bsp
    $base/kernels/pck/pck00009.tpc
    $mro/kernels/ik/mro_hirise_v11.ti
    $mro/kernels/iak/hiriseAddendum006.ti
    $base/kernels/lsk/naif0009.tls
    $mro/kernels/sclk/MRO_SCLKSCET.00041.65536.tsc
    $base/dems/molaMarsPlanetaryRadius0004.cub
      

Contents of the comment section in the CK kernel may include comments provided by the user in a file specified by the COMFILE parameter if desired.

To extract the contents of the SPICE CK 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 systems at the location 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 CK 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 CK SPICE kernel in the TO file requires the NAIF utility program, commnt.

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

spiceinit from=PSP_001446_1790_RED2_0.cub CK=PSP_001446_1790_RED2_0.bc

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 above HiRISE spiceinit example is not representative of how every mission instrument would use the CK kernels produced by ckwriter. MESSENGER MDIS is one known variation.

MESSENGER has three differnet CK kernels that are used in spiceinit . The somewhat complex nature of how these kernels are determined when spiceinit is run is hidden from the user in the kernel database backend. The CK kernel produced by ckwriter replaces two of these kernels (attitude history and daily kernels). The pivot kernel is still required in addition to the kernel produced by ckwriter. This requires special consideration when running spiceint using these kernels.

MESSENGER MDIS pivot kernels are of the form MMMMMMMMMM_CCCCCC_mdis_pivot_pvtres.bc where the "M"s are numerical representations of mission elasped time (MET) and the "C"s are the number of images covered in the pivot kernel. It is sufficient to select the latest version of the pivot kernel (as it is for all MESSENGER kernels except daily CKs) as new entries are added to previous versions and redistributed by the MESSENGER team.

Here is a T/C shell example showing how to apply a CK kernel produced by ckwriter on MESSENGER MDIS images that are covered in the kernel:

ckwriter from=EN0131771668M.cub to=EN0131771668M.bc
set extra = ls -1t $ISISDATA/messenger/kernels/ck/*_mdis_pivot_pvtres.bc | head -1
spiceinit from=EN0131771668M.cub ck=EN0131771668M.bc extra=$extra        
        

Note that this form of the spiceinit command can only be used on ckwriter kernels. The normal form must be used on images that do not contain coverage in the ckwriter produced kernels (unless they are formally incorporated into ISIS as a "smithed" kernel set).

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 quaternions 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 or have images separated into even/odd image lines (e.g., LROC WAC) 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 orientation for the same time coverage. In this case, two runs of ckwriter 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

This file is optional and its contents will be added to the output CK SPICE kernel file specified by the TO parameter. Comments contained in this file will be included in the the generic comment under the heading User Comments. 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 ck_kernel.bc where ck_kernel.bc is a NAIF CK SPICE kernel file. If no COMFILE is provided, a line containing "NONE" is written to the output CK file.

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

Description

Name of the output NAIF CK SPICE kernel that will be generated from the input file list. This format will be consistant with the NAIF spice kernel format for type 3 (continuous). 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	*.bc

Description

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

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

Description

CKTYPE allows the user to specify which type of kernel to create. Valid values are 1-5 for CK kernels. However, at this time, this application only supports type 3 kernels. Please see the NAIF CK reference for additional information regarding these kernel types.

Type	integer
Default	3
Minimum	3 (inclusive)
Maximum	3 (inclusive)

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 CK file is generated. WARNING will log the images with overlaps and the output TO CK kernel is still generated.

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