Cassini MAG Data Processing Software: CAL 1.0 User Guide

This document is a guide to TransCal, the data processing application that transforms calibrated magnetic field vectors from the spacecraft coordinate system to a user-selected available coordinate system. This document explains what TransCal does, how to install it, and how to use it. Examples are provided.

Contents

2. Scope

This document is included in the DOCUMENT/TRANSCAL_GUIDE directory of each MAG Archive volume. See Section 4.6 of Ref. 1 below.

Contents

3. References

1. MAG Standard Data Products Archive Volume Software Interface Specification, Document IO-AR-020, N. Achilleos, S. Kellock, A. Hitchman and S. Joy, 2004 (revised 2005).

2. ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/ascii/individual_docs

Contents

4. Introduction

TransCal transforms calibrated magnetic field vectors from spacecraft coordinates into a user-selected coordinate system. Available coordinate systems include standard inertial reference systems and body-fixed systems for Earth, Jupiter, and Saturn.

TransCal reads calibrated magnetic field vectors from a file produced by the application CAL02. (The application CAL02 and its User Guide are included in the CALIB directory of each MAG Archive volume.) The CAL02 calibrated vector files are of the type known as “UCLA Flatfiles”; data files are binary with fixed-length records and have accompanying text header files. Each data record produced by CAL02 contains time (Spacecraft Clock), a calibrated FGM or VHM magnetic field vector, and two status words.

In order to perform coordinate transformations, TransCal relies extensively on the SPICE package of subroutines and kernel files (see Ref. 2). At runtime various SPICE kernel files need to be loaded that provide information regarding the spacecraft trajectory, spacecraft attitude, planetary constants, leapseconds, and Spacecraft Clock (SCLK) time conversion. Examples of these SPICE kernel files are included in the SOFTWARE/EXAMPLE_FILES directory of the MAG Archive. See Table 20 of Ref. 1 for descriptions of these SPICE kernel files. Spacecraft attitude information may be obtained either from a SPICE C kernel or from a MAG REDR Standard Product data file of type CHATT (See Table 15 and Table 31 of Ref. 1).

TransCal writes output files in flatfile format. Each record contains time (Spacecraft Event Time in TAI, International Atomic Time), calibrated magnetic field vector in selected coordinate system, magnitude of calibrated magnetic field vector, and position of spacecraft with respect to user-selected reference body. (See Sec. 6.3.1 of this document.) A report file is also generated that displays user selections, names of files loaded, and number of vectors read and written.

Contents

5. Installation

TransCal was developed in Microsoft Visual C/C++, running under Windows NT, according to the requirements specified by the MAG Principal Investigator. For MS Windows systems, the application file TransCal.EXE may simply be copied into a convenient directory. Alternatively, one may open MS Visual C/C++, create a new project, add to the project the TransCal source code files and the SPICE Toolkit Library, and compile and build a new executable. See Table 1 in Appendix of this document for description of source code files.

TransCal could with some changes be compiled and run on other operating systems. It does not explicitly call any system-dependent functions but uses flatfile functions available in the UCLA source code files FF_IGPP and TIME_IGPP. The UCLA source code is designed to be used with Unix, MacOS, and Linux, in addition to Windows, by means of appropriate DEFINE statements. TransCal also relies extensively on functions from the CSPICE library. This library is part of the CSPICE package, which is compatible with most operating systems, and is available for downloading at ftp://naif.jpl.nasa.gov/pub/naif.

Contents

6. Usage

TransCal is a Win32 Console Application. This means that when TransCal is launched, by double-clicking on the application icon or a shortcut, a DOS-type window will appear, in which the user types answers to various questions. (Console applications may also be launched by opening the Command Prompt window and typing the name of the application. This is convenient because the properties of the command window can be customized.)

First the user is asked the name of the file in which to write the report for this run, and the report file is opened. Then the user chooses the Reference Body for the output spacecraft position and selects the coordinate system into which the magnetic field vector will be transformed. Next, the user chooses whether to obtain spacecraft attitude information from quaternions in a channelized attitude flatfile or from a SPICE C kernel. (The C option is preferred if the C kernel file is available.) Then the user is asked for the name of a SPICE metafile that contains the filenames of all the SPICE kernel files to be loaded. The number of SPICE kernel files that are successfully opened and loaded is displayed. The user is then asked for the name of the input calibrated vector data file and whether byte-swapping needs to be applied, and similarly the name of the output data file. (Byte order is reversed for PC and Unix systems, so input flatfiles generated on a Unix system need to be byte swapped, and output flatfiles intended for use on a Unix system also need to be byte swapped.) If the quaternion attitude option was chosen, the user is asked for the name of the CHATT flatfile.

The report file displays the user inputs, the types and names of the SPICE kernel files that were loaded, the name of the CHATT file if one was used, and the number of vectors read and written.

When TransCal is run interactively as described above, the user will be given the choice of re-entering names of files that cannot be opened. If batch processing is being used, that is, if the standard input has been assigned to a file instead of a device, a file that cannot be opened will cause TransCal to exit after writing an error message to the report file.

6.1 Sample TransCal Console Window

C:\cassini\y99archive>transcal
TransCal v050324

Enter Report File Name: transcal_rpt.txt
Opened Report File transcal_rpt.txt

Enter Reference Body ID
      (399 for Earth, 699 for Saturn, 599 for Jupiter, 10 for Sun): 399

Available Coordinate Systems:
     0 J2000
     1 ECLIPJ2000
     2 IAU_VENUS
     3 IAU_EARTH
     4 GSE
     5 GSM
     6 RTN
     7 CASSINI (no transformation)
     8 J3 (IAU_JUPITER)
     9 JMAG XYZ
     10 JMAG RTP
     11 KG (IAU_SATURN)
     12 SATURN RTP
     13 KSM (SUN-SATURN)
     14 KSO (SUN-SATURN_ORBIT_PLANE
Enter Number of Coordinate System: 4

Enter Q to use Quaternions from flatfile, C to use C-Kernel file: c

Enter Name of Spice Metafile with KERNELS_TO_LOAD:
kernels.txt
Spice Kernels Loaded = 6

Enter Input Flatfile Name (s/c coords): 99238_mrdcd_hkvhmn_C
Enter 1 to SWAP BYTES on INPUT Flatfile; 0 not to swap: 1

Enter Output Flatfile Name: 99238_mrdcd_hkvhmn_gse
Enter 1 to SWAP BYTES on OUTPUT Flatfile; 0 not to swap: 1

Working.
Number of Vectors Read:    10714
Number of Vectors Written: 10714
End TRANSCAL

Press Enter to Exit

C:\cassini\y99archive>

6.2 Sample TransCal Report

TransCal v050324 Report

Cassini Position is relative to Body 399
Position Coordinate System is GSE

Vectors Will Be Transformed from Cassini body-fixed to GSE

Attitudes will be calculated from C Kernel File(s)

3 Spice Text Kernel Files Loaded
\cassini\spicekernels\naif0007.tls
\cassini\spicekernels\cpck30Sep2004_jupiter.tpc
\cassini\spicekernels\cas00090.tsc
2 Spice SPK Files Loaded
\cassini\spicekernels\000331R_SK_V2P12_EP15.bsp
\cassini\spicekernels\010420R_SCPSE_EP1_JP83.bsp
1 Spice C Kernels Loaded
\cassini\spicekernels\99235_99242rb.bc

Opened Input Flatfile 99238_mrdcd_hkvhmn_C
X, Y, Z components assumed in Columns 2, 3, 4
Input Flatfile Times assumed SCLK(1958)

Input Byte Swapping is ON

Opened Output Flatfile 99238_mrdcd_hkvhmn_gse
Output Byte Swapping is ON

Number of Vectors Read:    10714

Number of Vectors Written: 10714
End Report

6.3 TransCal Output File Description

The output data file consists of fixed-length 36-byte records. Each record contains binary representations of time (SCET), components of field vector transformed to a selected coordinate system, field magnitude, and XYZ position of spacecraft with respect to selected body of reference.

6.3.1 TransCal Output Data File Format

In the following file format table, Type T means 8-byte double-precision representation of SCLK count and Type R means 4-byte float. In the column names, <suf> represents a suffix that indicates the coordinate system, such as RTN or GSE. The coordinate systems of the magnetic field vector and the spacecraft position are specified explicitly in the abstract section of the header file.

Column Name	Data Type	Start Byte	Description
001 TIME_TAI	T	0	Time (SCET) in TAI system. Reference epoch is 2000 Jan 1 12:00 TAI (=11:59:28 UTC).
002 BX_<suf>	R	8	Calibrated magnetic field X component in nT
003 BY_<suf>	R	12	Calibrated magnetic field Y component in nT
004 BZ_<suf>	R	16	Calibrated magnetic field Z component in nT
005 B	R	20	Magnitude of calibrated magnetic field vector in nT
006 X_<suf>	R	24	X component of Spacecraft position in km (reference body and coordinate system are specified in text header file)
007 Y_<suf>	R	28	Y component of Spacecraft position in km, as above
008 Z_<suf>	R	32	Z component of Spacecraft position in km, as above

6.3.2 Sample TransCal Text Header File

DATA = 99238_mrdcd_hkvhmn_gse.ffd
CDATE = 2005 132 MAY 12 11:49:14
RECL =    36
NCOLS =     8
NROWS =      10714
OPSYS = WINDOWS
EPOCH = J2000
# NAME      UNITS     SOURCE                    TYPE LOC
001 TIME_TAI SEC       CA_HK_RG_VHM              T        0
002 BX_GSE    nT        CA_HK_RG_VHM              R        8
003 BY_GSE    nT        CA_HK_RG_VHM              R       12
004 BZ_GSE    nT        CA_HK_RG_VHM              R       16
005 BTOTAL    nT        CA_HK_RG_VHM              R       20
006 X_GSE     km        Spice SPK                 R       24
007 Y_GSE     km        Spice SPK                 R       28
008 Z_GSE     km        Spice SPK                 R       32
ABSTRACT
FIRST TIME         = 99 238 AUG 26 00:00:24.632
LAST TIME          = 99 239 AUG 27 00:00:21.361
OWNER              = MAG_TEAM
MISSING DATA FLAG = 1.00000E+034
AVERAGE INTERVAL   =     00:00:00.064
#########
CASSINI ABSTRACT
#########
INPUT FILE: 99238_mrdcd
FLAT FILE MAKER: caspre2ff v1.5 SUN
COMPILATION DATE : 03/10/05-15:05:59
wTime0 and MCI determine dt between vectors except for channel data
Use Configuration File : F --- Use IFC Table    : F
User defined wtime0    : F --- User defined MCI : F
Default wTime0         :   125.00000
Default MCI            :    62.47700
Time for channel data is extracted from the Tertiary data
SCET (Jan 1, 1958 00:00:00) 99 238 AUG 26 00:00:20.977 1314316820.977
SCLK (Jan 1, 1958 00:00:00) 99 238 AUG 26 00:07:13.105 1314317233.105
Flatfile times are SCLK based t0 = Jan 1 1958 00:00:00
TIMEOFFSET 0.000000 SCLKDIFFFLAT 0.000000
CASSINI SCLK (1958)= FLATFILE (1966)+ SCLKDIFFFLAT
Start/Stop times are approximate SCLK Convertions
#########
Calibration: Cal02 v041206
Input Flatfile = 99238_mrdcd_hkvhmn
Sensor = VHM
Calibration Source File = vhm_esb05_cal.ffd
Output Byte Swapping was ON
Number of records not calibrated = 0
Output Times are left unchanged
#########
TransCal v050324
Input Flatfile was 99238_mrdcd_hkvhmn_C.ffd
Output Byte Swapping was ON
TransCal FFD times are TAI (International Atomic Time)
Reference Epoch is 2000 Jan 1 12:00:00 TAI (= 11:59:28 UTC)
TransCal header FIRST TIME and LAST TIME are UTC
Magnetic Field Coord Sys is GSE
Position Coord Sys is GSE
Position Reference Body is EARTH
Spacecraft Attitude is from C Kernel
Spice Kernel files:
\cassini\spicekernels\naif0007.tls

6.3.2 Sample TransCal Text Header File (continued)

\cassini\spicekernels\cpck30Sep2004_jupiter.tpc
\cassini\spicekernels\cas00090.tsc
\cassini\spicekernels\000331R_SK_V2P12_EP15.bsp
\cassini\spicekernels\010420R_SCPSE_EP1_JP83.bsp
\cassini\spicekernels\99235_99242rb.bc
END

Contents

7. Algorithm and Method

In this section, all functions that are said to be called by TransCal are included in the source code file transcal.cpp, unless they are specifically identified as part of the SPICE toolkit in CSPICE.LIB or part of the UCLA flatfile package.

7.1 Algorithm

The following summarizes the algorithm used by TransCal to transform calibrated magnetic field vectors from the Cassini spacecraft coordinate system to the user-selected coordinate system.

B_out = T * Q * B,

where

B_out = calibrated field vector in selected coordinate system,

B = calibrated field vector in spacecraft coordinate system,

Q = rotation matrix from spacecraft coordinate system to J2000, obtained either from quaternion in CHATT flatfile or SPICE C kernel, and,

T = rotation matrix from J2000 to selected coordinate system.

The spacecraft position vector is given by

P = T * PJ,

where

PJ = the spacecraft position vector in J2000 obtained from the SPICE SP kernel, and,

T is as above.

Details of time conversion from SCLK counts to Ephemeris Time are given in Section 7.2 below and in Figure 1.

7.2 SPICE Kernel Files

The main program calls a function loadkernels to load SPICE kernel files. The user is asked for the name of a SPICE text metafile that contains a list of the SPICE kernel files to load. Then the SPICE function furnsh_c reads this metafile and loads the SPICE kernels. (See kernel.req in Ref. 2 for more details.) Multiple SP kernels and C kernels can be loaded, highest priority last. The Cassini Spice Team (contact Diane Conner) maintains a list of which Spice kernels to use for given time intervals, as well as much other useful information, at https://cassini.jpl.nasa.gov/io/spice. Calls to SPICE functions ktotal_c and kdata_c determine the number and types and names of the SPICE kernels that were loaded, and this information is returned to the main program, which writes to the report file the names of the SPICE kernels that were loaded.

Example of SPICE text metafile

\begintext

List of Spice kernel files for 99238.

\begindata

KERNELS_TO_LOAD = (
'\cassini\spicekernels\naif0007.tls',
'\cassini\spicekernels\cpck30Sep2004_jupiter.tpc',
'\cassini\spicekernels\cas0090.tsc',
'\cassini\spicekernels\99235_99242rb.bc ',
'\cassini\spicekernels\000331R_SK_V2P12_EP15.bsp',
'\cassini\spicekernels\010420R_SCPSE_EP1_JP83.bsp')

\begintext

The following table shows examples of SPICE kernel files and gives brief descriptions. (See also Table 20 of Ref. 1) TransCal always requires a leapsecond file, a planetary constants file, a SCLK file for time conversion, and a spacecraft trajectory file. The C kernel file (*.bc) is not required if the user does not choose the C attitude option. Examples of SPICE kernel files will be included in the SOFTWARE/EXAMPLE_FILES directory on the MAG Archive volume. Cassini SPICE kernels are available at ftp://naif.jpl.nasa.gov/pub/naif/CASSINI/kernels. The Unix binary kernels are now directly readable on the PC.

Examples of SPICE Kernel Files

File	Description
naif0007.tls	SPICE Leap Second File
Cpck30Sep2004_jupiter.tpc	SPICE Planetary Constants File
cas00090.tsc	SPICE SCLK-SCET File
000331R_SKV2P12EP15.bsp	SPICE Cassini trajectory file
99235_99242rb.bc	SPICE Cassini C Kernel file

7.3 Time Conversion

The main program calls a function get_transff to read a time and a magnetic field vector from a calibrated FGM or VHM data file. This input time is Spacecraft Clock (SCLK) with reference epoch 1958 Jan 1 00:00. The function fftimeconv converts this input time both to SPICE Ephemeris Time (also called TDB, Terrestrial Barycentric Time), and also to Encoded SCLK, which is needed if spacecraft attitudes are to be derived from a SPICE C kernel. The function fftimeconv calls the CSPICE functions scencd_c and sct2e_c to do the conversion from SCLK that removes the effect of the spacecraft clock rate drift. A SPICE SCLK-SCET kernel file is required.

For output, the main program calls write_transff, which converts Ephemeris Time to TAI (International Atomic Time) with a call to CSPICE function unitim_c. Ephemeris Time is greater than TAI by about 32.184 seconds. TAI is "ahead" of UTC by the number of included leap seconds. The reference epoch for TAI is "2000 Jan 1 12:00:00 TAI", which is "2000 Jan 1 11:59:28 UTC", since at this time the number of leap seconds is 32. See the SPICE documents sclk.req and time.req in Ref. 2 for detailed discussions of spacecraft clock time conversions and timing systems.

Figure 1 in the Appendix of this document shows a numerical time processing example. (Note that the conversion from SCLK to Ephemeris Time limits the time resolution to 1/256 second, about 4ms. The times of the individual field vector measurements were assigned with precision better than 1 ms. The function fftimeconv calculates the fraction of time that gets truncated in the conversion process and adds it back to the returned Ephemeris Time, so that the relative timing of consecutive vector measurements is preserved. This is not shown in the diagram.)

7.4 Coordinate System Transformations

TransCal first calculates the transformation matrix from the spacecraft coordinate system to the basic SPICE inertial reference system called J2000. (This system is defined by the Earth Equinox and Equator at the J2000 epoch.)

If Option Q is selected, get_qmatrix calls CSPICE function q2m_c to calculate the rotation matrix using the quaternion values in the corresponding CHATT file. Quaternion values are available every 4 seconds; TransCal now interpolates between the rotation matrices derived from consecutive quaternions using the routines axisar_c and raxisa_c according to the method described in the Spice document Rotation.req.

If Option C is selected, this matrix is calculated by get_ct, which uses CSPICE function ckgp_c. Either option may return a zero matrix if attitude information is not available; in such cases no output record is written.

TransCal then calculates the transformation matrix from J2000 to the selected coordinate system. Standard fixed-body coordinate systems for the planets are defined using values obtained from the planetary constants kernel (*.pck), and transformation matrices to these systems are returned by calls to the CSPICE function tipbod_c. Coordinate transformations that are not predefined in SPICE are calculated using CSPICE function twovec_c. Inputs to twovec_c are a primary vector, the index of the axis in the direction of the primary vector, a secondary vector, and the index of the axis that lies in the plane containing the primary and secondary vectors.

The input magnetic field vector is now multiplied by the product of the two matrices described above. The position vector of the spacecraft with respect to the selected reference body is obtained by the CSPICE function spkezr_c using the SPICE spacecraft trajectory kernel file. In most cases the position vector is also transformed to the selected coordinate system, but if the selected system is spherical, the position is transformed to another suitable system.

The following table lists the currently available coordinate system choices.

No.	Name	Definition	XYZ Position
0	J2000	SPICE Inertial Reference Frame Earth Equinox and Equator at J2000 epoch	J2000
1	ECLIPJ2000	SPICE Inertial Reference Frame Earth Equinox and Ecliptic at J2000 epoch	ECLIPJ2000
2	IAU_VENUS	SPICE Body-Fixed Frame	IAU_VENUS
3	IAU_EARTH	SPICE Body-Fixed Frame	IAU_EARTH
4	GSE	Geocentric Solar Ecliptic; X is Earth to Sun; Z is North Ecliptic Pole	GSE
5	GSM	Geocentric Solar Magnetic; X is Earth to Sun; Z in plane containing X and Earth North Magnetic Pole	GSM
6	RTN	X is Sun to Spacecraft; Z is in plane containing X and Sun's rotation axis.	ECLIPJ2000
7	CASSINI	No Transformation (Identity Matrix)	J2000
8	J3 (IAU_JUPITER)	SPICE Body-Fixed Frame	IAU_JUPITER
9	JMAG XYZ	Z is Jupiter Dipole, X in plane containing Z and Prime Meridian from IAU_JUPITER	JMAG XYZ
10	JMAG RTP	X is Jupiter to S/C; Y is in plane containing X and Jupiter Dipole.	JMAG XYZ
11	KG (IAU_SATURN)	SPICE Body-Fixed Frame	KG (IAU_SATURN)
12	Saturn RTP	X is Saturn to S/C; Y (=THETA) is south in plane containing X and Saturn Axis.	KG (IAU_SATURN)
13	KSM (Sun-Saturn)	X is Saturn to Sun; Z is north in plane containing X and Saturn Axis.	KSM
14	KSO (Sun and Saturn-Orbit-Plane	X is Saturn to Sun; Z is north perpendicular to Saturn Orbital Plane	KSO

Contents

8. Appendix

8.1 TransCal Source Code File Descriptions

File	Description
TransCal.exe	Application
transcal.cpp	C++ Source, Main Program and functions
Spiceusr.h	C Header File, CSPICE declarations and typedefs
CSPICE.LIB	C Library of CSPICE procedures
ff_igpp.c	C Source, UCLA Flatfile procedures
ff_igpp.h	C Header File, UCLA Flatfile declarations and type defs
time_igpp.c	C Source, UCLA Flatfile Time Functions
time_igpp.h	C Header File, UCLA Flatfile Time declarations and definitions
Time_igppp.h	C Header File, More UCLA Time definitions

Figure 1

Contents