PCK Required Reading |
Table of ContentsPCK Required Reading Abstract Intended Audience References Introduction Body Codes Epochs and Reference Frames Planetocentric Coordinates Using the PCK System: Overview Orientation Models used by PCK Software The Two Formats of PCK files Detection of Non-native Text Files DAF Run-Time Binary File Format Translation NAIF Text Kernel Format Text PCK Contents Text PCK Kernel Variable Names Restrictions on the Form of Orientation Models in Text PCK Kernels Models for the Sun, Planets, and Asteroids in Text PCK Kernels Models for Satellites in Text PCK Kernels Epoch and Frame Specifications in Text PCK Kernels Shape models in Text PCK Kernels Summary of PCK Variables used in Text PCK Kernels by SPICE Creating and Modifying Text PCKs Binary PCK Kernel Format Segments--The Fundamental PCK Building Blocks The Comment Area Binary PCK Data Types Supported Data Types Type 2: Chebyshev (Angles only) Type 3: Chebyshev (Angles and derivatives) Creating Binary PCKs PCK Software Getting PCK Data into Your Program Loading Text PCK Kernels Loading Binary PCK Kernels Unloading Binary PCK Kernels Access Routines High-Level PCK Data Access Low-Level PCK Data Access Examples Transforming a body-fixed state to the inertial J2000 frame Creating a binary PCK file, type 03. Summary of Calling Sequences Appendix A: Sample Text PCK file PCK Required Reading
Abstract
Intended Audience
References
Introduction
Historically, only one type of PCK existed, the text PCK file (called the "P_constants kernel.") These ASCII files can be easily viewed and modified via text editor. The current SPICE system also supports a binary PCK. These files contain more precise body orientation information in binary format, this format permits large amounts of data to be stored and quickly accessed. Binary PCK files exists only for the moon, earth, and the asteroid Eros. The purpose of the PCK and associated software is to provide SPICE users a convenient mechanism for supplying planetary physical constants to application programs. SPICELIB software reads files conforming to these formats and returns both the data contained in such files and a few commonly used numeric quantities derived from the kernel data. Body Codes
In this document, the following features of the code system will be relied on:
PNN, where P is 1, ..., 9 and NN is 01, ... 98
PXNNN, where P is 1, ..., 9, X is 0 or 5, and NNN is 001, ... 999 Codes with X = 5 are provisional.
Epochs and Reference Frames
Typical choices of reference frames associated with PCK constants would be J2000 or B1950. Typical choices of reference epochs would be the J2000 epoch (JED 24515145.0) or the J1950 epoch (JED 2433282.5). Within SPICELIB, reference frames are usually indicated by short character strings, such as 'J2000'. However, SPICELIB also has a system of integer codes used by some routines to name reference frames. This coding system is described in detail in [219]. An example of the correspondence of codes and names is shown below:
Code Name Description ----- -------- ------------------------------------------- 1 J2000 Earth mean equator, dynamical equinox of J2000 2 B1950 Earth mean equator, dynamical equinox of B1950 Planetocentric Coordinates
Using the PCK System: Overview
The use of PCK data in an application program requires three steps:
Step 2 is referred to as ``loading'' a PCK file. Text PCK files are loaded by calling the SPICELIB subroutine FURNSH and supplying the name of the PCK file to load as the input argument. All of the data in a text PCK file is read into memory when the file is loaded by an application program at run-time. Binary PCK files are also loaded by calling the SPICELIB subroutine FURNSH. This data will be accessible throughout the rest of the program run, unless it is deliberately overwritten or unloaded. Multiple text and multiple binary PCKs can be used simultaneously. The data available from binary PCKs take precedence over that from text PCKs. If data for a requested planetary constant and time period is covered by a loaded binary PCK file, the subsystem returns and uses the binary data. If multiple binary PCK files are loaded, the most recently loaded file takes precedence, down to the binary file loaded earliest. The subsystem defaults to text PCK data when no binary PCK data is available. If the user loaded multiple text PCKs, and those PCKs contained variable assignments using the same variable name, the later loads overwrite the assignments defined by earlier loads. Step 3, accessing loaded PCK data, is accomplished via calls to SPICELIB routines. At the lowest level, these access routines allow the calling program to retrieve specified data that has been read from one or more PCK files. Higher-level access routines can return quantities derived from PCK data that has been loaded; the most commonly used such quantity is a matrix that transforms state vectors between inertial and body-fixed planetocentric coordinates. The SPICELIB subroutine SXFORM can calculate this transformation. The subroutine BODVRD retrieves information on body orientation and body shape. For text PCK files, the PCK software can be thought of as ``buffering'' all data loaded from PCK files: the data from these files is retained in memory. Therefore, repeated calls to the PCK access routines do not incur the inefficiency of re-reading data from files. For binary PCK file, like the case of the SPK and CK readers, only a portion of the most recently used information is buffered. The data structure used by SPICELIB to maintain associations of text kernel variable names and values is called the ``kernel pool.'' Data loaded into memory via FURNSH is referred to as ``being present in the kernel pool.'' There is no analog to the kernel pool for binary PCK files. Orientation Models used by PCK Software
The orientation models use three Euler angles to describe the pole and prime meridian location: the first two angles, in order, are the right ascension and declination (henceforth RA and DEC) of the north pole of a body as a function of time. The third angle is the prime meridian location (represented by `W'), which is expressed as a rotation about the north pole, also a function of time. The coordinate transformation defined by the Euler angles is represented by the matrix product
[ W ] [ Pi/2 - Dec ] [ Pi/2 + RA ] 3 1 3where
[ W ] idenotes the matrix that rotates vectors by -W about the ith coordinate axis, using the right hand rule. (This notation is explained in detail in [214]). In PCK files, the time arguments of functions that define orientation always refer to Barycentric Dynamical Time (TDB), measured in centuries or days past a specified epoch such as J2000, which is Julian ephemeris date 2451545.0. The time units expected by the SPICELIB software are ephemeris days for prime meridian motion and ephemeris centuries for motion of the pole. The Two Formats of PCK files
Detection of Non-native Text Files
Environment Native End-Of-Line Indicator ___________ _____________________ PC DOS/Windows <CR><LF> Unix <LF> Linux <LF> Alpha Digital Unix <LF> Mac OS X <LF> Macintosh Classic (OS9) <CR>As of the N0057 release of the SPICE Toolkit (March, 2004) the SPICELIB data loading mechanism detects and prohibits loading text kernel files containing lines terminated with EOL character(s) non-native to the platform on which the Toolkit was compiled. If a non-native EOL terminator is detected in the first 132 characters of a text kernel, the execution is stopped and an error message is displayed. This feature fails on files smaller that 132 bytes or have the first line longer that 132 characters. DAF Run-Time Binary File Format Translation
NAIF Text Kernel Format
Text PCK files conform to a flexible format called ``NAIF text kernel'' format. (A number of SPICELIB kernels other than text PCKs use this NAIF text kernel format is described in detail in [218]. For the reader's convenience, an overview of the format is provided here. NAIF text kernels are, first of all, ASCII files. As such, they are human readable and can be easily modified by text editors. In addition, NAIF text kernels can be readily ported between computer systems, even when the systems in question have different file systems and file formats. The NAIF text kernel format provides for representation of data in a ``keyword = value'' syntax. The format also provides for the inclusion of free-form comment blocks. There are two kinds of data that can be placed in NAIF text kernel files: double precision numbers and UTC time strings. According to the text kernel format, a text kernel nominally consists of a series of sets of contiguous lines (or ``blocks'') of comments, alternating with blocks of data. Comment blocks are started with the string (called a ``control sequence'')
\begintextalone on a line, as shown here. Comment blocks are ended by the control sequence
\begindataalone on a line. In a text kernel file, the lines preceding the first
\begindatacontrol sequence are considered to constitute a comment block; the
\begintextcontrol sequence is optional for this comment block. Comment blocks can contain arbitrary text, except for non-printing characters or lines that can be interpreted as control sequences. On the other hand, data must be organized according to a very specific format: all of the data in a text kernel must appear in the form of an ``assignment'' such as
NAME = ( VALUE1, VALUE2, ... )where name is a string no longer than 32 characters, and the values on the right hand side are double precision numbers. A specific example is shown below:
BODY399_RADII = ( 6378.140 6378.140 6356.75 )Some variations on the form shown here are allowed: commas between data values are optional, the right hand side of the assignment can be continued over multiple lines, and the numbers can be expressed as integers or reals without causing the PCK software to fail. Assignments of scalars do not require the value on the right hand side to be enclosed in parentheses, but that notation is frequently used as a visual cue. Blank lines within or between assignments are ignored by the SPICELIB software that reads text kernels. In addition to numbers, UTC strings can be assigned to variables. The ``@'' character is used to identify the strings as time strings. The strings are stored internally as double precision numbers representing ``UTC seconds past J2000.'' An example is the assignment:
SCLK_KERNEL_ID = ( @01-MAY-1991/16:25 )See [218] for a complete discussion of the allowed form of assignments. The effect of an assignment in a text PCK file is to associate values with a name. The name is referred to as a ``kernel variable.'' When a text PCK file is loaded by an application, the associations of names and values established by the PCK are maintained: the values associated with a given name can be retrieved at any time. Text PCK Contents
SPICELIB includes a set of routines (GIPOOL, GDPOOL, GIPOOL) for general access to text PCK defined data. Another set (BODVRD, BODVCD, SXFORM, PXFORM) recognizes and uses particular PCK data to return body constants or the matrices to transform position or state vectors between reference frames. In this document, the formulas defining time-varying coordinate transformation matrices and Euler angles are referred to as ``orientation models'' since they define the orientation of an extended body with respect to specific inertial frames. Because PCK access routines that deal with orientation models are used extensively in SPICELIB and applications that use the Toolkit, the kernel variables that these routines rely on will be discussed in detail. Those functions defining the Euler angles are characterized by a set of parameters. The specific values of the parameters are values assigned to kernel variables in PCK files. The functions themselves are implemented by code within SPICELIB routines. The general form of the functions is that used in the IAU/IAG 2000 report. Values shown in this document reflect the 2000 report. For the latest PCK values, check with NAIF. In a text PCK file, the variables (Euler angles)
RA, DEC, Wfor the Earth are represented by the names
BODY399_POLE_RA BODY399_POLE_DEC BODY399_POLE_PMThe equations above are expressed in a text PCK file by the kernel variable assignments (Values taken from IAU/IAG 2000 report.)
BODY399_POLE_RA = ( 0. -0.641 0. ) BODY399_POLE_DEC = ( +90. -0.557 0. ) BODY399_PM = ( 190.16 +360.9856235 0. )Note that the string ``PM'' is used in place of ``W'' for the kernel variable associated with the prime meridian. If you examine a PCK file produced by NAIF, you'll see an additional symbol grouped with the ones listed here; it is
BODY399_LONG_AXISThis term is currently zero for all bodies except Mars. It represents the offset between the longest axis of the triaxial ellipsoid used to model a body and the prime meridian of the body. Text PCK Kernel Variable Names
BODYnnn_<item name>where
<item name>is a short string that identifies the type of quantity the kernel variable represents. For example, the variable containing quadratic polynomial coefficients for the right ascension of the Earth's north pole is
BODY399_POLE_RANote the number ``399'' appearing in the kernel variable names; this is the NAIF integer code for the Earth. The following sections specify the specific item names recognized by PCK access routines. Restrictions on the Form of Orientation Models in Text PCK Kernels
To date, no PCK files containing models for the rotation of comets have been produced or collected by NAIF. Models for the rotation of comets, as well as for the rotation of asteroids and the natural satellites of planets, can be accommodated by the PCK system only if the models have the form described in the section ``Models for the Sun, Planets, and Asteroids'' or in ``Models for Satellites'' or if binary PCK data is available. Models for the Sun, Planets, and Asteroids in Text PCK Kernels
Let RA and DEC represent the right ascension and declination of a body's north pole, and let W be the prime meridian location, measured in the counterclockwise direction, from the cross product of the Earth's ``mean'' North pole at the J2000 epoch (as used in defining the J2000 frame) and BODY's North pole at et, to BODY's prime meridian at et. The variables RA, DEC, and W constitute sufficient information to compute the transformation from a specified inertial frame to body-fixed, planetocentric coordinates for the body to which they apply, at a specified time. The angles RA, DEC, and W are defined as follows:
2 RA2*t RA = RA0 + RA1*t/T + ------ 2 T 2 DEC2*t DEC = DEC0 + DEC1*t/T + ------- 2 T 2 W2*t W = W0 + W1*t/d + ----- 2 dwhere
d = seconds/day T = seconds/Julian century t = ephemeris time, expressed as seconds past the reference epoch for this body or planetary systemBelow is an example showing actual values of the parameters used to define the latest IAU model for orientation of the Earth. Here, the motions of both the pole and the prime meridian are given by linear polynomials; the quadratic terms are all zero. The values shown here are taken from the IAU/IAG 2000 report. In that document, the names
alpha 0and
delta 0are used in place of the names RA and DEC used here.
alpha = 0.00 - 0.641 T 0 delta = 90.0 - 0.557 T 0 W = 190.16 + 360.9856235 d T represents centuries past J2000 (TDB), d represents days past J2000 (TDB). Models for Satellites in Text PCK Kernels
Expressions for the right ascension and declination of the north pole and the location of the prime meridian for any satellite of a given planet are as follows:
2 ____ RA2*t \ RA = RA0 + RA1*t/T + ------ + / a sin theta 2 ---- i i T i 2 ____ DEC2*t \ DEC = DEC0 + DEC1*t/T + ------- + / d cos theta 2 ---- i i T i 2 ____ W2*t \ W = W0 + W1*t/d + ----- + / w sin theta 2 ---- i i d iwhere
d = seconds/day T = seconds/Julian century t = ephemeris time, expressed as seconds past a reference epochRA0, RA1, DEC0, DEC1, W0, and W1 are constants specific to each satellite. The nutation precession angles
theta iare specific to each planet. The coefficients
a , d , and w i i iare specific to each satellite. As an example, the nutation precession angles for Earth given by [252] are shown below. That document uses the variable names E1---E5 in place of
theta --- theta 1 5in the equations above.
E1 = 125.045 - 0.052992 d E2 = 250.090 - 0.105984 d E3 = 260.008 + 13.012001 d E4 = 176.625 + 13.340716 d E5 = 357.529 + 0.985600 d Here d represents days past J2000 (TDB)Because the NAIF Toolkit software expects the time units for the angles to be centuries (as in the IAU models for most bodies---the Earth is an exception), the linear coefficients are scaled by 36525.0 for use in the kernel variable assignments:
BODY3_NUT_PREC_ANGLES = ( 125.045 -1935.5328 250.090 -3871.0656 260.008 475263.3 176.625 487269.6519 357.529 35999.04 )In this assignment, the constant and linear polynomial coefficients for each nutation precession angle are listed together: the numbers 125.045 and -1935.5328 are the constant and linear terms for the angle ``E1,'' and so on. Note the body number 3 in the kernel variable name above; this number designates the Earth-Moon barycenter. The PCK access routines expect nutation precession angles to be associated with the barycenters of planetary systems. Here are the expressions for the right ascension and declination of the moon, also taken from [252]:
alpha = 270.000 + 0.003 T - 3.878 sin(E1) - 0.120 sin(E2) 0 + 0.070 sin(E3) - 0.017 sin(E4) delta = 66.541 + 0.013 T + 1.543 cos(E1) + 0.024 cos(E2) 0 - 0.028 cos(E3) + 0.007 cos(E4) W = 38.317 + 13.1763582 d + 3.558 sin(E1) + 0.121 sin(E2) - 0.064 sin(E3) + 0.016 sin(E4) + 0.025 sin(E5) Here d represents days past J2000 (TDB), and T represents Julian centuries past J2000 (TDB). E1--E5 are the nutation precession angles.The polynomial terms are assigned to symbols by the statements
BODY301_POLE_RA = ( 270.000 0.003 0. ) BODY301_POLE_DEC = ( +66.541 0.013 0. ) BODY301_PM = ( 38.317 +13.1763582 0. )The coefficients of the trigonometric terms are assigned to symbols by the statements
BODY301_NUT_PREC_RA = ( -3.878 -0.120 +0.070 -0.017 0. ) BODY301_NUT_PREC_DEC = ( +1.543 +0.024 -0.028 +0.007 0. ) BODY301_NUT_PREC_PM = ( +3.558 +0.121 -0.064 +0.016 +0.025 )Note that for the RA and PM (prime meridian) assignments, the ith term is the coefficient of sin(Ei) in the expression used in the IAU model, while for the DEC assignment, the ith term is the coefficient of cos(Ei) in the expression used in the IAU model. SPICELIB software for text PCKs expects the models for satellite orientation to follow the form of the model shown here: the polynomial terms in the RA, DEC, and W expressions are expected to be quadratic, the trigonometric terms for RA and W (satellite prime meridian) are expected to be sums of sines of nutation precession angles, and the trigonometric terms for DEC are expected to be sums of cosines of nutation precession angles. The nutation precession angles themselves are defined by linear polynomial functions of time. Note that the number of values defining the nutation precession angles for a planetary system must be consistent with the number of trigonometric terms used in the expressions for the RA, DEC and W angles for the satellites of that system. See ``Creating and Modifying Text PCKs Kernels'' for details. Epoch and Frame Specifications in Text PCK Kernels
The default constants and frame for a body are overridden by setting the values of the kernel variables
BODY<id code>_CONSTANTS_REF_FRAMEand
BODY<id code>_CONSTANTS_JED_EPOCHHere
<id code>is:
BODY<id code>_CONSTANTS_REF_FRAMEare the codes returned by the SPICELIB routine IRFNUM. Some of the commonly used codes and the corresponding frames are:
Code Frame ---- ----- 1 J2000 2 B1950 3 FK4 (used in CSPICE for `EME50')For example, to use constants referenced to the FK4 or EME50 frame for the asteroid Gaspra (ID code = 9511010), the PCK file containing the constants should include the assignment
BODY9511010_CONSTANTS_REF_FRAME = ( 3 )The values of the epoch specifier variable
BODY<id code>_CONSTANTS_JED_EPOCHare Julian ephemeris dates. To use constants for Gaspra referenced to the J1950 epoch, the PCK file containing the constants should include the assignment
BODY9511010_CONSTANTS_JED_EPOCH = ( 2433282.5D0 )The creator of a PCK file can set the frame and epoch of the constants on a body-by-body basis, except in the case of planets and their (natural) satellites, where a single choice of frame and epoch must be used for each planetary system. For example, to use constants referenced to the B1950 frame and J1950 epoch for the Earth and Moon, you would make the assignments
BODY3_CONSTANTS_REF_FRAME = ( 2 ) BODY3_CONSTANTS_JED_EPOCH = ( 2433282.5D0 )The ID code `3' designates the Earth-Moon barycenter. Note: the assignment
BODY399_CONSTANTS_REF_FRAME = ( 2 ) BODY399_CONSTANTS_JED_EPOCH = ( 2433282.5D0 )would be ignored by the PCK reader routines; you cannot assign a frame or epoch using the ID code of a planet or satellite. Using constants referenced to frames or epochs other than J2000 does not affect the definitions of the inputs or outputs of any of the PCK access routines. These routines make the necessary transformations internally to take into account the reference frame and epoch of the orientation constants in the kernel pool. Thus the PCK access routine SXFORM, which has the argument list
SXFORM ( FROM, TO, ET, ROTATE )returns the transformation matrix mapping state vectors frame ``FROM'' into frame ``TO'' for ephemeris time expressed as ``ET'' seconds past the J2000 epoch (JED 2451545.0), regardless of the epoch or frame of the orientation constants used to compute ``ROTATE.'' Shape models in Text PCK Kernels
In text PCK files produced by NAIF, the radius values for body nnn are assigned to the variable
BODYnnn_RADIIThree radius values are always assigned for each instance of this variable. The data are ordered as in the IAU/IAG 2000 report: the equatorial radii are listed with the largest axis, often called the ``a'' axis, appearing first; the polar radius is last. Spheroids and spheres are obtained when two or all three radii are equal. Example: Radii of the Earth.
BODY399_RADII = ( 6378.140 6378.140 6356.75 ) Summary of PCK Variables used in Text PCK Kernels by SPICE
BODYppp_POLE_RA BODYppp_POLE_DEC BODYppp_PMFor a satellite (say body number sss), one or more PCK files containing values for the following variables must be loaded:
BODYsss_POLE_RA BODYsss_POLE_DEC BODYsss_PM BODYsss_NUT_PREC_RA BODYsss_NUT_PREC_DEC BODYsss_NUT_PREC_PM BODYbbb_NUT_PREC_ANGLESwhere the code bbb embedded in the last name above is that of the barycenter of the planetary system to which the satellite belongs. The triaxial ellipsoidal model for body nnn is expressed by the assignment
BODYnnn_RADII = ( <larger equatorial radius>, <smaller equatorial radius>, <polar radius> ) Creating and Modifying Text PCKs
Although the text PCK format makes it easy to modify text PCK files, NAIF recommends that application programmers avoid software designs that call for special-purpose, user-created text PCK files. The opportunities for confusion and errors increase with the number of available versions of a text PCK file (or any data file). NAIF recommends that you take the following precautions when modifying a text PCK file:
BODYnnn_where nnn is the NAIF integer code of the body the variable applies to. Kernel variables having names recognized by users' application software are a potential problem area: if the names used in the application don't match those in the text PCK file, the application will fail to obtain the data as intended. The most frequent cause of this type of failure is misspelling of variable names, but programmers who considering changing the names of PCK variables already in use should also keep this problem in mind. Modifying orientation models for satellites requires attention to the consistency between the number of nutation precession angles and the number of coefficients of trigonometric functions having the nutation precession angles as arguments. For any planetary system, there should be twice as many values for the nutation precession angles as the maximum number of trigonometric terms in the expressions for prime meridian location or right ascension or declination of the pole of any satellite in the system. This is because the nutation precession angles are defined by linear polynomials; each polynomial has two defining coefficients. For example, the 1991 IAU model for the Earth-Moon system uses the following values to determine the Moon's orientation:
BODY3_NUT_PREC_ANGLES = ( 125.045 -1935.5328 250.090 -3871.0656 260.008 475263.3 176.625 487269.6519 357.529 35999.04 ) BODY301_POLE_RA = ( 270.000 0.003 0. ) BODY301_POLE_DEC = ( +66.541 0.013 0. ) BODY301_PM = ( 38.317 +13.1763582 0. ) BODY301_NUT_PREC_RA = ( -3.878 -0.120 +0.070 -0.017 0. ) BODY301_NUT_PREC_DEC = ( +1.543 +0.024 -0.028 +0.007 0. ) BODY301_NUT_PREC_PM = ( +3.558 +0.121 -0.064 +0.016 +0.025 )Note that there are five nutation precession angles, with two coefficients defining each one. The trigonometric terms in the expressions for the right ascension, declination, and prime meridian location for the moon require five nutation precession angles. If a NAIF Toolkit user were to update this model with a new one that had, for example, only one nutation precession angle, then the variables
BODY301_NUT_PREC_RA BODY301_NUT_PREC_DEC BODY301_NUT_PREC_PMwould each have to be assigned only one value. Failure to make this change would result in an error being signaled at run-time by any SPICELIB PCK access routine that uses these variables. Binary PCK Kernel Format
Segments--The Fundamental PCK Building Blocks
The data in each segment are stored as a single array. The summary for the array, called a `descriptor', has two double precision components:
The Comment Area
SPICELIB provides a family of subroutines for handling this Comment Area. This software provides the ability to add, extract, read, and delete comments and convert commented files from binary format to transfer format and back to binary again. Binary PCK Data Types
Supported Data Types
Type 2: Chebyshev (Angles only)
The segments contains an arbitrary number of logical records with each record describing a set of Chebyshev coefficients valid across an interval of fixed length. The subroutine PCKE02 contains the algorithm used to construct a set of Euler angles from a particular record and epoch. A segment consists of a set of records, ordered by increasing initial epoch, each record containing the same number of coefficients. The segment structure is illustrated below:
+---------------+ | Record 1 | +---------------+ | Record 2 | +---------------+ . . . +---------------+ | Record N | +---------------+ | INIT | +---------------+ | INTLEN | +---------------+ | RSIZE | +---------------+ | N | +---------------+A four-number `directory' at the end of the segment contains the information needed to determine the location of the record corresponding to a particular epoch.
+------------------+ | MID | +------------------+ | RADIUS | +------------------+ | X coefficients | +------------------+ | Y coefficients | +------------------+ | Z coefficients | +------------------+The first two elements in the record, MID and RADIUS, are the midpoint and radius of the time interval covered by coefficients in the record. These are used as parameters to perform transformations between the domain of the record (from MID - RADIUS to MID + RADIUS) and the domain of Chebyshev polynomials (from -1 to 1 ). The same number of coefficients is always used for each component, and all records are the same size (RSIZE), so the degree of each polynomial is ( RSIZE - 2 ) / 3 - 1 Type 3: Chebyshev (Angles and derivatives)
Each segment contains an arbitrary number of logical records. Each record contains a set of Chebyshev coefficients for angles and derivatives valid throughout an interval defined in the record. The lengths of these intervals may vary within a segment. The subroutine PCKE03 contains the algorithm used to construct a set of Euler angles from a particular record and epoch. All records contain the same number of coefficients. A segment of this type is structured as follows:
+---------------+ | Record 1 | +---------------+ | Record 2 | +---------------+ . . . +---------------+ | Record N - 1 | +---------------+ | Record N | +---------------+where each record has the following format:
--------------------------------------------------- | Midpoint of the approximation interval in TDB | --------------------------------------------------- | Radius of the approximation interval in seconds | --------------------------------------------------- | coefficients for the RA position | --------------------------------------------------- | coefficients for the DEC position | --------------------------------------------------- | coefficients for the W position | --------------------------------------------------- | coefficients for the RA velocity | --------------------------------------------------- | coefficients for the DEC velocity | --------------------------------------------------- | coefficients for the W velocity | ---------------------------------------------------TDB is time in ephemeris seconds past J2000, called et in the SPICELIB system. Creating Binary PCKs
The user should keep in mind that the PCK segments should be as large as possible to create smaller, faster to load files. The are generally three steps to creating a binary PCK file.
CALL PCKOPN ( FILE, IFNAME, I, HANDLE )The method for beginning the segment, adding data to the segment and closing the segment differs with the PCK type. For segments of type 2, there is a segment writing routine called PCKW02 in SPICELIB. This routine takes as input arguments the handle of an PCK file that is open for writing, the information needed to construct the segment descriptor, and the data to be stored in the segment. The header of the subroutine provides a complete description of the input arguments and an example of its usage. Here's an example of a call to PCKW02:
CALL PCKW02 ( HANDLE, BODY, FRAME, FIRST, LAST, SEGID, INTLEN, N, POLYDG, CDATA, BTIME )For type 3, there are three subroutines used in creating a binary PCK file. They are PCK03B, which begins a type 3 segment, PCK03A, which adds data to segment, and PCK03E, which ends a segment. The type 3 subroutines can be used in a loop, where PCK03A is called to add data to the segment. Here is a code fragment that begins a type 3 segment, writes data to that segment in a loop, and then closes the segment.
CALL PCK03B ( HANDLE, SEGID, BODY, FRAME, ETSTRT, ETSTOP, CHBDEG ) DO WHILE ( <a condition> ) ... CALL PCK03A ( HANDLE, N, COEFFS, EPOCHS ) ... END DO CALL PCKO3E ( HANDLE )When a user is finished writing segments to an PCK file, the file must be closed with the subroutine PCKCLS.
CALL PCKCLS ( HANDLE ) PCK Software
Getting PCK Data into Your Program
It is also wise to avoid designing data processing systems that effectively place PCK loading in a tight loop by requiring repeated runs of programs that expend a significant fraction of their run time on loading PCK files. If a program loads PCK files, it is preferable that it do all of its processing in a single run, or at least in a small number of runs, rather than carry out its processing by being re-run a large number of times: the former design will greatly reduce the ratio of the time the program spends loading PCKs to the time it spends on the rest of its data processing. Loading Text PCK Kernels
CALL FURNSH ( 'P_CONSTANTS.KER' )File names supplied to FURNSH will generally be system-dependent. It is good programming practice to not use hard-coded file names in calls to FURNSH. Instead, applications should obtain kernel file names by one of the following methods:
Each time a text PCK is loaded, the assignments made in the file are maintained in the PCK software. In particular, if a kernel variable occurs in multiple PCKs loaded in a single run of a program, the value of the variable will be the one assigned in the following priority: last binary PCK file loaded, previously loaded binary PCK files, then last loaded text PCK files followed by previously loaded text PCK files. All binary PCK files take precedence over text PCK files. Within the binary and/or text file groups, the last loaded files takes precedence. Loading Binary PCK Kernels
CALL FURNSH ( 'example.pck' )Once an PCK file has been loaded, it may be accessed by the PCK software. Each set of constants is computed from a distinct segment. A PCK file may contain any number of segments. In fact, the same file may contain overlapping segments: segments containing data for the same body over a common interval. When this happens, the latest segment in a file supersedes any competing segments earlier in the file. Similarly, the latest file loaded supersedes any earlier files. In effect, several loaded files become equivalent to one large file. Binary PCK files take precedence over text PCK files. Unloading Binary PCK Kernels
CALL UNLOAD ( FILE ) { Unload binary PCK file } Access Routines
All of the routines listed here make use of the orientation models discussed in the section titled ``Orientation Models used by PCK Software.'' Note that in order to use these routines, an application must first load a PCK file (or files) containing sufficient data to define all of the required orientation models. If needed data has not been loaded, these routines will signal run-time errors when called. High-Level PCK Data Access
PXFORM ( FROM, TO, ET, ROTATE )In the argument list for PXFORM:
CALL PXFORM_C( "B1950", "IAU_EARTH", ET, ROTATE )returns a matrix ``ROTATE'' such that left-multiplying V50 by ``ROTATE'' --- accomplished in SPICELIB by the call
CALL MXM ( ROTATE, V50, VBODFX )will return the vector ``VBODFX'' specified relative to the Earth's (``body-fixed'') planetocentric frame at time ``ET''. Note that many practical applications of PXFORM require that a light-time corrected value of et be supplied as an input. See ``Computing the Sub-Observer Point'' in the ``Examples'' section below. The fundamental quantities defined by PCK orientation models are actually Euler angles, not matrices. These Euler angles, which we call ``RA, DEC, and W,'' are related to the matrix ``ROTATE'' shown above by the equation
ROTATE = [ W ] [ Pi/2 - DEC ] [ Pi/2 + RA ] 3 1 3The units of these angles are radians. To directly retrieve these angles, use the call
BODEUL ( BODY, ET, RA, DEC, W, LAMBDA )
SPICELIB provides a routine analogous to PXFORM that returns the matrix to transform state vectors between reference frames. This routine is called SXFORM; the calling sequence being
SXFORM ( FROM, TO, ET, XFORM )The input arguments ``FROM'', ``TO'', and ``ET'' have the same meanings as in the argument list of PXFORM. The output argument ``XFORM'' is the 6x6 matrix required to transform state vectors from inertial to body-fixed coordinates. Left multiplication of a state vector by ``XFORM'' will transform it from the frame specified by ``FROM'' to the frame specified by ``TO'' at time ``ET''. Low-Level PCK Data Access
The lowest-level SPICELIB PCK access routines are GIPOOL, GDPOOL and GCPOOL. These are general-purpose routines for retrieving any text kernel data by data type (integer, double precision, and character string, respectively) loaded via FURNSH. The calling sequences for the routines:
GDPOOL ( NAME, START, ROOM, N, VALS, FOUND ) GCPOOL ( NAME, START, ROOM, N, VALS, FOUND ) GIPOOL ( NAME, START, ROOM, N, VALS, FOUND )The meanings of the arguments are follows:
In text PCK's produced by NAIF, PCK variables will have names conforming to the naming convention used in SPICELIB, that is, the kernel variable names have the form
BODYnnn_<item name>BODVRD and BODVCD retrieve the values of such variables from the kernel pool; BODVRD accepts as inputs the body name and a string making up the portion of the item's name following the prefix:
BODVRD ( BODYNM, ITEM, MAXN, DIM, VALUES )BODVCD functions in the same manner as BODVRD except BODVCD accepts as inputs the body NAIF ID and the item string, ``ITEM'', as described for BODVRD:
BODVCD ( BODYID, ITEM, MAXN, DIM, VALUES )For example, to obtain the radii of the of Earth, a program could use either the call
CALL BODVRD ( 'EARTH', 'RADII', 3, DIM, VALUES )or the call
CALL BODVCD ( 399, 'RADII', 3, DIM, VALUES )Both calls return the dimension and values associated with the variable
BODY399_RADIInamely
DIM = 3 VALUE(1) = 6378.140 VALUE(2) = 6378.140 VALUE(3) = 6356.755It is possible to test whether a kernel variable has been loaded by calling the SPICELIB logical function BODFND, as long as the variables in question follow the SPICELIB naming convention. The calling sequence is
FOUND = BODFND ( BODY, ITEM )where body is the NAIF integer code of the body, and ``ITEM'' is the string making up the portion of the item's name following the prefix
BODYnnn_For example, to test whether values for Jupiter's radii have been loaded, the test
FOUND = BODFND ( 599, 'RADII' )could be used. The variable ``FOUND'' would be returned as .TRUE. if a PCK file had been loaded containing an assignment of the variable
BODY599_RADII Examples
Transforming a body-fixed state to the inertial J2000 frame
The following code fragment shows how to use the SPICELIB routine SXFORM to transform state vectors between coordinate frames. The 6-vector ``STATE'' represents the body-fixed state (position and velocity) of an object with respect to the center of the body at time ``ET''. The matrix ``XFORM'' is declared as a 6x6 double-precision matrix. This program loads both a text and a binary PCK file. The question of from which file is the data retrieved is answered by the coverage of the files. If a particular requested time and body is covered by the loaded binary file, the binary data will be used. If not, the text data will be used. In this example, we present a small program that solves a realistic geometry problem: transform an earth station location given geodetic coordinates to the corresponding state vector in the J2000 reference frame.
PROGRAM PCK_1 DOUBLE PRECISION LON DOUBLE PRECISION LAT DOUBLE PRECISION ALT DOUBLE PRECISION F DOUBLE PRECISION EQUATR DOUBLE PRECISION POLAR DOUBLE PRECISION ET DOUBLE PRECISION ABC (3) DOUBLE PRECISION POS (3) DOUBLE PRECISION JSTATE (6) DOUBLE PRECISION XFORM (6,6) DOUBLE PRECISION STATE (6) INTEGER DIM INTEGER I DOUBLE PRECISION RPD C C C Suppose you have geodetic coordinates of a station on the C surface of Earth and that you need the inertial (J2000) C state of this station. The following code fragment C illustrates how to transform the geodetic state of the C station to a J2000 state. C C Load the SPK, PCK and LSK kernels. C CALL FURNSH( '/kernels/gen/lsk/naif0008.tls') CALL FURNSH( '/kernels/gen/pck/pck00008.tpc') CALL FURNSH( '/kernels/gen/spk/de405_2000-2050.bsp') C C Also load a high precision earth orientation kernel. This C returns orientation to milli-second accuracy. C CALL FURNSH( '/kernels/gen/pck/earth_000101_050509_050215.bpc') C C Define a geodetic longitude, latitude, altitude C coordinate set. These coordinates are defined in the C non-inertial, earth fixed frame 'ITRF93'. C LON = 118.25D * RPD() LAT = 34.05D * RPD() ALT = 0.D C C Define a UTC time of interest. Convert the 'utc' string C to ephemeris time J2000. C CALL STR2ET ( 'March 1, 2005', ET) C C Retrieve the equatorial and polar axis of the earth. C CALL BODVRD ( 'EARTH', 'RADII', 3, DIM, ABC ) EQUATR = ABC(1) POLAR = ABC(3) C C Calculate the flattening factor for earth. C F = ( EQUATR - POLAR ) / EQUATR C C Calculate the Cartesian coordinates on earth C in the ITRF93 frame for the location at C LON, LAT, ALT. C CALL GEOREC ( LON, LAT, ALT, EQUATR, F, POS ) C C GEOREC returned the position vector of the geodetic C coordinates, but we want the state vector. Since it is a fixed C location in the 'ITRF93' frame, the location has no velocity C in that frame. We need to extend 'pos' to a 6-vector, the final C three elements with value 0. Copy POS to the first C three elements of STATE. C CALL VEQU ( POS, STATE ) CALL VPACK ( 0.D, 0.D, 0.D, STATE(4) ) C C Retrieve the transformation matrix from 'ITRF93' C to 'J2000' at epoch 'et'. C CALL SXFORM ( 'ITRF93', 'J2000', ET, XFORM ) C C Transform the Cartesian state vector from 'IAU_EARTH' C to 'J2000.' C CALL MXVG ( XFORM, STATE, 6,6, JSTATE ) C C Write out the results. C DO I = 1, 6 WRITE(*,*) JSTATE(I) END DO C C It's always good form to unload kernels after use. C CALL UNLOAD ( 'standard.ker' ) END Creating a binary PCK file, type 03.
The following routines will be used in this example:
Variable declarations for the example code fragment.
CHARACTER*(128) FILE CHARACTER*(60) IFNAME CHARACTER*(32) FRAME CHARACTER*(40) SEGID DOUBLE PRECISION ET DOUBLE PRECISION ETSTRT DOUBLE PRECISION ETSTOP DOUBLE PRECISION RECORD(*) DOUBLE PRECISION STEP INTEGER BODY INTEGER CHBDEG INTEGER HANDLE C THIS IS A CODE FRAGMENT, NOT A PROGRAM! C C Assign the name of the file to be created. C FILE = 'new_pck.bpc' C C Assign an internal filename for the file. C IFNAME = 'THIS IS A NEW PCK FILE' C C Open the PCK file. C CALL PCKOPN ( FILE, IFNAME, 0, HANDLE ) C C Set the identifier for the segment. This is a character C string of at most 40 printing ASCII characters. It may C be blank. C SEGID = 'This is a test. This is only a test.' C C Set the body for the PCK segment. We will use the C Moon, ID code 301. C BODY = 301 C C We will be using the J2000 reference frame for the segment. C FRAME = 'J2000' C C Set the degree of the Chebyshev polynomials used for the C segment. C CHBDEG = 10 C C Begin the PCK segment. C CALL PCK03B ( HANDLE, SEGID, BODY, FRAME, . ETSTRT, ETSTOP, CHBDEG ) C C We have a start time and a stop time available, ETSTRT C and ETSTOP, and we want to generate records for C sub-intervals of the interval (ETSTRT, ETSTOP). For C simplicity, we will assume equal width intervals and C that (ETSTOP-ETSTRT)/STEP is a positive integer. The C times are in ET, ephemeris seconds past J2000. C C The time step will be one day, 86400 seconds. C STEP = 86400.0D0 C C Set the initial time. C ET = ETSTRT C C Loop until we have processed all of the time intervals, c i.e., when ET >= ETSTOP. C DO WHILE ( ET .LT. ETSTOP ) C C Get a type 03 PCK record for the interval ET, ET+STEP C CALL GETREC ( ET, ET+STEP, RECORD ) C C Add the record to the segment. C CALL PCK03A ( HANDLE, 1, RECORD, ET ) C C Increment the time interval. C ET = ET + STEP END DO C C End the segment. C CALL PCK03E ( HANDLE ) C C Close the PCK file. C CALL PCKCLS ( HANDLE ) Summary of Calling Sequences
FURNSH ( FILE ) for text and binary PCKsUnloading binary PCK files:
UNLOAD ( FILE ) for text or binary PCKsSearching binary PCK files for appropriate information:
PCKSFS ( BODY, TIME, HANDLE, DESCR, IDENT, FOUND )Testing for the presence of variables in the text kernel pool:
BODFND ( BODY, ITEM )Obtaining values assigned variables from the text kernel pool:
BODVRD ( BODYNM, ITEM, MAXN, DIM, VALUES ) BODVCD ( BODYID, ITEM, MAXN, DIM, VALUES ) GDPOOL ( NAME, START, ROOM, N, VALS, FOUND ) GCPOOL ( NAME, START, ROOM, N, VALS, FOUND ) GIPOOL ( NAME, START, ROOM, N, VALS, FOUND )Obtaining Euler angles and their derivatives from a binary PCK file:
PCKEUL ( BODY, ET, FOUND, REF, EULANG )Obtaining position transformation matrices between reference frames:
PXFORM ( FROM, TO, ET, ROTATE )Obtaining Euler angles defining inertial-to-body-fixed coordinate transformations:
BODEUL ( BODY, ET, RA, DEC, W, LAMBDA )Obtaining state transformation matrices between reference frames:
SXFORM ( FROM, TO, ET, ROTATE )Opening a binary PCK file for writing:
PCKOPN ( NAME, IFNAME, NCOMCH, HANDLE )Writing type 2 segment to a binary PCK file:
PCKW02 ( HANDLE, BODY, FRAME, FIRST, LAST, SEGID, INTLEN, N, POLYDG, CDATA, BTIME )Writing type 3 segment to a binary PCK file:
To begin a type 3 segment: PCK03B ( HANDLE, SEGID, BODY, FRAME, FIRST, LAST, CHBDEG ) To add data to a type 3 segment: PCK03A ( HANDLE, NRECS, RECRDS, EPOCHS ) To end a type 3 segment: PCK03E ( HANDLE )Close a binary PCK file after writing:
PCKCLS ( HANDLE )Reading a type 2 segment from a binary PCK file:
PCKE02 ( ET, RECORD, EULANG )Evaluating a type 2 segment from a binary PCK file:
PCKE02 ( ET, RECORD, EULANG )Reading a type 3 segment from a binary PCK file:
PCKR03 ( HANDLE, DESCR, ET, RECORD )Evaluating a type 3 segment from a binary PCK file:
PCKE03 ( ET, RECORD, ROTMAT ) Appendix A: Sample Text PCK file
P_constants (PcK) SPICE kernel file =================================================================== Update by: Karen Zukor (NAIF) 1994 March 30 First draft of a PCK with internal labels included. NOTE: some of the label keywords, values, syntax and overall organization are likely to change. Do not write any code that uses the above labels. Organization -------------------------------------------------------- The sections of this file are as follows. Introductory Information: -- Version description -- Disclaimer -- Sources -- Explanation of the PcK contents -- Body numbers and names Pck Data: -- Orientation constants for the Sun and planets -- Orientation constants for satellites -- Radii for all bodies Version description -------------------------------------------------------- This is a prototype PcK, for use in SPICE training and constants evaluation only. This file is based on the 1991 IAU report, NAIF document [306]. Disclaimer -------------------------------------------------------- This constants file may not contain the parameter values that you prefer. Note that this file may be readily modified by you or anyone else. NAIF suggests that you inspect this file visually before proceeding with any critical or extended data processing. NAIF requests that you update the `by line' and date if you modify the file. Sources -------------------------------------------------------- The sources for the constants listed in this file are: 1. ``Report of the IAU/IAG/COSPAR Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 1991,'' March 3, 1992. 2. ``The Astronomical Almanac,'' 1990. 3. ``Planetary Geodetic Control Using Satellite Imaging,'' Journal of Geophysical Research, Vol. 84, No. B3, March 10, 1979, by Thomas C. Duxbury. This paper is cataloged as NAIF document 190.0. 4. Letter from Thomas C. Duxbury to Dr. Ephraim Lazeryevich Akim, Keldish Institute of Applied Mathematics, USSR Academy of Sciences, Moscow, USSR. This letter is catalogued as NAIF document number 195.0. 5. Mars Observer Planetary Constants and Models, November 1990, Mars Observer Document No. 642-321, JPL Document No. D-3444. Most values are from [1], and these are generally taken from [1]. All exceptions are commented where they occur in this file. The exceptions are: -- The second nutation precession angle (M2) for Mars is represented by a quadratic polynomial in the 1991 IAU report. The SPICE subroutine BODEUL can not handle this term (which is extremely small), so we truncate the polynomial to a linear one. -- The expression for the prime meridian of Deimos ( body 402 ) includes a cosine term, which BODEUL doesn't yet handle. The amplitude of the term is 0.19 degrees. We simply ignore this term. Body numbers and names (Contains only information pertinent to Mars Observer) ---------------------------------------------------------- Barycenters: 3 Earth barycenter 4 Mars barycenter While not relevant to the P_constants kernel, we note here for completeness that 0 is used to represent the solar system barycenter. Mass centers: 399 Earth 401 Phobos 402 Deimos 499 Mars 10 Sun Orientation constants for the Sun and planets -------------------------------------------------------- Sun \begindata BODY10_POLE_RA = ( 286.13 0. 0. ) BODY10_POLE_DEC = ( 63.87 0. 0. ) BODY10_PM = ( 84.10 +14.18440 0. ) BODY10_LONG_AXIS = ( 0. ) \begintext Earth \begindata BODY399_POLE_RA = ( 0. -0.641 0. ) BODY399_POLE_DEC = ( +90. -0.557 0. ) BODY399_PM = ( 190.16 +360.9856235 0. ) BODY399_LONG_AXIS = ( 0. ) \begintext The linear terms before and after scaling: -.052992 --> -1935.5328 -.105984 --> -3871.0656 -13.012 --> -475263.3 13.340716 --> +487269.6519 -.9856 --> -35999.04 \begindata BODY3_NUT_PREC_ANGLES = ( 125.045 -1935.5328 250.090 -3871.0656 260.008 475263.3 176.625 487269.6519 357.529 35999.04 ) \begintext Mars \begindata BODY499_POLE_RA = ( 317.681 -0.108 0. ) BODY499_POLE_DEC = ( +52.886 -0.061 0. ) BODY499_PM = ( 176.868 +350.8919830 0. ) \begintext Source [3] specifies the following value for the lambda_a term ( BODY4_LONG_AXIS ) for Mars. This term is the POSITIVE WEST LONGITUDE, measured from the prime meridian, of the longest axis of the ellipsoid representing the `mean planet surface', as the article states. body499_long_axis = ( 110. ) Source [4] specifies the lambda_a value body499_long_axis = ( 104.9194 ) We list these lambda_a values for completeness. [5] gives equal values for both equatorial radii, so the lambda_a offset does not apply. The 1991 IAU report defines M2, the second nutation precession angle, by: 2 192.93 + 1128.4096700 d + 8.864 T We truncate the M2 series to a linear expression. Again, the linear terms are scaled by 36525.0: -0.4357640000000000 --> -15916.28010000000 1128.409670000000 --> 41215163.19675000 -1.8151000000000000E-02 --> -662.9652750000000 \begindata BODY4_NUT_PREC_ANGLES = ( 169.51 -15916.2801 192.93 +41215163.19675 53.47 -662.965275 ) \begintext Orientation constants for the satellites -------------------------------------------------------- Satellites of Mars Phobos: The quadratic prime meridian term is scaled by 1/36525**2: 8.864000000000000 ---> 6.6443009930565219E-09 \begindata BODY401_POLE_RA = (317.68 -0.108 0. ) BODY401_POLE_DEC = (+52.90 -0.061 0. ) BODY401_PM = ( 35.06 +1128.8445850 8.864 ) BODY401_LONG_AXIS = ( 0. ) BODY401_NUT_PREC_RA = ( +1.79 0. 0. ) BODY401_NUT_PREC_DEC = ( -1.08 0. 0. ) BODY401_NUT_PREC_PM = ( -1.42 -0.78 0. ) \begintext Deimos: There's a new wrinkle in the Deimos prime meridian expression, which is: 2 W = 79.41 + 285.1618970 d - 0.520 T - 2.58 sin M 3 + 0.19 cos M . 3 ^ (new wrinkle) At the present time, the constants kernel software (the routine bodeul_ in particular) cannot handle the cosine term; we omit this term for the time being. The maximum error we can make is 0.19 degrees. The quadratic prime meridian term is scaled by 1/36525**2: -0.5200000000000000 ---> -3.8978300049519307E-10 \begindata BODY402_POLE_RA = (316.65 -0.108 0. ) BODY402_POLE_DEC = (+53.52 -0.061 0. ) BODY402_PM = ( 79.41 +285.1618970 -3.897830D-10 ) BODY402_LONG_AXIS = ( 0. ) BODY402_NUT_PREC_RA = ( 0. 0. +2.98 ) BODY402_NUT_PREC_DEC = ( 0. 0. -1.78 ) BODY402_NUT_PREC_PM = ( 0. 0. -2.58 ) \begintext Radii of bodies -------------------------------------------------------- Sun Value for the Sun is from the 1990 Almanac (page K7). \begindata BODY10_RADII = ( 696000. 696000. 696000. ) \begintext Earth Values for the Earth are unchanged in the 1991 IAU report. \begindata BODY399_RADII = ( 6378.140 6378.140 6356.75 ) \begintext Mars Current values taken from [5]: \begindata BODY499_RADII = ( 3393.4 3393.4 3375.7 ) \begintext Satellites of Mars \begindata BODY401_RADII = ( 13.4 11.2 9.2 ) BODY402_RADII = ( 7.5 6.1 5.2 ) |