OEM2SPK User's Guide =========================================================================== Last revised on 2021 DEC 31 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 in the comment area of the SPK file. OEM2SPK accepts OEM version 1.0 or OEM version 2.0. OEM version 2.0 may provide acceleration components on the ephemeris data line. OEM2SPK ignores them. OEM version 2.0 may provide covariance matrix data demarcated by COVARIANCE_START and COVARIANCE_STOP keywords. If this data is present, OEM2SPK extracts and places it into the comment area of the SPK file. This addition can be suppressed using the setup file keyword COVARIANCE_COMMENTS. OEM METADATA blocks in OEM version 2.0 may provide the optional keyword pair, USEABLE_START_TIME and USEABLE_STOP_TIME, in addition to the required keyword pair, START_TIME and STOP_TIME. If the former pair exists, OEM2SPK uses it instead of the latter pair. OEM2SPK can be made to accept body name-to-NAIF ID mappings that are not built into the SPICE Toolkit; this is done via the setup file. See the sections below titled ``Optional Assignments'' and ``Detailed Description of Setup File Keywords.'' Usage -------------------------------------------------------- The command syntax of OEM2SPK is as follows: oem2spk [-setup ] [-input ] [-output ] [-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 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 One of these two assignments specifying the name of an LSK file must be present in the setup file: LEAPSECONDS_FILE = 'leapseconds file name' -- or -- KERNELS_TO_LOAD = ( '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' COVARIANCE_COMMENTS = 'YES' or 'NO' NAIF_BODY_NAME += ( 'spacecraft name' ) NAIF_BODY_CODE += ( spacecraft NAIF ID ) Detailed Description of Setup File Keywords -------------------------------------------------------- LEAPSECONDS_FILE Name of the SPICE LSK file, including full or relative path specification. Alternatively the name of the LSK file can be specified using the standard meta-kernel keywords -- KERNELS_TO_LOAD or KERNELS_TO_LOAD + PATH_VALUES + PATH_SYMBOLS. If needed, additional kernels such as FKs providing the object name-IDs mappings can be specified together with the LSK file in the standard meta-kernel keyword value list. If both the LEAPSECONDS_FILE keyword and the standard meta-kernel keywords are provided the file given in the LEAPSECONDS_FILE keyword is loaded after the files listed in the meta-kernel keywords. 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 `EME2000' is mapped to the string `J2000': STRING_MAPPING = ('EME2000','J2000') This mapping causes OEM2SPK to interpret the assignment REF_FRAME = EME2000 as REF_FRAME = J2000 The mapping feature may be used to map the frame name `ICRF' to the name `J2000'. 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 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. If the output SPK file is to be used for DSN metric predict generation, a minimum spacing limit less than 1 millisecond should not be 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. COVARIANCE_COMMENTS Optional flag specifying whether the covariance matrices from the input OEM file should be copied to the comment area of the output SPK file. This keyword can have one of these two values: 'YES' if the matrices should be copied and 'NO' if not. If this keyword is not present, the program assumes the value 'YES'. NAIF_BODY_NAME/CODE Optionally, for spacecraft whose name-to-NAIF ID mapping is not built into the toolkit and is not provided in the text kernels listed in the standard meta-kernel keywords, the NAIF_BODY_NAME and NAIF_BODY_CODE keywords can be used to define the missing name-to-NAIF ID mappings right in the setup file. Note the ``+='' operator is used for these assignments rather than the ``='' operator. This has the effect of adding the name-to-NAIF ID mapping to the existing set of mappings, rather than overwriting previously existing mappings. See naif_ids.req for details. 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 ``EME2000'' in the OEM file is mapped to the name SPICE frame name ``J2000.'', the spacecraft name ``EXOMARS-ORBITER'' in the OEM file is mapped to the SPICE name ``TGO'', and the SPICE name ``TGO'' is associated with the NAIF ID -143. \begindata LEAPSECONDS_FILE = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' INTERPOLATION_DEGREE = 11 STRING_MAPPING = ( 'EME2000', 'J2000', 'EXOMARS-ORBITER', 'TGO' ) NAIF_BODY_NAME += ( 'TGO' ) NAIF_BODY_CODE += ( -143 ) \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 ``EME2000'' 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 = ( 'EME2000', 'J2000' ) \begintext Limiting time coverage We modify the first example above to limit the time coverage to the day October 9, 2003 (TDB). \begindata KERNELS_TO_LOAD = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' INTERPOLATION_DEGREE = 11 STRING_MAPPING = ( 'EME2000', '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 = ( 'EME2000', '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 KERNELS_TO_LOAD = '/kernels/gen/lsk/leapseconds.ker' INTERPOLATION_METHOD = 'HERMITE' INTERPOLATION_DEGREE = 11 STRING_MAPPING = ( 'EME2000', '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-2, November, 2009. 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 = 2.0 CREATION_DATE = 2013-07-18T17:24:44.185268 ORIGINATOR = JPL ... META_START OBJECT_NAME = MER-1 OBJECT_ID = -253 TIME_SYSTEM = TDB REF_FRAME = EME2000 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 = EME2000 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. -- All covariance matrices from the input OEM file, if any are provided, and if such addition is not suppressed by setting the setup file keyword COVARIANCE_COMMENTS to 'NO'. 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. 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.