SPK2OEM User's Guide =========================================================================== Last revised on 2021 DEC 31 by N. J. Bachman. Abstract -------------------------------------------------------- SPK2OEM is a utility program that converts a binary SPICE SPK file to a CCSDS ``Orbit Ephemeris Message'' text file (also referred to as an ``OEM'' or ``OEM file''). Summary -------------------------------------------------------- SPK2OEM is a SPICE Toolkit-based utility program that converts a binary SPICE SPK file to a CCSDS ``Orbit Ephemeris Message'' text file which conforms to the CCSDS specifications CCSDS Orbit Data Messages Blue Book, version CCSDS 502.0-B-1, September, 2004. CCSDS Orbit Data Messages Blue Book, version CCSDS 502.0-B-2, November, 2009. CCSDS orbit ephemeris message files are referred to below as ``OEMs'' or ``OEM files.'' OEM files represent an ephemeris as a sequence of pairs of associated metadata and data blocks. A metadata block is a contiguous sequence of records containing information required to interpret the subsequent data block: target and center identity, time bounds, name of reference frame, intended polynomial interpolation method and polynomial degree, and name of the time system associated with time values. Each data block is a contiguous sequence of records, each of which contains a time tag and a six-element state vector. SPK2OEM requires as inputs an SPK file, a setup file containing commands that control SPK2OEM's operation, and a SPICE leapseconds kernel. The input SPK file may contain data for multiple bodies (aka ``ephemeris objects''), but data for only one body may be written to the output OEM file. SPK2OEM's data conversion process involves sampling state vectors from the input SPK file and transferring these states to the output OEM file. SPK2OEM has two different data sampling modes: -- Data-driven mode: SPKOEM samples input state vectors in such a way that the output OEM blocks faithfully replicate the input ephemeris, provided the OEM blocks are interpolated properly. Data-driven sampling is available only for segments of SPK data type 1 (Modified Divided Difference Arrays), type 9 (Sliding-window Lagrange Interpolation, Variable Spacing) or SPK type 13 (Sliding-window Hermite Interpolation, Variable Spacing). In the case of types 9 and 13, the states and time tags of the input segment are copied to the corresponding output OEM block. In the case of type 1, each difference line is mapped to an OEM block; while this produces an OEM that faithfully replicates the input ephemeris, it typically results in a profusion of OEM blocks. The default sampling mode is ``data-driven.'' -- Uniform sampling mode: SPK2OEM samples input SPK data at user-specified, uniform time intervals. Each segment maps to a single OEM block. SPK2OEM can convert SPKs containing segments of any SPK data type using uniform sampling. The resulting OEM ephemeris will normally suffer some loss of accuracy due to this change of representation. Uniform sampling is invoked by assigning a non-zero value to the keyword SAMPLE_SPACING in the setup file. See the description below of the SAMPLE_SPACING keyword for further information. The user may optionally specify a text file containing descriptive text to be placed in a comment block at the start of the OEM. (Doing this is highly recommended.) Any comments existing in the comment area of the input SPK file are automatically transferred to a comment block in the output OEM. These comments will come after any text provided via the optional text file mentioned above. For documentation purposes the contents of the SPK2OEM setup file are automatically placed at the end of the series of comments created at the head of the OEM file. Usage -------------------------------------------------------- The command syntax of SPK2OEM is as follows: spk2oem [-setup ] [-input ] [-output ] [-h|-help] [-t|-template] [-u|-usage] [-v|-version] Invoking spk2oem with the -u flag will cause spk2oem to write this usage 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 input or output file names assigned using setup keywords are ignored. The input file must already exist. Running SPK2OEM -------------------------------------------------------- You will need a setup file to execute the SPK2OEM utility program. The format for the setup file is described in the following section. As it executes, the program will display program version information, silently perform the conversion, then 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, which may occur on the command line, the program requires all inputs such as body names, leapseconds kernel and comment file names, etc. to be provided in a setup file. A template for the setup file is shown below. \begindata VERSION_NUMBER = 'Output OEM version: '1.0' (default) or '2.0'' ORIGINATOR = 'File creator' TIME_ZONE = 'Time zone of file creation location' OBJECT_NAME = 'Ephemeris object name' INPUT_SPK_FILE = 'SPK file name' OUTPUT_OEM_FILE = 'OEM file name' LEAPSECONDS_FILE = 'Leapseconds file name' COMMENT_FILE = 'Comment file name' START_TIME = 'OEM start time' STOP_TIME = 'OEM stop time' TIME_FORMAT = 'TIMOUT-style format string including time system' STRING_MAPPING = ( 'first input value', 'first mapped value', 'second input value', 'second mapped value', ... ) INTERPOLATION_METHOD = 'HERMITE' or 'LAGRANGE' INTERPOLATION_DEGREE = 1 to 15 MINIMUM_SPACING = Minimum valid time tag spacing in seconds [Applies to type 1 SPK segments only] MAXIMUM_SPACING = Maximum valid time tag spacing in seconds [Applies to type 1 SPK segments only] SAMPLE_SPACING = Nominal time tag spacing for blocks created by uniform sampling of SPK states BLOCK_INSET = Time increment by which to trim block coverage bounds, expressed in seconds. Normally zero, but a non-zero value can be helpful for debugging. \begintext The setup file format and contents are discussed in detail below. Text file format The format of the setup file must conform to the SPICE text kernel specification. This means 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 any \begintext token. Still more assignments could follow another \begindata token. The names of the setup file keywords must be strictly uppercase while the standard value 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 (not counting newline 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 correctly parse setup file lines that contain non-printing characters. Required Assignments The following assignments must be present in a setup file: OBJECT_NAME = 'name of ephemeris object' LEAPSECONDS_FILE = 'leapseconds file name' STRING_MAPPING = ( '', '' ) The leapseconds file name may include path information. The object ID is a special case: while the SPICE Toolkit does use integer codes to refer to ephemeris objects, the encoding scheme used by SPICE is one of many mutually incompatible schemes. For this reason the integer code used by SPICE is not written out; instead, the user is required to supply the ID to be written via a STRING_MAPPING assignment. For example, if the OEM were intended to use the ID code 074 for the ephemeris object, the string mapping assignment would be STRING_MAPPING = ( '', '074' ) Note that the token '' is not a symbol for a NAIF integer code; rather it is a literal string value and should be written exactly as it appears above. Also note that all values on the right hand side of the string mapping assignment are strings, so the integer code 074 is enclosed in single quotes. Since NAIF IDs for spacecraft are negative numbers, and since most other ID code conventions call for positive ID codes, normally the replacement object ID will differ from the object's NAIF ID by sign even if the absolute values of the IDs are identical. The string mapping defined in the setup file enables the user to control values written to the metadata blocks of the OEM file: the user may substitute specified values for the ones written by default by SPK2OEM. See the discussion of the string mapping keyword below for details. The following assignments are required in the setup file if their values are not provided on the command line: INPUT_SPK_FILE = 'input SPK file name' OUTPUT_OEM_FILE = 'output OEM file name' Conditional Assignments In addition to setting the ephemeris object's ID code, it may be necessary to map other metadata values. For example, if the input SPK file contains data referenced to the J2000 (aka EME2000) inertial reference frame, by default the string 'J2000' will appear as the value associated with the REF_FRAME keyword, since this is the name the SPICE system uses to refer to this reference frame. This value may need to be mapped to the value expected by the OEM consumer; this latter value could be 'EME2000' or any alias for J2000 allowed by the OEM specification. To replace 'J2000' with 'EME2000', the string mapping assignment above is extended to include the NAIF frame name and the replacement frame name: STRING_MAPPING = ( '', '074', 'J2000', 'EME2000' ) In addition to the REF_FRAME keyword the OEM '2.0' standard allows specifying the epoch of reference frame using the REF_FRAME_EPOCH keyword. However, OEM2SPK does not support this optional keyword since epochs of SPICE reference frames are intrinsic to their definitions. The INTERPOLATION_METHOD keyword should be used when uniform sample spacing is used (indicated by a positive SAMPLE_SPACING value) or when data-driven sampling is used and the input ephemeris is represented by type 1 SPK segments. INTERPOLATION_METHOD = '' Possible values for the interpolation method are 'HERMITE' and 'LAGRANGE'. The interpolation method defaults to 'HERMITE'. The INTERPOLATION_DEGREE keyword should be used when uniform sample spacing is used. INTERPOLATION_DEGREE = The interpolation degree should lie in the range 1:15. When the degree is not determined by the input data and no setup value has been provided, a default value of 15 is used. Optional Assignments All of the assignments shown below are optional. Each of these options is discussed in detail below. VERSION_NUMBER = 'Output OEM format version' COMMENT_FILE = 'Comment file name' START_TIME = 'OEM start time' STOP_TIME = 'OEM stop time' TIME_FORMAT = 'TIMOUT-style format string including time system' MINIMUM_SPACING = Minimum time tag spacing in seconds MAXIMUM_SPACING = Maximum time tag spacing in seconds SAMPLE_SPACING = State sampling time tag spacing in seconds BLOCK_INSET = Time increment by which to trim block coverage bounds, expressed in seconds. Normally zero, but non-zero value can be helpful for debugging. Detailed Description of Setup File Keywords -------------------------------------------------------- OBJECT_NAME Name of the ephemeris object (typically a spacecraft) whose ephemeris is to be translated to OEM format. The name must be recognized by the SPICE system. INPUT_SPK_FILE Name and optional path of the SPICE SPK input file. Required only if the input SPK name is not supplied on the command line. If the SPK file name is supplied on the command line, that name supersedes the name associated with this keyword in the setup file. OUTPUT_OEM_FILE Name and optional path of the CCSDS ``ephemeris message'' or ``OEM'' output file. Required only if the output OEM name is not supplied on the command line. If the OEM file name is supplied on the command line, that name supersedes the name associated with this keyword in the setup file. VERSION_NUMBER The CCSDS ``ephemeris message'' or ``OEM'' output file format version. The version should be either '1.0' or '2.0'. If this keyword is omitted, the program defaults to the version '1.0'. LEAPSECONDS_FILE Name and optional path of the SPICE leapseconds kernel (LSK) file name. COMMENT_FILE Name and optional path of an optional comment file. Use this keyword if you want to include comments provided in this text file in the initial comment block of the OEM file. START_TIME OEM start time. The coverage of the output OEM file will start at the greater of this time and the earliest subsequent start time of any segment for the body of interest in the source SPK 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 OEM stop time. The coverage of the output OEM file will stop at the lesser of this time and the latest preceding stop time of any segment for the body of interest in the source SPK 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. TIME_FORMAT Time format to be used in the output metadata and data blocks. The time format specification must be supported by the SPICELIB routine TIMOUT. In addition, the format must contain one of the following time system specifiers: ::TDB, ::TDT, or ::UTC. See the header of TIMOUT for details. STRING_MAPPING The user may control the representation of values written to 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 defaults 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', ... ) The STRING_MAPPING assignment must define an a replacement value for the object ID; other replacements are optional. By default, SPK2OEM writes to each metadata block the assignment OBJECT_ID = The pattern on the right hand side can be set to the proper value via the string mapping. In the example below, the string '' is mapped to the string '074': STRING_MAPPING = ( '', '074' ) This mapping causes SPK2OEM to write to the output metadata blocks the assignment OBJECT_ID = 074 In the example below, the mapping is extended so that the reference frame name `J2000' is mapped to the string `EME2000': STRING_MAPPING = ( '', '074', 'J2000', 'EME2000' ) This mapping causes SPK2OEM to replace the SPICE reference frame name 'J2000' with the string 'EME2000' on the right hand side of the assignment REF_FRAME = EME2000 The mapping feature may be used to map the frame name `J2000' to the name `ICRF'. See the chapter below titled ``ICRF vs J2000'' for more information. The scope of the mapping is restricted to the values associated with the metadata keywords CENTER_NAME OBJECT_ID OBJECT_NAME REF_FRAME INTERPOLATION_METHOD This indicates the interpolation method to be specified in the output OEM's metadata blocks. The INTERPOLATION_METHOD keyword applies when uniform sample spacing is used; when data-driven sampling is used, the keyword applies only to data blocks created from type 1 SPK segments. Allowed values are 'LAGRANGE' and 'HERMITE'. If the keyword is omitted, the method will default to HERMITE. The two paragraphs below describe normal processing invoked by the INTERPOLATION_METHOD assignment for type 1 segments when data-driven sampling is used. The spacing of time tags associated with output states will be modified if necessary to accommodate user-specified minimum and maximum spacing constraints. The degree of the output interpolating polynomial degree will not exceed 15. When Lagrange interpolation is specified, each data block in the output OEM file will contain a sufficient number of states to define, for each state component, a Lagrange interpolating polynomial that matches the input ephemeris on the time interval covered by the block. If the source SPK difference line has maximum order N, then the Lagrange polynomial degree specified in the corresponding output metadata block has degree N+2, and the block will contain at least N+3 states. When Hermite interpolation is specified, each data block in the output OEM file will contain a sufficient number of states to define, for each position component, a Hermite interpolating polynomial that matches the input ephemeris on the time interval covered by the block. The derivative with respect to time of each Hermite polynomial matches the corresponding velocity given by the input ephemeris. If the source SPK difference line has maximum order N, then the Hermite polynomials defined by the states in the corresponding OEM block must have order N+2, and the block will contain at least (N+3)/2 states. INTERPOLATION_DEGREE This is the polynomial degree to be specified in the output OEM metadata blocks. This value is used only when uniform sampling is used; otherwise it is ignored. The degree must be in the range 1:15 inclusive. MINIMUM_SPACING Minimum OEM time tag spacing in seconds. This value applies only for type 1 segments when data-driven sampling is used. Time tags located too close together may cause extreme loss of precision in Lagrange and Hermite polynomial interpolation algorithms. The minimum spacing limit may be used to prevent this problem in cases where the default algorithm would generate states too close together. The minimum spacing value can also be used to reduce the total number of data records in the output OEM file. However, this usage will cause loss of precision in the output ephemeris. SPK2OEM will normally not place output states closer together than the specified minimum time tag spacing: the only exception occurs when the coverage interval of the block containing the states is shorter than the minimum spacing. States will always be output for the start and stop times of each data block, even when the separation of these times is less than the specified minimum. If a minimum spacing limit is not specified in the setup file, a default value of 1 second is used. MAXIMUM_SPACING Maximum time tag spacing in seconds. This value applies only for type 1 segments when data-driven sampling is used. SPK2OEM will normally place in a data block the minimum number of evenly-spaced states such that the specified interpolation method duplicates the ephemeris defined by the corresponding difference line in the source type 1 SPK segment. When a maximum spacing value is specified, if the maximum is less than the separation implied by the default spacing algorithm, SPK2OEM will emit a sufficient number of evenly-spaced states so that the time tags of these states will be separated by no more than the specified limit, as long as this separation does not violate the specified minimum spacing. The spacing will always be large enough to conform to the specified minimum limit, except when the block coverage is too short to permit this. SAMPLE_SPACING When this keyword is assigned a positive value, SPK2OEM will map each SPK segment to a corresponding OEM block having states whose time tags are nominally separated by the given value. The spacing between time tags is always uniform and will be made smaller than the nominal value if necessary to achieve uniformity. Units associated with the spacing value are seconds. The SAMPLE_SPACING keyword is ignored when assigned a value of zero seconds. The SAMPLE_SPACING keyword must be used in order to convert SPK segments of types other than 1, 9, or 13. The SAMPLE_SPACING keyword may be used to prevent conversion of type 1 segments from producing a very large number of OEM blocks: when uniform sample spacing is selected, the output OEM file will contain one block for each type 1 segment rather than one block for each difference line; the count of OEM blocks may be reduced by several orders of magnitude. The principal drawback of the uniform sampling technique is that states obtained by interpolating states in the OEM block may not accurately reflect the original ephemeris represented by the SPK file. BLOCK_INSET (Used only for debugging.) Time increment by which to trim block coverage bounds, expressed as a positive number of seconds. When this keyword is used, each output data block is modified so that its start time is increased, and its stop time decreased, by the specified inset amount. This creates gaps between the coverage intervals of the data blocks. This feature simplifies correct comparison of the ephemeris defined by the OEM against that defined by the source SPK file or other ephemerides. Without these gaps, comparisons of states whose time tags lie at block boundaries can easily fail due to round-off error in time: given a request time nominally equal to a block boundary time, different ephemeris systems may compute a state for that time by interpolating states from either of the neighboring blocks whose coverage intervals intersect at the request time. Setup File Examples -------------------------------------------------------- Simple setup files This example is for the Mars Reconnaissance Orbiter spacecraft. \begindata OBJECT_NAME = 'MRO' INPUT_SPK_FILE = 'spk_psp_rec0605_0601_1388_p-v1.bsp' OUTPUT_OEM_FILE = 'spk_psp_rec0605_0601_1388_p-v1.oem' LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'LAGRANGE' STRING_MAPPING = ( 'J2000', 'EME2000', '', '074' ) \begintext This is a second version of the same file; the input and output file names are not listed here because they are expected to be supplied on the command line. The interpolation type has been changed to Hermite. \begindata OBJECT_NAME = 'MRO' LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' STRING_MAPPING = ( 'J2000', 'EME2000', '', '074' ) \begintext Limiting time coverage We further modify the example above to limit the time coverage to the day September 13, 2006 (TDB). \begindata OBJECT_NAME = 'MRO' LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' STRING_MAPPING = ( 'J2000', 'EME2000', '', '074' ) START_TIME = '2006 SEP 13 00:00:00 TDB' STOP_TIME = '2006 SEP 14 00:00:00 TDB' \begintext Controlling density of state data We further modify the example above to limit spacing of states so that all states are at least one minute apart. A block with coverage less than one minute will contain only two states whose time tags match the endpoints of the block. \begindata OBJECT_NAME = 'MRO' LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' STRING_MAPPING = ( 'J2000', 'EME2000', '', '074' ) START_TIME = '2006 SEP 13 00:00:00 TDB' STOP_TIME = '2006 SEP 14 00:00:00 TDB' MINIMUM_SPACING = 60 \begintext We add the instruction to make states no further than 10 minutes apart. \begindata OBJECT_NAME = 'MRO' LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' STRING_MAPPING = ( 'J2000', 'EME2000', '', '074' ) START_TIME = '2006 SEP 13 00:00:00 TDB' STOP_TIME = '2006 SEP 14 00:00:00 TDB' MINIMUM_SPACING = 60 MAXIMUM_SPACING = 600 \begintext Here we request uniform state sampling at 10-minute intervals. The resulting OEM file will have only one data block per type 1 segment for MRO in the input SPK file. However, the fidelity of the OEM file relative to the input ephemeris will be degraded. \begindata OBJECT_NAME = 'MRO' LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' STRING_MAPPING = ( 'J2000', 'EME2000', '', '074' ) START_TIME = '2006 SEP 13 00:00:00 TDB' STOP_TIME = '2006 SEP 14 00:00:00 TDB' SAMPLE_SPACING = 600.0 \begintext Changing the format version of the output OEM file We further modify the example above to change the format version of the output OEM file from the default version, '1.0', to the new format version, '2.0'. \begindata VERSION_NUMBER = '2.0' OBJECT_NAME = 'MRO' LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' STRING_MAPPING = ( 'J2000', 'EME2000', '', '074' ) START_TIME = '2006 SEP 13 00:00:00 TDB' STOP_TIME = '2006 SEP 14 00:00:00 TDB' SAMPLE_SPACING = 600.0 \begintext Instead of 'CCSDS_OEM_VERS = 1.0', the resulting OEM file will contain 'CCSDS_OEM_VERS = 2.0' followed immediately by comments allowed in the OEM head. Description of Output Data Format -------------------------------------------------------- The format of the OEM created by SPK2OEM conforms to the CCSDS ephemeris message specification (see the Summary section at the start of this document for the version). In the metadata and data blocks, date values are written with eight digits representing fractional seconds. Position and velocity components are written in scientific notation using 16-digit mantissas. Below is an example OEM file. Only a small portion of the file is shown. Deleted portions of the OEM file are represented by ellipses. Each state vector consists of six components written with identical formats; only their first and part of their second position components are shown. Only four metadata blocks and corresponding data blocks are shown. CCSDS_OEM_VERS = 1.0 CREATION_DATE = 2006-12-15T02:03:25.183439 ORIGINATOR = JPL COMMENT COMMENT Source SPK file: /ftp/pub/naif/MRO/kernels/spk/ ... COMMENT COMMENT COMMENT Comments from source SPK file: COMMENT ***************************************************** ... COMMENT ; spk_psp_rec0605_0601_1388_p-v1.bsp LOG FILE COMMENT ; COMMENT ; Created 2006-09-12/10:46:39.00. COMMENT ; COMMENT ; BEGIN NIOSPK COMMANDS ... COMMENT COMMENT \beginlabel COMMENT MISSION_NAME = MARS_RECONNAISSANCE_ORBITER COMMENT SPACECRAFT_NAME = MARS_RECONNAISSANCE_ORBITER COMMENT DATA_SET_ID = SPICE_SPK_FILE COMMENT KERNEL_TYPE_ID = SPK COMMENT PRODUCT_ID = spk_psp_rec0605_0601_1388_p-v1.xsp COMMENT PRODUCT_CREATION_TIME = 2006-255T10:47:04 COMMENT PRODUCER_ID = NAV COMMENT START_TIME = 2006-09-12T06:40:00.000 COMMENT STOP_TIME = 2006-11-12T16:00:00.000 COMMENT \endlabel COMMENT ***************************************************** ... COMMENT End of comments from source SPK file COMMENT COMMENT SPK2OEM RUN DATE/TIME: 2006-12-14T18:02:20 COMMENT SPK2OEM SETUP FILE: mro.setup COMMENT SPK2OEM INPUT FILE: /ftp/pub/naif/MRO/kernels/spk/ ... COMMENT SPK2OEM OUTPUT FILE: mro.oem COMMENT SPK2OEM version: 1.0.0 25-FEB-2005 COMMENT COMMENT SPK2OEM setup file: COMMENT ***************************************************** ... COMMENT COMMENT \begindata COMMENT ORIGINATOR = 'JPL' COMMENT TIME_ZONE = 'PST' COMMENT OBJECT_NAME = 'MRO' COMMENT INPUT_SPK_FILE = ( COMMENT '/ftp/pub/naif/MRO/kernels/spk/spk_psp_rec0605_06 ... COMMENT OUTPUT_OEM_FILE = 'mro.oem' COMMENT LEAPSECONDS_FILE = 'lsk' COMMENT STRING_MAPPING = ( '', '074', COMMENT 'J2000', 'EME2000' ) COMMENT COMMENT COMMENT \begintext COMMENT COMMENT ***************************************************** ... COMMENT META_START OBJECT_NAME = MARS RECON ORBITER OBJECT_ID = 074 CENTER_NAME = MARS BARYCENTER REF_FRAME = EME2000 TIME_SYSTEM = TDB START_TIME = 2006-09-12T06:40:00.00000000 STOP_TIME = 2006-09-12T06:40:00.01573157 INTERPOLATION = HERMITE INTERPOLATION_DEGREE = 3 META_STOP 2006-09-12T06:40:00.00000000 1.702853058696742E+03 3.0088 ... 2006-09-12T06:40:00.01573157 1.702875974223865E+03 3.0088 ... META_START OBJECT_NAME = MARS RECON ORBITER OBJECT_ID = 074 CENTER_NAME = MARS BARYCENTER REF_FRAME = EME2000 TIME_SYSTEM = TDB START_TIME = 2006-09-12T06:40:00.01573157 STOP_TIME = 2006-09-12T06:40:00.14557984 INTERPOLATION = HERMITE INTERPOLATION_DEGREE = 3 META_STOP 2006-09-12T06:40:00.01573157 1.702875974222389E+03 3.0088 ... 2006-09-12T06:40:00.14557984 1.703065104717810E+03 3.0086 ... META_START OBJECT_NAME = MARS RECON ORBITER OBJECT_ID = 074 CENTER_NAME = MARS BARYCENTER REF_FRAME = EME2000 TIME_SYSTEM = TDB START_TIME = 2006-09-12T06:40:00.14557984 STOP_TIME = 2006-09-12T06:40:01.22899299 INTERPOLATION = HERMITE INTERPOLATION_DEGREE = 3 META_STOP 2006-09-12T06:40:00.14557984 1.703065104686267E+03 3.0086 ... 2006-09-12T06:40:01.22899299 1.704642171230372E+03 3.0066 ... META_START OBJECT_NAME = MARS RECON ORBITER OBJECT_ID = 074 CENTER_NAME = MARS BARYCENTER REF_FRAME = EME2000 TIME_SYSTEM = TDB START_TIME = 2006-09-12T06:40:01.22899299 STOP_TIME = 2006-09-12T06:40:11.68949133 INTERPOLATION = HERMITE INTERPOLATION_DEGREE = 11 META_STOP 2006-09-12T06:40:01.22899299 1.704642171258416E+03 3.0066 ... 2006-09-12T06:40:03.32109266 1.707682577028593E+03 3.0028 ... 2006-09-12T06:40:05.41319233 1.710716448696539E+03 2.9990 ... 2006-09-12T06:40:07.50529199 1.713743775016463E+03 2.9952 ... 2006-09-12T06:40:09.59739166 1.716764544769154E+03 2.9914 ... 2006-09-12T06:40:11.68949133 1.719778746762019E+03 2.9876 ... ... ICRF vs J2000 =========================================================================== The International Celestial Reference System (ICRS) defines coordinate axes that are closely aligned with those of the J2000 (aka EME2000) reference frame. The International Celestial Reference Frame (ICRF) and later versions of it (ICRF1, etc.) are realizations of the ICRS. For brevity, we'll simply refer to ``the ICRF'' below. The rotational offset between the J2000 frame and the ICRS has magnitude of under 0.1 arcseconds. Certain JPL data products are referenced to the ICRF or later versions of it. These include, but are not limited to, -- DE4xx series planetary ephemerides -- Satellite ephemerides compatible with DE4xx planetary ephemerides -- Small body ephemerides compatible with DE4xx planetary ephemerides -- Orientation of the terrestrial frame ITRF93 -- Orientation of the lunar principal axes frame Rotation models provided by the IAU are referenced to the ICRF. Modern spacecraft ephemerides and attitude data, other than those for Earth orbiters, are likely referenced to the ICRF. Users should consult documentation or data providers to verify this for data sets of interest. SPK and binary PCK files produced by NAIF from the data sources listed above are referenced to the same version of the ICRF as the corresponding data sources. For historical and backward compatibility reasons, these data products are labeled as being referenced to the J2000 frame. No transformation is required to convert state vectors or orientation data from the J2000 frame to the ICRF (or later version), if the vectors or orientation data are computed using SPICE kernels created from the data sources listed above. For example: -- A call to @SPKEZR with the input frame name J2000 will return a state vector referenced to the ICRF, if the SPK data are from a JPL planetary ephemeris SPK, or from any other SPK in which data are referenced to the ICRF and labeled as referenced to the J2000 frame. -- A call to @PXFORM with the input ``from'' frame name J2000 and input ``to'' frame name ITRF93 will return a 3x3 matrix that transforms position vectors from the ICRF to the ITRF93 terrestrial frame, if the Earth orientation data are provided by a NAIF high-precision, binary Earth PCK. -- A call to @PXFORM with the input ``from'' frame name J2000 and input ``to'' frame name IAU_MARS will return a 3x3 matrix that transforms position vectors from the ICRF to the Mars body-fixed, body-centered IAU_MARS frame, if the orientation data are provided by a NAIF generic text PCK. -- A call to @PXFORM with the input ``from'' frame name J2000 and an input ``to'' CK frame name will return a 3x3 matrix that transforms position vectors from the ICRF to the specified CK frame, if the CK data used by this call are referenced to the ICRF and labeled as referenced to the J2000 frame. SPICE kernel creators intending to support use of data referenced to the ICRF, as shown above, should write the data without first converting it to the J2000 frame. Segments of such SPK, CK, or binary PCK files should indicate the frame is J2000. It is strongly recommended that kernel creators add comments to the files to explain the actual characteristics of the data. SPICE users who export kernel data to non-SPICE file formats may need to transform the data, depending on the frame to which the SPICE data are actually referenced (as opposed to the frame to which the kernel indicates the data are referenced), and depending on the desired output frame. Appendix A --- Revision History =========================================================================== 2021 DEC 31 by N. J. Bachman Started revision history appendix. Added discussion of ICRF and J2000 frames.