ISIS Application Documentation

kerneldbgen

Printer Friendly View | TOC | Home

Creates a database of kernels

Overview

Parameters

Example 1

Example 2

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

History

Drew Davidson	2005-08-03	Original version
Drew Davidson	2005-08-03	Added relative pathnames to output database
Drew Davidson	2005-08-16	Added examples
Elizabeth Miller	2005-10-05	Moved from Geometry category to System
Brendan George	2005-11-03	Added application test
Elizabeth Miller	2005-11-21	Fixed constriction on filename size and fixed bug in appTest
Jacob Danton	2005-12-27	Made changes to SpiceDbGen to comply with changes in KernelDb
Brendan George	2006-10-05	Modified call to retrieve current time to refer to Time class, instead of Application class
Jeff Anderson	2006-10-24	Removed spaces between Spacecraft Clock Count and Leapsecond Kernel keywords
Stuart Sides	2006-11-21	Fixed bug where spk and ck kernel files were flagged as "Predict" instead of "Predicted"
Steven Lambright	2008-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 Sides	2010-04-27	Modified to use a vector of filters for each quality of kernel instead of a single string
Christopher Austin	2011-05-06	Added documentation for ISIS array input.
Steven Lambright	2013-02-15	Added the EXTRA option. Also, added basic support for kerneldb files being specified for SCLK/LSK parameters. Fixes #1023.
Stuart Sides	2015-03-29	Added three additional decimal places to the output of the TIME keyword in output kernel database file. Fixes #2236.
Christopher Combs	2018-01-11	Added STARTOFFSET and ENDOFFSET parameters to allow for slight editing to start and end times. Fixes #5272.
Kristin Berry	2018-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 Mapel	2019-08-13	Added the ability to use a list of kernels instead of a location and filters. Fixes #3390.

U.S. Department of the Interior | U.S. Geological Survey
ISIS | Privacy & Disclaimers | Astrogeology Research Program
To contact us, please post comments and questions on the USGS Astrogeology Discussion Board
To report a bug, or suggest a feature go to: ISIS Github
File Modified: 02/21/2025 19:28:11

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

Close Window

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

Option List:

Option

Brief

Description

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

Close Window

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.

Close Window

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

Close Window

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

Close Window

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

Close Window

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

Close Window

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

Close Window

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

Close Window

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

Close Window

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

Close Window

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

Close Window

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)

Close Window

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)

Close Window

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

Close Window

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

Close Window

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

Close Window

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

Links open in a new window.

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.

Quick Links

Documentation Versions

kerneldbgen

Description

Categories

Related Objects and Documents

Applications

History

Parameter Groups

Files

Kernel Type

Coverage Level

Predict

Reconstructed

Smithed

Offset

Dependency Kernels

Files: TO

Description

Kernel Type: TYPE

Description

Exclusions

Coverage Level: LEVEL

Description

Predict: PREDICTDIR

Description

Predict: PREDICTFILTER

Description

Predict: PREDICTLIST

Description

Reconstructed: RECONDIR

Description

Reconstructed: RECONFILTER

Description

Reconstructed: RECONLIST

Description

Smithed: SMITHEDDIR

Description

Smithed: SMITHEDFILTER

Description

Smithed: SMITHEDLIST

Description

Offset: STARTOFFSET

Description

Offset: ENDOFFSET

Description

Dependency Kernels: SCLK

Description

Dependency Kernels: LSK

Description

Dependency Kernels: EXTRA

Description

Example 1

Description

Command Line

GUI Screenshot

Input Image

Output Images

Example 2

Description

Command Line

GUI Screenshot

Input Image

Data File

Output Image