SPKMERGE User's Guide

SPKMERGE builds new SPK files by merging entire or subsets of one or more existing SPK files. SPKMERGE creates SPK kernels that have no overlapping ephemeris.

SPKMERGE reads all its input from a command file. A command file is an ASCII formatted file that you must supply.

Command file syntax

Inputs are specified in a command file by using assignments. The rules for forming assignments are listed here.

-- An assignment must start on a line by itself. A keyword must appear first, followed by an equals sign, followed by a value.

-- Keywords are not case sensitive---they may appear in upper, lower, or mixed case.

-- Spaces and tabs are ignored, except for those embedded within values.

-- Values may extend over multiple lines. No continuation characters are necessary.

-- A semi-colon signals the beginning of a comment. All characters following a semi-colon on a line are ignored.

-- Values must not exceed 300 characters.

-- Some assignments must be present in the command file, while others are optional.

-- Most assignments can only follow certain other assignments.

-- All assignments have restrictions on the number of times they can appear in the command file.

Command file keywords

A command file must contain at least these three keywords:

   LEAPSECONDS_KERNEL
   SPK_KERNEL
   SOURCE_SPK_KERNEL

   LOG_FILE
   BEGIN_TIME
   END_TIME
   BODIES
   INCLUDE_COMMENTS

leapseconds_kernel

The value of this keyword must be the name of a SPICE leapseconds kernel file. This assignment must be present, and is usually the first assignment in the command file. If the leapseconds kernel does not reside in the current directory, remember to include the directory path of the file, as shown in this example:

   leapseconds_kernel  = /kernels/lsk/naif0004.tls

spk_kernel

The value of this keyword must be the name of the SPK file that SPKMERGE is to create. After this assignment, the names one or more source SPK files must be listed by using the `source_spk_kernel' assignment.

Multiple SPK files can be created by SPKMERGE by repeating this assignment.

source_spk_kernel

The value of this keyword must be the name of an existing SPK file that you want to merge into a new SPK file. Multiple SPK files can be merged into a new SPK file by repeating this assignment. Before you name the files you want to merge, you must have previously specified the name of a new SPK kernel by using the `spk_kernel' assignment.

The sample command file below instructs SPKMERGE to create one SPK file by merging three existing SPK files in their entirety.

   leapseconds_kernel  = /kernels/lsk/naif0003.tls
 
   spk_kernel          = complete.bsp
     source_spk_kernel = planets.bsp
     source_spk_kernel = gll_1.bsp
     source_spk_kernel = gll_2.bsp

bodies

This keyword is optional. If present, it restricts which bodies are merged. This keyword can appear in one of two places: after a `source_spk_kernel' assignment, or before the first `source_spk_kernel' assignemt. In the former case, the keyword lists the bodies that should be merged from a specific source SPK file; in the latter case, the keyword lists the bodies that should be merged from source SPK files that do not have specific bodies mentioned. A body listed in this asignment does not have be contained within the source SPK file(s) the asignment applies to. Remember that SPKMERGE will not create a file that has overlapping data, so even if an SPK kernel contains a body you list, it may not necessarily be merged.

The bodies must be given as NAIF body IDs; the IDs may be delimited by spaces or commas.

Here, only bodies 10, 399 and 301 will be merged from `planets.bsp'. The other two files will be merged in thier entirety---assuming no overlapping data.

   leapseconds_kernel  = /kernels/lsk/naif0003.tls
 
   spk_kernel          = complete.bsp
     source_spk_kernel = planets.bsp
       bodies          = 10, 399, 301
     source_spk_kernel = gll_1.bsp
     source_spk_kernel = gll_2.bsp

   leapseconds_kernel  = /kernels/lsk/naif0003.tls
 
   spk_kernel          = complete.bsp
     bodies            = 10, 399, 301, -77
     source_spk_kernel = planets.bsp
     source_spk_kernel = gll_1.bsp
     source_spk_kernel = gll_2.bsp

begin_time, end_time

These two keywords operate just like the `bodies' keyword, except they restrict times instead of bodies. The `end_time' keyword must immediately follow the `begin_time' keyword. Together, these keywords represent a time window. Multiple windows can be specified by repeating these two asignments. Times must be in UTC. Below are a few examples.

   leapseconds_kernel  = /kernels/lsk/naif0003.tls
 
   spk_kernel          = complete.bsp
     source_spk_kernel = planets.bsp
       begin_time      = 1 JAN 1994 00:00:00.000
       end_time        = 1 JUL 1994 00:00:00.000
     source_spk_kernel = gll_1.bsp
       begin_time      = 1 JAN 1994 00:00:00.000
       end_time        = 1 JUL 1994 00:00:00.000
     source_spk_kernel = gll_2.bsp
       begin_time      = 1 JAN 1994 00:00:00.000
       end_time        = 1 JUL 1994 00:00:00.000

   leapseconds_kernel  = /kernels/lsk/naif0003.tls
 
   spk_kernel          = complete.bsp
     begin_time        = 1 JAN 1994 00:00:00.000
     end_time          = 1 JUL 1994 00:00:00.000
     source_spk_kernel = planets.bsp
     source_spk_kernel = gll_1.bsp
     source_spk_kernel = gll_2.bsp

log_file

If this keyword present, it instructs SPKMERGE to create a log file. This keyword can only follow an `spk_kernel' assignment. A log file created by SPKMERGE will contain a list of all the SPK files that were used to create an SPK file, including all the times and all the bodies. The log file will be in the form of a command file, so it can be used as such if the need arises. An exact copy of the log file is always placed in the comment area of an SPK file created by SPKMERGE.

include_comments

If this keyword present, it can only have a value of `YES' or `NO' (upper or lower case), and it can only follow a `source_spk_kernel' assignment. If the value of this keyword is affirmative, the comment area of the source SPK file named prior to this assignment is merged into the new SPK file, otherwise it is not. The default action is not to merge the comment area of a source SPK file.

Running SPKMERGE

SPKMERGE will prompt for the name of the command file when you start the program. Alternately, you can name the command file as the first argument on the command line.