Index Page

FRMDIFF User's Guide


   FRMDIFF User's Guide
      Abstract
      Summary
      If You Are in a Hurry
         To Check if Two CK Files Provide Identical Data
         To Assess Difference Between Two CK Files
         To Sample Quaternions from a CK File
         To Compute Transformation Between Two Frames
      Usage
      Options

   Inputs
      Kernel Files
         Primary Kernel Files
         Additional Kernel Files
      Comparison Runs vs. Sampling Runs
      Runs with Two, One, and No Primary Kernel File(s)
         Runs with Two Primary Kernel Files
         Runs with One Primary Kernel File
         Runs Without Primary Kernel Files
      ``From'', ``To'', and ``Coverage'' Frames
         ``From'' Frames
         ``To'' Frames
         ``Coverage'' Frames
      Times for Comparison/Sampling
         Coverage Window
         Times within Coverage Window
      Angular Velocities

   Output
      Overview of Report Types
         Time Tag Format for ``dump*'' Reports
         Numeric Format for ``dump*'' Reports
         Angle Units for ``dumpaa'' and ``dumpea'' Reports
      Report Header
         Report Header for Comparing Two Orientations
         Report Header for Coverage/Gaps for Two Orientations
         Report Header for Sampling an Orientation
         Report Header for Coverage/Gaps for An Orientation
      Report Formats
         Basic Report (no ``-t'' or ``-t basic'')
         Statistics Report (``-t stats'')
         Angle and Axis Dump Report (``-t dumpaa'')
         Matrix Dump Report (``-t dumpm'')
         SPICE-Style Quaternion Dump Report (``-t dumpqs'')
         ``Other''-Style Quaternion Dump Report (``-t dumpqo'')
         Euler Angles Dump Report (``-t dumpea'')
         Coverage Intervals Dump Report (``-t dumpc''):
         Coverage Gaps Dump Report (``-t dumpg'')

   Examples
      Checking if Two CKs Provide the Same Orientation
      Comparing Predicted and Reconstructed CKs
      Comparing Orientations from a CK Read Using Different SCLKs
      Comparing Binary and Text PCKs
      Comparing Two Text PCKs
      Sampling Orientation from a CK
      Sampling Orientation of a Built-in Frame
      Sampling Orientation of a Dynamic Frame
      Sampling Orientation With Two Different ``Coverage'' Frames
      Displaying Overlap in Coverage between Two CKs
      Displaying Gaps in a CK File

   Miscellaneous Things to Consider
      ``Apples vs. Oranges''
      Using Euler Angles for Small Rotation Differences
      Single Epoch

   References

   Acronyms

   Appendix 1: Comparison, Sampling and Report Quantity Algorithms
      Computing Rotation and Angular Velocity Difference
      Sampling Rotation and Angular Velocity
      Converting Rotation to Angle/Axis
      Converting Rotation to SPICE-Style Quaternion
      Converting Rotation to ``Other''-Style quaternion
      Converting Rotation to Euler Angles

FRMDIFF User's Guide

Last revised on 2014 JAN 21 by B. V. Semenov.

Top

Abstract

FRMDIFF is a program that samples orientation of a reference frame known to SPICE or computes differences between orientations of two reference frames known to SPICE, and either displays this orientation or these differences, or shows statistics about it or them.

Top

Summary

FRMDIFF provides means for sampling orientation of a single reference frame, or for comparing orientations of two reference frames known to SPICE and supported by data from SPICE kernels.

To sample orientation of a single frame the program computes a set of transformations from one frame (the ``from'' frame) to another frame (the ``to'' frame) over an interval of time with fixed or variable time step, using a given set of kernel files. Then, depending on the requested type of output report, it prints to the screen a table containing these transformations expressed as total rotation angles and axes, quaternions, matrices or Euler angles and angular velocities, or only magnitude of the maximum rotation and angular velocity, or results of a simple statistical analysis of rotations.

To compare orientations of two frames the program computes a set of transformations from one frame (the ``from'' frame) to another frame (the ``to'' frame) over an interval of time with a fixed or variable time step using one set of kernels, computes a set of transformations for the same or a different ``from''-``to'' frame combination at the same times using the same or a different set of kernels, and then computes the difference in rotation and angular velocity between the corresponding transformations. Depending on the requested type of output report the program prints to the screen only maximum differences in rotation and angular velocity, or a complete table of rotation and angular velocity differences expressed as total rotation angles and axes, matrices, quaternions, or Euler angles, or results of a simple statistical analysis of the rotation differences.

Top

If You Are in a Hurry

This section shows four very common FRMDIFF usage scenarios with just enough explanations to get you going. An extensive set of detailed examples is provided at the end of this User's Guide.

Top

To Check if Two CK Files Provide Identical Data

To check if two CK files containing orientation for the same structure with respect to the same reference frame provide identical data, run FRMDIFF as follows:

   % frmdiff -k <lsk> <sclk> <fk> -s <step> <ck1> <ck2>

where ``<lsk>'', ``<sclk>'', ``<fk>'', ``<ck1>'' and ``<ck2>'' are the names of LSK, SCLK, FK, and two CK files (all five are required), and ``step'' is the time step, in seconds. If the maximum rotation angle in the output is zero (or close to zero, accounting for round off), then the CKs contain the same data. To include angular velocities in comparison, add ``-a yes'' before ``-s'', like this:

   % frmdiff -k <lsk> <sclk> <fk> -a yes -s <step> <ck1> <ck2>

Top

To Assess Difference Between Two CK Files

To assess the difference between two CK files containing orientation for the same structure with respect to the same reference frame as a function of time, run FRMDIFF as follows:

   % frmdiff -k <lsk> <sclk> <fk> -t dumpaa -s <step> <ck1> <ck2>

where ``<lsk>'', ``<sclk>'', ``<fk>'', ``<ck1>'' and ``<ck2>'' are the names of LSK, SCLK, FK, and two CK files (all five are required); ``-t dumpaa'' sets the output format to the rotation angle and axis dump; and ``step'' is the time step, in seconds. The program's output, which can be rather lengthy, can be re-directed to a file using the ``>'' pipe. Using the data captured in the file the total rotation angle (column 2) can be plotted against TDB seconds (column 1) to analyze the difference. To print output time tags as UTC in ISO date format instead of TDB seconds, add

   -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'

before ``-k''. To use the Euler angle dump output instead of the rotation angle and axis dump output, replace ``dumpaa'' with ``dumpea''. To include angular velocities in the comparison, add ``-a yes'' before ``-s'', like this (the command line below is wrapped to fit the page width):

   % frmdiff -k <lsk> <sclk> <fk> -t dumpaa -a yes -s <step>
             <ck1> <ck2>

Top

To Sample Quaternions from a CK File

To sample orientation provided in a CK file and print it as SPICE-style quaternions, run FRMDIFF as follows:

   % frmdiff -k <lsk> <sclk> <fk> -t dumpqs -s <step> <ck>

where ``<lsk>'', ``<sclk>'', ``<fk>'', and ``<ck>'' are the names of LSK, SCLK, FK, and CK files (all four are required); ``-t dumpqs'' sets the output format to the SPICE-style quaternion dump; and ``step'' is the time step, in seconds. The program's output can be re-directed to a file using the ``>'' pipe. To print output time tags as UTC in ISO date format, add

   -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'

before ``-k''. To use the ``other''-style quaternion dump instead of the SPICE-style quaternion dump, replace ``dumpqs'' with ``dumpqo''. To include angular velocities, add ``-a yes'' before ``-s''; to print angular velocities in the structure frame rather than the base frame, also add ``-m to'', like this (the command line below is wrapped to fit the page width):

   % frmdiff -k <lsk> <sclk> <fk> -t dumpqo -a yes -m to
             -s <step> <ck>

Top

To Compute Transformation Between Two Frames

To compute transformation from one frame known to SPICE to another frame known to SPICE and display this transformation as Euler angles, run FRMDIFF as follows (the command line below is wrapped to fit the page width):

   % frmdiff -k <kernels> -t dumpea
             -b <begintime> -e <endtime> -s <step>
             -f1 <from_frame> -t1 <to_frame>

where ``<kernels>'' are the names of kernel files needed to compute the transformation (an LSK must be included); ``-t dumpea'' sets the output format to the Euler angles dump; ``<begintime>'' and ``<endtime>'' set the begin and end time, as UTC, for the period of interest; ``step'' is the time step, in seconds; and ``<from_frame>'' and ``<to_frame>'' are the names of the frames from which and to which the transformation can be computed. For lengthy reports the program's output should be re-directed to a file using the ``>'' pipe.

Note that if the ``<to_frame>'' is a CK-based (Class 3) or PCK-based (Class 2) frame, the list of kernels (``<kernels>'') includes CKs or binary PCKs providing data for that frame, and ``-b <begintime> -e <endtime>'' are omitted, the program will automatically determine the ``<to_frame>''s data availability time window and will compute transformations with specified step over that whole window.

Top

Usage

FRMDIFF is a command line program with the following usage:

   % frmdiff [options] <first kernel> <second kernel>
   % frmdiff [options] <kernel>
   % frmdiff [options]

where either of the kernels can be a CK, a PCK, an FK, or any other SPICE kernel. The options are:

   -k  <supporting kernel(s) name(s)>
   -f1 <first ``from'' frame, name or ID>
   -t1 <first ``to'' frame, name or ID>
   -c1 <first frame for coverage look up, name or ID>
   -k1 <additional supporting kernel(s) for first file>
   -f2 <second ``from'' frame, name or ID>
   -t2 <second ``to'' frame, name or ID>
   -c2 <second frame for coverage look up, name or ID>
   -k2 <additional supporting kernel(s) for second file>
   -a  <compare angular velocities, yes|no (default: no)>
   -m  <frame for angular velocities, from|to (default: from)
   -b  <interval start time>
   -e  <interval stop time>
   -n  <number of points: 1 to 1000000 (default: 1000)>
   -s  <time step in seconds>
   -f  <time format, et|sclk|sclkd|ticks|picture_for_TIMOUT>
       (default: et)>
   -t  <report: basic|stats|dumpaa|dumpm|dumpqs|dumpqo|dumpea
       |dumpc|dumpg>
   -o  <rotation axes order (default: z y x)>
   -x  <units for output angles>
   -d  <number of significant digits: 6 to 17 (default: 14)>

The order of options and case of the option keys are not significant. The values provided after the option keys must be separated from keys by one or more spaces. Un-recognized options are not specifically checked for; instead they are treated as continuation of the value provided using the preceding recognized option.

Top

Options

Kernel file names and control parameters are provided to the program using the following command line options (only a brief description of each option is given in the list below; details, defaults, and dependencies are discussed later in this document):

<first kernel>: is the name of the first primary kernel. When two primary kernels are provided to the program this name must be the second to last item on the command line.

<second kernel>: is the name of the second primary kernel. When two primary kernels are provided to the program this name must be the last item on the command line.

<kernel>: is the name of the only primary kernel. When only one primary kernel is provided to the program this name must be the last item on the command line.

-k <kernels>: is used to specify the list of additional kernels that should be used for both frame transformations to be computed. Kernel names following ``-k'' must be separated by spaces.

-f1 <frame>: is used to specify the ``from'' frame for the first (or only) frame transformation to be computed. This frame must be known to SPICE and can be specified using the frame name, ID, or class ID.

-t1 <frame>: is used to specify the ``to'' frame for the first (or only) frame transformation to be computed. This frame must be known to SPICE and can be specified using the frame name, ID, or class ID.

-c1 <frame>: is used to specify the ``coverage'' frame to be used to look up the first coverage window. This frame must be known to SPICE and must be either a PCK-based (Class 2) or CK-based (Class 3) frame. It can be specified using the frame name, frame ID, or, if the first (or only) primary kernel is a CK or a binary PCK, class ID. If the first (or only) primary kernel file is a CK or a binary PCK, it must contain data for this frame.

-k1 <kernels>: is used to specify the list of additional kernels that should be used only for the first frame transformation to be computed. Kernel names following ``-k1'' must be separated by spaces.

-f2 <frame>: is used to specify the ``from'' frame for the second (or only) frame transformation to be computed. This frame must be known to SPICE and can be specified using the frame name, ID, or class ID.

-t2 <frame>: is used to specify the ``to'' frame for the second (or only) frame transformation to be computed. This frame must be known to SPICE and can be specified using the name, ID, or class ID.

-c2 <frame>: is used to specify the ``coverage'' frame to be used to look up the second coverage window. This frame must be known to SPICE and must be either a PCK-based (Class 2) or CK-based (Class 3) frame. It can be specified using the frame name, frame ID, or, if the second (or only) primary kernel is a CK or a binary PCK, class ID. If the second (or only) primary kernel file is a CK or a binary PCK, it must contain data for this frame.

-k2 <kernels>: is used to specify the list of additional kernels that should be used only for the second frame transformation to be computed. Kernel names following ``-k2'' must be separated by spaces.

-b <time>: is used to specify the coverage window begin time. This option must be provided when no primary kernels and ``coverage'' frames are specified. The time string provided using this option can be in any form accepted by SPICE's str2et_c function.

-e <time>: is used to specify the coverage window end time. This option must be provided when no primary kernels and ``coverage'' frames are specified. The time string provided using this option can be in any form accepted by SPICE's str2et_c function.

-n <number>: is used to specify the number of points within the coverage window, for which the frame transformation(s) must be computed. The number must be an integer between 1 and 1,000,000. The default value is 1000.

-s <step>: is used to specify the step, in seconds, for determining points within the coverage window, for which the frame transformation(s) must be computed. The step must be greater than 1E-8. This option supersedes ``-n''.

-t <report_type>: is used specify the type of report that the program should display:

                             basic   to display only the maximum
                                     rotation angle and angular
                                     velocity (AV) magnitude (default)
 
                             stats   to display statistics on rotation
                                     angles and AVs
 
                             dumpaa  to display a table of rotation
                                     angles and axes
 
                             dumpm   to display a table of matrices
 
                             dumpqs  to display a table of SPICE-style
                                     quaternions
 
                             dumpqo  to display a table of ``other''-
                                     style quaternions
 
                             dumpea  to display a table of Euler angles
 
                             dumpc   to display a table of coverage
                                     intervals
 
                             dumpg   to display a table of coverage
                                     gaps

-a <av_flag>: is used to tell the program whether angular velocities should be computed along with rotations:

                             no      to compute only rotations
                                     (default)
 
                             yes     to compute rotations and
                                     angular velocities

-m <av_frame>: is used to tell the program in which frame angular velocities should be reported:

                             from    to output angular velocities in
                                     ``from'' frame (default)
 
                             to      to output angular velocities in
                                     ``to'' frame

-f <time_type>: is used to specify the type of time tag to be used in tabular reports (``-t'' with ``dumpm'', ``dumpqs'', ``dumpqo'', ``dumpea'', ``dumpc'', or ``dumpg''):

                             et      to display times as TDB seconds
                                     past J2000 (default)
 
                             sclk    to display times as string SCLKs
 
                             sclkd   to display times as decimal SCLKs
 
                             ticks   to display times as encoded SCLK
                                     ticks
 
                             <PICT>  any time format picture accepted
                                     by the @TIMOUT @routine (for
                                     example ``YYYY-MM-DDTHR:MN:SC.###
                                     ::RND'' for time tags for be
                                     displayed as UTCs in ISO date
                                     format)

-o <axes>: is used to specify the list of axes determining the order of rotations used for converting rotation matrices to Euler angles. The value must be a space-delimited list of three axes from the set of ``X'', ``Y'', ``Z'' (case-insensitive). The second axis must differ from the first and third axes. The default order is ``Z Y X''.

-x <units>: is used to specify the units for the angles in the rotation angle and axis dump (``-t dumpaa'') and Euler angle dump (``-t dumpea'') reports; ignored for all other report types. Supported units are:

                             radians (default)
                             degrees
                             arcminutes
                             arcseconds
                             hourangle
                             minuteangle
                             secondangle

-d <number>: is used to specify the number of significant digits in the output numeric times (TDB seconds past J2000, decimal SCLKs and encoded SCLK ticks) and rotation component values or rotation difference component values included in the dump, coverage and coverage gap reports. The number must be an integer between 6 and 17. The default value is 14.

-v: causes the program to display only the version line. This option overrides all other options.

-u: causes the program to display the usage message. This option overrides all other options except ``-v''.

-h: causes the program to display a brief help message. This option overrides all other options except ``-v'' and ``-u''.

Top

Inputs

For a successful run the program must be supplied with kernel files providing sufficient data to compute the frame transformation(s) of interest, and with control parameters clearly specifying, together with default values determined from the kernels, what transformations should be computed and at what times. Both the kernels and the control parameters are provided to the program using command line options.

Top

Kernel Files

In most cases one or more kernel files must be provided to the program to perform comparison or sampling of frame orientations. Depending on how the kernel files are provided, they fall into one of two categories -- primary kernel files and additional kernel files.

Primary kernel files -- two, one, or none -- are provided at the end of the command line without any command line keys. Normally these kernel files contain orientations that differ (for example, predicted and reconstructed CKs for the same frame and time period, two versions of an FK with different alignment data for the same frame, etc.), or contain orientation to be sampled. These kernel files are also examined by the program to determine the default values for the ``from'', ``to'', and ``cov'' frames, and to determine the coverage window boundaries. Note that becasue the program slightly contracts coverage windows determined from CK files to compensate for roundoff occuring in SCLK to ET time conversions, in general FRMDIFF cannot be used to sample or compare CKs with discrete data, e.g. Type 1 CKs or Type 3 CKs with singleton intervals. For additional discussion of this limitation see the ``Coverage Window'' section below.

Additional kernel files -- none, or as many as needed -- are provided anywhere on the command line (except at the very end) using the ``-k'', ``-k1'', and ``-k2'' keys. Normally these kernel files contain additional SPICE data needed to compute requested orientations (for example, LSK and SCLK files providing supporting time conversion data, FK files providing frame definitions needed by SPICE to recognize specified frames, etc).

Top

Primary Kernel Files

The primary kernels can be of any type -- CK, PCK, FK, SCLK, LSK or even SPK -- and are provided as the last or the last two items on the command line. Since the primary kernel files do not require specific command line keys, the program determines if they were given by examining the last two words on the command line as follows:

--

Due to the parsing approach described above, misspelling a primary kernel name leads to the program deciding that it either runs with no primary kernel files (if the last file name is misspelled) or that it runs with one primary kernel instead of two (if the second to last file name is misspelled). In either case, the misspelled file name(s) is(are) treated as a part of the value of the command line option immediately preceding it(them) causing the program to signal an error indicating an incorrect option value.

On the other hand, if any of the options for specifying additional kernel files (``-k'', ``-k1'', ``-k2'') followed by actual files names is provided at the end of the command line (for the case of no primary kernels) or immediately preceding the only primary file (for one primary kernel case), the last one or the last two additional kernels are mistakenly picked as the primary kernel(s). In this situation the program usually signals an error indicating that orientation could not be computed because insufficient data was loaded.

Top

Additional Kernel Files

As for primary kernels, additional kernels can also be of any type -- CK, PCK, FK, SCLK, LSK or even SPK. Unlike primary kernels, additional kernels are specified using the dedicated ``-k'', ``-k1'', and ``-k2'' keys. Any number of additional kernels can be provided using any of the three keys, with kernel file names listed in any order, separated by blanks. While in some rare cases no additional kernel files are required, in most cases at least an LSK file and an SCLK file containing time correlation data and an FK file containing frame definitions should be specified using these keys. The additional kernels are used by the program as follows:

--

Neither the combined set of additional kernel files given using ``-k''/``-k1'' nor the combined set of additional kernel files given using ``-k''/``-k2'' can contain enough data to compute corresponding orientations at any time in the time buffer without loading the corresponding primary file(s). If they do, the program signals an error. The two exceptions from this requirement are:

--

Top

Comparison Runs vs. Sampling Runs

The program automatically decides whether it should compare two orientations or sample one orientation, based on the primary kernels provided at the end of the command line, additional kernel files provided using the ``-k1'' and ``-k2'' keys, and on the ``from'' and ``to'' frames specified on the command line using the ``-f1'', ``-t1'', ``-f2'', and ``-t2'' keys and/or determined from the primary kernel data.

To run the program in comparison mode, it is enough to satisfy any of the following guidelines for specifying inputs that tell the program to compute two different orientations:

--

To run the program in sampling mode, it is required to satisfy all of the following guidelines telling the program to compute a single orientation:

--

There are only two cases when the program runs in sampling mode after being given two primary kernels and/or two orientation-specific additional kernel sets. These cases are:

--

Top

Runs with Two, One, and No Primary Kernel File(s)

The number and types of primary kernel files and the mode in which the program is run (``comparing'' vs. ``sampling'') directly affect the requirements in regards to which command line options must be provided, approaches for determining default values for omitted options, and ways in which kernels are loaded and orientations are computed. The three subsections below discuss specifics of runs with two, one, and no primary kernel files.

Top

Runs with Two Primary Kernel Files

When two primary kernel files are provided on the command line:

--

Top

Runs with One Primary Kernel File

When one primary kernel file is provided on the command line:

--

Top

Runs Without Primary Kernel Files

When no primary kernel files are specified on the command line:

--

Top

``From'', ``To'', and ``Coverage'' Frames

The program has six command line keys -- ``-f1'', ``-t1'', ``-c1'', ``-f2'', ``-t2'', and ``-c2'' -- to specify frames to be used to compute rotations (``-f*'' and ``-t*'' keys) and to determine coverage from primary or additional CK or binary PCK files (``-c*'' keys). A single frame can be specified using each of these keys using the frame name, frame ID, or frame class ID (only for runs with primary kernel files that are CKs or binary PCKs).

Whether the frame is specified by the name, ID, or class ID, it must be known to SPICE, i.e. it must either be a built-in frame or one of the frames defined in the FK file(s) provided as primary or additional kernels. If the frame name, ID, or class ID specified on the command line or picked from the primary file is not recognized after loading the kernel files provided using ``-k''/``-k1'' and the first primary file for the ``-*1'' frames, or provided using ``-k''/``-k2'' and the second primary file for the ``-*2'' frames, the program signals an error.

Not all six frames have to be specified for every program run. In fact in many cases only one, two, or even no frames can be given and the program will set the rest to default values based on the other frames that are provided and/or by examining the primary kernel files. The three subsections below discuss specifying and picking defaults for the ``from'', ``to'', and ``coverage'' frames.

Top

``From'' Frames

The following rules apply to specifying and picking defaults for the ``from'' frames:

--

Top

``To'' Frames

The following rules apply to specifying and picking defaults for the ``to'' frames:

--

Top

``Coverage'' Frames

The following rules apply to specifying and picking defaults for the ``coverage'' frames:

--

Top

Times for Comparison/Sampling

The program picks times at which orientation(s) are computed based on the coverage window determined by examining the primary or additional files(s) and/or specified using the ``-b'' and ``-e'' keys, and on either the number of points within that window specified using the ``-n'' key or the time step specified using the ``-s'' key''.

The coverage window begin and end times specified using the ``-b'' and ``-e'' options can be in any format accepted by SPICE's str2et_c function (see str2et_c header for details). If one or both of these times are provided, an LSK file must be provided as one of the additional or primary kernels.

The number of points specified using the ``-n'' key must be an integer between 1 to 1,000,000 while the step specified using the ``-s'' key must be in seconds and be greater than 1.0E-8. If both ``-n'' and ``-s'' are specified, ``-s'' takes precedence.

The coverage window determined by examining the primary or additional kernels -- especially if these kernels are CK files, which frequently have gaps in coverage -- may consist of many intervals, some of which may be singletons (with the interval begin time equal to the interval end time). Whether the coverage window consists of only one interval or of many intervals, the program computes times within the window in such a way that the interval ends are always included in the set of points. The rest of times are distributed within the intervals, stepping from the beginning of each interval with the specified step. If the number of points is given instead of the step, the step is computed using the measure of the coverage window (the sum of the lengths of the individual intervals) and the specified number of points.

Not all of the keys controlling selection of points have to be specified for every program run. In some cases none of these options are required; in the other cases ``-b'', ``-e'', ``-c1'', and/or ``-c2'' must be specified. The two subsections below discuss specifics of providing and picking defaults for the coverage window and step or number of points.

Top

Coverage Window

The program determines the coverage window either by examining the primary or additional kernels (resulting in the ``default coverage window''), or by using the begin and end times specified using the ``-b'' and ``-e'' keys, or as a combination of both.

The default coverage window can be determined only from the primary or additional kernel files that are binary PCK files (using SPICE's pckcov_c function) or CK files (using SPICE's ckcov_c function) and only if these kernels contain data for the ``coverage'' frames either specified using the ``-c1''/``-c2'' keys or set to default values as described earlier in this document. When both ``coverage'' frames are specified or set to default values, the program determines the frame-specific coverage window for each of them using the corresponding primary or additional kernels and sets the default coverage window to the intersection of these two frame-specific coverage windows. When only one ``coverage'' frame is specified or set to the default value, the program determines the frame-specific coverage window for that frame using corresponding primary or additional kernels and sets the default coverage window to that frame-specific coverage window.

In cases when a frame-specific coverage window is obtained from the corresponding primary kernel, the program examines only that primary kernel to construct the desired frame-specific coverage window. In cases when a frame-specific coverage window is obtained from additional kernels, the program examines all kernels of a particular type -- all CKs if the ``coverage'' frame is a CK-based frame or all binary PCKs if the ``coverage'' frame is a PCK-based frame -- listed explicitly with the ``-k''/``-k1'' or ``-k''/``-k2'' keys or included in meta-kernels provided with these keys and constructs the frame-specific coverage window as the union of coverages obtained from individual additional kernels.

When the program determines the coverage window for a CK file it slightly contracts the actual coverage window given by the CK data to compensate for roundoff occuring in SCLK-ET time conversions. The contraction is done by adjusting inward the window interval boundary times by three times the amout of maximum roundoff that was determined by converting all boundary times from SCLK to ET then back to SCLK. This adjustment is done to ensure that the program is able to compute orientation at any time within the comparison or sampling time domain using the high level SPICE frames routines (pxform_c and sxform_c). While this contraction does not have any noticable effect when the program is run with CKs containing continuous data, it makes the program unuseable with CKs containing disrete data -- Type 1 CKs and Type 3 CKs with singleton intervals -- because such contraction eliminates all singleton intervals corresponding to the discrete time point from the comparison window. The error messages that the program would display in such cases say that CK files do not provide any roundoff-adjusted coverage for a particular CK-based frame. An exception to this limitation is the rare ciscumstance when SCLK-ET time conversions have no round off; in such cases the program will work on CKs containing discrete data.

If the default coverage window was determined from primary or additional kernel file(s) and either ``-b'' or ``-e'', or both ``-b'' and ``-e'' were specified, it is truncated according to these begin and end times. If the time specified using ``-b'' is before the start of the default window, this time is ignored. If the time specified using ``-b'' is after the end of the default coverage window, the program signals an error. If the time specified using ``-e'' is after the end of the default window, this time is ignored. If the time specified using ``-e'' is before the start of the default coverage window, the program signals an error.

If no ``coverage'' frames are specified or set by default, or if one or both ``coverage'' frames are given but corresponding primary or additional kernels don't contain any data for them, both the coverage window begin time and the coverage window end time must be specified using the ``-b'' and ``-e'' keys because the program has no way to determining the default coverage window. If either ``-b'' or ``-e'' is not provided in such cases, the program signals an error.

Top

Times within Coverage Window

The program picks times within the coverage window based on the number of points specified using the ``-n'' key or the time step specified using the ``-s'' key''.

When neither the number of points is specified using ``-n'' nor the step is specified using ``-s'', the number of points is set to a default value determined by examining the coverage window. If the total number of endpoints -- 2 for each non-singleton interval, 1 for each singleton interval -- for all intervals in the coverage window is greater than 1000, the number of points is set to the number of endpoints and the step is not computed. Otherwise it is set to 1000 or a number less than but close to 1000 (the actual number is determined at run-time based on the lengths of the intervals) and the step is computed by dividing the measure of the coverage window by the number of points minus the number of endpoints.

When the number of points is specified using ``-n'' but this number is less than the number of the coverage window interval endpoints, the value given using ``-n'' is ignored and the number of points is set to the number of interval endpoints and the step is not computed. Otherwise the number of points is set to the value provided using ``-n'' or a number less than but close to this value (the actual number is determined at run time based on the lengths of the intervals) and the step is computed by dividing the measure of the coverage window by the number of points minus the number of endpoints.

When step is specified using ``-s'', the number of points is computed by adding the number of interval endpoints to the total of the numbers of points that can fit within each non-singleton interval when it's stepped through with this step. If the resultant number of points is greater than 1,000,000, the program signals an error.

Whether the step was provided or computed using the provided or default number of points, the set of times at which orientation is computed includes all interval ends -- 2 for each non-singleton interval, 1 for each singleton interval -- plus additional points computed by stepping with this step within each non-singleton interval starting from the interval start time. The last point within each non-singleton interval is computed such that it always lies inside the 1.5*step to 0.5*step range off the interval end.

Care should be taken when picking the step using ``-s'' or specifying the number of points using ``-n''. Picking a very small step for a large time window, or very many points for any window, leads to very long run times. In some cases the number of points computed using the step may even be greater that 1,000,000, preventing the program from running because its buffers are not large enough to deal with so many points. On the other hand, picking a large step or too few points prevents the program from doing a thorough comparison.

Top

Angular Velocities

The ``-a'' key is used to tell the program to compute angular velocities in addition to orientations. When the value provided using ``-a'' is ``yes'', the program computes angular velocities and reports them or their differences along with the orientation or orientation differences. If the key is omitted or set to ``no'', the program does not compute angular velocities. For any value other than ``yes'' or ``no'' the program reports an error.

If the program samples or compares angular velocities (``-a yes''), the ``-m'' key is used to specify whether they or their differences should be reported in the ``from'' frame(s) or the ``to'' frame(s). When the value provided using the ``-m'' key is ``to'', the program reports angular velocities or their differences in the ``to'' frames. If the key is omitted or set to ``from'', the program reports angular velocities or their differences in the ``from'' frames. For any value other than ``to'' or ``from'' the program reports an error.

In order for the program to compute angular velocities the data provided to it must support this computation. This is not an issue for any frames except for CK-based frames. Therefore, when using CK files, whether as primary or as additional kernels, it's important to make sure that these CKs include angular velocities before requesting the program to compute angular velocities.

Top

Output

In a successful run the program prints to the screen a report consisting of the report header and report data. The report header provides the complete information about kernels and control parameters used by the program. The report data provides information about the orientation and angular velocity differences (for comparison runs) or orientations and angular velocities (for sampling reports) in a variety of ways, called report types. The algorithms used to compute orientations and angular velocities and their differences and to convert them to various representations used in the reports are shown in ``Appendix 1''.

Top

Overview of Report Types

The report data can be of one of the following types depending on the value provided using the ``-t'' key:

basic: the basic report including only the maximum and the average rotation angle difference (for comparison runs) or rotation angle (for sampling runs) and, if requested, the maximum and the average angular velocity magnitude difference (for comparison runs) or angular velocity magnitude (for sampling runs). This is the default report displayed when ``-t'' is omitted.

stats: the statistics report including a small set of statistical information on the difference between two frame orientations (for comparison runs) or statistics on a single orientation (for sampling runs). In addition to the items from the basic report (maximums and averages), this report includes RMS of the rotation angle difference/angle and angular velocity difference/angular velocity and the times when the maximum value of the rotation angle difference/angle and the angular velocity difference/angular velocity were found.

dumpaa: the angle and axis dump report containing a table listing the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as the rotation angle and axis and, if requested, the components and the magnitude of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the orientations were computed.

dumpm: the matrix dump report containing a table listing the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as a 3x3 rotation matrix and, if requested, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the orientations were computed.

dumpqs: the SPICE-style quaternion dump report containing a table listing the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as a SPICE-style quaternion and, if requested, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the orientations were computed.

dumpqo: produces the ``other''-style quaternion dump report containing a table listing the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as SPICE-style quaternion and, if requested, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the orientations were computed.

dumpea: the Euler angle dump report containing a table listing the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as three Euler angles and, if requested, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the orientations were computed.

dumpc: the coverage intervals dump report containing a table listing the start and stop times and durations for the intervals inside the coverage window, during which orientation(s) can be computed.

dumpg: the coverage gaps dump report containing a table listing the start and stop times and duration for the gaps inside the coverage window, during which orientation(s) cannot be computed.

The ``basic'' and ``stats'' report are useful for quick assessment of whether and by how much two frame transformations differ (for comparison runs) or of the maximum/average magnitude of one frame transformation (for sampling runs). The ``dumpaa'', ``dumpm'', ``dumpqs'', ``dumpqo'', and ``dumpea'' are useful to capture detailed information about differences of two transformations (in comparison runs) or information about a single transformation (for sampling runs) in various formats as a function of time, for analysis or use in other applications. The ``dumpc'' and ``dumpg'' reports are useful for CK or binary PCK coverage overlap analysis.

All reports have rigid formats. The only items in the reports that can be altered by command line options are:

--

Top

Time Tag Format for ``dump*'' Reports

The format of the time tags in the ``dump*'' reports is controlled using the ``-f'' key. The following values can be provided using ``-f'':

et: to display times as TDB seconds past J2000 (default format when ``-f'' is omitted)

sclk: to display times as string SCLKs

sclkd: to display times as decimal SCLKs

ticks: to display times as encoded SCLK ticks

<PICTUR>: a time format picture acceptable for timout_c function. For example:

                    YYYY-MM-DDTHR:MN:SC.### ::RND    for UTC ISO date
                    YYYY-DOYTHR:MN:SC.### ::RND      for UTC ISO DOY
                    JULIAND.######### ::TDB          for Julian day TDB

When one of the SCLK formats (``sclk'', ``sclkd'', ``ticks'') is specified, TDB times used internally by the program are converted to SCLK times using the SCLK ID associated with one of the ``to'' or ``coverage'' CK-based frames in the following priority order (from highest to lowest): first ``to'' frame, first ``coverage'' frame, second ``to'' frame, second ``coverage'' frame. If neither of the ``to'' or ``coverage'' frames is a CK frame, the program signals an error.

When decimal SCLK tags are requested, the SCLK string returned by SPICE's sce2s_c function is converted to ``decimal'' SCLK by stripping off the partition, using the left field as the integer part and converting the rest of the fields to the decimal fraction of the left field using the SCLK field values from the string SCLK and SCLK moduli and offsets from the SCLK kernel file. For example, the SCLK string ``1/883612839.255'' that has seconds in the left field and a count of ticks having duration of 1/256 of a second in the right field is converted to this DP SCLK 883612839.996094. This conversion is supported only for type 1 clocks.

When one of the numeric formats (``et'', ``sclkd'', ``ticks'') is specified, times are displayed in the scientific format with 14 significant digits (e.g. +1.2345678901234E+01), unless ``-d'' is used to specify a different number of significant digits.

``-f'' does not apply to times in the report header and the statistics report, in which the times are always displayed as TDBs in calendar and seconds past J2000 numeric (in scientific format with 14 significant digits) formats.

Top

Numeric Format for ``dump*'' Reports

The default format of numeric time tags (TDB seconds past J2000, decimal SCLKs and encoded SCLK ticks), rotation and angular velocity component values, and rotation and angular velocity difference component values in all ``dump*'' reports is the scientific format with 14 significant digits (e.g. +1.2345678901234E+01). A different number of significant digits can be specified using the ``-d'' option as an integer in the range from 6 to 17. If specified, the number of significant digits is used for all numeric items in the ``dump*'' report data part (table) but is not used for any numbers in the table header or in the data part of the non-``dump*'' (``basic'' and ``stats'') reports.

The default format, with 14 significant digits, is usually adequate for output from all comparison runs and from all sampling runs that are intended to produce tables of rotations or rotation differences for plotting but, due to round off, it may not be adequate for sampling runs that are intended to generate tables of quaternions, angles, or matrices for subsequent interpolation or packaging into CK files. For such outputs the number of significant digits should be increased to 16 -- if output rotations are planned to be packaged into an CK file using the MSOPCK program that employs a custom parser to ingest input numeric data -- or 17 -- if output rotations will read by an application that uses language-native means to parse input numeric data.

Top

Angle Units for ``dumpaa'' and ``dumpea'' Reports

The angles in the ``dumpaa'' and ``dumpea'' reports can be displayed using one of the following units depending on the value provided using the ``-x'' key:

                    radians (default)
                    degrees
                    arcminutes
                    arcseconds
                    hourangle
                    minuteangle
                    secondangle

``-f'' applies neither to the angles in the basic and statistics reports (in which the angles are always displayed in radians) nor to angular velocities in any reports (which are always displayed in radians per second).

Top

Report Header

The top portion of each report generated by the program is occupied by the report header providing complete information about the kernels and control parameters used by the program. The format and the set of information provided in the report header depends on

--

All lines in the report header have

as the first character. This allows common plotting programs, such as GNUPLOT, to skip these header lines when plotting the ``dump''-type reports generated by the program.

Top

Report Header for Comparing Two Orientations

For runs comparing two orientations the report header has the following format (the line numbers given on the left are not present in the actual report; they are provided for referencing purposes only):

    1  #
    2  # Comparison of N rotations
    3  #
    4  #    from 'FROM1NAME' (FROM1ID) to 'TO1NAME' (TO1ID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # with N rotations
   12  #
   13  #    from 'FROM2NAME' (FROM2ID) to 'TO2NAME' (TO2ID)
   14  #    computed using
   15  #
   16  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
   17  #       -K2/KERNEL1 -K2/KERNEL2 ... -K2/KERNELm
   18  #       SECONDKERNEL
   19  #
   20  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   21  # within the continuous time period
   22  #
   23  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   24  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   25  #
   26  # including differences in AVs relative to the FRAME frames.
   27  #
   28  # TIMESPEC.
   29  #

where:

--

            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID <nnn>.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID <nnn>.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID <nnn>.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '<format>' format.''

Top

Report Header for Coverage/Gaps for Two Orientations

For runs displaying coverage or gaps in coverage for two orientations the report header has the following format (the line numbers given on the left are not present in the actual report; they are provided only for referencing purposes):

    1  #
    2  # Coverage overlap for rotation
    3  #
    4  #    from 'FROM1NAME' (FROM1ID) to 'TO1NAME' (TO1ID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # and rotation
   12  #
   13  #    from 'FROM2NAME' (FROM2ID) to 'TO2NAME' (TO2ID)
   14  #    computed using
   15  #
   16  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
   17  #       -K2/KERNEL1 -K2/KERNEL2 ... -K2/KERNELm
   18  #       SECONDKERNEL
   19  #
   20  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   21  # within the continuous time period
   22  #
   23  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   24  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   25  #
   26  # TIMESPEC.
   27  #

where:

--

            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID <nnn>.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID <nnn>.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID <nnn>.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '<format>' format.''

Top

Report Header for Sampling an Orientation

For runs sampling an orientation the report header has the following format (the line numbers given on the left are not present in the actual report; they are provided for referencing purposes only):

    1  #
    2  # Sampling of N rotations
    3  #
    4  #    from 'FROMNAME' (FROMID) to 'TONAME' (TOID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   12  # within the continuous time period
   13  #
   14  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   15  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   16  #
   17  # including angular velocities relative to the FRAME frame.
   18  #
   19  # TIMESPEC
   20  #

where:

--

            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID <nnn>.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID <nnn>.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID <nnn>.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '<format>' format.''

Top

Report Header for Coverage/Gaps for An Orientation

For runs displaying coverage or gaps in coverage for an orientation the report header has the following format (the line numbers given on the left are not present in the actual report; they are provided for referencing purposes only):

    1  #
    2  # Coverage for rotation
    3  #
    4  #    from 'FROMNAME' (FROMID) to 'TONAME' (TOID)
    5  #    computed using
    6  #
    7  #       -K/KERNEL1  -K/KERNEL2  ... -K/KERNELn
    8  #       -K1/KERNEL1 -K1/KERNEL2 ... -K1/KERNELm
    9  #       FIRSTKERNEL
   10  #
   11  # with a S second (DDDAYS:HR:MN:SC.MSECND) step size
   12  # within the continuous time period
   13  #
   14  #    from 'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   15  #    to   'YYYY MON DD HR:MN:SC.### TDB' (SSS.###### TDB seconds)
   16  #
   17  # TIMESPEC
   18  #

where:

--

            -f et       ``Times are TDB seconds past J2000.''
 
            -f sclk     ``Times are SCLKs computed using SCLK
                        ID <nnn>.''
 
            -f sclkd    ``Times are decimal SCLKs computed using
                        SCLK ID <nnn>.''
 
            -f ticks    ``Times are SCLK ticks computed using
                        SCLK ID <nnn>.''
 
            -f PICTURE  ``Times were generated by TIMOUT using
                        '<format>' format.''

Top

Report Formats

Top

Basic Report (no ``-t'' or ``-t basic'')

The basic report indicates if the two frame transformations are different, or if a single transformation is a non-zero transformation, by displaying only the maximum and the average rotation angle difference (for comparison runs) or rotation angle (for sampling runs) and, if requested using the ``-a'' key, the maximum and the average angular velocity magnitude difference (for comparison runs) or angular velocity magnitude (for sampling runs).

The basic report has the following format:

 
   Absolute difference magnitudes:
 
                                       maximum             average
 
     Rotation (rad):                  MAX_ANGLE         AVERAGE_ANGLE
     Angular Velocity (rad/s):        MAX_RATE          AVERAGE_RATE

where:

--

Top

Statistics Report (``-t stats'')

The statistics report provides a small set of statistical information on the difference of two frame transformations (for comparison runs) or a single transformation (for sampling runs). It includes the same items as the basic report (maximums and averages) plus a few additional parameters such as RMS of the rotation angle difference/angle and angular velocity difference/angular velocity and the times when the maximum value of the rotation angle difference/angle and angular velocity difference/angular velocity were found.

The statistics report has the following format:

 
   1) Average difference
 
      1a) Rotation (rad):                               AVERAGE_ANGLE
 
      1b) Angular velocity (rad/s):                     AVERAGE_RATE
 
 
   2) RMS of difference
 
      2a) Rotation (rad):                               RMS_OF_ANGLE
 
      2b) Angular velocity (rad/s):                     RMS_OF_RATE
 
 
   3) Maximum rotation difference
 
      3a) Rotation (rad):                               MAX_ANGLE
 
      3b) Epoch (TDB, seconds past J2000):              TDB_SECONDS
 
      3c) Epoch (TDB, calendar format):         YYYY-MON-DD-HR:MN:SC.MMM
 
 
   4) Maximum angular velocity difference
 
      4a) Angular velocity (rad/s):                     MAX_RATE
 
      4b) Epoch (TDB, seconds past J2000):              TDB_SECONDS
 
      4c) Epoch (TDB, calendar format):         YYYY-MON-DD-HR:MN:SC.MMM

where:

--

Top

Angle and Axis Dump Report (``-t dumpaa'')

The angle and axis dump report displays the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as the rotation angle and axis and, if requested using the ``-a'' key, the components and the magnitude of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the frame transformations were computed. The angle is displayed in units specified using the ``-x'' key -- ``radians'' (default), ``degrees'', ``arcminutes'', ``arcseconds'', ``hourangle'', ``minuteangle'', or ``secondangle''. The time tags are displayed in the format specified using the ``-f'' key, discussed earlier in this document.

The angle and axis dump report has the following format:

   # angle is shown in UNITS.
   #
   # time, angle, axis_x, axis_y, axis_z, av_x, av_y, av_z, av_magnitude
   TIME ANGLE AXIS(1) AXIS(2) AXIS(3) AV(1) AV(2) AV(3) |AV|
   ...
   TIME ANGLE AXIS(1) AXIS(2) AXIS(3) AV(1) AV(2) AV(3) |AV|

where:

--

Top

Matrix Dump Report (``-t dumpm'')

The matrix dump report displays the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as a 3x3 rotation matrix and, if requested using the ``-a'' key, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the frame transformations were computed. The time tags are displayed in the format specified using the ``-f'' key, discussed earlier in this document.

The matrix dump report has the following format:

   # time, m11, m12, m13, m21, m22, m23, m31, m32, m33, av_x, av_y, av_z
   TIME M11 M12 M13 M21 M22 M23 M31 M32 M33 AV(1) AV(2) AV(3)
   ...
   TIME M11 M12 M13 M21 M22 M23 M31 M32 M33 AV(1) AV(2) AV(3)

where:

--

Top

SPICE-Style Quaternion Dump Report (``-t dumpqs'')

The SPICE-style quaternion dump report displays the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as a SPICE-style quaternion and, if requested using the ``-a'' key, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which the frame transformations were computed. The time tag is displayed in the format specified using the ``-f'' key, discussed earlier in this document.

The SPICE-style quaternion dump report has the following format:

   # time, q_cos, q_sin1, q_sin2, q_sin3, av_x, av_y, av_z
   TIME QS(1) QS(2) QS(3) QS(4) AV(1) AV(2) AV(3)
   ...
   TIME QS(1) QS(2) QS(3) QS(4) AV(1) AV(2) AV(3)

where:

--

Top

``Other''-Style Quaternion Dump Report (``-t dumpqo'')

The ``other''-style quaternion dump report displays the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as the ``other''-style (or engineering-style) quaternion and, if requested using the ``-a'' key, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling reports), along with the time, for each of the times at which frame transformations were computed. The time tags are displayed in the format specified using the ``-f'' key, discussed earlier in the document.

The ``other''-style quaternion dump report has the following format:

   # time, q_sin1, q_sin2, q_sin3, q_cos, av_x, av_y, av_z
   TIME QO(1) QO(2) QO(3) QO(4) AV(1) AV(2) AV(3)
   ...
   TIME QO(1) QO(2) QO(3) QO(4) AV(1) AV(2) AV(3)

where:

--

Top

Euler Angles Dump Report (``-t dumpea'')

The Euler angles dump report displays the orientation difference (for comparison runs) or orientation (for sampling runs) expressed as three Euler angles and, if requested using the ``-a'' key, the components of the angular velocity difference (for comparison runs) or angular velocity (for sampling runs), along with the time, for each of the times at which frame transformations were computed. The order of rotations is specified using the ``-o'' key as sequence of three axes from the set of ``X'', ``Y'', ``Z'' (case-insensitive), separated by spaces. The second axis in the sequence must differ from the first and third axes. When ``-o'' is not provided, the default order is set to ``Z Y X''. The angles are displayed in the units specified using the ``-x'' key -- ``radians'' (default), ``degrees'', ``arcminutes'', ``arcseconds'', ``hourangle'', ``minuteangle'', or ``secondangle''. The time tags are displayed in the format specified using the ``-f'' key, discussed earlier in this document.

The Euler angles dump report has the following format:

   # angles are shown in UNITS
   #
   # time, angle_AXIS3, angle_AXIS2, angle_AXIS1, av_x, av_y, av_z
   TIME ANGLE3 ANGLE2 ANGLE1 AV(1) AV(2) AV(3)
   ...
   TIME ANGLE3 ANGLE2 ANGLE1 AV(1) AV(2) AV(3)

where:

--

Top

Coverage Intervals Dump Report (``-t dumpc''):

The coverage intervals dump report displays the start and stop times for the intervals inside the coverage window, during which frame transformations can be computed. The time tags are displayed in the format specified using the ``-f'' key, discussed earlier in the document.

The coverage intervals dump report has the following format:

   # int_start_time, int_end_time, int_duration_sec, int_duration_string
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
   ...
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM

where:

--

Top

Coverage Gaps Dump Report (``-t dumpg'')

The coverage gaps dump report displays the start and stop times for the gaps inside the coverage window, during which frame transformations cannot be computed. The time tags are displayed in the format specified using the ``-f'' key, discussed earlier in this document.

The coverage gaps dump report has the following format:

   # gap_start_time, gap_end_time, gap_duration_sec, gap_duration_string
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM
   ...
   STARTTIME STOPTIME SECONDS DAYS:HR:MN:SC.MMMMMM

--

Top

Examples

The examples below illustrate some of the common FRMDIFF usage scenarios. In all examples the files are assumed to be in the current directory, the FRMDIFF command lines, which usually occupy a single line, span multiple lines and use the UNIX shell style continuation character (backslash), and the report lines are truncated to fit the width of the page (``...'' at the end of a line indicates that it was truncated).

Top

Checking if Two CKs Provide the Same Orientation

In this example the program is run to check if the daily reconstructed MRO CK ``mro_sc_2009-01-26.bc'' and the weekly reconstructed MRO CK ``mro_sc_psp_090120_090126.bc'' provide the same data. The CK files are provided as primary kernels to make the program run in comparison mode. The LSK ``naif0009.tls'' and SCLK ``MRO_SCLKSCET.00027.tsc'', required to support time conversions, and the FK ``mro_v13.tf'', required because it defines the MRO spacecraft frame and the frame used as the base frame in the CKs, apply to both CKs and, therefore, are provided using the ``-k'' key. To make sure the comparison is thorough the step is set to 1 second using the ``-s'' key. No other options need to be specified because the primary kernels are CKs, which the program can examine to automatically pick the ``from'' and ``to'' frames and the coverage window. The basic report displaying the maximum difference will suffice for this case; therefore, there is no need to specify the ``-t'' option.

   % frmdiff -k naif0009.tls MRO_SCLKSCET.00027.tsc mro_v13.tf \
             -s 1 \
             mro_sc_2009-01-26.bc mro_sc_psp_090120_090126.bc
   # int_start_time, int_end_time, int_duration_sec, int_duration_string
   #
   # Comparison of 86401 rotations
   #
   #    from 'MRO_MME_OF_DATE' (-74900) to 'MRO_SPACECRAFT' (-74000)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.tsc mro_v13.tf
   #       mro_sc_2009-01-26.bc
   #
   # with 86401 rotations
   #
   #    from 'MRO_MME_OF_DATE' (-74900) to 'MRO_SPACECRAFT' (-74000)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.tsc mro_v13.tf
   #       mro_sc_psp_090120_090126.bc
   #
   # with a 1.0000000000000 second (0:00:00:01.000000) step size
   # within the continuous time period
   #
   #    from '2009 JAN 26 00:01:06.261' TDB (286200066.26113 TDB seco...
   #    to   '2009 JAN 27 00:01:06.024' TDB (286286466.02413 TDB seco...
   #
 
   Absolute difference magnitudes:
 
                                        maximum                 avera...
 
     Rotation (rad):             +0.0000000000000E+00      +0.0000000...

The zero maximum rotation difference indicates that these two CKs provide the same data.

Top

Comparing Predicted and Reconstructed CKs

In this example the program is run to assess, for a specified period of time, the difference of the spacecraft orientation provided by the predicted CASSINI spacecraft CK ``09009_09025pa_fsiv_lud2.bc'' and the reconstructed CASSINI spacecraft CK ``09006_09011ra.bc''. The CK files are provided as primary kernels to make the program run in comparison mode. The LSK ``naif0009.tls'' and the SCLK ``cas00130.tsc'', required to support time conversions, and the FK ``cas_v40.tf'', required because it defines the CASSINI spacecraft frame, apply to both CKs and, therefore, are provided using the ``-k'' key. The angle and axis dump report is requested using ``-t dumpaa'' and the step is set to 10 seconds using ``-s 10''. The time boundaries for the period of interest are specified using ``-b'' and ``-e''. No other options need to be specified because the primary kernels are CKs, which the program can examine to automatically pick the ``from'' and ``to'' frames and the default coverage window (which is intersected with the window of interest specified using ``-b'' and ``-e''). The program's output is re-directed to the file ``output.txt'' using the ``>'' shell pipe, with the contents of the file shown using the UNIX ``cat'' command.

   % frmdiff -k naif0009.tls cas00130.tsc cas_v40.tf \
             -s 10 -b 2009-JAN-09 00:00 -e 2009-JAN-10 00:00 -t dumpaa \
             09009_09025pa_fsiv_lud2.bc 09006_09011ra.bc \
             > output.txt
   % cat output.txt
   #
   # Comparison of 3143 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09009_09025pa_fsiv_lud2.bc
   #
   # with 3143 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09006_09011ra.bc
   #
   # with a 10.000000000000 second (0:00:00:10.000000) step size
   # within the non-continuous (with 1 gaps) time period
   #
   #    from '2009 JAN 09 15:17:06.359' TDB (284786226.35996 TDB seco...
   #    to   '2009 JAN 10 00:01:06.184' TDB (284817666.18419 TDB seco...
   #
   # Times are TDB seconds past J2000.
   #
   # angle is shown in radians.
   #
   # time, angle, axis_x, axis_y, axis_z
   +2.8478622635996E+08 +5.4958832051797E-05 +8.2101753099566E-01 +4....
   +2.8478623635996E+08 +5.4931030131424E-05 +8.2046010733260E-01 +4....
   +2.8478624635996E+08 +5.4903290577181E-05 +8.1990116349661E-01 +4....
   ...
   +2.8481765833081E+08 +2.3714852496640E-05 +4.7607884330795E-01 -8....
   +2.8481766618419E+08 +1.7506382825421E-05 -3.3218433215999E-01 -6....

The orientation difference expressed as the rotation angle (column 2) can be plotted against TDB seconds (column 1) for analysis.

Note that the time window shown in the report header is different from the requested window specified using the ``-b'' and ``-e'' options. The reason for that is the lack of coverage for the requested windows in one of the CKs (``09009_09025pa_fsiv_lud2.bc'').

To find out when the difference between two orientations is the greatest without plotting the difference as suggested above, the program can be re-run with the same options to generate a statistics report (``-t stats''). For such a run it makes sense to also decrease the time step in order to determine the time of interest more accurately, for example by setting the step to 1 second (``-s 1'').

   % frmdiff -k naif0009.tls cas00130.tsc cas_v40.tf \
             -s 1 -b 2009-JAN-09 00:00 -e 2009-JAN-10 00:00 -t stats \
             09009_09025pa_fsiv_lud2.bc 09006_09011ra.bc
   #
   # Comparison of 31414 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09009_09025pa_fsiv_lud2.bc
   #
   # with 31414 rotations
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09006_09011ra.bc
   #
   # with a 1.0000000000000 second (0:00:00:01.000000) step size
   # within the non-continuous (with 1 gaps) time period
   #
   #    from '2009 JAN 09 15:17:06.359' TDB (284786226.35996 TDB seco...
   #    to   '2009 JAN 10 00:01:06.184' TDB (284817666.18419 TDB seco...
   #
 
   1) Average difference
 
      1a) Rotation (rad):                               0.00007738559...
 
 
   2) RMS of difference
 
      2a) Rotation (rad):                               0.00016380723...
 
 
   3) Maximum rotation difference
 
      3a) Rotation (rad):                               0.00098956656...
 
      3b) Epoch (TDB, seconds past J2000):              284788762.33081
 
      3c) Epoch (TDB, calendar format):         2009-JAN-09-15:59:22.330

As seen in the report the maximum difference between orientations provided by these CKs between 2009-JAN-09 15:17:06 TDB and 2009-JAN-10 00:01:06 TDB is about 1 milliradian near 2009-JAN-09 15:59:22 TDB.

Top

Comparing Orientations from a CK Read Using Different SCLKs

In this example the program is run to assess the effect that using an out-of-date SCLK kernel has on the 2001 Mars Odyssey spacecraft orientation computed from the M01 CK file ``m01_sc_2009-01-27.bc''. To make the program run in comparison mode, the current SCLK ``ORB1_SCLKSCET.00157.tsc'' and the out-of-date SCLK ``ORB1_SCLKSCET.00147.tsc'' are provided using the ``-k1'' and ``-k2'' keys while the CK is provided as the only primary kernel. (Alternatively, the SCLK kernels could be provided as two primary kernels while the CK could be provided using the ``-k'' key, in which case the ``from'' and ``to'' frames and the coverage boundaries would have to be specified because the program would not be able to determine defaults from the SCLK kernels.) The LSK ``naif0009.tls'', required to support time conversions, and the FK ``m01_v28.tf'', required because it defines the M01 spacecraft frame, are provided using the ``-k'' key. The angle and axis dump report is requested using ``-t dumpaa'' and the step size is set to 10 seconds using ``-s 10''. No other options need to be specified because the primary kernel is a CK, which the program can examine to automatically pick the ``from'' and ``to'' frames and the default coverage window. The program's output is re-directed to the file ``output.txt'' using the ``>'' shell pipe, with the contents of the file shown using the UNIX ``cat'' command.

   % frmdiff -k naif0009.tls m01_v28.tf \
             -k1 ORB1_SCLKSCET.00157.tsc \
             -k2 ORB1_SCLKSCET.00147.tsc \
             -s 10 -t dumpaa \
             m01_sc_2009-01-27.bc \
             > output.txt
   % cat output.txt
   #
   # Comparison of 8283 rotations
   #
   #    from 'MARSIAU' (16) to 'M01_SPACECRAFT' (-53000)
   #    computed using
   #
   #       naif0009.tls m01_v28.tf
   #       ORB1_SCLKSCET.00157.tsc
   #       m01_sc_2009-01-27.bc
   #
   # with 8283 rotations
   #
   #    from 'MARSIAU' (16) to 'M01_SPACECRAFT' (-53000)
   #    computed using
   #
   #       naif0009.tls m01_v28.tf
   #       ORB1_SCLKSCET.00147.tsc
   #       m01_sc_2009-01-27.bc
   #
   # with a 10.000000000000 second (0:00:00:10.000000) step size
   # within the non-continuous (with 2 gaps) time period
   #
   #    from '2009 JAN 27 00:01:07.301' TDB (286286467.30114 TDB seco...
   #    to   '2009 JAN 28 00:01:03.083' TDB (286372863.08345 TDB seco...
   #
   # Times are TDB seconds past J2000.
   #
   # angle is shown in radians.
   #
   # time, angle, axis_x, axis_y, axis_z
   +2.8628646730114E+08 +1.6811778261922E-04 -1.6518133891799E-03 -1....
   +2.8628647730114E+08 +1.6807590586987E-04 -2.5417591048513E-03 -9....
   ...
   +2.8637285336657E+08 +1.5490156847677E-04 -1.0767849826583E-03 -1....
   +2.8637286308345E+08 +1.5459290844816E-04 +5.3342008940173E-05 +1....

The orientation difference expressed as rotation angle (column 2) can be plotted against TDB seconds (column 1) for analysis.

Top

Comparing Binary and Text PCKs

In this example the program is run to compare Earth orientations provided by the high precision Earth orientation binary PCK file ``earth_000101_090421_090128.bpc'' and the low precision Earth orientation text PCK file ``pck00008.tpc''. The PCK files are specified as two primary kernels to make the program run in comparison mode. For this run both ``to'' frames must be specified because the frame associated with the high precision orientation -- ``ITRF93'' -- is different from the frame associated with the low precision orientation -- ``IAU_EARTH''. These two frames are provided using the ``-t1'' and ``-t2'' keys. Note that neither the coverage boundaries nor the ``from'' frames need to be specified because the program can set them to default values obtained by examining the binary PCK. The step is set to 1 hour (``-s 3600'') and the report type is picked to be the Euler angle dump (``-t dumpea'') with the rotation axis order Z,Y,X (``-o z y x''). Reporting differences as Euler angles might be desirable in this case because the angles will show how much of the difference is in the pole tilt (combination of angles about X and Y) and how much of it is in the rotation about the pole (angle about Z). The ``-x'' option used to report angles in degrees (``-x degrees''). The program's output is re-directed to the file ``output.txt'' using the ``>'' shell pipe, with the contents of the file shown using the UNIX ``cat'' command.

   % frmdiff -t1 ITRF93 -t2 IAU_EARTH \
             -s 3600 -t dumpea -o Z Y X -x degrees \
             earth_000101_090421_090128.bpc pck00008.tpc \
             > output.txt
   % cat output.txt
   #
   # Comparison of 81553 rotations
   #
   #    from 'ECLIPJ2000' (17) to 'ITRF93' (13000)
   #    computed using
   #
   #       earth_000101_090421_090128.bpc
   #
   # with 81553 rotations
   #
   #    from 'ECLIPJ2000' (17) to 'IAU_EARTH' (10013)
   #    computed using
   #
   #       pck00008.tpc
   #
   # with a 3600.0000000000 second (0:01:00:00.000000) step size
   # within the continuous time period
   #
   #    from '2000 JAN 01 00:01:04.183' TDB (-43135.816087188 TDB sec...
   #    to   '2009 APR 21 00:01:06.185' TDB (293544066.18557 TDB seco...
   #
   # Times are TDB seconds past J2000.
   #
   # angles are shown in degrees.
   #
   # time, ang3_about_Z, ang2_about_Y, ang1_about_X
   -4.3135816087188E+04 +4.6935841900452E-02 -1.3237283886873E-03 -1....
   -3.9535816087188E+04 +4.6935945731300E-02 -8.1268845525487E-04 -2....
   ...
   +2.9354046418391E+08 +5.9885369786058E-02 -1.7263299596662E-03 +1....
   +2.9354406618557E+08 +5.9885381660130E-02 -1.9758128919827E-03 +5....

The Euler angles about Z, Y, and X (column 2, 3, 4) can be plotted against TDB seconds (column 1) for analysis.

Top

Comparing Two Text PCKs

In this example the program is run to compare Mars orientations provided by the text PCK file ``pck00006.tpc'' containing 1994 IAU constants and the text PCK ``pck00008.tpc'' containing IAU 2000 constants. The PCK files are specified as two primary kernels to make the program run in comparison mode. Since both files are neither CKs nor binary PCKs, the ``from'' and ``to'' frames and the time boundaries for coverage window must be specified using the ``-t1'' (or ``-t2''), ``-f1'' (or ``-f2''), and ``-b'' and ``-e'' keys. Since the time boundaries are provided on the command line, the LSK ``naif0009.tls'' required for time conversions must be provided using ``-k'' (either ``-k1'' or ``-k2'' can also be used). The step is set to 1 hour (``-s 3600'') and the report type is picked to be the Euler angles dump (``-t dumpea'') with the rotation axis order Z,Y,X (``-o z y x''). Reporting differences as Euler angles might be desirable in this case because the angles will show how much of the difference is in the pole tilt (combination of angles about X and Y) and how much of it is in the rotation about the pole (angle about Z). The ``-x'' option is used to report angles in degrees (``-x degrees''). The ``-f'' option is used to print times as UTC in ISO date format (``-f YYYY-MM-DDTHR:MN:SC ::RND''). The program's output is re-directed to the file ``output.txt'' using the ``>'' shell pipe, with the contents of the file shown using the UNIX ``cat'' command.

   % frmdiff -k naif0009.tls -f1 J2000 -t1 IAU_MARS \
             -b 2005-01-01 -e 2006-01-01 \
             -t dumpea -o z y x -x degrees \
             -f YYYY-MM-DDTHR:MN:SC ::RND -s 3600 \
             pck00006.tpc pck00008.tpc \
             > output.txt
   % cat output.txt
   #
   # Comparison of 8761 rotations
   #
   #    from 'J2000' (1) to 'IAU_MARS' (10014)
   #    computed using
   #
   #       naif0009.tls
   #       pck00006.tpc
   #
   # with 8761 rotations
   #
   #    from 'J2000' (1) to 'IAU_MARS' (10014)
   #    computed using
   #
   #       naif0009.tls
   #       pck00008.tpc
   #
   # with a 3600.0000000000 second (0:01:00:00.000000) step size
   # within the continuous time period
   #
   #    from '2005 JAN 01 00:01:04.183' TDB (157809664.18393 TDB seco...
   #    to   '2006 JAN 01 00:01:05.183' TDB (189345665.18393 TDB seco...
   #
   # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC ::RND'...
   #
   # angles are shown in degrees.
   #
   # time, ang3_about_Z, ang2_about_Y, ang1_about_X
   2005-01-01T00:00:00 +2.7193295981800E-01 +4.3458477098658E-04 +4.0...
   2005-01-01T01:00:00 +2.7193298908895E-01 +3.1750496671468E-04 +5.0...
   ...
   2005-12-31T23:00:00 +2.7218789688912E-01 +3.4616175147429E-04 -4.9...
   2006-01-01T00:00:00 +2.7218792598016E-01 +4.5965878416891E-04 -3.9...

The Euler angles about Z, Y, and X (column 2, 3, 4) can be plotted against UTC (column 1) for analysis.

Top

Sampling Orientation from a CK

In this example the program is run to sample the orientation and angular velocity of Deep Impact Flyby (DIF) spacecraft from the daily CK ``dif_sc_2009-01-27.bc'' every five seconds over the whole period covered by the file and and print the orientation as engineering style quaternions and angular velocities expressed in the spacecraft frame, tagged with DP SCLKs. In addition to the CK file the LSK ``naif0009.tls'' and SCLK ``DIF_SCLKSCET.00036.tsc'', required to support time conversions, and the FK ``di_v17.tf'', required because it defines the DIF spacecraft frame, must be provided to the program. The CK file is provided as the only primary kernel and all other kernels are provided using ``-k'' to make the program run in sampling mode. The step is set to 5 seconds using ``-s 5''. The report type is set to the ``other''-style quaternion dump using ``-t dumpqo''. The output time format is set to DP SCLK using ``-f sclkd''. ``-a yes'' and ``-m to'' are specified to add angular velocities rotated to the spacecraft frame (the ``to'' frame) to the output. No other options need to be specified because the primary kernel is a CK, which the program can examine to automatically pick the ``from'' and ``to'' frames and the coverage window. The program's output is re-directed to the file ``output.txt'' using the ``>'' shell pipe, with the contents of the file shown using the UNIX ``cat'' command.

   % frmdiff -k naif0009.tls DIF_SCLKSCET.00036.tsc di_v17.tf \
             -s 5 -t dumpqo -f sclkd -a yes -m to \
             dif_sc_2009-01-27.bc \
             > output.txt
   % cat output.txt
   #
   # Sampling of 16864 rotations
   #
   #    from 'J2000' (1) to 'DIF_SPACECRAFT' (-140000)
   #    computed using
   #
   #       naif0009.tls DIF_SCLKSCET.00036.tsc di_v17.tf
   #       dif_sc_2009-01-27.bc
   #
   # with a 5.0000000000000 second (0:00:00:05.000000) step size
   # within the non-continuous (with 2 gaps) time period
   #
   #    from '2009 JAN 27 00:01:06.713' TDB (286286466.71354 TDB seco...
   #    to   '2009 JAN 28 00:01:05.346' TDB (286372865.34683 TDB seco...
   #
   # including angular velocities relative to 'to' frame.
   #
   # Times are decimal SCLKs computed using SCLK ID -140.
   #
   # time, q_sin1, q_sin2, q_sin3, q_cos, av_x, av_y, av_z
   2.8628543276953E+08 +6.9350853049532E-01 +3.7594179111024E-01 -6.1...
   2.8628543776953E+08 +6.9350851552324E-01 +3.7594215798843E-01 -6.1...
   ...
   2.8637182501172E+08 +6.9259444035804E-01 +3.8202205741497E-01 -6.0...
   2.8637183010156E+08 +6.9259433874053E-01 +3.8202240378948E-01 -6.0...

Top

Sampling Orientation of a Built-in Frame

In this example the program is run to print the rotation from the ``J2000'' frame to the ``ECLIPJ2000'' frame, both of which are built-in frames. To get this rotation, ``J2000'' is specified using ``-f1'' and ``ECLIPJ2000'' is specified using ``-t1''. While it may seem that no kernels would be needed in this case, it is not true. An LSK must be provided to the program because the time at which the orientation should be computed must be provided on the command line twice using the ``-b'' and ``-e'' keys and this time has to be converted to TDB inside the program. Therefore the program is given the LSK ``naif0009.tls'' using the ``-k'' option and an arbitrary time (``2000-01-01'') twice using the ``-b'' and ``-e'' options. The Euler angle dump report is picked using ``-t dump'' with the axis order X,Y,Z picked using ``-o x y z''. The angles are requested to be printed in degrees using ``-x degrees''.

   % frmdiff -k naif0009.tls \
             -f1 J2000 -t1 ECLIPJ2000 \
             -b 2000-01-01 -e 2000-01-01 \
             -t dumpea -o x y z -x degrees
   #
   # Sampling of 1 rotations
   #
   #    from 'J2000' (1) to 'ECLIPJ2000' (17)
   #    computed using
   #
   #       naif0009.tls
   #
   # at continuous coverage intervals' endpoints
   # within the continuous time period
   #
   #    from '2000 JAN 01 00:01:04.183' TDB (-43135.816087188 TDB sec...
   #    to   '2000 JAN 01 00:01:04.183' TDB (-43135.816087188 TDB sec...
   #
   # Times are TDB seconds past J2000.
   #
   # angles are shown in degrees.
   #
   # time, ang3_about_X, ang2_about_Y, ang1_about_Z
   -4.3135816087188E+04 +2.3439291111111E+01 +0.0000000000000E+00 +0....

Top

Sampling Orientation of a Dynamic Frame

In this example the program is run to sample orientation of the Geocentric Solar Ecliptic frame (``GSE''), a dynamic frame defined in the FK ``RSSD0002.TF'', relative to the ``J2000'' inertial frame and print this orientation as Euler angles tagged with Julian day TDB. The frames are specified using ``-f1'' and ``-t1''. All kernels needed to compute this transformation and convert times -- the FK, LSK ``NAIF0009.TLS'' and SPK ``DE405.BSP'' -- are listed using the ``-k'' key. Since there are no primary kernels, the default coverage window cannot be picked automatically. Therefore the coverage window boundaries are specified using ``-b'' and ``-e''. The step is set to 1 day using ``-s 86400''. The Euler angles dump report is requested using ``-t dumpea''. The time format for output is set to be the Julian day TDB using

   -f 'JULIAND.######### ::TDB''

The program's output is re-directed to the file ``output.txt'' using the ``>'' shell pipe, with the contents of the file shown using the UNIX ``cat'' command.

   % frmdiff -k RSSD0002.TF NAIF0009.TLS DE405.BSP \
             -f1 J2000 -t1 GSE \
             -b 2008-01-01 -e 2009-01-01 -s 86400 \
             -t dumpea -f 'YYYY-MM-DD HR:MN:SC.### ::RND ::TDB' \
             > output.txt
   % cat output.txt
   #
   # Sampling of 367 rotations
   #
   #    from 'J2000' (1) to 'GSE' (1500399)
   #    computed using
   #
   #       RSSD0002.TF ../lsk/NAIF0009.TLS ../spk/DE405.BSP
   #
   # with a 86400.000000000 second (1:00:00:00.000000) step size
   # within the continuous time period
   #
   #    from '2008 JAN 01 00:01:05.183' TDB (252417665.18391 TDB seco...
   #    to   '2009 JAN 01 00:01:06.183' TDB (284040066.18393 TDB seco...
   #
   # Times were generated by TIMOUT using 'JULIAND.######### ::TDB' f...
   #
   # angles are shown in radians.
   #
   # time, ang3_about_Z, ang2_about_Y, ang1_about_X
   2454466.500754400 -1.3994266054604E+00 +1.6337747151270E-06 +4.090...
   2454467.500754400 -1.3816355414305E+00 +1.6343360047251E-06 +4.090...
   ...
   2454831.500754400 -1.4039978657128E+00 +1.8387392674578E-06 +4.090...
   2454832.500766000 -1.3862038203964E+00 +1.8393010792771E-06 +4.090...

Top

Sampling Orientation With Two Different ``Coverage'' Frames

In this example the program is run to sample orientation of the MGS MAG +Y sensor frame, ``MGS_MAG_+Y_SENSOR'', relative to the ``J2000'' inertial frame over two hour period from 2006-04-01 11:00 to 2006-04-01 13:00 (given using ``-b'' and ``-e'') and print this orientation as Euler angles tagged with UTC in ISO-date format. The ``from'' and ``to'' frames are specified using ``-f1'' and ``-t1''. All kernels needed to compute this transformation and convert times are listed in the meta-kernel ``mgs_2006_v01.tm'' from the MGS SPICE PDS data set, specified using the ``-k'' key. Because computing this orientation requires data from MGS solar array CKs and spacecraft CKs, both of which have gaps in coverage, ``-c1'' and ``-c2'' are used to tell the program to look up available coverages for the frames ``MGS_LEFT_SOLAR_ARRAY'' and ``MGS_SPACECRAFT'' associated with data in these CKs and intersect this available coverage with the requested two hour interval to guarantee that the program won't stop from not being able to compute orientation in one of the gaps. The step is set to 1 minute using ``-s 60''. The Euler angles dump report is requested using ``-t dumpea''. The time format for output is set to be the UTC in ISO-date format using

   -f  'YYYY-MM-DDTHR:MN:SC.### ::RND'

The program's output is re-directed to the file ``output.txt'' using the ``>'' shell pipe, with the contents of the file shown using the UNIX ``cat'' command.

   % frmdiff -k  mgs_2006_v01.tm \
             -f1 J2000 \
             -t1 MGS_MAG_+Y_SENSOR \
             -c1 MGS_LEFT_SOLAR_ARRAY \
             -c2 MGS_SPACECRAFT \
             -t  dumpea \
             -f  'YYYY-MM-DDTHR:MN:SC.### ::RND' \
             -b  2006-04-01 11:00 \
             -e  2006-04-01 13:00 \
             -s  60 \
             > output.txt
   % cat output.txt
   #
   # Sampling of 121 rotations
   #
   #    from 'J2000' (1) to 'MGS_MAG_+Y_SENSOR' (-94051)
   #    computed using
   #
   #       mgs_2006_v01.tm
   #
   # with a 60.000000000000 second (0:00:01:00.000000) step size
   # within the non-continuous (with 1 gaps) time period
   #
   #    from '2006 APR 01 11:01:05.185' TDB (197161265.18566 TDB seco...
   #    to   '2006 APR 01 13:01:05.185' TDB (197168465.18566 TDB seco...
   #
   # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC.### ::...
   #
   # angles are shown in radians.
   #
   # time, ang3_about_Z, ang2_about_Y, ang1_about_X
   2006-04-01T11:00:00.000 +1.1187945929621E+00 -1.7969108686644E-01 ...
   2006-04-01T11:01:00.000 +1.1187852723628E+00 -1.7931962082645E-01 ...
   2006-04-01T11:02:00.000 +1.1186582180859E+00 -1.7869508126719E-01 ...
   ...
   2006-04-01T12:57:55.804 +1.1175120633959E+00 -1.7734256227094E-01 ...
   2006-04-01T12:58:55.804 +1.1174237423840E+00 -1.7692771707569E-01 ...
   2006-04-01T13:00:00.000 +1.1173605546240E+00 -1.7633741045076E-01 ...

Top

Displaying Overlap in Coverage between Two CKs

In this example the program is run to determine the time intervals when both the MRO spacecraft CK ``mro_sc_psp_080408_080414.bc'' and MRO CRISM instrument CK ``mro_crm_psp_080413_080430.bc'' provide coverage and to display the boundaries of these intervals as UTC in ISO DOY format. The CKs are provided as the two primary kernels with other kernels -- the LSK ``naif0009.tls'' and the SCLK ``MRO_SCLKSCET.00027.65536.tsc'', required for time conversions, and the MRO FK ``mro_v13.tf'', defining frames used in the CKs, -- provided using ``-k''. The report is set to the coverage intervals dump using ``-t dumpc'' and the output time format is set to UTC in ISO DOY format using

   -f 'YYYY-DOYTHR:MN:SC.### ::RND'

For runs like this usually both ``from'' frames and both ``to'' frames should be specified using ``-f1'', ``-f2'', ``-t1'', and ``-t2'' and these frames should match the base and structure frames from the CK files (the names of the base and structure frames can be seen in the CK summary produced by the ``BRIEF'' utility program run using the ``-rel -n'' options).

   % frmdiff -k naif0009.tls MRO_SCLKSCET.00027.65536.tsc mro_v13.tf \
             -f1 MRO_MME_OF_DATE -t1 MRO_SPACECRAFT \
             -f2 MRO_CRISM_BASE  -t2 MRO_CRISM_ART \
             -t dumpc -f 'YYYY-DOYTHR:MN:SC.### ::RND' \
             mro_sc_psp_080408_080414.bc mro_crm_psp_080413_080430.bc
   #
   # Coverage overlap for rotation
   #
   #    from 'MRO_MME_OF_DATE' (-74900) to 'MRO_SPACECRAFT' (-74000)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.65536.tsc mro_v13.tf
   #       mro_sc_psp_080408_080414.bc
   #
   # and rotation
   #
   #    from 'MRO_CRISM_BASE' (-74011) to 'MRO_CRISM_ART' (-74012)
   #    computed using
   #
   #       naif0009.tls MRO_SCLKSCET.00027.65536.tsc mro_v13.tf
   #       mro_crm_psp_080413_080430.bc
   #
   # with a 0.56599156324219 second (0:00:00:00.565992) step size
   # within the non-continuous (with 22 gaps) time period
   #
   #    from '2008 APR 13 00:29:16.745' TDB (261318556.74553 TDB seco...
   #    to   '2008 APR 13 01:12:03.742' TDB (261321123.74222 TDB seco...
   #
   # Times were generated by TIMOUT using 'YYYY-DOYTHR:MN:SC.### ::RN...
   #
   # interval_start, interval_stop, interval_duration_sec, interval_d...
   2008-104T00:28:11.560 2008-104T00:31:11.564         180.003858    ...
   2008-104T00:43:10.558 2008-104T00:43:14.559           4.001042    ...
   ...
   2008-104T01:10:08.423 2008-104T01:10:12.424           4.000950    ...
   2008-104T01:10:54.556 2008-104T01:10:58.557           4.001042    ...

Top

Displaying Gaps in a CK File

In this example the program is run to display the gaps in the CASSINI CK ``09006_09011ra.bc''. The CK is given as the only primary kernel, with all other kernels -- the LSK ``naif0009.tls'' and the SCLK ``cas00130.tsc'', required for time conversions, and the CASSINI FK ``cas_v40.tf'', defining frames used in the CK, -- provided using ``-k''. The report type is set to the coverage gaps dump using ``-t dumpg'' and the output time format is set to UTC in ISO date format using

   -f 'YYYY-MM-DDTHR:MN:SC.### ::RND'

There is no need to specify the ``to'' and ``from'' frames because the program will pick them automatically by examining the CK file.

   % frmdiff -k naif0009.tls cas00130.tsc cas_v40.tf \
             -t dumpg -f 'YYYY-MM-DDTHR:MN:SC.### ::RND' \
             09006_09011ra.bc
   #
   # Coverage for rotation
   #
   #    from 'J2000' (1) to 'CASSINI_SC_COORD' (-82000)
   #    computed using
   #
   #       naif0009.tls cas00130.tsc cas_v40.tf
   #       09006_09011ra.bc
   #
   # with a 439.60863577834 second (0:00:07:19.608636) step size
   # within the non-continuous (with 8 gaps) time period
   #
   #    from '2009 JAN 06 00:01:08.565' TDB (284472068.56521 TDB seco...
   #    to   '2009 JAN 11 00:01:05.243' TDB (284904065.24341 TDB seco...
   #
   # Times were generated by TIMOUT using 'YYYY-MM-DDTHR:MN:SC.### ::...
   #
   # gap_start, gap_stop, gap_duration_sec, gap_duration_string
   2009-01-06T13:45:49.779 2009-01-06T13:46:10.029          20.249856...
   2009-01-06T15:15:49.740 2009-01-06T15:16:49.990          60.249572...
   ...
   2009-01-09T15:16:43.897 2009-01-09T15:17:12.147          28.249799...
   2009-01-10T17:18:27.481 2009-01-10T17:18:55.480          27.999801...

Top

Miscellaneous Things to Consider

Top

``Apples vs. Oranges''

Even though the program has the flexibility to compare any two transformations -- for example the transformation from the ``J2000'' frame to the ``IAU_MARS'' frame with the transformation from the ``MRO_SPACECRAFT'' frame to the ``MRO_CTX'' frame -- it doesn't mean that such comparisons make sense. In general, it makes sense to compare only transformations that are close to each other and have the same ``from'' frame.

Top

Using Euler Angles for Small Rotation Differences

While Euler angles included in the Euler angles dump report (``-t dumpea'') may be one of the more intuitive representations of rotations, in many cases, depending on the rotation order, the angle magnitudes can be large and not representative of the small rotation differences. The total rotation angle provided in the rotation angle and axis report (``-t dumpaa'') is a much more reliable indicator of the difference of two rotations.

Top

Single Epoch

Due to the algorithm which the program uses to determine the coverage window, when orientations must be compared at, or an orientation must be sampled at, a certain epoch this epoch must be provided on the command line twice, once using the ``-b'' key and once using the ``-e'' key.

Top

References

1.

2.

3.

4.

5.

6.

Acronyms

AV: angular velocity

ET: Ephemeris Time (synonymous to TDB)

SCLK: Spacecraft CLocK time

TDB: Barycentric Dynamical Time (synonymous to ET)

Top

Appendix 1: Comparison, Sampling and Report Quantity Algorithms

Top

Computing Rotation and Angular Velocity Difference

When run in comparison mode the program uses the following SPICE routines to compute the rotation and angular velocity differences at each of the times:

--

            pxform_c ( FROM1, TO1, ET, M1 );
            pxform_c ( FROM2, TO2, ET, M2 );
 
            mxmt_c   ( M1, M2, MDIFF );

--

            sxform_c ( FROM1, TO1, ET, X1 );
            xf2rav_c ( X1, M1, AV1 );
 
            sxform_c ( FROM2, TO2, ET, X2 );
            xf2rav_c ( X2, M2, AV2 );
 
            mxmt_c   ( M1, M2, MDIFF );
            vsub_c   ( AV1, AV2, AVDIFF );

--

            sxform_c ( FROM1, TO1, ET, X1 );
            xf2rav_c ( X1, M1, AV1 );
 
            sxform_c ( FROM2, TO2, ET, X2 );
            xf2rav_c ( X2, M2, AV2 );
 
            mxmt_c   ( M1, M2, MDIFF );
            vsub_c   ( AV1, AV2, AVDIFFFR );
 
            mxv_c    ( M1, AVDIFFFR, AVDIFF );

where FROM1, FROM2, TO1, TO2, and ET are the ``from'' and ``to'' frames of interest and time, MDIFF and AVDIFF are the rotation and angular velocity differences to be reported.

Top

Sampling Rotation and Angular Velocity

When run in sampling mode the program uses the following SPICE routines to compute the rotation and angular velocity at each of the times:

--

            pxform_c ( FROM, TO, ET, MDIFF );

--

            sxform_c ( FROM, TO, ET, X );
            xf2rav_c ( X, MDIFF, AVDIFF );

--

            sxform_c ( FROM, TO, ET, X );
            xf2rav_c ( X, MDIFF, AV );
 
            mxv_c    ( MDIFF, AV, AVDIFF );

where FROM, TO, and ET are the ``from'' and ``to'' frames of interest and time, MDIFF and AVDIFF are the rotation and angular velocity to be reported.

Top

Converting Rotation to Angle/Axis

If no ``-t'' is specified, or if ``-t basic'', ``-t stats'', or ``-t dumpaa'' is specified, the program converts MDIFF to the rotation angle and axis using

            raxisa_c ( MDIFF, AXIS, ANGLE );

Top

Converting Rotation to SPICE-Style Quaternion

If ``-t dumpqs'' is specified, the program converts MDIFF to the SPICE-style quaternion using

            m2q_c ( MDIFF, QS );

Top

Converting Rotation to ``Other''-Style quaternion

If ``-t dumpqo'' is specified, the program converts MDIFF to the ``other''-style quaternion using

            m2q_c ( MDIFF, QS );
            QO[0] = -QS[1];
            QO[1] = -QS[2];
            QO[2] = -QS[3];
            QO[3] =  QS[0];

Top

Converting Rotation to Euler Angles

If ``-t'' dumpea is specified, the program converts MDIFF to Euler angles using

            m2eul_c ( MDIFF, AXIS3, AXIS2, AXIS1, ANG3, ANG2, ANG1 );

where AXIS1-3 are either defaults (``Z Y X'') or the axes specified using the ``-o'' key. The axes are ``passed'' as input to M2EUL in the same order as they are listed using ``-o''. For example, for ``-o X Z Y'' M2EUL is called with ``( MDIFF, 1, 3, 2, ...)''.

Table of Contents

FRMDIFF User's Guide

Abstract

Summary

If You Are in a Hurry

To Check if Two CK Files Provide Identical Data

To Assess Difference Between Two CK Files

To Sample Quaternions from a CK File

To Compute Transformation Between Two Frames

Usage

Options

Inputs

Kernel Files

Primary Kernel Files

Additional Kernel Files

Comparison Runs vs. Sampling Runs

Runs with Two, One, and No Primary Kernel File(s)

Runs with Two Primary Kernel Files

Runs with One Primary Kernel File

Runs Without Primary Kernel Files

``From'', ``To'', and ``Coverage'' Frames

``From'' Frames

``To'' Frames

``Coverage'' Frames

Times for Comparison/Sampling

Coverage Window

Times within Coverage Window

Angular Velocities

Output

Overview of Report Types

Time Tag Format for ``dump*'' Reports

Numeric Format for ``dump*'' Reports

Angle Units for ``dumpaa'' and ``dumpea'' Reports

Report Header

Report Header for Comparing Two Orientations

Report Header for Coverage/Gaps for Two Orientations

Report Header for Sampling an Orientation

Report Header for Coverage/Gaps for An Orientation

Report Formats

Basic Report (no ``-t'' or ``-t basic'')

Statistics Report (``-t stats'')

Angle and Axis Dump Report (``-t dumpaa'')

Matrix Dump Report (``-t dumpm'')

SPICE-Style Quaternion Dump Report (``-t dumpqs'')

``Other''-Style Quaternion Dump Report (``-t dumpqo'')

Euler Angles Dump Report (``-t dumpea'')

Coverage Intervals Dump Report (``-t dumpc''):

Coverage Gaps Dump Report (``-t dumpg'')

Examples

Checking if Two CKs Provide the Same Orientation

Comparing Predicted and Reconstructed CKs

Comparing Orientations from a CK Read Using Different SCLKs

Comparing Binary and Text PCKs

Comparing Two Text PCKs

Sampling Orientation from a CK

Sampling Orientation of a Built-in Frame

Sampling Orientation of a Dynamic Frame

Sampling Orientation With Two Different ``Coverage'' Frames

Displaying Overlap in Coverage between Two CKs

Displaying Gaps in a CK File

Miscellaneous Things to Consider

``Apples vs. Oranges''

Using Euler Angles for Small Rotation Differences

Single Epoch

References

Acronyms

Appendix 1: Comparison, Sampling and Report Quantity Algorithms

Computing Rotation and Angular Velocity Difference

Sampling Rotation and Angular Velocity

Converting Rotation to Angle/Axis

Converting Rotation to SPICE-Style Quaternion

Converting Rotation to ``Other''-Style quaternion

Converting Rotation to Euler Angles