[Spice_discussion] OEM files
Nat Bachman
Nathaniel.Bachman at jpl.nasa.gov
Fri Apr 23 15:57:55 PDT 2010
Hi William,
NAIF was once upon a time in the business of writing software
for converting between OEMs and SPK files. I don't know if our
programs support the current OEM format. I've attached the
user's guide for OEM2SPK. Let me know if this looks like it will
do the job. I'll be able to give you an executable if you want one;
I'll need to know which platform you're using.
Best regards,
-Nat
Nathaniel.Bachman at jpl.nasa.gov
William Thompson wrote:
> Is there a simple utility to convert OEM files into SPICE kernels? I
> was able to get a rough approximation by editing the OEM files by
> hand, but something more automated would be useful.
>
-------------- next part --------------
OEM2SPK User's Guide
===========================================================================
Last revised on 2007 MAR 29 by N. J. Bachman.
Abstract
--------------------------------------------------------
OEM2SPK is a utility program that converts a CCSDS ``Orbit Ephemeris
Message'' text file (also referred to as an ``OEM'' or ``OEM file'') to
a binary SPICE SPK file containing type 9 or type 13 segments.
Summary
--------------------------------------------------------
OEM2SPK is a SPICE-based utility program that converts a CCSDS
``Ephemeris Message'' text file (referred to as an ``OEM'' or ``OEM
file'' below) to a binary SPICE SPK file containing type 9 or type 13
segments. This SPK file is constructed according to the DAF (Double
precision Array File) architecture.
OEM2SPK requires as inputs an OEM file, a SPICE leapseconds kernel, and
a setup file containing commands that control OEM2SPK's operation.
The user may optionally specify a text file containing descriptive text
to be placed in the comment area of the SPK file. (Doing this is highly
recommended.)
For documentation purposes the contents of the OEM2SPK setup file are
automatically placed at the end of the comment area of the SPK file.
Usage
--------------------------------------------------------
The command syntax of OEM2SPK is as follows:
epm2spk [-setup <setup file name>]
[-input <input data file name>]
[-output <output SPK file name>]
[-append]
[-h|-help]
[-t|-template]
[-u|-usage]
[-v|-version]
Invoking OEM2SPK with the -u flag will cause OEM2SPK to write this
syntax summary to standard output.
If a setup file name isn't provided on the command line, the program
will prompt for it. It will not prompt for the input or output file
names -- these must be provided on the command line or in the setup
file. If input and output file names are provided on the command line,
any file names assigned using setup keywords are ignored.
The input file must already exist.
If the -append key or the corresponding setup file keyword is not
specified, the output SPK file must not exist prior to running the
program. The output file will be created with the name specified after
the -output key on the command line, or if this specification is
omitted, the name specified in the setup file via the OUTPUT_SPK_FILE
keyword.
If the -append key or the corresponding setup file keyword is provided
and the SPK file specified after the -output key exists, then new data
will be appended to it.
If the -append key or the corresponding setup file keyword is provided
but the SPK file specified after the -output key doesn't exist, then a
new SPK file will be created.
Caution: if the program fails for any reason, it in most cases deletes
the output file, even if it was appending data to an existing SPK file.
Therefore, users should always make a backup copy of an SPK file to
which new data are going to be appended before running the program in
append mode.
Also, the program cannot append data to an existing SPK file if its
format is not native to the platform on which the program is running.
Refer to the CONVERT User's Guide for details.
Execution of OEM2SPK
--------------------------------------------------------
You will need a setup file to execute the OEM2SPK utility program. The
format for the setup file is described below.
As it executes, the program will display program version information,
then silently perform the conversion.
During normal execution, each OEM data block will be converted to an SPK
segment of type 9 or 13, depending on the interpolation method specified
in the OEM metadata block preceding the data block. The interpolation
degree is also specified in the metadata block.
At the end of the program's execution, the program will report
successful completion with an ``All done'' message. If the conversion
fails, error diagnostic information will be written to standard output.
Setup File Format and Contents
--------------------------------------------------------
Other than the input and output file names, and the optional append
flag, all of which may occur on the command line, the program requires
all inputs such as leapseconds kernel and comment file names, SPK time
bounds, etc. to be provided in a setup file. The format of this file
must conform to the SPICE text kernel specification. This implies that
input values must be assigned to keyword variables using the format
KEYWORD = VALUE
Each assignment is restricted to a single line. Sets of these
assignments must be enclosed between
\begindata
\begintext
tokens, each of which must also be placed on a line by itself. Free-form
descriptive/explanatory text may occur after the
\begintext
token. Still more assignments could follow another
\begindata
token.
The names of the setup file keywords must be strictly uppercase while
the standard values (e.g. names of reference frames) of keywords may be
upper, lower or mixed case. Any white space preceding or following
keyword names, values and equal sign is ignored.
All character string values and time strings must be enclosed in single
quotes, provided on a single line and be no longer than 80 characters.
When multiple values are allowed and used, enclose the complete set in
the "()" characters: KEYWORD = ( 'value1', 'value2', 'value3' ... ).
Commas separating multiple values are optional.
All assignments are either required, conditional, or optional as
described below.
A setup file may contain blank lines. Non-printing characters including
TAB should not be used in a setup file. The program may not be able to
parse correctly setup file lines that contain non-printing characters.
Required Assignments
The following assignment must be present in a setup file:
LEAPSECONDS_FILE = 'leapseconds file name'
The following assignments are required in the setup file if their values
are not provided on the command line:
INPUT_OEM_FILE = 'input OEM file name'
OUTPUT_SPK_FILE = 'output SPK file name'
Conditional Assignments
STRING_MAPPING = ('first input value', 'first mapped value',
'second input value','second mapped value',
... )
Optional Assignments
COMMENT_FILE = 'Comment file name'
START_TIME = 'SPK start time'
STOP_TIME = 'SPK stop time'
INTERPOLATION_METHOD = 'HERMITE' or 'LAGRANGE'
INTERPOLATION_DEGREE = one of {3, 7, 11, 15} if interpolation
method is HERMITE; one of {1, 3, ... , 15}
if interpolation method is LAGRANGE
MINIMUM_SPACING = Minimum valid time tag spacing in seconds
MAXIMUM_SEP_QUOTIENT = maximum allowed value of
(t3-t2)/(t2-t1) and (t2-t1)/(t3-t2) for
consecutive time tags t1, t2, t3
APPEND_TO_OUTPUT = 'YES' or 'NO'
Detailed Description of Setup File Keywords
--------------------------------------------------------
LEAPSECONDS_FILE This is the SPICE LSK file name, including
full or relative path specification.
INPUT_OEM_FILE Name of the CCSDS ``ephemeris message'' or
``OEM'' input file. If the OEM file name is
supplied on the command line, this keyword
is optional, and the name supplied on the
command line supersedes the name associated
with this keyword, if present in the setup
file.
OUTPUT_SPK_FILE Name of the SPICE SPK output file. If the
SPK file name is supplied on the command
line, this keyword is optional, and the
name supplied on the command line
supersedes the name associated with this
keyword, if present in the setup file.
STRING_MAPPING The user may control interpretation of
values read from the metadata blocks of the
OEM file via a ``string mapping'' feature
provided by the setup file. This capability
allows the user to substitute specified
values for the ones seen on the
right-hand-sides of ``keyword=value''
assignments in the metadata blocks.
The syntax for the mapping assignment is:
STRING_MAPPING = (
'first input value',
'first mapped value',
'second input value',
'second mapped value',
...
)
In the example below, the reference frame
name `EME 2000' is mapped to the string
`J2000':
STRING_MAPPING = ('EME 2000','J2000')
This mapping causes OEM2SPK to interpret
the assignment
REF_FRAME = EME 2000
as
REF_FRAME = J2000
The scope of the mapping is restricted to
the values associated with the metadata
keywords
OBJECT_NAME
REF_FRAME
CENTER_NAME
COMMENT_FILE Comment file name. This keyword is used if
you want to include comments provided in
this file in the comment area of the SPK
file. Include path if needed.
START_TIME SPK start time. The coverage of the output
SPK file will start at the greater of this
time and the start time of the OEM file.
The time value must be a string having a
format recognized by the SPICELIB routine
STR2ET. The time value must be enclosed in
single quotes.
STOP_TIME SPK stop time. The coverage of the output
SPK file will end at the lesser of this
time and the end time of the OEM file. The
time value must be a string having a format
recognized by the SPICELIB routine STR2ET.
The time value must be enclosed in single
quotes.
INTERPOLATION_METHOD This indicates the default interpolation
method to be applied to the discrete, input
state data to create an ephemeris defined
on one or more time intervals. The default
method is used only for OEM data blocks
whose metadata don't specify an
interpolation method. A default
interpolation degree should be specified
along with the default method. Supported
values are 'LAGRANGE' and 'HERMITE'. If
Lagrange interpolation is specified, any
segments in the output SPK file for which
the default method is used will have SPK
data type 9. If Hermite interpolation is
specified, any such segments will have SPK
data type 13.
If the output SPK file is to be used for
DSN metric predict generation, Hermite
interpolation must be selected. If the OEM
file contains metadata blocks indicating a
different interpolation method, the OEM
file must be modified before it will be
usable for metric predicts generation.
See the SPK Required Reading (spk.req) for
a detailed discussion of SPK data types 9
and 13.
INTERPOLATION_DEGREE This is the default degree of the
interpolating polynomials used by the SPK
reader software. The default degree is used
only for OEM data blocks whose metadata
don't specify an interpolation method. The
degree should be one of {3, 7, 11, 15} if
the interpolation method is Hermite; it
should be one of {1, 3, ... , 15} if the
interpolation method is Lagrange. These
choices enforce continuity of position and
velocity within the segments of the output
SPK file.
If the output SPK file is to be used for
DSN metric predict generation, one of the
degrees {3, 7, 11, 15} must be selected. If
the OEM file contains metadata blocks
indicating a different interpolation
degree, the OEM file must be modified
before it will be usable for metric
predicts generation.
Data blocks containing too few states to
support interpolation of the specified
degree are mapped to segments with the
largest valid degree possible for the
number of states.
MINIMUM_SPACING Minimum valid OEM time tag spacing in
seconds. Time tags located too close
together may cause extreme loss of
precision in the interpolation algorithms
used by the SPK system. If consecutive time
tags within a data block have spacing less
than the minimum spacing limit, OEM2SPK
will signal an error and delete the output
file.
If a minimum spacing limit is not specified
in the setup file, a default value of 1
millisecond is used.
MAXIMUM_SEP_QUOTIENT The maximum allowed value of
(t3-t2)/(t2-t1) and (t2-t1)/(t3-t2) for
consecutive time tags t1, t2, t3. When the
relative sizes of the intervals between
consecutive time tags differ too greatly,
extreme loss of precision in the
interpolation algorithms used by the SPK
system may result. If a sequence of three
consecutive time tags within a data block
have separation ratios exceeding the
specified limit, OEM2SPK will signal an
error and delete the output file.
If a maximum separation quotient is not
specified in the setup file, a default
value of 100 is used.
APPEND_TO_OUTPUT Optional flag specifying whether it's
permitted to append new segments to an
existing SPK file. This keyword can have
one of these two values: 'YES' if segments
can be appended and 'NO' if appending
segments is not permitted. If this keyword
is not present, the program assumes the
value 'NO'. An -append flag specified on
the command line overrides either value of
this keyword.
Setup File Examples
--------------------------------------------------------
Simple setup files
This example creates an SPK file containing segments whose default
interpolation method is 'HERMITE' (corresponding to the SPK data type
13) and whose default interpolation degree is 11. Note that these values
are used only to process OEM data blocks whose associated metadata don't
specify an interpolation method.
The reference frame name ``EME 2000'' in the OEM file is mapped to the
name ``J2000.''
\begindata
LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker'
INTERPOLATION_METHOD = 'HERMITE'
INTERPOLATION_DEGREE = 11
STRING_MAPPING = ( 'EME 2000', 'J2000' )
\begintext
This example creates an SPK file containing segments whose default
interpolation method is 'LAGRANGE' (corresponding to the SPK data type
9) and whose default interpolation degree is 7. Note that these values
are used only to process OEM data blocks whose associated metadata don't
specify an interpolation method.
The reference frame name ``EME 2000'' in the OEM file is mapped to the
name ``J2000.''
\begindata
LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker'
INTERPOLATION_METHOD = 'LAGRANGE'
INTERPOLATION_DEGREE = 7
STRING_MAPPING = ( 'EME 2000', 'J2000' )
\begintext
Limiting time coverage
We modify the first example above to limit the time coverage to the day
October 9, 2003 (TDB).
\begindata
LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker'
INTERPOLATION_METHOD = 'HERMITE'
INTERPOLATION_DEGREE = 11
STRING_MAPPING = ( 'EME 2000', 'J2000' )
START_TIME = '2003 OCT 9 00:00:00 TDB'
STOP_TIME = '2003 OCT 10 00:00:00 TDB'
\begintext
Screening out numerically problematic data
We modify the example above so that an error will be signaled if time
tags in the input OEM file are too close together. Catching the problem
at this point will likely lead to a shorter debugging process than would
be possible if the problem were allowed to propagate into the output SPK
file.
In this setup file, we instruct OEM2SPK to reject the input file if two
consecutive time tags within a data block are less than 0.1 seconds
apart.
\begindata
LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker'
INTERPOLATION_METHOD = 'HERMITE'
INTERPOLATION_DEGREE = 11
STRING_MAPPING = ( 'EME 2000', 'J2000' )
START_TIME = '2003 OCT 9 00:00:00 TDB'
STOP_TIME = '2003 OCT 10 00:00:00 TDB'
MINIMUM_SPACING = 0.1
\begintext
In this setup file, we add to the previous example file the restriction
that any three consecutive time tags in a block not have a separation
quotient greater than 10. The term ``separation quotient'' refers to the
maximum of (t3-t2)/(t2-t1) and (t2-t1)/(t3-t2) for consecutive time tags
t1, t2, t3. Large separation quotients can lead to degraded accuracy of
Hermite or Lagrange polynomial interpolation.
\begindata
LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker'
INTERPOLATION_METHOD = 'HERMITE'
INTERPOLATION_DEGREE = 11
STRING_MAPPING = ( 'EME 2000', 'J2000' )
START_TIME = '2003 OCT 9 00:00:00 TDB'
STOP_TIME = '2003 OCT 10 00:00:00 TDB'
MINIMUM_SPACING = 0.1
MAXIMUM_SEP_QUOTIENT = 10
\begintext
Description of Input OEM File
--------------------------------------------------------
OEM Format
The format of the OEM file read by OEM2SPK must conform to the CCSDS
ephemeris message specification
CCSDS Orbit Data Messages Blue Book, version CCSDS 502.0-B-1,
September, 2004.
For the reader's convenience, a fragment of an example OEM file is shown
below. Because of space limitations, not all of the file is shown. The
comments copied from the input SPK file are represented by an ellipsis
symbol. Also, each state vector consists of six components written with
identical formats; only the first and part of the second position
components are shown. Only the first two metadata blocks and
corresponding data blocks are shown.
CCSDS_OEM_VERS = 1.0
CREATION_DATE = 2003-05-14T23:03:44.185268
ORIGINATOR = JPL
...
META_START
OBJECT_NAME = MER-1
OBJECT_ID = -253
TIME_SYSTEM = TDB
REF_FRAME = EME 2000
CENTER_NAME = MARS BARYCENTER
START_TIME = 2003-12-29T18:33:34.13505481
STOP_TIME = 2003-12-30T09:49:23.43617127
INTERPOLATION = HERMITE
INTERPOLATION_DEGREE = 15
META_STOP
2003-12-29T18:33:34.13505381 -0.10150125908348599E+07 0.67097 ...
2003-12-29T21:36:43.99527752 -0.99432835829362448E+06 0.65712 ...
2003-12-30T00:39:53.85550120 -0.97364075022932014E+06 0.64327 ...
2003-12-30T03:43:03.71572488 -0.95294972768552462E+06 0.62942 ...
2003-12-30T06:46:13.57594859 -0.93225524712366960E+06 0.61557 ...
2003-12-30T09:49:23.43617227 -0.91155725999004336E+06 0.60172 ...
META_START
OBJECT_NAME = MER-1
OBJECT_ID = -253
TIME_SYSTEM = TDB
REF_FRAME = EME 2000
CENTER_NAME = MARS BARYCENTER
START_TIME = 2003-12-30T09:49:23.43617527
STOP_TIME = 2004-01-02T03:18:07.48962345
INTERPOLATION = HERMITE
INTERPOLATION_DEGREE = 15
META_STOP
2003-12-30T09:49:23.43617427 -0.91155725998601958E+06 0.60172 ...
2003-12-30T19:10:38.30095273 -0.84811255086536938E+06 0.55925 ...
2003-12-31T04:31:53.16573119 -0.78463242340936360E+06 0.51677 ...
2003-12-31T13:53:08.03050965 -0.72111419899827824E+06 0.47427 ...
2003-12-31T23:14:22.89528807 -0.65755418764822988E+06 0.43174 ...
2004-01-01T08:35:37.76006653 -0.59394726299135527E+06 0.38919 ...
2004-01-01T17:56:52.62484499 -0.53028619144541258E+06 0.34660 ...
2004-01-02T03:18:07.48962345 -0.46656052193974855E+06 0.30397 ...
...
Restrictions on OEM Contents
-- Spacing of successive time tags within a data block must be
sufficient to allow the polynomial interpolation algorithms
used in the SPK system to function normally. Extreme loss of
precision in time, represented as a count of seconds past J2000
TDB, will result from time tags spaced too closely.
Note that for epochs within several decades of J2000, IEEE
double precision floating point numbers can represent seconds
past J2000 to about the level of 1.E-7 seconds. So differences
of successive tags one second apart are represented with
approximately single precision accuracy.
OEM2SPK checks the time tag spacing in the input OEM file. The
default minimum spacing value is 1 millisecond; users can reset
this value using the MINIMUM_SPACING keyword in the setup file
(see the setup file description above). The input file will not
be processed if successive time tags are seen having spacing
less than the limit.
-- When the relative sizes of the intervals between consecutive
time tags differ too greatly, extreme loss of precision in the
interpolation algorithms used by the SPK system may result.
The term ``separation quotient'' refers to the maximum of
(t3-t2)/(t2-t1) and (t2-t1)/(t3-t2) for consecutive time tags
t1, t2, t3. OEM2SPK checks the separation quotient for each
sequence of three consecutive time tags within each data block
in the input OEM file. The default maximum separation quotient
value is 100; users can reset this value using the
MAXIMUM_SEP_QUOTIENT keyword in the setup file (see the setup
file description above). The input file will not be processed
if successive time tags are seen having separation quotient
exceeding the limit.
-- OEM data blocks must always contain at least two states.
OEM data blocks need not contain as many states as are required
for interpolation using the method and degree specified in
their associated metadata blocks or in the setup file. See the
discussion below regarding reduction of interpolation order.
Description of Output SPK File
--------------------------------------------------------
SPK Comment Area
OEM2SPK appends comments to the comment area of the output SPK file. The
additions are:
-- The contents of a comment file, if any, specified in the setup
file.
-- The run time and date, the names of the setup, input, and
output files, and an indication of whether the output file was
new or appended to.
-- The contents of the setup file.
If OEM2SPK is commanded to append its output to an existing file, the
new comments added by OEM2SPK will appear at the end of the comment area
of the SPK file.
Mapping of OEM Data Blocks to Segments
The discussion below applies to segments created by translating data
from the input OEM file. Since the SPK data resulting from the
translation may be appended to an existing SPK file, the resulting file
may contain segments of any data type.
The output SPK file will contain one or more SPK segments for each OEM
data block. All of these segments will have data type 9 or 13, according
to the interpolation method specified in their associated metadata
blocks or in the setup file.
When a data block is mapped to multiple segments, the segments will be
constructed (padded with additional states at the boundaries) so that
the SPK interpolation algorithms will behave as though the block had
mapped to one large segment.
The partitioning of the output SPK data into segments will prevent
interpolation across OEM data block boundaries.
Recommended Interpolation Method and Order
Normally, the interpolation method and order are given by metadata in
the input OEM file. However, the interpolation order must satisfy
several constraints:
-- For Hermite interpolation, the degree must be odd and be in the
range 3:15.
-- For Hermite interpolation, it is strongly recommended that the
degree be one of the values {3,7,11,15}. (These degrees are
equivalent to 3 mod 4.)
The basis of this recommendation is that the SPK type 13
interpolation scheme uses a ``sliding window'' technique: for a
given epoch at which the ephemeris is to be interpolated, a
sequence of consecutive time tags called a ``window'' is
selected such that the request epoch is ``centered,'' to the
extent possible, within the window. States corresponding to the
window of time tags are then interpolated to produce a state at
the request time.
When the interpolation degree is equivalent to 3 mod 4, as the
request time varies, the switch from one window to the next is
constrained to occur at epochs of states from the OEM file;
hence position and velocity are continuous. For other degrees,
the switch-over points occur midway between time tags from the
OEM file, and position and velocity will generally be
discontinuous, though the discontinuities may be small.
For SPK files to be used by the DSN for metric predict
generation, it is essential to select Hermite interpolation and
interpolation degree equivalent to 3 mod 4.
-- For Lagrange interpolation, the degree must be in the range
1:15. It is strongly recommended that the degree be odd; this
is due to the same continuity considerations as described above
for Hermite interpolation.
Reduction of Interpolation Order
OEM data blocks are permitted to contain fewer than the nominal number
of states corresponding to the specified interpolating polynomial
degree. When such blocks are encountered, OEM2SPK will create segments
having reduced polynomial degree. The maximum degree consistent with the
interpolation method will be selected.
When Lagrange interpolation is used, if the nominal number of states
required is N, and n < N states are available, the polynomial degree
will be n-1.
When Hermite interpolation is used, if the nominal number of states
required is N, and n < N states are available, the polynomial degree
will be 2n-1.
Note that the resulting degree may not belong to the set
{3, 7, 11, 15}
for Hermite interpolation or
{1, 3, ..., 15}
for Lagrange interpolation. The discontinuity problems caused by degrees
outside of these sets cannot occur in segments containing fewer than the
nominal number of states.
More information about the Spice_discussion
mailing list