Setting up ISIS data for a new mission¶
Every spacecraft camera that ISIS supports requires a directory in the ISIS data area. It stores the camera position, orientation, sensor properties, etc.; data that is later added to an image to process with spiceinit. This page documents how to set up such a directory for a new mission, with the Chandrayaan-2 Lunar orbiter data serving as an example.
The environmental variable ISISDATA points to the top-most directory in the ISIS data area. We will create there the subdirectory ${ISISDATA}/chandrayaan2, and inside of it there will be a directory named kernels that will have the above-mentioned metadata, which in the planetary data community is called SPICE kernels.
The kernels directory has subdirectories with names such as spk, ck, ik, etc., whose meaning will be discussed shortly. Each of these must have one more index files, in plain text, with a name such as kernels.0000.db, that enumerates the SPICE kernels and some of their properties. This file name normally has four digits, and the number gets incremented if there is more than one index.
For spk and ck kernels, ISIS3 provides a dedicated tool called kerneldbgen. For the others, this index file needs to be set up manually.
SPK kernels¶
SPK stands for Spacecraft Position Kernels. They contain the ephemeris (position and velocity) information for spacecraft, planetary bodies, etc. The kernels usually have the .bsp extension. Create the directory:
and copy there these files. Run a command as:
cd ${ISISDATA}/chandrayaan2/kernels/spk
kerneldbgen \
to = '$chandrayaan2/kernels/spk/kernels.????.db' \
type = SPK \
recondir = '$chandrayaan2/kernels/spk' \
reconfilter = 'ch2*.bsp' \
lsk = '$base/kernels/lsk/naif????.tls'
Determining kernel patterns for kerneldbgen
Determining the right patterns usually requires specific knowledge about the instruments. Some missions have files such as ckinfo.txt and spkinfo.txt that contains information on the qualities includes in the directory and what patterns they follow. If you are making a new configuration, you mostly care about patterns for reconstructed kernels, which are usually in ckinfo.txt and spkinfo.txt. See an LRO example where reconstructed kernels are described.
It is very important to use single quotes above, not double quotes, so that the shell does not expand these variables. This also ensures relative paths are created, rather than absolute ones specific to a given file system.
This will create an index file such as kernels.0000.db. Before rerunning this command, delete any existing .db files, unless adding information complementary to existing ones, as otherwise new entries will be made.
Save this command to a shell script in the current directory named makedb, so that it keeps a record of how the index was produced. See also the makedb script for other datasets, for comparison.
CK kernels¶
CK (Spacecraft Pointing Kernels) contain the attitude (orientation) information for the spacecraft and its instruments. The command for assembling the index file for this is very similar.
cd ${ISISDATA}/chandrayaan2/kernels/ck
kerneldbgen \
to = '$chandrayaan2/kernels/ck/kernels.????.db' \
type = CK \
recondir = '$chandrayaan2/kernels/ck' \
reconfilter = 'ch2*.bc' \
sclk = '$chandrayaan2/kernels/sclk/ch2_sclk_v1.tsc' \
lsk = '$base/kernels/lsk/naif????.tls'
FK Kernels¶
FK (Frame Kernels) define reference frames that are not intrinsically defined by SPICE (like spacecraft frames or instrument frames) and establish relationships between them. They are crucial for transforming data between different coordinate systems.
Navigate to your mission's FK kernel directory (for example, $ISISDATA/chandrayaan2/kernels/fk). Create a file named kernels.0000.db with content like this, listing your .tf (Text Frame) files:
Object = Frame
Group = Selection
File = ("chandrayaan2", "kernels/fk/ch2_v01.tf")
EndGroup
EndObject
IK Kernels¶
IK (Instrument Kernels) provide detailed information about the instrument's physical properties, such as focal length, pixel scale, and lens distortion models.
Go to $ISISDATA/chandrayaan2/kernels/ik. Create a file named kernels.0000.db with content along the lines of:
Object = Instrument
Group = Selection
Match = ("Instrument", "InstrumentId","IIR")
File = ("chandrayaan2", "kernels/ik/ch2_iir_v01.ti")
EndGroup
Group = Selection
Match = ("Instrument", "InstrumentId","OHRC")
File = ("chandrayaan2", "kernels/ik/ch2_ohr_v01.ti")
EndGroup
Group = Selection
Match = ("Instrument", "InstrumentId","TMC-2")
File = ("chandrayaan2", "kernels/ik/ch2_tmc_v01.ti")
EndGroup
EndObject
It is very important to have the precise name of each instrument, and to ensure the proper .ti files are passed in.
Consider also inspecting the analogous files for other missions.
SCLK Kernels¶
SCLK (Spacecraft Clock Kernels) contain the mapping between the spacecraft's internal clock time (SCLK) and ephemeris time (ET).
Navigate to your mission's SCLK kernel directory (e.g., $ISISDATA/chandrayaan2/kernels/sclk). Create a file named kernels.0000.db with content like this, listing your .tsc (Text Spacecraft Clock) files:
Object = SpacecraftClock
Group = Selection
File = ("chandrayaan2", "kernels/sclk/ch2_sclk_v1.tsc")
EndGroup
EndObject
IAK Kernels¶
IAK (Instrument Addendum Kernels) provide additional, instrument-specific information that is not typically found in standard IK files. This can include subtle detector characteristics, advanced distortion models, or unique calibration parameters.
For Chandrayaan2 data, such kernels were not supplied and needed to be guessed.
Navigate (or create) your mission's IAK kernel directory (e.g., $ISISDATA/chandrayaan2/kernels/iak). Create a file named kernels.0000.db with content like:
Object = InstrumentAddendum
Group = Selection
Match = ("Instrument","InstrumentId", "TMC-2")
File = ("chandrayaan2", "kernels/iak/ch2_tmc_iak_v01.ti")
EndGroup
EndObject
Ensure that the instrument id and .ti files are correctly specified. If no .ti entries exist, omit the Match and File entries.
Other kernels¶
There exist a few kernels that apply to all missions, and are usually stored in the $ISISDATA/base/kernels directory. These include LSK (Leapsecond Kernels), PCK (Planetary Constants Kernels), and EK (Event Kernels). These should normally already exist in the data area.
Record the new dataset¶
Add an entry of the form::
to isis/IsisPreferences in the ISIS source directory for future uses, and to the local version of this file in the installation directory for current use. Ensure that the entry is in the DataDirectory group, as for other missions.