ISIS Documentation

spiceinit

Update SPICE data (kernels, pointing, and position) for a camera cube

This program searches the ISIS data areas in order to discern the SPICE kernels required for the camera cube. Cubes which have supported camera models in the ISIS system require spacecraft position, pointing, body shape and orientation, sun position, and other information in order to compute ground positions (latitude/longitude) and photometric viewing angles. This information is stored in SPICE kernels.

The program uses the "SpacecraftName", "InstrumentId", "TargetName", "StartTime", and "StopTime" keywords from the cube's label to determine which kernels to use. It attempts to find kernel files for the following keywords and writes them to the Kernels group:

  • Leap Second (LS)
  • Spacecraft Clock (SCLK)
  • Target Position (TSPK)
  • Target AttitudeShape (PCK)
  • Instrument (IK)
  • Instrument Addendum (IAK)
  • Frame (FK)
  • Spacecraft Position (SPK)
  • Instrument Pointing (CK)
  • Shape Model (DEM)
If you are unfamilar with SPICE terminology it is recommended you read the NAIF required reading at http://naif.jpl.nasa.gov/naif/doc_C.html

The program modifies the kernels group and writes the name of the SPICE files that need to be loaded by the camera models. It has the option of pre-reading the data from the SPICE kernels and loading it as a binary table attached to the cube. This can faciliate faster load times and allows the instrument pointing to be easily updated.

As kernels are loaded they override the data in previously loaded kernels. The order in which kernels are loaded is:

  1. Target Position
  2. Instrument Position
  3. Instrument Pointing
  4. Frame
  5. Target Attitude Shape
  6. Instrument
  7. Instrument Addendum
  8. Leap Second
  9. Spacecraft Clock
  10. Extra
The spiceinit program will always try to use the highest quality kernels possible. This only applies to kernels that are not specified manually. The kernel qualities are, from best to worst:
  1. Smithed
    2. This is considered the best quality kernel and will be used first when selected. Smithed kernels have been improved or adjusted for accuracy by a mission team or for the purpose of a cartographic product. Consider the source, content and completeness of Smithed kernels when selecting this level of quality.
  2. Reconstructed
    3. These kernels are typically produced by a mission a few weeks after the target has been reached.
  3. Predicted
    4. These are preliminary kernels produced by a mission and are the best-estimates of where the spacecraft will be at any given time.
  4. Nadir
    5. This is the worst quality kernel and is used as a last resort because it assumes the spacecraft is always nadir-looking.

The InstrumentPositionQuality and InstrumentPointingQuality keywords are added to the Kernels group to indicate the level of quality of the loaded kernels. At least one of the parameters CKPREDICTED, CKNADIR, CKRECON, or CKSMITHED must be entered. Furthermore, at least one of the parameters SPKPREDICTED, SPKRECON, or SPKSMITHED must be entered.

Please note: Kernel Files specified that reside in the current working directory will not have their paths expanded. This is to allow variables like $msg/ to work correctly.

The spiceinit program will also add the RayTraceEngine, OnError, and Tolerance keywords to the Kernels group if specified in the IsisPreferences file. If included, these keywords specify the ray-tracing engine to use and how to use it for shapemodels. Please see the IsisPreferences file for more details.

Troubleshooting: If spiceinit is failing with the error "No Camera Kernel found for the image ..." then try enabling the "CKPREDICTED" or "CKNADIR" option. A similar error exists for SPK kernels, and you can enable "SPKPREDICTED" to get past that error. "PREDICTED" and "NADIR" options typically have less accuracy than reconstructed and smithed kernels which is why they are disabled by default.

Issues running HRSC using ISIS SPICE Web Service: Currently HRSC images cannot be spiceinit'd using ISIS SPICE web services. This is due to the HRSC camera model relying on cube data to process line scan times. When using the SPICE server, only the label is returned causing the camera model to fail initialization. In order to run spiceinit on HRSC images, download the MEX data locally. See download instructions at https://github.com/DOI-USGS/ISIS3/blob/dev/README.md#mission-specific-data-downloads.

Categories

Related Applications to Previous Versions of ISIS

This program replaces the following applications existing in previous versions of ISIS:
  • levinit
  • naiflab
  • spicelab

History

Debbie A. Cook2000-06-08 Original Version
Stuart Sides2003-11-05 Complete rewrite under ISIS 3.0 conversion.
Stuart Sides2004-01-14 Modified to use an existing "Kernels" group instead of creating a new one. This was because the mission specific import program (e.g., moc2isis) was modified to create the "kernels" group and put the "NaifFrameCode" into it.
Stuart Sides2004-01-23 Added new parameter "TEST." This parameter controls the testing of the final kernel list. If false the kernels will not be tested for completeness by creating a camera model.
Stuart Sides2004-02-23 Added elevation model DEM capabilities.
Stuart Sides2004-02-24 Completed capabilities to search for kernels of different qualities such as PREDICTED, NADIR, RECONSTRUCTED, and C-SMITHED.
Stuart Sides2005-11-08 Added fix for framing cameras, so they would not need a stop time in the instrument group of the labels.
Elizabeth Miller2005-11-14 Added appTest
Jacob Danton2005-12-22 Added support for multiple files within the kernels
Jacob Danton2005-12-27 Added a progress bar
Jacob Danton2006-01-03 Fixed the xml description
Jacob Danton2006-01-25 Changed the mission translation file name
Jacob Danton2006-01-25 Changed the appTest to comply with changes in the String class.
Jeff Anderson2006-03-27 Modified to write InstrumentPointing, InstrumentPosition, SunPosition, and BodyRotation information to SPICE tables in the cube.
Brendan George2006-09-19 Added call to modify the history of the cube
Brendan George2006-10-19 Modifed to remove label entries for SPICE tables, if ATTACH is unchecked, and the input cube already has them.
Steven Lambright2007-07-10 Combined Frame and InstrumentPointing. Changed to support new version of KernelDb. Cleaned up the code.
Steven Lambright and Steve Koechle2007-07-10 Fixed problem where the allowed kernels were being set improperly.
Steven Lambright2007-08-10 Fixed so that when no spacecraft pointing is found, but frame kernels are, and Nadir is allowed it still adds the Nadir keyword.
Steven Koechle2007-10-05 Added a check to see if the cube had an existing polygon, if so delete it.
Steven Koechle2007-10-25 Fixed Smithed enum, changed from C-Smithed.
Steven Koechle2007-12-14 Added error handling logic. If the user chose to use Nadir CK and another type, and the system found a file where the image falls in a gap (no pointing is available) Nadir would never be calculated. Fixed.
Steven Lambright2008-02-13 Added time padding options
Steven Lambright2008-02-21 Added additional explanation of time padding options
Steven Lambright2008-02-22 Split the CK parameter into FK and CK, they are still combined in the label as InstrumentPointing.
Steven Lambright2008-04-14 All found CK kernels will now be tested before giving an error
Christopher Austin2008-05-02 Fixed the propagation of the EXTRA Kernel.
Steven Lambright2008-05-12 Removed references to CubeInfo
Steven Lambright2008-05-19 Fixed documentation
Christopher Austin2008-06-03 Furthered documentation.
Steven Koechle2008-06-17 Added CK check and throw more appropriate error
Christopher Austin2008-09-12 Added the removal of StartPadding and EndPadding keywords from previous spiceinit runs, and added some double inited tests. NOTE: Whenever adding new keywords, run spiceinit twice on the same cube in your test, dumping out both labels to verify that the keyword is not being duplicated.
Tracie Sucharski2009-03-12 If spice is put into a Table, append the kernel name to the Kernel group keyword to keep track of original spice kernels.
Steven Koechle2009-05-12 Added CameraVersion into the Kernel labels
Steven Lambright2009-07-09 Error messages from the camera are now reported
Steven Lambright2009-07-21 Fixed handling of user-entered CK kernels
Janet Barrett and Steven Lambright2011-05-25 Added support for storing text spice kernel values in the cube labels
Steven Lambright and Jai Rideout2011-08-30 Added support for using a spiceinit web service
Steven Lambright2011-10-05 As a result of our test and review team, I have updated the documentation to match the recommendations of Laz Kestay and Ken Edmundson. Fixes #423.
Jai Rideout2011-11-18 Fixed bug in writing tables to the cube that were retrieved from the web service.
Debbie A. Cook2012-07-06 Updated Spice members to be more compliant with ISIS coding standards. References #972.
Jeannie Backer2013-02-26 Added ability to load multiple ck database files from the system using a conf file. Changed methods to lower camel case to comply with Isis3 standards. Added web example. References #924.
Tammy Becker2014-03-31 Made a few documentation modifications regarding kernel quality keywords and shapemodel keyword. References #1849.
Kimberly Oyama2014-04-27 Added assets directory for web example. Updated Documentation. Fixes #1849.
Tyler Wilson2016-12-19 Changed the URL for the spice server to https://services.isis.astrogeology.usgs.gov/cgi-bin/spiceinit.cgi and the default port to 443 (it was originally 80). This is due to the recent https migration implementation from within the Department of the Interior, which was causing people on the outside of the DOI network to get an unrecognized server response error when attempting to download spice data. Fixes #4552.
Christopher Combs2017-06-01 Removed examples with links leading to missing images. Created two new examples: one with default settings and another with a user-chosen ShapeModel.
Kristin Berry2017-06-06 Updated spiceinit to retain ShapeModel-related keywords set by the ShapeModelFactory and add them to the kernel group. Like other keywords in the kernels group, if they are present at the beginning of a spiceinit run (if we are re-spiceiniting) they are removed.
Kristin Berry2017-08-06 Updated spiceinit to remove code dealing with the CubeSupported Pvl Keyword, from the ShapeModel group in the IsisPreferences file, which has been removed.
Christopher Combs2018-01-11 Made change to camera construction error throw for better reporting on uninstantiated cameras. Fixes #5163.
Jesse Mapel2020-02-26 Changed PCK selection to use the same qualities as CK so that target body parameters derived from bundle adjustment can be used alongside CKs derived from bundle adjustment. Fixes #3669.
Jesse Mapel2020-12-10 Modified to remove state string and model information from the csminit application.
Kaitlyn Lee2020-12-21 Updated shape model keyword in the kernels group when shape=user and web=true with the user specified model. Fixes #1986
Kaitlyn Lee2020-12-22 Moved writeHistory() call to main function because a history entry was only being written to the cube when using a data area for kernels (not using the web service). Fixes #4040.
Adam Paquette2021-08-10 Fixed the NaifKeywords PvlObject not being updated/replaced when spiceinit with web=true was run on a cube that was already spiceinit'd.