FRMDIFF User's Guide =========================================================================== Last revised on 2014 JAN 21 by B. V. Semenov. 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. 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. 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. 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 -s where ``'', ``'', ``'', ``'' and ``'' 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 -a yes -s 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 -t dumpaa -s where ``'', ``'', ``'', ``'' and ``'' 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 -t dumpaa -a yes -s 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 -t dumpqs -s where ``'', ``'', ``'', and ``'' 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 -t dumpqo -a yes -m to -s 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 -t dumpea -b -e -s -f1 -t1 where ``'' 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; ``'' and ``'' set the begin and end time, as UTC, for the period of interest; ``step'' is the time step, in seconds; and ``'' and ``'' 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 ``'' is a CK-based (Class 3) or PCK-based (Class 2) frame, the list of kernels (``'') includes CKs or binary PCKs providing data for that frame, and ``-b -e '' are omitted, the program will automatically determine the ``''s data availability time window and will compute transformations with specified step over that whole window. Usage -------------------------------------------------------- FRMDIFF is a command line program with the following usage: % frmdiff [options] % frmdiff [options] % frmdiff [options] where either of the kernels can be a CK, a PCK, an FK, or any other SPICE kernel. The options are: -k -f1 -t1 -c1 -k1 -f2 -t2 -c2 -k2 -a -m -e -n -s