Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions


ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation


kerneldbgen

Standard View | TOC | Home

Creates a database of kernels

Description
Categories
Groups
Examples
History


Description

This program is used to give the programmer and ISIS programs a database with which they can reference coverage times for ck and spk kernels. Output will thus be to a pvl file specified in the TO parameter. It should be noted that the user is encouraged to use system preferences when defining pathnames, for example $mgs or $base. If this is not possible, for example kernels are being referenced that are located in a user's development area, absolute pathnames should be used. Relative pathnames using ".", "..", or user-defined environment variables are highly discouraged.

Kernels have different qualities. The lowest quality is nadir, which supplies what may be considered "placeholder" values. Generally, nadir kernels exist to fill in gaps and mimic the instrument pointing at -90 degrees. Since they only mimic pointing data, they cannot be used for SPKs, since these kernels specify positions rather than pointing.

The second lowest quality kernel is predict. Predict kernels are based on the predicted location of spacecraft and thus are subject to error.

Reconstructed kernels are of higher quality than predicts. They are supplemented with information as to the actual position of bodies and spacecraft.

The highest quality kernels are smithed. These generally come from reconstructed kernels that have been corrected even further by an individual institution.

The four levels of kernels listed above are the only ones that will be listed in the database. Kernels are ordered from the lowest quality at the top of the output file to the highest quality at the bottom of the output file within individual kernel qualities, kernels are listed from earliest to latest created file. This is done in anticipation of programs such as spiceinit which read from the bottom of the file for the best kernel.


This program's database is in pvl format, and as such order is significant. The last listed kernel file covering the timespan will be used. Because of this in combination with the individual needs of specific missions, ISIS arrays can be used to control kernel file order.

      For example, using the pure string expression:

      "m01_sc_ext??_rec_nadir.bc ; m01_sc_ext??.bc"

      would result in the listing:

      m01_sc_ext10.bc
      m01_sc_ext10_rec_nadir.bc
      m01_sc_ext11.bc
      m01_sc_ext11_rec_nadir.bc
      m01_sc_ext12.bc
      m01_sc_ext12_rec_nadir.bc
      m01_sc_ext13.bc
      m01_sc_ext13_rec_nadir.bc

          while using the ISIS array expression:

          ("m01_sc_ext??_rec_nadir.bc", "m01_sc_ext??.bc")

          would result in the listing:

      m01_sc_ext10_rec_nadir.bc
      m01_sc_ext11_rec_nadir.bc
      m01_sc_ext12_rec_nadir.bc
      m01_sc_ext13_rec_nadir.bc
      m01_sc_ext10.bc
      m01_sc_ext11.bc
      m01_sc_ext12.bc
      m01_sc_ext13.bc
    


Categories


Related Objects and Documents

Applications


Parameter Groups

Files

Name Description
TO Location of the output file

Kernel Type

Name Description
TYPE Kernel type

Coverage Level

Name Description
LEVEL The level of time-granularity for the time-coverage interval to be output to the SPICE database.

Predict

Name Description
PREDICTDIR Directory where the predict quality kernels are located
PREDICTFILTER Filter to identify predict quality kernels
PREDICTLIST Prioritized list of predict quality kernels

Reconstructed

Name Description
RECONDIR Directory where the reconstructed quality kernels are located
RECONFILTER Filter to identify reconstructed quality kernels
RECONLIST Prioritized list of reconstructed quality kernels

Smithed

Name Description
SMITHEDDIR Directory where the smithed quality kernels are located
SMITHEDFILTER Filter to identify smithed quality kernels
SMITHEDLIST Prioritized list of smithed quality kernels

Offset

Name Description
STARTOFFSET Seconds to subtract from each start time in the kernel.
ENDOFFSET Seconds to add to each end time in the kernel.

Dependency Kernels

Name Description
SCLK Spacecraft clock kernel
LSK Leapsecond kernel
EXTRA Other kernels

Files: TO

Description

This parameter may be used as a relative pathname to specify the location of an output PVL database containing data on all of kernels matched by kerneldbgen. It should be noted that version sequences may be included in the pathname, in which case a new version will be created.

Type filename
Default ./kernels.????.db

Kernel Type: TYPE

Description

The kernel type specifies what sort of information the kernel contains. Since kerneldbgen is intended for use only in situations where the most recent kernel does not eclipse the content of previous kernels, there are only two options: Spacecraft pointing kernels (CK) and Spacecraft position kernels (SPK).

Type string
Default CK
Option List:
Option Brief Description
CK Spacecraft pointing kernels The kernels to be listed in the output database will include spacecraft pointing data. In order to properly calculate times, a spacecraft clock kernel (SCLK) and leapsecond kernel (LSK) must also be furnished via the dependency kernel group below.
SPK Spacecraft position kernels The kernels to be listed in the output database will include spacecraft position data. Unlike calculations for pointing data, only the leapsecond kernel (LSK) needs to be provided.

Exclusions

  • SCLK

Coverage Level: LEVEL

Description

Type string
Default SEGMENT
Option List:
Option Brief Description
SEGMENT SPICE Segment The coarsest level of time granularity, a SPICE segment is composed of SPICE intervals.
INTERVAL SPICE Interval A finer level of time granularity.

Predict: PREDICTDIR

Description

This parameter specifies the path upon which the regular expression in "PREDICTFILTER" will operate. Since this parameter will be used explicitly in the "File" keyword of the generated database, it is recommended that only shortcuts known to the ISIS system and absolute pathnames are used. If left as "none" no predicted kernels will be included in the database

Type string
Default none

Predict: PREDICTFILTER

Description

This parameter is used to specify the kernel or kernels to be identified as predicted. Any combination of kernel file names or regular expression may be specified. The value of "PREDICTDIR" is prepended to each element before being expanded. Each regular expression is evaluated then the results are sorted according to ASCII order and added to the list of available kernels.

Type string
Default none

Predict: PREDICTLIST

Description

This parameter is used to specify a file list that contains the kernel or kernels to be identified as predicted. The order of the kernels in the file list will be retained with kernels later in the list taking precedence when multiple kernels cover the same time range.

Type filename
File Mode input
Exclusions
  • PREDICTDIR
  • PREDICTFILTER
Filter *.txt *.lis

Reconstructed: RECONDIR

Description

This parameter specifies the path upon which the regular expression in "RECONFILTER" will operate. Since this parameter will be used explicitly in the "File" keyword of the generated database, it is recommended that only shortcuts known to the ISIS system and absolute pathnames are used. If left as "none" no reconstructed kernels will be included in the database.

Type string
Default none

Reconstructed: RECONFILTER

Description

This parameter is used to specify the kernel or kernels to be identified as reconstructed. Any combination of kernel file names or regular expression may be specified. The value of "RECONDIR" is prepended to each element before being expanded. Each regular expression is evaluated then the results are sorted according to ASCII order and added to the list of available kernels.

Type string
Default none

Reconstructed: RECONLIST

Description

This parameter is used to specify a file list that contains the kernel or kernels to be identified as reconstructed. The order of the kernels in the file list will be retained with kernels later in the list taking precedence when multiple kernels cover the same time range.

Type filename
File Mode input
Exclusions
  • RECONDIR
  • RECONFILTER
Filter *.txt *.lis

Smithed: SMITHEDDIR

Description

This parameter specifies the path upon which the regular expression in "SMITHEDFILTER" will operate. Since this parameter will be used explicitly in the "File" keyword of the generated database, it is recommended that only shortcuts known to the ISIS system and absolute pathnames are used. If left as "none" no smithed kernels will be included in the database

Type string
Default none

Smithed: SMITHEDFILTER

Description

This parameter is used to specify the kernel or kernels to be identified as smithed. Any combination of kernel file names or regular expression may be specified. The value of "SMITHED"DIR" is prepended to each element before being expanded. Each regular expression is evaluated then the results are sorted according to ASCII order and added to the list of available kernels.

Type string
Default none

Smithed: SMITHEDLIST

Description

This parameter is used to specify a file list that contains the kernel or kernels to be identified as smithed. The order of the kernels in the file list will be retained with kernels later in the list taking precedence when multiple kernels cover the same time range.

Type filename
File Mode input
Exclusions
  • SMITHEDDIR
  • SMITHEDFILTER
Filter *.txt *.lis

Offset: STARTOFFSET

Description

This parameter is used to specify the amount of offset (in seconds) to apply to the StartTime value for each kernel that is used to populate the db file. This value will be subtracted from the value found in the kernel. If left as 0.0, no offset will be applied, and the Time will be copied over as written in the kernel.

Type double
Default 0.0
Minimum 0.0 (inclusive)

Offset: ENDOFFSET

Description

This parameter is used to specify the amount of offset (in seconds) to apply to the EndTime value for each kernel that is used to populate the db file. This value will be added to the value found in the kernel. If left as 0.0, no offset will be applied, and the Time will be copied over as written in the kernel.

Type double
Default 0.0
Minimum 0.0 (inclusive)

Dependency Kernels: SCLK

Description

This parameter specifies a spacecraft clock kernel for use in determining spacecraft pointing data. An actual kernel may be used, or a pvl file of the form kernels.????.db that specifies SCLK data may be used, where ???? is the version sequence.

Type filename

Dependency Kernels: LSK

Description

This parameter specifies a leapsecond kernel for use in determining spacecraft data. An actual kernel may be used, or a pvl file of the form kernels.????.db that specifies LSK data may be used, where ???? is the version sequence.

Type filename

Dependency Kernels: EXTRA

Description

This parameter specifies additional kernels required to fully vet the CK/SPK kernels. An actual kernel may be used, or a pvl file of the form kernels.????.db that specifies LSK data may be used, where ???? is the version sequence.

Type filename
Internal Default none

Examples


Example 1

Messenger ck kernels

Description

Use the ck option to create a database of spacecraft pointing kernels. In this example, a database is being created for the pivot kernels pertaining to the Messenger spacecraft.

Command Line

kerneldbgen 'to=pivot_kernels.????.db type = ck recondir = $Messenger/kernels/ck reconfilter= *_mdis_pivot.bc lsk = $Base/kernels/lsk/naif0008.tls sclk = $Messenger/kernels/sclk/messenger_167.tsc'
This command line argument will create the database pivot_kernels.0002.db, assuming "0001" is the highest version in the target directory. Note the use of single quotes around the invocation of kerneldbgen. This is done because this particular run uses several characters such as the wildcard (*) that would be interpreted by the shell.

GUI Screenshot

kerneldbgen gui

Example GUI

Screenshot of the GUI with parameters set to create a kernel database of Messenger pivot kernels. Unlike running from the command line, the program need not go through the shell. Consequently, the input does not need to include escape sequences or quotes.

Input Image

The directory before kerneldbgen

List of files before kerneldbgen has been run

Parameter Name: RECONDIR

As seen in this terminal snapshot, there are a number of files that will match the reconfilter in the directory specified by the recondir. The highest pivot_kernels version is 0001.

Output Images

The directory after kerneldbgen

List of files after kerneldbgen has been run

Parameter Name: TO

None of the original files have been altered, but the versioning system has created a new version of the pivot_kernels database named pivot_kernels.0002.db. The content of this file is listed below.

The database file

The database created by kerneldbgen

Parameter Name: TO

As seen here, the database has picked up all of the files that match the filter specified. Each time coverage interval is listed as a selection, and the dependency kernels is listed in a "dependency" group. Note that since the only type of filter specified was for Reconstructed kernels, that is the only type of kernel to appear in the database.


Example 2

MGS CK kernels

Description

Use the ck option to create a database of pointing kernels. In this example, kernels are being created for Mars Odyssey, both predict and reconstructed quality. This example should be of interest because it shows both the creation of a database with multiple levels of quality, and it also shows the use of several different filters used in conjunction to pick up a variety of reconstructed kernel names

Command Line

kerneldbgen 'to=kernels.????.db type = ck reconfilter= *_nadir.bc recondir = $Odyssey/kernels/ck reconfilter= m01_sc_ab*.bc;m01_sc_ext?.bc;m01_sc_map.bc;m01_sc_map?.bc;m01_sc_map??.bc;m01_sc_map?_v2.bc' lsk = $Base/kernels/lsk/naif0008.tls sclk = $Odyssey/kernels/sclk/ORB1_SCLKSCET.00113.tsc'
This command line argument will create the database kernels.0001.db, assuming that file does not already exist in the target directory. As in the previous example, the command line argument is surrounded by single quotes in order to escape characters that would otherwise be considered special by the shell.

GUI Screenshot

kerneldbgen gui

Example GUI

Screenshot of the GUI with parameters set to create a kernel database mixed with nadir kernels and reconstructed kernels.

Input Image

The directory before kerneldbgen

List of files before kerneldbgen has been run

Parameter Name: RECONDIR

As seen in this terminal snapshot, there are a number of files that will match the reconfilter in the directory specified by the recondir. The highest pivot_kernels version is 0001.

Data File

kernels.0001.db Here one can examine the results of the datafile. Note the ascending order of kernel quality.

Output Image

The directory after kerneldbgen

List of files after kerneldbgen has been run

Parameter Name: TO

None of the original files have been altered, but the versioning system has created the first version of the kernel database, kernels.0001.db. The content of this file is listed as well.


History

Drew Davidson2005-08-03 Original version
Drew Davidson2005-08-03 Added relative pathnames to output database
Drew Davidson2005-08-16 Added examples
Elizabeth Miller2005-10-05 Moved from Geometry category to System
Brendan George2005-11-03 Added application test
Elizabeth Miller2005-11-21 Fixed constriction on filename size and fixed bug in appTest
Jacob Danton2005-12-27 Made changes to SpiceDbGen to comply with changes in KernelDb
Brendan George2006-10-05 Modified call to retrieve current time to refer to Time class, instead of Application class
Jeff Anderson2006-10-24 Removed spaces between Spacecraft Clock Count and Leapsecond Kernel keywords
Stuart Sides2006-11-21 Fixed bug where spk and ck kernel files were flagged as "Predict" instead of "Predicted"
Steven Lambright2008-08-01 Fixed bug where some ck kernels could not be loaded due to their size. Also added naif status calls, which will provide easy to read iExceptions to the user instead of a dump to the terminal window when a problem occurs.
Stuart Sides2010-04-27 Modified to use a vector of filters for each quality of kernel instead of a single string
Christopher Austin2011-05-06 Added documentation for ISIS array input.
Steven Lambright2013-02-15 Added the EXTRA option. Also, added basic support for kerneldb files being specified for SCLK/LSK parameters. Fixes #1023.
Stuart Sides2015-03-29 Added three additional decimal places to the output of the TIME keyword in output kernel database file. Fixes #2236.
Christopher Combs2018-01-11 Added STARTOFFSET and ENDOFFSET parameters to allow for slight editing to start and end times. Fixes #5272.
Kristin Berry2018-05-09 Added the LEVEL=(SEGMENT*, INTERVAL) option to specify the time coverage level to be used for the generated database. SPICE segements are made up of SPICE intervals. Segments (the only option in the past) are now the default, but interval can be selected if needed. Fixes #5410.
Jesse Mapel2019-08-13 Added the ability to use a list of kernels instead of a location and filters. Fixes #3390.