N IF

Navigation and Ancillary Information Facility

Welcome
to the
SPICE Tutorials

April 2023
 N IF Objectives
Navigation and Ancillary Information Facility

• Provide an overview of the entire SPICE system

• Provide a sense of the purpose and uses of SPICE
• Provide an introduction to the primary SPICE components
• Provide examples of how to use SPICE software and data files
• Provide some insight into conventions and common problems
• Provide substantive programming examples
• Provide a peek at new capabilities being worked on or
considered
• Familiarize you with available SPICE resources

• Going through these extensive tutorials and the associated

programming lessons will not be enough to make you well
versed in SPICE – it’s just a significant start towards that goal.

Welcome to tutorials 2
 N IF Tutorials Scope
Navigation and Ancillary Information Facility

• Broad coverage
– Begins at a high level, but quickly drills down to details
– Touches on many SPICE-related topics that could be of interest to
science and engineering teams
» Depth of discussion varies somewhat amongst topics
• Provide information for FORTRAN, C, IDL and
MATLAB programmers
– Does not cover Java Native Interface (JNISpice), or the Python
(e.g. SpiceyPy), Ruby, Swift and other 3rd party offerings.
• Some tutorials have important material provided in a
“Backup” section: you should read those charts too!
• Some topics are addressed rather little or not at all
– Kernel production
– Archiving SPICE data
Welcome to tutorials 3
 N IF Repeated Material
Navigation and Ancillary Information Facility

• Some topics will be repeated in two or more

tutorials
– We’re not trying to bore you, but…
» we don’t wish to assume people will read all of the tutorials
at the same time
» we think some items are sufficiently important to mention
them more than once

Welcome to tutorials 4
 N IF Your SPICE Odyssey Begins Here
Navigation and Ancillary Information Facility

… but it does take a

modest amount of effort
to learn enough about
SPICE to begin to use its
features with good success.

It helps to have some

math skills, some innate sense
of spatial orientation, and
some familiarity with your
computer’s operating
…•••• system, a code editor, and a
compiler or Integrated
Development Environment (IDE).
Welcome to tutorials 5
 N IF SPICE Seems “Large”
Navigation and Ancillary Information Facility

• The generic SPICE Toolkit contains:

– several hundred public APIs (“modules” or “subroutines”)
– about 17 utility and application executables
– about 26 subsystem technical reference documents
– and more

• Don’t let this size bother you… just work your way
into it bit by bit
• Most customers use only a handful of these APIs
• Hundreds of others just like you are using SPICE
today

Welcome to tutorials 6
 N IF The NAIF Team at JPL
Navigation and Ancillary Information Facility

Chuck Acton Nat Bachman Alyssa Bailey

Matt Barnes Boris Semenov Ed Wright

Welcome to tutorials 7
N IF
Navigation and Ancillary Information Facility

The SPICE Story

April 2023
 N IF Why Did NAIF Build SPICE?
Navigation and Ancillary Information Facility

• Starting in the early 1980’s scientists said they

would like to:
- use common observation geometry computation tools and
methods throughout a project’s lifecycle, and for all projects
(national and international)

- be able to produce custom observation geometry calculations

themselves, whenever and however they want

- understand the calculations and data used to produce

observation geometry data

- have the ability to revise the data and software tools used to
produce their own observation geometry data

SPICE Story 2
 N IF What Existed Prior to SPICE ?
Navigation and Ancillary Information Facility

“SEDR” - Supplemental Experiment Data Record

Trajectory JPL Scientist’s Institution
Data

Scientist’s Data
Analysis Program
S/C
Orientation
Data
SEDR
Generation SEDR SEDR
Scientist’s
Software
Science
SEDR Modules Results
Parameters
Database Instrument
calibration
and other
data
SEDR
Commands Science
EDR* EDR EDR Instrument
Science Data
Telemetry
Generation

SPICE Story * EDR = Experiment Data Record = "raw" science instrument data 3
 N IF SEDR System Characteristics
Navigation and Ancillary Information Facility

• The SEDR generation program was built and operated at

JPL
– Scientist’s requirements on SEDR had to be provided long before launch
» Late or post-launch updates were hard/expensive to accommodate
• Difficult to change WHAT gets computed
• Difficult to change HOW items are computed (algorithms, parameters)
• Difficult to change the TIMES at which items get computed
– Generally only one SEDR file would be produced for each period of time
» Result: the scientist can’t get better observation geometry data
if/when better inputs (e.g. spacecraft trajectory or orientation, etc.)
become available
– SEDR generation was done “in the blind”
» Operators were not familiar with processes used to make the inputs
» Operators were not familiar with scientist’s processing schemes
» Result: SEDR often did not fully meet science team’s expectations
– The SEDR system was not exportable to other institutions

SPICE Story 4
 N IF The SPICE Idea
Navigation and Ancillary Information Facility

Any Mission Scientist’s Institution

Operations Center
Scientist’s Data
Analysis Program

SPICE Selected Scientist’s

Kernels SPICE SPICE Science
Generation Kernels Software Results
Software Modules
Modules

Target body ephemeris

Target body size/shape/orientation
S/C trajectory
S/C orientation
Instrument geometry
Reference frame specs

Science
Telemetry

SPICE Story 5
 N IF SPICE Benefits vs. SEDR
Navigation and Ancillary Information Facility

• The customer has great flexibility in deciding:

– what observation geometry parameters are computed
– at what times or at what frequency these parameters are computed
– for what time span(s) these parameters are computed
– electing if/when to re-do parameter computations using new
(better) or otherwise different data as inputs
• The customer also has:
– multi-mission tools and methods that can be reused on many tasks
– full visibility into algorithms and data used in geometry
calculations
• The flight project operations center can:
– concentrate on producing better ancillary data, rather than on
producing lots of SEDRs and frequently updating the SEDR
software
• The SPICE process may be replicated anywhere

SPICE Story 6
 N IF SPICE “Challenges” vs. SEDR
Navigation and Ancillary Information Facility

• There are often many SPICE data files produced by

the mission
– It can be a challenge to select the correct ones for a particular
job
• Customers (usually) must do some non-trivial
programming to read SPICE data and compute
whatever is needed
• If the mission operations center is other than JPL,
the appropriate project people need to learn how to
produce and validate their SPICE data
• In some areas of SPICE, the offering of choices to
allow correct handling of different situations may
present complexity that is unwarranted for
“simple” problems
SPICE Story 7
 N IF SPICE Evolution
Navigation and Ancillary Information Facility

• At the behest of scientists, over many years the

use of SPICE has grown throughout NASA and
within space agencies and countries around the
globe

SPICE Story 8
 N IF Space Agencies Using SPICE
Navigation and Ancillary Information Facility

CSA RSA
ESTEC DLR
GRC MIT
Ames ESAC
LASP APL ESOC
JPL
GSFC ASI
SWRI CNES KARI JAXA
Langley
JSC
Marshall UAESA
ISRO

NASA Field Centers European Space Agency Indian Space Research Organization

U.S. Institutions French Space Agency Japan Aerospace Exploration Agency

Canadian Space Agency German Space Agency Russian Federal Space Agency
UAE Space Agency Italian Space Agency Korean Aerospace Research Institute
SPICE Story 9
 N IF SPICE Flight Project Users
Navigation and Ancillary Information Facility

SPICE Story 10
N IF
Navigation and Ancillary Information Facility

An Overview of SPICE
NASA’s Observation Geometry System
for Space Science Missions

April 2023
 N IF What Can One Do With SPICE?
Navigation and Ancillary Information Facility

Compute many kinds of observation

geometry parameters at selected times
Examples

• Positionsand velocities of
planets, satellites, comets,
asteroids and spacecraft

• Size,shape and orientation

of planets, satellites, comets
and asteroids
• Orientationof a spacecraft
and its various moving
structures
• Instrument field-of-view
location on a planet’s
surface or atmosphere

Overview of SPICE 2
 N IF What One Can Do With SPICE
Navigation and Ancillary Information Facility

Find times when a specified “geometric event” occurs

Examples

50

100
150
When is the spacecraft’s
When is an object
altitude within a given
in shadow (occultation) ?
range (say 50 to 100 km)?

When is an
When is an object in front of instrument
another, as seen from a pointing at
spacecraft (transit)? an object?
Overview of SPICE 3
 N IF Examples of How SPICE Is Used
Navigation and Ancillary Information Facility

Evaluation of a
planned trajectory

Spacecraft Visibility
Angular size of Phobos
Station #1
as seen from the MEX spacecraft
Station #2 Mission engineering
Station #3 analyses
Time

Planning an instrument
pointing profile

Observation geometry Elevation

visualization

Latitude
Science data archiving
and analysis

Longitude
Overview of SPICE 4
 N IF SPICE Pictorial Summary
Navigation and Ancillary Information Facility
From assorted sources
Planet ephemeris

S/C trajectory

S/C orientation
Your Program

SPICE
Distances
Utility Your Velocities
Programs Modules
SPICE Altitudes
Kernels Latitudes
(Data) A Few Longitudes
SPICE Lighting Angles
Modules
etc., etc.

Text editor

Spacecraft geometry Ancillary Observation

Instrument geometry Data Files Geometry
Planet size, shape, orientation Parameters
From assorted sources or
Overview of SPICE
Time Intervals
5
 N IF What are “Ancillary Data?”
Navigation and Ancillary Information Facility
Orientation
and
Antenna size/shape
of Earth J2000 reference frame
reference
(ICRF)
frame Sun
Spacecraft
Reference frames
Earth
Positions/velocities • Solar System Barycenter
Orientations
Sizes/shapes Instrument
reference frame
Time Conversions Positions and velocities
of spacecraft and
solar system bodies Planet
reference
Orientation frame
of spacecraft

Orientation
and
size/shape
of planet
The Solar System

Planet

Time Conversion
Calculations
Overview of SPICE 6
 N IF How Use Ancillary Data?
Navigation and Ancillary Information Facility

• Ancillary data are those that help scientists and

engineers determine observation geometry, such as:
– where the spacecraft was located
– how the spacecraft and its instruments were oriented (pointed)
– what was the location, size, shape and orientation of the target being
observed
– where on the surface the instrument was looking

• The text above uses past tense, but doing the same
functions for future times to support mission
planning is equally applicable

Overview of SPICE 7
 N IF From Where do Ancillary Data Come?
Navigation and Ancillary Information Facility

• From the spacecraft

• From the mission control center

• From the spacecraft and instrument builders

• From science organizations

• SPICE is used to organize and package these data

in a collection of stable file types–called "kernels”–
used by scientists and engineers

Overview of SPICE 8
 N IF Why Use SPICE?
Navigation and Ancillary Information Facility

• Knowing observation geometry and geometric

events is an important element of:
– space mission design,
– selection of observation opportunities,
– analysis of the science data returned from the instruments,
– mission engineering activities, and
– preparation of science data archives.

• Having a proven, extensive and reusable means for

producing and using ancillary data reduces cost
and risk, and can help scientists and engineers
achieve more substantive, accurate and timely
results.

Overview of SPICE 9
 N IF SPICE System Components
Navigation and Ancillary Information Facility

Ancillary data files (“kernels”)………..…………

Software (SPICE Toolkit) …………..

Documentation ……….........

Tutorials ………......

Programming lessons …..

Training classes ……………………

User consultation ………….……………………....

Overview of SPICE 10
 N IF Origin of the SPICE Acronym*
Navigation and Ancillary Information Facility

S Spacecraft

P Planet

I Instrument

C C-matrix (“Camera matrix”)

E Events

* Coined by Dr. Hugh Kieffer, USGS Astrogeology Branch, Flagstaff AZ, circa 1985
Overview of SPICE 11
 N IF SPICE Data Overview
Navigation and Ancillary Information Facility

Logical Components Kernels Contents

S Space vehicle or target
Spacecraft SPK body trajectory (ephemeris)

P
Planet
PcK Target body size,
shape and orientation

I
Instrument IK
Instrument field-of-view size,
shape and orientation

C CK
Orientation of space vehicle or
any articulating structure on it
Camera-matrix

Events information:
E EK - Science Plan (ESP)
- Sequence of events (ESQ)
Events ESP ESQ ENB - Experimenter’s Notebook (ENB)

FK Reference frame specifications

Others LSK Leapseconds tabulation

SCLK Spacecraft clock coefficients
DSK Digital shape models
MK Meta-kernel
Overview of SPICE 12
 N IF SPICE Kernels Details- 1
Navigation and Ancillary Information Facility

• Space vehicle ephemeris (trajectory)

SPK • Planet, satellite, comet and asteroid

ephemerides
• More generally, position of something
relative to something else

• Planet, satellite, comet and asteroid

orientations, sizes, shapes
PcK • See also DSK

• Possibly other similar “constants” such

as parameters for gravitational model,
atmospheric model or rings model

• Instrument field-of-view size, shape,

IK orientation
• Possibly additional information, such as
internal timing
Overview of SPICE 13
 N IF SPICE Kernels Details- 2
Navigation and Ancillary Information Facility

• Instrument platform (e.g. spacecraft) attitude

CK • More generally, orientation of something relative
to a specified reference frame

• “Events,” broken into three components:

EK – ESP: Science observation plans
3 components – ESQ: Spacecraft & instrument commands
– ENB: Experiment “notebooks” and ground data system logs

EK is not much used

Overview of SPICE 14
 N IF SPICE System Data - 3
Navigation and Ancillary Information Facility

• Frames
FK - Definitions of and specification of relationships
between reference frames (coordinate systems)
- Both “fixed” and “dynamic” frames are available

LSK • Leapseconds Tabulation

- Used for UTC <--> TDB (ET) time conversions

SCLK • Spacecraft Clock Coefficients

- Used for SCLK <--> TDB (ET) time conversions

• Shape models (tessellated plate model and digital

DSK elevation model*) (DSK)
*DEM portion under development

UTC = Coordinated Universal Time TDB = Barycentric Dynamical Time ET = Ephemeris Time SCLK = Spacecraft Clock Time

Overview of SPICE 15
 N IF SPICE System Data - 4
Navigation and Ancillary Information Facility

• Meta-kernel
MK - A means to conveniently specify a collection of
real kernels you would like to use together

Overview of SPICE 16
 N IF SPICE Toolkit Software
Navigation and Ancillary Information Facility
Contents Versions

• Library of APIs (modules) • Five (ten) languages

– But typically just a few are used – Fortran 77
within a customer’s program to – C
compute quantities derived from – IDL
SPICE data files – MATLAB
• Programs – Java Native Interface (JNI)
– Python, Ruby, Swift, Julia, Unreal
– SPICE data production Engine (provided by 3rd parties)
– SPICE data management • Four platforms
• Documentation – PC/Linux
– PC/Windows
– Highly annotated source code
– Sun/Solaris
– Technical Reference Manuals – Mac/OSX
– User Guides • Several compilers
– For the Fortran and C Toolkits

All combinations provided by NAIF are fully built and

individually tested before being made available to customers
Overview of SPICE 17
 Using SPICE:
N IF Mission Planning Example
Navigation and Ancillary Information Facility

SPK

PcK
User’s Planning Program
Evaluation of a
IK planned orbit

CK User’s Own Modules Instrument

pointing plan
EK
Observation
Selected geometry
SCLK SPICE Toolkit visualization
Library
LSK Modules Analysis of
expected
communications
FK
Maybe some link performance
other needed
DSK data as well

Select kernel types and specific kernels as needed

Overview of SPICE 18
 Using SPICE:
N IF Science Data Analysis Example
Navigation and Ancillary Information Facility
SPK

PcK
User’s Geometry Program
IK Instrument
Data
CK User’s Own Modules
User’s
Derived Science
EK Observation Data
Geometry
Analysis
Selected Program
SCLK
SPICE Toolkit Instrument
Library Calibration
LSK Modules Data

FK

Wonderful
DSK Science
Results
Select kernel types and specific kernels as needed

Overview of SPICE 19
 Using SPICE:
N IF Science Data Peer Review Example
Navigation and Ancillary Information Facility

SPK

PcK

WebGeocalc Server User’s Computer

IK with Web Browser

CK Numeric Results
Internet

FK
Graphic Results

SCLK

LSK

DSK

Overview of SPICE 20
 N IF SPICE System Characteristics - 1
Navigation and Ancillary Information Facility

• SPICE Toolkit software is portable between computers

• New Toolkits are released irregularly, when enough
new capability warrants it
• Code is very well tested before being released to users
• New Toolkits are always 100% backwards compatible
• Source code is provided, and is well documented
• Extensive user-oriented documentation is provided
• Software includes built-in exception handling
– Catches most invalid inputs

Overview of SPICE 21
 N IF SPICE System Characteristics - 2
Navigation and Ancillary Information Facility

• All numeric computations are double precision

• Kernel files are portable between computers
• Kernel files are separable
– Use only those you need for a particular application
• SPICE kernels and software are free of licensing and
U.S. ITAR restrictions
– Everyone is free to use SPICE

• No cost to individual end users

Overview of SPICE 22
 N IF Supported Environments
Navigation and Ancillary Information Facility

• The SPICE Toolkit has been ported to many

popular “environments”
– Each environment is characterized by…
» Language
» Hardware type (platform)
» Operating System
» Compiler (where applicable)
» Selected compilation options (32-bit or 64-bit)

• NAIF provides separate, ready-built SPICE Toolkit

packages for each supported environment
– If you need to port the Toolkit to a new environment yourself,
consult with NAIF staff first

Overview of SPICE 23
 N IF What “Vehicle” Types Can Be Supported?
Navigation and Ancillary Information Facility

• Cruise/Flyby • Landers
– Remote sensing – Remote sensing
– In-situ measurement – In-situ measurements
– Rover or balloon relay
– Instrument calibration

• Orbiters • Rovers
– Remote sensing – Remote sensing
– In-situ measurement – In-situ sensing
– Communications relay – Local terrain characterization

• Balloons* • Terrestrial applications

– Remote sensing – Ephemerides for telescopes
– Radiometric tracking & comm
– In-situ measurements
– Optical tracking & comm

Overview of SPICE * Not yet demonstrated 24

 N IF More Than Just Planetary Science
Navigation and Ancillary Information Facility

• Today SPICE is used well beyond just planetary

science missions.
– Heliophysics
– Earth science
– Observations from terrestrial observatories
– Space technology demos
– Planetariums
– Probably still more…?

Overview of SPICE 25
 N IF History
Navigation and Ancillary Information Facility

• A SPICE precursor was initiated in 1984 as part

of a major initiative to improve archiving and
distribution of space science data in all NASA
disciplines

• Responsibility for leading SPICE development

was assigned to the newly-created Navigation
and Ancillary Information Facility (NAIF),
located at the Jet Propulsion Laboratory

• Today’s SPICE system dates from about 1991

Overview of SPICE 26
 N IF Original Purpose for SPICE
Navigation and Ancillary Information Facility

• The original focus of SPICE was on ancillary data and

associated software needed by planetary scientists for:
– science data analysis, both during and after the mission operations
– science archive preparation

Science archive
preparation

Science Operations Archive

Initial science Post-mission

data analysis data analysis

Overview of SPICE 27
 N IF Large Breadth of Use
Navigation and Ancillary Information Facility

• The original focus of SPICE was on ancillary data and

associated software needed by planetary scientists for:
– science data analysis, both during and after the mission operations
– science archive preparation
• The scope of SPICE usage has grown to cover the full
mission lifecycle.
• Also education and public outreach.

Mission concept Mission design Detailed science Science archive

development validation observation planning preparation

Full Mission Lifecycle Archive

Mission Mission operations Initial science Post-mission

design support data analysis data analysis
Education and Public Outreach

Overview of SPICE 28
 N IF Ancillary Data Archives
Navigation and Ancillary Information Facility

• SPICE is the U.S. Planetary Data System’s recommendation

for archiving ancillary data

• Use of SPICE is recommended by the International Planetary

Data Alliance

• SPICE data for European planetary missions are archived in

ESA’s Planetary Science Archive
– Some of these data are also mirrored on the NAIF server

• SPICE data for some Japanese, Indian and Russian

missions may be available from their local archives

Overview of SPICE 29
 N IF SPICE Users
Navigation and Ancillary Information Facility

Overview of SPICE 30
 N IF Building Blocks for Your Applications
Navigation and Ancillary Information Facility

The “SPICE” observation geometry system can serve

as a set of building blocks for constructing tools
supporting multi-mission, international space
exploration programs.

I C
S P E

Overview of SPICE 31
N IF
Navigation and Ancillary Information Facility

Fundamental Concepts

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Preface
• Time
• Reference Frames
• Coordinate Systems
• Positions and States
• Aberration Corrections

Fundamental Concepts 2
 N IF Preface
Navigation and Ancillary Information Facility

• This tutorial introduces terminology and concepts

used in the later SPICE tutorials.
• Some of this material is more difficult than what
follows in later presentations.
– A complete understanding of this material is not essential in
order to use SPICE.
• Still, we think this information may be helpful,
so… on we go!

Fundamental Concepts 3
 N IF Time
Navigation and Ancillary Information Facility

• An epoch is an instant in time specified by some

singular event
– Passage of a star across your zenith meridian
– Eclipse of a spacecraft signal as it passes behind a solid body
• Clocks
– Clocks count epochs specified by events such as: “regular”
oscillations of a pendulum, quartz crystal, or electromagnetic
radiation from a specified source, measured from an agreed
upon reference epoch.
– Careful specification of epochs using clocks requires reference
to the particular clock and the location of that clock.
• Time Systems
– Are agreed upon standards for “naming” epochs, measuring
time, and synchronizing clocks

Fundamental Concepts 4
 N IF Atomic Time and UTC
Navigation and Ancillary Information Facility

• International Atomic Time (TAI)

– Statistical time scale
» Based on data from ~200 atomic clocks in over 50 national
laboratories
– Maintained by Bureau International des Poids et Mesures (BIPM)
– Unit is the SI (System International) second
» duration of 9192631770 periods of the radiation corresponding to
the transition between two hyperfine levels of the ground state of
the cesium 133 atom
– TAI is expressed as a count of atomic seconds past the astronomically
determined instant of midnight 1 Jan 1958 00:00:00
• Coordinated Universal Time (UTC)
– Civil Time at Greenwich England (~GMT)
– Usual Calendar Formats plus Hour:Minute:Second.fraction
• Relationship between TAI and UTC
– UTC + 10 seconds + number of leap seconds = TAI
» Valid only after Jan 01, 1972

Fundamental Concepts 5
 N IF Astronomical Time – UT1
Navigation and Ancillary Information Facility

• Astronomical Time (UT1) is an hour

representation of the angle between the
Greenwich zenith meridian and the location of the
“computed mean sun.”
• Used prior to atomic time for civil time keeping

UT1

Fundamental Concepts 6
 N IF Tying UTC to Earth’s Rotation (UT1)
Navigation and Ancillary Information Facility

Ideally, UTC noon and astronomical noon at Greenwich (UT1) should occur
simultaneously. However, the earth’s rotation is not uniform. Eventually,
UTC noon and astronomical noon at Greenwich get out of sync.

UTC

UT1

When the mismatch becomes greater than 0.9 atomic

seconds, a “leap second” is added to (or removed from)
the end of a designated UTC day—normally either June 30
or December 31.

The variations in the earth’s rotation that cause leap

seconds to be needed are not predictable.
Fundamental Concepts 7
 N IF Leapseconds (+ and -)
Navigation and Ancillary Information Facility

• “Normal” sequence of • Sequence with a

UTC time tags Positive Leapsecond
– 1998 Dec 31 23:59:58.0 – 1998 Dec 31 23:59:58.0
– 1998 Dec 31 23:59:59.0 – 1998 Dec 31 23:59:59.0
– 1999 Jan 01 00:00:00.0 – 1998 Dec 31 23:59:60.0
– 1999 Jan 01 00:00:01.0 – 1999 Jan 01 00:00:00.0
– 1999 Jan 01 00:00:01.0
Leap seconds complicate the task of • Sequence with a
finding the duration between two
UTC epochs: Negative Leapsecond
– 1998 Dec 31 23:59:57.0
• You need to know when past leap – 1998 Dec 31 23:59:58.0
seconds occurred to compute
durations defined by pairs of past – 1999 Jan 01 00:00:00.0
UTC epochs. – 1999 Jan 01 00:00:01.0
• Durations defined by pairs of future
UTC epochs are indeterminate if leap
seconds could occur in the interim.

Fundamental Concepts 8
 N IF Barycentric Dynamical Time
Navigation and Ancillary Information Facility

• Barycentric Dynamical Time (TDB) and Ephemeris

Time (ET) are synonyms in SPICE documentation.
• TDB is
– a mathematical ideal used in the equations of motion.
– used as the independent time variable for many SPICE
subroutine interfaces.
– related to Barycentric Coordinate Time (TCB) by an offset and
a scale factor.
– TDB advances on average at very close to the same rate as
TAI---the difference is nearly periodic.

Fundamental Concepts 9
 N IF Terrestrial Dynamical Time
Navigation and Ancillary Information Facility

• Terrestrial Dynamical Time (TDT)

– TDT is the Ideal Time (proper time) on Earth at sea level
– TDT = TAI + 32.184 seconds
– The IAU has adopted the name “Terrestrial Time” (TT)
» But this is called TDT throughout SPICE documentation
• TDB and TDT have nearly the same reference
epoch (approximately 1 Jan 2000, 12:00:00 at
Greenwich England), called “J2000.”
• TDB and TDT advance at different rates.
– Variations are small: ~ 1.6 milliseconds
– Variations are almost periodic with a period of 1 sidereal year
(to first order)
– Variations are due to relativistic effects
» TDB = TDT + 0.001657 sin( E + 0.01671sin(E) )
• Use of TDT in the SPICE system is quite limited.
– SCLK kernels
– Duration computations involving UTC
Fundamental Concepts 10
 N IF Offsets between Time Systems
Navigation and Ancillary Information Facility

Difference between seconds past J2000 in a given time system

and TDB seconds past J2000 TDB. Systems used for
comparison are TDT, TAI, and UTC:

TDT-TDB
Magnified by 1000 As magnified amplitude
views show, slopes are
actually non-zero and non-
constant: clocks in
different time systems
generally run at slightly
different rates, and the
TAI-TDB differences in rates may be
time-varying.
Actual amplitude of Magnified by 1000
periodic term =
~1.6e-3 seconds Differences at TDB = J2000
are non-zero: the epoch
UTC-TDB “J2000” = 2000 JAN 1
12:00:00 in different time
systems occurs at different
TDB times.
Magnified by 1000

Fundamental Concepts 11
 N IF Spacecraft Clocks
Navigation and Ancillary Information Facility

• Spacecraft have onboard clocks to control

scheduling of observations, maneuvers, attitude
adjustments, etc.
• Used to time stamp data
• Fundamental unit of time is the “tick”
– Smallest increment possible for a spacecraft clock
– Nominal tick duration is spacecraft clock dependent
• Spacecraft clock time is a count of ticks since
some reference tick.
• The duration of the tick drifts with respect to other
time systems because spacecraft clocks are not
very stable
Fundamental Concepts 12
 N IF More about Spacecraft Clocks
Navigation and Ancillary Information Facility

• SCLK string formats vary from one spacecraft clock to the

next.
– Cassini: Maximum reading for partition 1 = 1/4294967295.255
» Partition number: 1
» Seconds: 4294967295
» Ticks (for Cassini, unit = 1/256 second): 255
– Galileo: Maximum reading for partition 1 = 1/16777215:90:09:07
» Partition number: 1
» "RIM" count (unit = 60 2/3 seconds): 16777215
» "Mod 91" count (unit = 2/3 second): 90
» "RTI" count (unit = 1/15 second): 9
» "Mod 8" count (unit = 1/120 second): 7
• The format of spacecraft clock and the relationship between
tick count and other time systems (usually UTC) is captured
in a SPICE SCLK kernel

Fundamental Concepts 13
 SPICE Definitions:
N IF Reference Frames & Coordinate Systems
Navigation and Ancillary Information Facility

• A reference frame is an ordered set of three

mutually orthogonal (possibly time dependent) unit-
length direction vectors, coupled with a location
called the frame’s “center” or “origin.”
– SPICE documentation frequently uses the shorthand
“frame” instead of “reference frame.”
– The ordered set of axes of a reference frame is also called a
“basis.”
• A coordinate system specifies the method of
locating a point within a reference frame.
Two examples of coordinate systems

Cartesian coordinates Spherical coordinates

Fundamental Concepts 14
 N IF Reference Frame Center
Navigation and Ancillary Information Facility

• A reference frame’s center is an ephemeris object whose

location is coincident with the origin (0, 0, 0) of the frame.
– The center of the IAU_<body> frame is center of mass of <body>.
– The center of any inertial frame is (in SPICE) the solar system barycenter.
» True even for frames naturally associated with accelerated bodies,
such as MARSIAU.
• A frame’s center plays little role in specification of states
– Origin cancels out when doing vector arithmetic
» Whether positions of objects A and B are specified relative to centers
C1 or C2 makes no difference:
(A – C1) – ( B – C1 ) = ( A – C2 ) – ( B – C2 ) = A – B
– But the center *is* used in computing light time to centers of non-inertial
frames
» When the aberration-corrected state of Titan as seen from the Cassini
orbiter is computed in the body-fixed IAU_Titan frame, light time is
computed from Titan’s center to the Cassini orbiter, and this light
time is used to correct both the state and orientation of Titan.
» (Light time and aberration corrections are discussed later on.)

Fundamental Concepts 15
 N IF Types of Reference Frames
Navigation and Ancillary Information Facility

• Inertial
– Non-rotating
» With respect to fixed stars
– Non-accelerating origin
» Velocity is typically non-zero; acceleration is negligible
– Examples:
» J2000 (also called ICRF), B1950
• Non-Inertial
– Examples
» Body-fixed
• Centered at body center
• Topocentric
» Instrument
» Dynamic frames
• For example, frames defined by time-dependent vectors

Fundamental Concepts 16
 N IF J2000 Frame
Navigation and Ancillary Information Facility

• The J2000* (aka EME2000) frame definition is based

on the earth’s equator and equinox, determined
from observations of planetary motions, plus other
data. Z is normal to the mean equator of date at epoch J2000
ZJ2000 TDB, which is approximately Earth’s spin axis orientation
at that epoch. (J2000 TDB is
2000 JAN 01 12:00:00 TDB, or JD 2451545.0 TDB).

Equatorial plane
Plane normal to the earth’s
spin axis, Z
Ecliptic plane
Plane defined by movement
of the earth around the sun

eg
.4 d
~23 YJ2000
Y = Z cross X
Intersection of
XJ2000 equatorial and
ecliptic planes,
called vernal
equinox

*Caution: The name “J2000” is also used to refer to the zero epoch of the ephemeris time system (ET, also known as TDB).

Fundamental Concepts 17
 N IF The ICRF Frame
Navigation and Ancillary Information Facility

• The ICRF* frame is defined by the adopted

locations of 295 extragalactic radio sources

Solar System Barycenter

*ICRF = International Celestial Reference Frame

The ICRF is managed by the International Earth Rotation Service (IERS)
Fundamental Concepts 18
 N IF J2000 vs. ICRF
Navigation and Ancillary Information Facility

• The realization of ICRF was made to coincide almost

exactly with the J2000 frame.
– The difference is very small–a rotation of less than 0.1 arc second
– These two frame names are treated synonymously in SPICE
» In reality, any SPICE data said to be referenced to the J2000
frame are actually referenced to the ICRF frame
» For historical and backwards compatibility reasons, only the
name “J2000” is recognized by SPICE software as a frame
name–not “ICRF”
• No transformation is required to convert SPICE state
vectors or orientation data from the J2000 frame to
the ICRF.

ICRF = International Celestial Reference Frame, defined by the IERS

IERS = International Earth Rotation Service
Fundamental Concepts 19
 N IF Body-fixed Frames
Navigation and Ancillary Information Facility

• Body-fixed frames are tied to a named

Z
body and rotate with it
– The most common names, those for planets,
satellites, the sun, and a few asteroids and comets,
are hard-coded in SPICE software
» Frame name style is “IAU_body name” •
• Examples: IAU_MARS, IAU_SATURN
» To see all such names, see:
• Frames Required Reading document, or
• •
• Latest generic PCK file
– The rotation state (the orientation and angular
velocity at time !) is usually determined using a Y
SPICE text PCK containing data published by the Body-fixed
IAU
X
– The earth and moon are special cases!
» IAU_EARTH and IAU_MOON both exist but
generally should NOT be used
» See the SPICE tutorial named “lunar-
earth_pck-fk” for the best frames to be used
for those bodies
– On very rare occasions a CK is used to provide a
body’s rotation state

Fundamental Concepts 20
 N IF Topocentric Frames
Navigation and Ancillary Information Facility

• Topocentric frames are z points “up”

attached to a surface Position Vector
• Z-axis is parallel to the
gravity gradient or
orthogonal to reference
spheroid y points West x points North
Azimuth (increases
in clockwise
direction, measured
from +x axis)
Elevation (angle between
Orthogonal
vector and x-y plane) projection of
position vector
One example of a topocentric frame. There onto x-y plane
are other types of topocentric frames: for
example, the z-axis could point down, the x-
axis North, and the y-axis East.
Fundamental Concepts 21
 N IF Coordinate System Conventions - 1
Navigation and Ancillary Information Facility

• Planetocentric coordinate systems (also known as latitudinal)

– For planets and their satellites the +Z axis (+90
LAT) always points to the north side of the
invariable plane (the plane whose normal
vector is the angular momentum vector of the Z
solar system)
» Planetocentric longitude increases positively
eastward
» Planetocentric latitude increases positively
northward

– Dwarf planets*, asteroids and comets spin in

the right hand sense about their “positive
pole.”
» What the IAU now calls the “positive pole” is Y
still referred to as the “north pole” in SPICE
documentation.
X
» The “positive pole” may point above or below
the invariable plane of the solar system (see
above).
» This revision by the IAU Working Group (2006)
inverts what had been the direction of the north
pole for Pluto, Charon and Ida.
– Planetocentric routines are RECLAT/ LATREC,
RADREC/RECRAD, DRDLAT/DLATDR
*The dwarf planets are: Ceres, Eris, Haumea, Makemake, Pluto
Fundamental Concepts 22
 N IF Coordinate System Conventions - 2
Navigation and Ancillary Information Facility

• Planetodetic coordinate systems

– Planetodetic longitude is
planetocentric longitude Z
» increases positively eastward
– Planetodetic latitude
» Tied to a reference ellipsoid
» For a point on a reference
ellipsoid, the angle measured
from the X-Y plane to the
surface normal at the point of
interest. For other points, equals Y
latitude at the nearest point on
the reference ellipsoid
X
» Latitude increases positively in
the +Z direction
• +Z is defined the same as for
planetocentric coordinates
– Planetodetic routines are
RECGEO/GEOREC,
DRDGEO/DGEODR
Fundamental Concepts 23
 N IF Coordinate System Conventions - 3
Navigation and Ancillary Information Facility

• Planetographic coordinate systems

– For planet and satellite planetographic
coordinate systems:
» Planetographic latitude is planetodetic Z
latitude Spin
direction
.
» Planetographic longitude is usually
defined such that the sub-observer
longitude increases with time as seen by
a distant, fixed observer in an inertial
reference frame
• The earth, moon and sun are exceptions;
planetographic longitude is positive east by
default
• Planetographic routines are PGRREC/RECPGR
Y

– For dwarf planets, asteroids and comets: X

» There are multiple, inconsistent
standards! (USNO, IAU, PDS)
» NAIF strongly suggests you use only
planetocentric or planetodetic
coordinates
• Planetocentric routines are RECLAT/ LATREC,
RADREC/RECRAD, DRDLAT/DLATDR
• Planetodetic routines are RECGEO/GEOREC, Distant Observer
Fundamental Concepts DRDGEO/DGEODR 24
 N IF State Vectors
Navigation and Ancillary Information Facility

• The state of an object is its position and velocity

relative to a second object
– In SPICE, these objects are often referred to as “target” and
“observer” or “center”
– E.g. Saturn relative to Saturn barycenter; Titan relative to Huygens
probe
– A state is always given in the TDB time system (also known as ET)
• In the SPK subsystem a state is a six dimensional
vector
– First three components are Cartesian position: x, y, z
– Second three components are Cartesian velocity: dx/dt, dy/dt, dz/dt
– Units are km, km/sec
• A state is specified relative to a reference frame

Fundamental Concepts 25
 N IF Transforming States
Navigation and Ancillary Information Facility

• To perform algebraic operations on states they

must be in the same reference frame.
• Position-only frame transformations require only
a rotation* matrix given as a function of time.
» PB (t) = RA to B(t) PA(t)
• Position and velocity frame transformations
require that we differentiate the above equation
» dPB (t) /dt = dRA to B(t)/dt PA(t) + RA to B(t) d PA(t)/dt
• We can use a 6x6 matrix to combine these two
transformations into a single equation

* Assuming both frames are right-handed

Fundamental Concepts 26
 N IF Transforming States
Navigation and Ancillary Information Facility

SB(t) = TA to B(t)SA(t)

where

Si(t) =
( ) Pi(t)
dPi(t)/dt i = A or B

and

( )
RA to B(t) 0
TA to B(t) =
dRA to B(t)/dt RA to B(t)

The SPICELIB routines SXFORM and PXFORM return state

transformation and position transformation matrices respectively.

Fundamental Concepts 27
 N IF Aberration Corrections: Introduction
Navigation and Ancillary Information Facility

• Within the SPICE system, “aberration corrections”

are adjustments made to state vectors and time-
dependent reference frames to accurately reflect
the apparent–as opposed to the actual–state and
attitude of a target object as seen from a specified
observer at a specified time.
– Actual, uncorrected states from an ephemeris are called
“geometric” states.
– When computing state vectors, SPICE users may request
geometric or aberration-corrected states.
• Aberration corrections are needed to accurately
answer questions such as:
– In which direction must a remote sensing instrument be pointed
to observe a target of interest?
– For a given pointing direction and observation time, what target
body surface location would be observed by a remote sensing
instrument?
– In which direction must an antenna be pointed to transmit a
signal to a specified target?
Fundamental Concepts 28
 N IF Computing Aberration-corrected States
Navigation and Ancillary Information Facility

• In order to compute an aberration-corrected state,

the state vectors used in the computation must all
be chained back to the Solar System Barycenter

Saturn

+ Cassini spacecraft
during interplanetary
cruise

The aberration-corrected red Solar System

vector cannot be computed Barycenter
unless all three green +
vectors are available.

Sun

Fundamental Concepts 29
 N IF Example: Predicted vs Actual Photo
Navigation and Ancillary Information Facility
We compare the predicted appearance of a photograph from an optical camera
against the actual photograph. We show three predictions derived using different
aberration corrections: NONE, LT ("light time only"), and LT+S ("light time plus
stellar aberration").
For each prediction, we use red overlays to indicate the expected location in the
photo of the images of an extended target body (for example, a natural satellite), of
features on the surface of the target body, and of a star.

NONE LT LT+S
Predicted images using Predicted images using light Predicted images using light
uncorrected target position time-corrected target time and stellar aberration-
and orientation and position and orientation and corrected target position, light
uncorrected star direction uncorrected star direction time-corrected target
vector vector orientation, and stellar
aberration-corrected star
direction vector
Fundamental Concepts 30
 N IF Prediction Without Corrections
Navigation and Ancillary Information Facility

Predicted target body, surface feature,

and star image locations (in red). Actual
locations are in blue and black.

Body motion
Actual relative to solar
star system barycenter
image

Actual
body
image

Using geometric target positions, target images in photos or other remote-sensing

observations don’t appear at their predicted locations.

Fundamental Concepts 31
 N IF Light Time Corrections
Navigation and Ancillary Information Facility

Target’s
velocity Target’s angular
vector velocity vector
Target’s (geometric) position
and orientation at time ET Target’s position and
Target travels this orientation at time ET-LT
path (along the black (light time corrected
Note: The angular separation of
the geometric and light time arc) in LT seconds position and orientation)
corrected positions as seen by
the observer has been
exaggerated for readability.

Light travels this path in LT seconds

Observer’s position at time ET

At time ET, the observer’s camera records photons emitted from the target at
time ET-LT, where LT is the one-way light time. The camera "sees" the
target's position and orientation at ET-LT.

Fundamental Concepts 32
 N IF Prediction Using Light Time Corrections
Navigation and Ancillary Information Facility

Predicted target body, surface feature,

and star image locations (in red). Actual
locations are in blue and black.

Body motion
relative to solar
Actual system barycenter
star
image
Actual
body
image

Using the light time corrected target position and orientation, the predicted
locations in the photo of the target image and surface features have changed, but
the accuracy of the prediction may still be poor.

Fundamental Concepts 33
 N IF Stellar Aberration Correction
Navigation and Ancillary Information Facility

Target’s apparent position

Target’s position and orientation and orientation
at time ET. This position is called
the geometric or uncorrected
position. Target’s position and
orientation at time ET-LT
Note: The angular separation of (light time corrected
the geometric, light time
corrected, and apparent position and orientation)
positions as seen by the
observer has been exaggerated
for readability.

Velocity component
orthogonal to
observer-target
position
To the observer, light appears to travel this path
Observer’s velocity
relative to Solar System Observer’s position at time ET
Barycenter

At time ET, the observer’s camera records photons emitted from the target at
time ET-LT, where LT is the one-way light time.
The vector from the observer at ET to the location of the target at ET-LT is
displaced by a physical phenomenon called stellar aberration. The displaced
vector yields the apparent position of the target.
Fundamental Concepts 34
 N IF Prediction Using "LT+S" Corrections
Navigation and Ancillary Information Facility

Actual
star
image

Actual
body
image

Predicted target body, surface feature, and star

image locations (in red)

Using the light time and stellar aberration-corrected target position, light time-
corrected target orientation, and stellar aberration-corrected star direction, we
obtain a significantly improved image location predictions.
Remaining prediction errors may be due to, among other causes, pointing
error, spacecraft and target ephemeris errors, and timing errors.
Fundamental Concepts 35
 N IF Newtonian Stellar Aberration Effect
Navigation and Ancillary Information Facility

Camera
Photon
Photon
emission
reception
from Target
at ET
Photon path length = c * LT at ET - LT

“V” = observer velocity component orthogonal to radiation path.

Observer path
length = V*LT We ignore parallel velocity component because it has negligible
effect on photon path geometry.

Observer at
ET-LT Solar System Barycentric Reference Frame

Component of photon path Photon

orthogonal to V. Length ~= c * LT emission
from Target
at ET - LT

Apparent direction to target

Component of
-Observer
photon path parallel
velocity
Camera Photon path in observer frame to V. Length ~=
component
Photon V*LT
orthogonal to
reception Stellar aberration angle dtheta radiation path
at ET sin(dtheta) = v/c +O(v2/c2)

Observer Reference Frame

Fundamental Concepts 36
 N IF Effect of Aberration Corrections - 1
Navigation and Ancillary Information Facility

• Angular offsets between corrected and

uncorrected position vectors over the time span
2004 Jan 1–2005 Jan1
– Mars as seen from MEX:
» LT+S vs NONE: .0002 to .0008 degrees
» LT vs NONE: .0006 to .0047 degrees
– Earth as seen from MEX:
» LT+S vs NONE: .0035 to .0106 degrees
» LT vs NONE: .0000 to .0057 degrees
– MEX as seen from Earth:
» LT+S vs NONE: .0035 to .0104 degrees
» LT vs NONE: .0033 to .0048 degrees
– Sun as seen from Mars:
» LT+S vs NONE: .0042 to .0047 degrees
» LT vs NONE: .0000 to .0000 degrees

Fundamental Concepts 37
 N IF Effect of Aberration Corrections - 2
Navigation and Ancillary Information Facility

• Angular offsets between corrected and uncorrected position

vectors over the time span 2004 Jan 1–2008 Jan1
– Saturn as seen from CASSINI:
» LT+S vs NONE: .0000 to .0058 degrees
» LT vs NONE: .0001 to .0019 degrees
– Titan as seen from CASSINI:
» LT+S vs NONE: .0000 to .0057 degrees
» LT vs NONE: .0000 to .0030 degrees
– Earth as seen from CASSINI:
» LT+S vs NONE: .0000 to .0107 degrees
» LT vs NONE: .0000 to .0058 degrees
– CASSINI as seen from Earth:
» LT+S vs NONE: .0000 to .0107 degrees
» LT vs NONE: .0000 to .0059 degrees
– Sun as seen from CASSINI:
» LT+S vs NONE: .0000 to .0059 degrees
» LT vs NONE: .0000 to .0000 degrees

Fundamental Concepts 38
 N IF Effect of Aberration Corrections - 3
Navigation and Ancillary Information Facility

• Angular offsets between corrected and uncorrected position

vectors over the time span 2025 Apr 1–2028 May 23
– Earth as seen from Mercury:
» LT+S vs NONE: .0001 to .0168 degrees
» LT vs NONE: .0050 to .0058 degrees
– Mercury as seen from Earth:
» LT+S vs NONE: .0001 to .0168 degrees
» LT vs NONE: .0000 to .0112 degrees
– Mercury as seen from MPO:
» LT+S vs NONE: .0004 to .0006 degrees
» LT vs NONE: .0000 to .0113 degrees
– MPO as seen from Earth:
» LT+S vs NONE: .0000 to .0169 degrees
» LT vs NONE: .0000 to .0113 degrees
– Earth as seen from MPO:
» LT+S vs NONE: .0000 to .0169 degrees
» LT vs NONE: .0050 to .0058 degrees

Fundamental Concepts 39
 N IF Effect of Aberration Corrections - 4
Navigation and Ancillary Information Facility

• Range differences between position vectors computed

using LT+S vs CN+S corrections, over the time span 2025
Apr 1–2028 May 23
– Earth as seen from Mercury:
» LT+S vs CN+S: 0.0000 to 0.6760 km
– Mercury as seen from Earth:
» LT+S vs CN+S: 0.0000 to 5.6949 km
– Mercury as seen from MPO:
» LT+S vs CN+S: 0.0000 to 0.0001 km
– MPO as seen from Earth:
» LT+S vs CN+S: 0.0000 to 5.8694 km
– Earth as seen from MPO:
» LT+S vs CN+S: 0.0000 to 0.6760 km

Fundamental Concepts 40
N IF
Navigation and Ancillary Information Facility

SPICE Conventions

A broad summary of standards, terms

and synanons used within SPICE

April 2023
 N IF SPICE Lexicon - 1
Navigation and Ancillary Information Facility

SPICE • The name of this ancillary

information system

NAIF • The name of the team of people

at JPL who lead development of
the SPICE system.
• Also the name of the ancillary
data node of NASA’s Planetary
Data System (PDS).

SPICE-based (code) • A program incorporating some

SPICE APIs (a.k.a. subroutines
or modules) to compute some
SPICE Conventions
geometric quantities.
2
 N IF SPICE Lexicon - 2
Navigation and Ancillary Information Facility

SPICE Toolkit • Names that refer to the principal

collection of software produced by
The Toolkit JPL’s NAIF Team as part of the SPICE
information system.
Toolkit • The Fortran 77 version of the Toolkit.
SPICELIB • The principal user library found within
Fortran versions of the Toolkit.

CSPICE • Refers to the entire C Toolkit, and also

to the principal user library found
within C versions of the Toolkit.
Icy • An IDL interface to CSPICE

Mice • A MATLAB interface to CSPICE

Kernel • A SPICE data file

Sorry for this rather confusing terminology!

SPICE Conventions 3
 N IF SPICE Lexicon - 3
Navigation and Ancillary Information Facility

• Text kernel
– Any kernel type consisting entirely of ASCII information, with each line
terminated using the local operating system convention (CR, LF, or CR+LF)
– Text kernel types are FK, IK, text PcK, LSK, SCLK, MK
– Any set of text kernels, excepting MKs, could be combined in a single file.
» But this is certainly not recommended!
• Binary kernel
– Any kernel type using a binary file format
– Binary types are SPK, binary PcK, CK, DBK and DSK
– Different binary kernel types cannot be combined together

• Transfer format kernel

– A hexadecimal (ASCII) version of a binary kernel, used ONLY for porting a
binary kernel between incompatible computers.
– Not as important as it was prior to the addition of the “run-time translation”
capability added in Toolkit version N0052 (January 2002).
» But still has a role in making native binary kernels required for some
operations.

SPICE Conventions 4
 N IF SPICE Lexicon - 4
Navigation and Ancillary Information Facility

• “Command file”
– Many SPICE application and utility programs either require, or
optionally accept, an input file containing program directives,
and sometimes input data.
– The following names are used synonymously:
» setup file
» preferences file
» command file
» specifications file
» definitions file
• “Found flag”
– A Boolean output (“True” or “False”) from a SPICE API that
informs your program whether or not data were found that
match your request
• Database Kernel (DBK)
– A SPICE kernel that, in conjunction with Toolkit DBK software,
provides a self-contained SQL-like database capability.

SPICE Conventions 5
 N IF SPICE Lexicon - 5
Navigation and Ancillary Information Facility

• Coverage
– The period(s) of time for which a time-based kernel contains data
• Deprecated software
– Toolkit code that, while still useable, has been superseded with a
newer and presumably better version
– We encourage you to not use deprecated SPICE software
– Deprecated modules are so marked in their headers
• Toolkit version naming
– "Nxxxx" e.g. N0066 is Version 66
» Often shortened to just Nxx (e.g. N66)
– Used for all instances of a given toolkit release
» Fortran (“Toolkit”), C (“CSPICE”), IDL (“Icy”), MATLAB (“Mice”)
• “Satellite” is used to refer only to a natural satellite,
never to a spacecraft.
• “Run-time” occurs when you execute a program
SPICE Conventions 6
 N IF SPICE Lexicon - 6
Navigation and Ancillary Information Facility
Names used synonymously
• Kernel, SPICE file, SPICE kernel, SPICE kernel file
• Meta-kernel, Furnsh Kernel
• Module, routine, subroutine, procedure, function, application program interface (API)
• Application, program, utility, executable
• Metadata, comments
• Time, Epoch
• Encoded SCLK, ticks*
• Frame, Reference Frame** ( ≠ Coordinate System) (See the "Frames & Coordinate Systems tutorial)
• Fixed offset frame, constant offset frame, TK frame, class 4 frame
• Ephemeris, trajectory
• Rectangular coordinates, Cartesian coordinates**
• Geodetic, Planetodetic (coordinate system)
• Ephemeris time (ET), Barycentric Dynamical Time (TDB)
• Attitude, orientation
• International Celestial Reference Frame (ICRF) and Earth Mean Equator and Equinox of 2000
reference frame (J2000)
• “Body”, “solar system object,” “ephemeris object”
* Encoded SCLK always refers to absolute time; “ticks” is used to refer to both durations and absolute times.
** Outside of SPICE the term “coordinate system” is often used synonymously with “frame” or “reference
frame.” We prefer to use “coordinate system” in the sense of describing how coordinates are measured
(e.g. cylindrical coordinate system, rectangular coordinate system, polar coordinate system, etc) within a
frame, and to use “frame” in the sense of a set of three orthogonal vectors that define an orientation.
SPICE Conventions 7
 N IF Kernel File Names
Navigation and Ancillary Information Facility

• SPICE imposes some restrictions on kernel file names

– No white space allowed within a name
– Maximum length of a name (including any path specifications) is 255 characters
» See the tutorial “Intro_to_kernels” for limitations on file name
specifications contained within meta-kernels (“furnsh kernels”)

• NAIF suggests names conform to the PDS3 standard: “36.3”

– <1 to 36 alphanumeric characters>.<1 to 3 chars>

• Common usage within NAIF for SPICE kernel file name extensions
is listed on the next page, with the following general style used:
t* text format (e.g. pck00010.tpc)
b* binary format (e.g. de430.bsp)
x* transfer format (e.g. de430.xsp)

SPICE Conventions 8
 Common SPICE Kernel
N IF File Name Extensions
Navigation and Ancillary Information Facility
SPK: SCLK:
.bsp binary SPK file .tsc text SCLK file
.xsp transfer format SPK file MK:
PcK: .tm text meta-kernel file (“FURNSH kernel”)
.tpc text PcK file
(The most common type PcK)
DSK:
.bpc binary PcK file .bds binary DSK file
(Very few instances of this)
.xpc transfer format PcK file DBK:
.bdb binary database kernel
IK: .xdb transfer format database kernel
.ti text IK file EK Family (ESP, ESQ, ENB)
FK: ESP:
.tf text FK file .bep binary Science Plan EK file
LSK: .xep transfer format Science Plan EK file
.tls text LSK file ESQ:
CK: .bes binary Sequence Component EK file
.bc binary CK file .xes transfer format Sequence Component EK file
.xc transfer format CK file
ENB:
.ten text Experimenter’s Notebook EK file
SPICE Conventions These are strong suggestions but not requirements 9
 N IF Common Document Name Extensions
Navigation and Ancillary Information Facility

• These extensions are used for plain ASCII

documents included with each Toolkit delivery
.ug User’s Guide
.req “Required Reading” technical reference document
.txt Used for a few miscellaneous documents
.idx Used only for the permuted index document

• All HTML documents included in the Toolkit have

extension .html

SPICE Conventions 10
 N IF Public and Private Modules
Navigation and Ancillary Information Facility

• All Toolkits include public and private modules

• Public modules are for you to use

– Names of public APIs are different in the four SPICE library implementations.
For example, the top level SPK reader SPKEZR has the following names
» in SPICELIB (FORTRAN) SPKEZR
» In CSPICE (C) spkezr_c
» ICY (IDL) cspice_spkezr
» MICE (MATLAB) cspice_spkezr and mice_spkezr

• Private modules are for NAIF staff use only

– Names of private modules start with “ZZ”
– They are present in the Toolkit only to support operations of “public”
modules
– Do not use “private” modules in your code – they may be changed by NAIF
without notice
SPICE Conventions 11
 N IF Reference Frame Conventions
Navigation and Ancillary Information Facility

• All reference frames used within SPICE are right handed

systems: this means X cross Y = Z

SPICE Conventions 12
 N IF Quaternions
Navigation and Ancillary Information Facility

• The SPICE system uses quaternions to provide orientation in C-kernels

• There are different “styles” of quaternions used in science and

engineering applications. Styles are characterized by
– The order of the quaternion elements
– The quaternion multiplication formula
– The convention for associating quaternions with rotation matrices

• Two of the commonly used styles are

– “SPICE”
» Used by Sir William Rowan Hamilton (discoverer of quaternions)
» Used in math and physics textbooks
– “Engineering” or “MSOP”
» Widely used in attitude control and other aerospace applications
– NAIF offers a comprehensive “white paper” on quaternions:
» https://naif.jpl.nasa.gov/pub/naif/misc/Quaternion_White_Paper/Quaternions_White_Paper.pdf

SPICE Conventions 13
 N IF Names and IDs
Navigation and Ancillary Information Facility

• Many items within SPICE have assigned names

(text strings) and IDs (integer numbers)

• The rules, standards, practices and exceptions

regarding these names and IDs are discussed in a
separate tutorial (“NAIF IDs and Names”)

SPICE Conventions 14
 N IF Use of Quotes
Navigation and Ancillary Information Facility

• Reminder of language-specific rules for quoting

strings used as values in API arguments
– Use double quotes in C and Java Native Interface (JNI) codes
"this is a string"
– Use single quotes in Fortran, IDL, MATLAB, and Python codes
'this is a string'

• Regardless of the language version of the SPICE

Toolkit you're using, in all SPICE text kernels,
string values are enclosed in single quotes. For
example:
INS-43012_FOV_SHAPE = 'CIRCLE'

SPICE Conventions 15
 N IF Pluto is a Special Case in SPICE
Navigation and Ancillary Information Facility

• For practical and historical reasons, Pluto is

treated as a planet when speaking about
ephemerides (SPK).

• But Pluto is treated as a “dwarf planet” when

speaking about orientation and rotational state
(PCK).

SPICE Conventions 16
N IF
Navigation and Ancillary Information Facility

IDs and Names

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Summary of naming/numbering schemes used

in SPICE
• Naming/numbering of objects
• Naming/numbering of reference frames
• Naming/numbering of DSK surfaces
• Connection between the schemes
• Oddball cases: SCLK and CK IDs
• Some examples

NAIF IDs and Names 2

 N IF Overview - 1
Navigation and Ancillary Information Facility

• SPICE uses IDs and names to identify:

– objects
– reference frames
– digital shape kernel (DSK) surfaces
• An ID is an integer number
• A name is a text string

• IDs are used primarily as data identifiers inside

SPICE kernels
– Users rarely have to use IDs
• Names are used primarily as input and output
arguments in SPICE software interfaces (APIs)
– Users deal with lots of names
NAIF IDs and Names 3
 N IF Overview - 2
Navigation and Ancillary Information Facility

• The schemes used for assigning IDs and names to

objects and to reference frames are independent!
– This means that, in general, SPICE does not make any
assumptions about reference frame names and IDs based on
associated object names and IDs
» There are some exceptions; they will be mentioned later

NAIF IDs and Names 4

N IF
Navigation and Ancillary Information Facility

Names and IDs

associated with
Objects
 N IF Object IDs and Names
Navigation and Ancillary Information Facility

• A single ID is assigned to an object of any of the

following types:
– Natural bodies -- planets, satellites, comets, asteroids
– Artificial bodies -- spacecraft, spacecraft structures, science
instruments, individual detectors within science instruments,
DSN stations
– Any other point, the location of which can be known within the
SPICE context, such as:
» barycenters of solar system and planetary systems, landing
sites, corners of solar arrays, focal points of antennas, etc.
• One or more names can be assigned to that same
object
• Within SPICE software there is a 1-to-MANY
mapping between the ID and the object’s name(s)
– On input, the names are treated as synonyms
– On output, the name that was last associated with the ID is
returned

NAIF IDs and Names 6

 N IF Object IDs: Where Used? - 1
Navigation and Ancillary Information Facility

• Object IDs are used in kernels as data identifiers:

» in SPKs -- to identify a body and its center of motion
» in text PCKs -- in keywords associated with a body
» in DSKs -- to identify a body
» in IKs -- in keywords associated with an instrument
» in FKs -- to specify the center used in computing light-time
correction, and to identify the body in PCK-based frames
» in FKs -- to identify target and observer in dynamic frame
specifications
» in SCLKs -- normally the SCLK ID used in keywords is the
negative of the spacecraft’s ID (thus is a positive integer)
» … and more…

NAIF IDs and Names 7

 N IF Object IDs: Where Used? - 2
Navigation and Ancillary Information Facility

• Object IDs are used in some APIs as input and/or

output arguments:

» in older SPK routines -- SPKEZ, SPKEZP, SPKGEO, …

» in older derived geometry routines -- ET2LST, …
» in older PCK routines -- BODVAR, BODMAT, …
» in IK routines -- GETFOV, indirectly in G*POOL, …
» in SCLK routines -- SCE2C, SCT2E, …
» in coverage routines -- SPKOBJ, SPKCOV, CKOBJ,
CKCOV, DSKOBJ, DSKSRF
» … and more…

NAIF IDs and Names 8

 N IF Object Names – Where Used?
Navigation and Ancillary Information Facility

• Object names are used in the high-level user

APIs as input and/or output arguments:
» in newer SPK routines -- SPKEZR, SPKPOS
» in newer derived geometry routines -- SINCPT, ILUMIN,
SUBPNT, SUBSLR, LIMBPT, TERMPT, LATSRF …
» in high-level Geometry Finder routines – GFPOSC,
GFDIST, GFSEP, GFILUM, …
» in newer PCK routines -- BODVRD, …

• Object names are not used as data identifiers

within kernels

NAIF IDs and Names 9

 N IF Object IDs and Names – Where Defined?
Navigation and Ancillary Information Facility

• Object name-to-ID mappings used by SPICE may be

defined in two places
– Built into Toolkit software: hard-coded in source code
» See NAIF_IDS.REQ for a complete listing of these built-in
(default) assignments

– In text kernels
» Normally used to define name/ID mappings for instruments, their
subsystems/detectors and spacecraft structures
• See comments and the actual data sections in a text kernel for the complete
listing of the names/IDs defined in that kernel
» These assignments exist most often in FKs (e.g. MER, MEX,
JUNO, MSL), sometimes in IKs (e.g. CASSINI, MGS), but could be
placed in any text kernel
– Mappings defined in text kernels take precedence over those defined
in Toolkit source code

NAIF IDs and Names 10

 Examples of Object IDs and Names
N IF Spacecraft and Ground Stations
Navigation and Ancillary Information Facility

• Spacecraft (negative numbers)

– For spacecraft supported by DSN, this number is the negative of
the DSN spacecraft ID
• -6 ‘PIONEER-6’, ‘P6’
• -64 ‘OSIRIS-REX’, ‘ORX’
• -82 ‘CASSINI’, ‘CAS’
– Unfortunately, sometimes DSN re-uses a number
» For example, -18 for MGN and LCROSS, -53 for MPF and M01
– NAIF does not assign NAIF IDs to spacecraft not tracked by DSN
» Projects not using DSN are free to choose NAIF IDs
themselves
» NAIF recommends such IDs to be in -9999 … -1000 range
• DSN ground stations (399000 + station number)
• 399005 ‘DSS-05’
• …
• 399066 ‘DSS-66’

• Non-DSN stations (398000 + some integer 0 to 999)

• 398990 ‘NEW_NORCIA’
• …
NAIF IDs and Names 11
 Examples of Object IDs and Names

N IF Planets
Navigation and Ancillary Information Facility

• Solar System Barycenter and Sun* (0 and 10)

• 0 ‘SOLAR SYSTEM BARYCENTER’, ‘SSB’
• 10 ‘SUN’

• Planetary system barycenters (numbers from 1 to 9)

• 1 ‘MERCURY BARYCENTER’
• 2 ‘VENUS BARYCENTER’
• 3 ‘EARTH MOON BARYCENTER’, ‘EMB’, …
• 4 ‘MARS BARYCENTER’
…
• 9 ‘PLUTO BARYCENTER’ (Within SPICE Pluto is still treated as a planet!)

• Planet-only mass centers (planet barycenter ID * 100 + 99)

• 199 ‘MERCURY’
• 299 ‘VENUS’
• 399 ‘EARTH’
• 499 ‘MARS’
• …
• 999 ‘PLUTO’ (Within SPICE Pluto is still treated as a planet!)

* Barycenter: the center of mass of a system (collection)

of two or more bodies, each of which orbits that point.
See the SPK tutorial for details.
NAIF IDs and Names 12
 Examples of Object IDs and Names
N IF Satellites
Navigation and Ancillary Information Facility

• Satellites (planet barycenter ID*100 + number <1… 98>)

• 301 ‘MOON’
• 401 ‘PHOBOS’
• 402 ‘DEIMOS’
• 501 ‘IO’
• 502 ‘EUROPA’
• …
• 901 ‘CHARON’, ‘1978P1’
• 902 ‘NIX’

NAIF IDs and Names 13

 Examples of Object IDs and Names
N IF Comets
Navigation and Ancillary Information Facility

• Periodic Comets (1 million + sequence number)

• 1000001 ‘AREND’
• 1000002 ‘AREND-REGAUX’
• …
• 1000032 Periodic comet with sequence number 999,999

• Sequence number is assigned by JPL's Solar System

Dynamics Group (SSD)

• 1,000,000..1,999,999 range accommodates 1 million

comets
– Sufficient as currently there are less than 10,000 known comets

• One can search the Solar System Dynamics (SSD)

small body database for comet NAIF IDs (SPK IDs) :
https://ssd.jpl.nasa.gov/tools/sbdb_lookup.html#/
NAIF IDs and Names 14
 Examples of Object IDs and Names
N IF Original Schema for Asteroids
Navigation and Ancillary Information Facility

• Numbered Asteroids (2 million + IAU asteroid number)

• 2000001 ‘CERES’
• …
• 2999999 Asteroid with IAU number 999,999
– There are three exceptions, for Gaspra, Ida and Dactyl
» See NAIF_IDS.REQ

• 2,000,000...2,999,999 range accommodates only 1

million asteroids
– Not sufficient as there are already 900,000+ known asteroids
– New schema allowing more objects is described on the next two pages
– The original schema above is still valid for the first 1 million asteroids

• One can search the SSD small body database for

original asteroid NAIF IDs (SPK IDs) :
https://ssd.jpl.nasa.gov/tools/sbdb_lookup.html#/
NAIF IDs and Names 15
 Examples of Object IDs and Names
N IF New Schema for Minor Planets1
Navigation and Ancillary Information Facility

• Different schemas are used for singular minor planets

and for multiple minor planet systems
• Singular minor planets2 with an official IAU number (20
million + IAU minor planet number)
• 20000001 ‘CERES’
• …
• 49999999 Minor planet with IAU number 29,999,999

• 20,000,000...49,999,999 range accommodates 30

million objects
– Sufficient assuming expected discovery rates for upcoming surveys

• One cannot yet search SSD small body database for

“new schema” minor planet NAIF IDs
1 Minor planets can be asteroids, trojans, centaurs, Kuiper belt objects, trans-Neptunian objects and dwarf planets
2 Numbered objects are those having permanent IAU-assigned IDs

NAIF IDs and Names 16

 Examples of Object IDs and Names
N IF New Schema for Minor Planets1
Navigation and Ancillary Information Facility

• Barycenter of a multiple minor planet 2 system (20

million + IAU number of primary minor planet in the
system)
• 20065803 ‘DYDIMOS BARYCENTER’

• Primary minor planet of a multiple minor planet system

(920 million + IAU number of primary minor planet in the
system)
• 920065803 ‘DYDIMOS’

• Moons in a multiple minor planet system ([1- 8]20

million + IAU number of primary minor planet in the
system)
• 120065803 ‘DIMORPHOS’

• One cannot yet search SSD small body database for

“new schema” minor planet NAIF IDs
1 Minor planets can be asteroids, trojans, centaurs, Kuiper belt objects, trans-Neptunian objects and dwarf planets
2 Numbered objects are those having permanent IAU-assigned IDs

NAIF IDs and Names 17

 Examples of Object IDs and Names
N IF Instruments
Navigation and Ancillary Information Facility the “minus” sign

• Science Instruments (s/c ID*1000 - instrument number)

– An instrument number should be picked for EVERY instrument,
instrument subsystem or detector, or spacecraft structure, the
parameters for which are to be stored in IKs, or the location of which
is to be stored in SPKs
– Instrument numbers are picked from the range 0…999. The only
requirement is that they must be unique within each mission
• …
• -82760 ‘CASSINI_MIMI_CHEMS’
• -82761 ‘CASSINI_MIMI_INCA’
• -82762 ‘CASSINI_MIMI_LEMMS1’
• -82763 ‘CASSINI_MIMI_LEMMS2’
• …
• -82001 ‘CASSINI_SRU-A’
• -82002 ‘CASSINI_SRU-B’
• -82008 ‘CASSINI_SRU-A_RAD’
• -82009 ‘CASSINI_SRU-B_RAD’
• …

NAIF IDs and Names 18

 N IF Object IDs/Names -- Mapping APIs
Navigation and Ancillary Information Facility

• SPICE provides two routines to map object IDs to

names, and vice versa

– To get the ID for a given object name:

CALL BODN2C ( NAME, ID, FOUND )

CALL BODS2C ( NAME, ID, FOUND ) (This is a more general version as
compared to BODN2C. Use this one.)

– To get the name for a given object ID:

CALL BODC2N( ID, NAME, FOUND )

– If the “FOUND” flag returned by either of these routines comes

back FALSE, then the input ID or name cannot be mapped

NAIF IDs and Names 19

 Adding New or Additional
N IF Object Name-to-ID Mappings
Navigation and Ancillary Information Facility

• You may define new or additional name-to-ID

mappings using assignments inside any text
kernel.
• For example, for a spacecraft:

NAIF_BODY_NAME += ( 'my_spacecraft_name' )
NAIF_BODY_CODE += ( my_spacecraft_ID )

Note the combination of + and =

• See “NAIF_IDs Required Reading” for details

• Caution: the object name length is limited to 36
characters

NAIF IDs and Names 20

N IF
Navigation and Ancillary Information Facility

Names and IDs

associated with
Reference Frames
 N IF Frame IDs and Names
Navigation and Ancillary Information Facility

• A single ID and a single name are assigned to a

reference frame of any of the following types
– Inertial frames
– Body-fixed frames
– Spacecraft and instrument frames
– Topocentric frames
– Any other reference frame for which the orientation may be
needed to compute observation geometry

NAIF IDs and Names 22

 N IF Frame IDs and Names – Where Defined?
Navigation and Ancillary Information Facility

• The reference frame name-to-ID mappings used by the

SPICE system are defined in two places

– Built into Toolkit software: hard-coded in source code

» For inertial frames
» For body-fixed frames defining the orientation for planets and
most satellites
» See FRAMES REQUIRED READING for a complete listing
– In text kernels: provided by KEYWORD=VALUE sets
» Almost always placed in FKs
» Rarely placed in other kernels, but could be in any text kernel
• (For example during operations MGS frames were defined in IKs and SCLK)

• Unlike for objects, only one name may be directly

associated with a reference frame ID
– However, an “alias” for a given reference frame can be established
by defining a new, zero-offset frame with its own unique name and ID
NAIF IDs and Names 23
 N IF Frame IDs and Names – Where Used?
Navigation and Ancillary Information Facility

• Reference frame IDs are used in the following

kernels as data identifiers
» in FKs -- to “glue” frame definition keywords together
» in SPKs -- to identify base reference frames
» in PCKs -- to identify base reference frames
» in CKs -- to identify base reference frames
» in DSKs -- to identify reference frames
– Reference frame IDs are not used as input and/or output
arguments in any high level user APIs

• Reference frame names are used

– as arguments in all high level APIs that require a reference frame
to be specified as an input
» in derived geometry routines -- SINCPT, ILUMIN, SUBPNT, …
» in frame transformation routines -- PXFORM, SXFORM
» In SPK routines -- SPKEZR, SPKPOS, …
– Frame names are not used as data identifiers within kernels
NAIF IDs and Names 24
 Examples of Frame IDs and Names
N IF Inertial and Body-fixed
Navigation and Ancillary Information Facility

• Inertial frames (positive integers starting at 1)

• 1 ‘J2000’
• …
• 17 ‘ECLIPJ2000’
• …

• Body-fixed frames (positive integers starting at 10001)

• …
• 10012 ‘IAU_VENUS’
• 10013 ‘IAU_EARTH’
• 10014 ‘IAU_MARS’
• …
• 10020 ‘IAU_MOON’
• …
• 13000 ‘ITRF93’
• …
• NOTE: SPICE users would rarely if ever need to know or use the
frame IDs; you use only the frame names

NAIF IDs and Names 25

 Examples of Frame IDs and Names
N IF Spacecraft and Instrument
Navigation and Ancillary Information Facility

• IDs for frames associated with spacecraft, spacecraft

structures, and instruments are usually defined as:
s/c ID times 1000 minus an arbitrary number

• Examples based on Cassini:

– Spacecraft frame (ID and name)
-82000 ‘CASSINI_SC_COORD’
– Spacecraft structure frame (ID and name)
-82001 ‘CASSINI_SRU-A’
– Instrument frames (ID and name)
-82760 ‘CASSINI_MIMI_CHEMS’
-82761 ‘CASSINI_MIMI_LEMMS_INCA’
-82762 ‘CASSINI_MIMI_LEMMS1’
-82763 ‘CASSINI_MIMI_LEMMS2’
-82764 ‘CASSINI_MIMI_LEMMS_BASE’
-83765 ‘CASSINI_MIMI_LEMMS_ART’
…

• NOTE: SPICE users would rarely if ever need to know or use

the frame IDs; you use only the frame names

NAIF IDs and Names 26

 N IF Frame IDs/Names -- Mapping APIs
Navigation and Ancillary Information Facility

• SPICE provides two routines NAMFRM and FRMNAM to

convert (map) reference frame IDs to names, and vice versa
– To get the ID for a given reference frame name
CALL NAMFRM( NAME, ID )
– To get the name for a given reference frame ID:
CALL FRMNAM( ID, NAME )
– If the ID or name cannot be mapped, these routines return zero and an
empty/blank string respectively.
• SPICE also provides the CCIFRM routine to get the frame
name, ID, and center associated with a given frame class and
class ID
CALL CCIFRM ( FRCLSS, CLSSID, FRCODE, FRNAME, CENT, FOUND )
– This routine is used for determining attributes of frames associated with
frame class IDs used in CK and binary PCK files.

• Note: SPICE users will rarely if ever need to call these routines

NAIF IDs and Names 27

N IF
Navigation and Ancillary Information Facility

Names and IDs

associated with
DSK Surfaces
 N IF Surface IDs and Names
Navigation and Ancillary Information Facility

• A single ID is assigned to each DSK topography

data set for a particular body
– this ID is called DSK surface ID or simply surface ID
• One or more names can be associated with that
surface ID
– These names are called DSK surface names or simply
surface names
• Within SPICE software there is a 1-to-MANY
mapping between the surface IDs and names
– On input, the names are treated as synonyms
– On output, the name that was last associated with the ID is
returned

NAIF IDs and Names 29

 N IF Surface IDs and Names – Where Defined?
Navigation and Ancillary Information Facility

• The surface name-to-ID mappings used by the SPICE

system are defined in text kernels
– usually in FKs
– using these triplets of keywords that include the ID of the
body, placing the name-to-ID mapping in the body’s
“namespace”
NAIF_SURFACE_NAME += ( 'my_surface_name' )
NAIF_SURFACE_CODE += ( my_surface_ID )
NAIF_SURFACE_BODY += ( body_ID )

Note the combination of + and =

• Since surface name-to-ID mappings are defined within

a body’s “namespace”, the same surface names and
IDs can be used for other bodies if desired

NAIF IDs and Names 30

 N IF Surface IDs and Names – Where Used?
Navigation and Ancillary Information Facility

• Surface IDs are used as data identifiers:

– inside DSK files
– in some mid-level DSK APIs -- DSKXV, DSKXSI
– in place of surface names in the METHOD argument in derived
geometry routines

• Surface names are used as topography data set

identifiers in all high-level, DSK-enabled APIs:
– in derived geometry routines -- SINCPT, ILUMIN, SUBPNT, …
– in topography sampling routine -- LATSRF
– in Geometry Finder routines -- GFOCLT

NAIF IDs and Names 31

 N IF Surface IDs and Names – Example
Navigation and Ancillary Information Facility

• Surface name-ID mappings for ROSETTA targets

DSK Surface Name ID Body ID

=========================== ===== =======
ROS_CG_M004_NSPCESA_N_V1 11000 1000012 (comet C-G)
ROS_CG_K250_NSPCESA_N_V1 11001 1000012
...
ROS_CG_M001_OSPGDLR_N_V1 24003 1000012
ROS_CG_M004_OSPGDLR_N_V1 24004 1000012

ROS_LU_K003_OSPCLAM_N_V1 1000 2000021 (aateroid Lutetia)

ROS_LU_K006_OSPCLAM_N_V1 1001 2000021
...
ROS_LU_M003_OSPCLAM_N_V1 1011 2000021

ROS_ST_K020_OSPCLAM_N_V1 1000 2002867 (asteroid Steins)

Note: the ROSETTA DSK surface name-ID schema appears rather

cryptic because of the need to accommodate multiple shape model
versions from multiple producers for three different targets.
NAIF IDs and Names 32
 N IF Surface Name/ID Mapping APIs
Navigation and Ancillary Information Facility

• SPICE provides four routines to convert (map) surface IDs to

names, and vice versa
– To get the surface ID for a given surface name and body name:
CALL SRFS2C( SRFSTR, BODSTR, CODE, FOUND )

– To get the surface ID for a given surface name and body ID:
CALL SRFSCC( SRFSTR, BODYID, CODE, FOUND )

– To get the surface name for a given surface ID and body name:
CALL SRFCSS( CODE, BODSTR, SRFSTR, FOUND )

– To get the surface name for a given surface ID and body ID:
CALL SRFC2S( CODE, BODYID, SRFSTR, FOUND )

• If the “FOUND” flag returned by either of these routines

comes back FALSE, then the input ID or name cannot be
mapped
NAIF IDs and Names 33
 Connections between
N IF Objects and Frames
Navigation and Ancillary Information Facility

• Although object and reference frame

naming/numbering schemes are independent, there is
nevertheless much overlap in the way objects and
frames are named and numbered
• This overlap is due to the following reasons
– Conventions adopted over the course of SPICE implementation
» Example: PCK-based body-fixed frames for planets and
satellites are named ‘IAU_<body name>’
• However, the IDs of these frames have nothing in common with the IDs of the
objects (bodies) for which these frames are defined
– The need for the object and frame IDs to be unique
» For this reason both the instrument (object) IDs and the
instrument frame IDs are derived from the ID of the spacecraft
on which the instrument is flown
– The need for the object and frame names to be meaningful
» For this reason the instrument frame names normally contain
both the name of the spacecraft and the name of the instrument

NAIF IDs and Names 34

 N IF “Odd Ball” Cases
Navigation and Ancillary Information Facility

• CK IDs
– Historically IDs used in CKs are called structure IDs but in reality they
are much more closely related to frames than to objects
– To find which frame is associated with a particular CK ID, look through
the FK for a frame whose _CLASS_ID keyword is set to the CK ID
» For CK-based frames both the frame ID and frame CLASS_ID are
set equal to the CK ID
• SCLK IDs
– Because most spacecraft have only one on-board clock, the SCLK ID of
that clock is simply the spacecraft ID. This SCLK ID is used by SPICE
APIs. Caution: the negative of the SCLK ID is used in SCLK kernel
keywords.
– Should a spacecraft carry more than one independent clock, unique
SCLK IDs for these other clocks would be needed
» Normally the ID of an additional clock will be set to the ID of the
instrument, of which that clock is a part
– SCLK IDs are used in SCLK APIs (must be provided by the user) and by
the frames subsystem when it reads CKs to determine orientation of
CK-based frames (gets SCLK ID from CK_*_SCLK keyword provided in
the frame definition or computes it by dividing CK ID by 1000)
NAIF IDs and Names 35
 N IF Name/IDs Example -- CASSINI (1)
Navigation and Ancillary Information Facility

Objects IDs/Names Frames IDs/Names

10 ‘SUN’ 1 ‘J2000’
Ephemeris objects

399 ‘EARTH’ 10013 ‘IAU_EARTH’

699 ‘SATURN’ 10016 ‘IAU_SATURN’
601 ‘MIMAS’ 10039 ‘IAU_MIMAS’
602 ‘ENCELADUS’ 10040 ‘IAU_ENCELADUS’
Spacecraft

structures

-82 ‘CASSINI’ -82000 ‘CASSINI_SC_COORD’

and its

-82001 ‘CASSINI_SRU-A’ -82001 ‘CASSINI_SRU-A’

-82790 ‘CASSINI_CDA’ -82790 ‘CASSINI_CDA’

instrument
CDA

-82791 ‘CASSINI_CDA_ART’
-82792 ‘CASSINI_CDA_BASE’

-82820 ‘CASSINI_CAPS_IMS’ -82820 ‘CASSINI_CAPS’

-82821 ‘CASSINI_CAPS_ELS’ -82821 ‘CASSINI_CAPS_ART’
instrument
CAPS

-82822 ‘CASSINI_CAPS_IBS_DT1’ -82822 ‘CASSINI_CAPS_BASE’

-82823 ‘CASSINI_CAPS_IBS_DT2’
-82824 ‘CASSINI_CAPS_IBS_DT3’

NAIF IDs and Names 36

 N IF Name/IDs Example -- CASSINI (2)
Navigation and Ancillary Information Facility

• The lists provided on the previous page are by no

means complete
– There are many more Saturnian satellites and other natural bodies
of interest to the Cassini mission, each having an associated frame
– There are many more instruments on the Cassini spacecraft, with
multiple frames associated with each of them
• To find names and IDs associated with these objects
and frames, users should refer as follows
– For names/IDs of Cassini instruments: Cassini IKs
» For other missions this information is in the mission’s FK
– For names of the reference frames associated with the Cassini
spacecraft, its subsystems and instruments: the Cassini FK
– For names of inertial frames and body-fixed frames associated with
natural bodies: FRAMES.REQ
– For names/IDs of natural objects: NAIF_IDS.REQ

NAIF IDs and Names 37

N IF
Navigation and Ancillary Information Facility

Getting, Installing and Verifying

the SPICE Toolkit

April 2023
 N IF Getting the Toolkit
Navigation and Ancillary Information Facility

• All official NAIF-supported instances of the SPICE Toolkit are

freely available from the NAIF server
https://naif.jpl.nasa.gov/naif/toolkit.html
– No password or identification is needed
• To download a Toolkit package
– Select language – FORTRAN, C, IDL, MATLAB or Java Native Interface
– Select computer platform/OS/compiler combination
» Be careful to pick the right architecture: 64 or 32 bit
– Download all toolkit package components
» Package file – toolkit.tar.Z (or toolkit.zip),
cspice.tar.Z (or cspice.zip),
icy.tar.Z (or icy.zip),
mice.tar.Z (or mice.zip),
JNISpice.tar.Z (or JNISpice.zip)
» Installation script (if present) – import*.csh
» Accompanying documents - README, dscriptn.txt, whats.new

Installing the SPICE Toolkit 2

 N IF Installing the Toolkit
Navigation and Ancillary Information Facility

• To install the Toolkit on Linux or Mac platform, follow the directions

given in the README. Normally this consists of the following:

prompt> chmod u+x importSpice.csh ( or chmod u+x import<language>.csh )

prompt> ./importSpice.csh ( or ./import<language>.csh )
prompt> rm toolkit.tar ( or rm <toolkit_name>.tar )

• To install the Toolkit on a PC running Windows, do the following:

• unzip the toolkit (or cspice or icy or mice) to expand the

archive.
prompt> unzip toolkit.zip

• You now have the expanded toolkit (or cspice or icy or mice or
JNISpice) package. In it the APIs are already compiled into
object modules, the needed libraries have been assembled,
and the several Toolkit utility executables have been built. In
most cases you need NOT re-do any of this build work! But
read on about some special circumstances.
Installing the SPICE Toolkit 3
 N IF Configuring Your Computer
Navigation and Ancillary Information Facility

• For some programming environments there are

required additional steps to prepare for
programming using SPICE.

• For some programming environments there are

recommended additional steps to make program
development easier.

• Read the “Preparing for Programming” tutorial

and the “README” file found in the Toolkit
download directory for more information!

Installing the SPICE Toolkit 4

 N IF Checking It Out
Navigation and Ancillary Information Facility

• Try an executable: tobin

– Use the Toolkit’s tobin utility to convert the SPICE transfer
format SPK files supplied with the Toolkit into binary format.
– The available transfer format files, cook_01.tsp and
cook_02.tsp, are found in the ../data directory*
» For example try this:
prompt> tobin cook_01.tsp

» This should produce an output file named cook_01.bsp

– Then try using brief to summarize the converted SPK kernel

prompt> brief cook_01.bsp

* According to modern SPICE conventions, the file name extension ".tsp" seen above
should be “.xsp”. The “.tsp” extension is kept for historical reasons.

Installing the SPICE Toolkit 5

 N IF Installation Problems?
Navigation and Ancillary Information Facility

• New versions of operating systems, compilers,

and MATLAB and IDL processors are released
rather frequently as compared to the frequency of
new SPICE Toolkit releases
– Sometimes this results in incompatibility issues with SPICE
• Sometimes a customer wants to use the Toolkit in
an environment not (officially) supported by NAIF
» Example: Octave instead of Matlab
» Example: Ubuntu instead of Linux
» Example: clang instead of gcc
– Porting a Toolkit to an unsupported environment might be
straightforward, but could be problematic
• See the next charts for a bit more information
regarding Toolkit installation issues
Installing the SPICE Toolkit 6
 N IF Compatibility Issues
Navigation and Ancillary Information Facility

• Problems may occur if your version of the

operating system, compiler, or IDL or MATLAB is
substantially newer or older than what NAIF used
in making its build
– First examine NAIF’s “Bugs” webpage for any relevant info:
» https://naif.jpl.nasa.gov/naif/bugs.html
– Then try rebuilding the Toolkit using the script “makeall.csh”
(or “makeall.bat”) located in the “top level” directory (toolkit or
cspice or icy or mice)

• If this doesn’t seem to work, contact NAIF,

providing error messages observed and version
numbers for your OS and your compiler or your
MATLAB or IDL app

Installing the SPICE Toolkit 7

 N IF Porting the Toolkit
Navigation and Ancillary Information Facility

• The packages provided on the NAIF server have

been built and tested by NAIF using the particular
environments shown at the end of this tutorial.

• If you try porting an instance of the Toolkit to an

unsupported environment there are numeric and
possibly compiler optimization issues that must be
carefully dealt with.
– You should definitely run NAIF’s test harness (e.g. tspice, for
Fortran, or tspice_c, for cspice/Mice/Icy) as part of your porting
confirmation process.
– Contact one of the NAIF team members for access to and
instructions on running the appropriate tspice test harness.
» https://naif.jpl.nasa.gov/naif/contactinfo.html
Installing the SPICE Toolkit 8
N IF
Navigation and Ancillary Information Facility

Introduction to the Family of

SPICE Toolkits

April 2023
 N IF Topics (1)
Navigation and Ancillary Information Facility

• Toolkit Architecture
• Toolkit Architecture Pictorial
• Fortran Toolkit
• C Toolkit
• IDL Toolkit
• Matlab Toolkit
• Toolkit Contents
• Toolkit Characteristics
• Toolkit Versions

Introduction to the SPICE Toolkit 2

 N IF Topics (2)
Navigation and Ancillary Information Facility

• Toolkit Library Overview

• Toolkit Library Capabilities
• Toolkit Directory Structure
• Toolkit Application Programs
• Toolkit Utility Programs
• Toolkit Documentation

Introduction to the SPICE Toolkit 3

 N IF Backup Topics
Navigation and Ancillary Information Facility

• Supported Environments
• Supported Environments – Fortran – N0067
• Supported Environments – C – N0067
• Supported Environments - IDL
• Supported Environments - MATLAB
• Status for Other Environments
• Bibliography

Introduction to the SPICE Toolkit 4

 N IF Toolkit Architecture (1)
Navigation and Ancillary Information Facility

The SPICE Toolkit is officially available in Fortran

77, C, IDL and MATLAB.
https://naif.jpl.nasa.gov/naif/toolkit.html

A beta Java Native Interface version (JNISpice) is

also available
https://naif.jpl.nasa.gov/pub/naif/misc/JNISpice/

Introduction to the SPICE Toolkit 5

 N IF Toolkit Architecture (2)
Navigation and Ancillary Information Facility

The Toolkits are packaged and delivered as

standalone products. The IDL, MATLAB and
JNISpice Toolkits by necessity also include the
complete C Toolkit.

Other people have created Python, Ruby, Swift,

Julia, Rust, and Unreal Engine toolkits, available
from their own websites, linked from the NAIF
server “Useful Links” page:
https://naif.jpl.nasa.gov/naif/links.html

NAIF has NOT been involved in creating, testing or

documenting these. Check with their authors about
functionality and details.
Introduction to the SPICE Toolkit 6
 N IF Toolkit Architecture Pictorial
Navigation and Ancillary Information Facility

Fortran C IDL MATLAB Java

User’s User’s User’s User’s User’s
Application Application Application Application Application
Program Program Program Program Program

C Interface Routines Matlab Wrappers Java Wrappers

C Interface Routines C Interface Routines
ANSI C Wrappers ANSI C Wrappers ANSI C Wrappers ANSI C Wrappers
ANSI
f2c Translated C Translated C Translated C Translated C
Fortran 77

Application Application
and Application Application Application
f2c and and and and
Utility Utility Utility Utility Utility
Programs Programs Programs Programs Programs

Language FORTRAN C IDL MATLAB Java

Product “Toolkit” “CSPICE” “Icy” “Mice”
name “JNISpice”
(Documentation
needs to be
improved)

Introduction to the SPICE Toolkit 7

 N IF Fortran Toolkit (1)
Navigation and Ancillary Information Facility

“Toolkit,” the Fortran 77 Toolkit.

• Developed first: in use since February 1990.
• Contains code written in ANSI Standard Fortran
77.
– A few widely supported non-ANSI extensions are used, for example:
» DO WHILE, DO…END DO.
• Compiles under a wide variety of Fortran
compilers.
– While NAIF cannot guarantee proper functioning of SPICE
under F90/F95 compilers except on officially supported
environments, those compilers might properly compile
SPICELIB with the resulting libraries being callable from
F90/F95 code if that compiler supports the F77 standard.

Introduction to the SPICE Toolkit 8

 N IF Fortran Toolkit (2)
Navigation and Ancillary Information Facility

• The Fortran Toolkit serves as an extension to

Fortran 77 such that the SPICE Toolkit adds and
improves Fortran functionality. The extensions
include:
– Improved string routines
– Simplified I/O routines
– Vector math
– Simple regex like functions
– Additional, general use, data structures
– Exception handling

Introduction to the SPICE Toolkit 9

 N IF Fortran Toolkit (3)
Navigation and Ancillary Information Facility

• Many of the routine names used in the various

Toolkits, descend from the original, six character,
Fortran names. NAIF maintains those names for
ease-of-compatibilty.

Introduction to the SPICE Toolkit 10

 N IF C Toolkit (1)
Navigation and Ancillary Information Facility

“CSPICE,” the C-language Toolkit

• Designed to duplicate the functionality of the
Fortran Toolkit.
• All CSPICE source code is in ANSI C.
– The Fortran SPICE Toolkit code is converted to ANSI C using
the automatic translation program f2c, Feldman. 1990 [1].
– High-level functions have been hand-coded in C and
documented in C style in order to provide a natural C-style API.
These functions are called “wrappers.”

Introduction to the SPICE Toolkit 11

 N IF C Toolkit (2)
Navigation and Ancillary Information Facility

• Most wrappers encapsulate calls to C functions

generated by f2c
– The simpler wrappers do their work in-line to boost
performance
– f2c’d functions may be called directly, but this is strongly
discouraged since f2c’d functions emulate Fortran
functionality:
– Call by reference
– Fortran-style array indexing
– Fortran-style strings
• CSPICE runs under a wide variety of ANSI C
compilers.

Introduction to the SPICE Toolkit 12

 N IF C Toolkit (3)
Navigation and Ancillary Information Facility

• CSPICE functions may be called from within C++

source code.
– CSPICE prototypes are protected from name mangling.
• Current CSPICE Limitations
– Not all “Required Reading” reference documents have been
converted to C style, with C examples.
– Eventually all will be converted.
• CSPICE wrappers do not exist for every API
provided in the Fortran toolkits.
– But CSPICE does include all the most commonly used
modules.
– More will be added as time permits.

Introduction to the SPICE Toolkit 13

 N IF C Toolkit (4)
Navigation and Ancillary Information Facility

• In some very limited cases, code generated by f2c

fails to emulate Fortran accurately. Should not be
a problem.
– List-directed I/O has some problems (not consequential for
CSPICE).
– Treatment of white space in text output is slightly different in
CSPICE.
– Logical unit-to-file name translation does not handle file name
"synonyms" properly under Linux: once opened with a
specified name, a file must be referred to using the same name
throughout a program run

Introduction to the SPICE Toolkit 14

 N IF IDL Toolkit (1)
Navigation and Ancillary Information Facility

“Icy,” the Interactive Data Language Toolkit

• Provides an IDL-callable “wrapper” interface for
many CSPICE wrapper routines.
– Example:
» CSPICE: spkezr_c ( targ, et, ref, abcorr, obs, state, &ltime );
» Icy: cspice_spkezr, targ, et, ref, abcorr, obs, state, ltime
– NAIF adds additional interfaces to Icy as time permits.
• By necessity all Icy Toolkit packages include the
complete CSPICE Toolkit.
– Additional Icy software components are:
» IDL interface wrappers (implemented in ANSI C)
» Icy cookbook programs (implemented in IDL)

Introduction to the SPICE Toolkit 15

 N IF IDL Toolkit (2)
Navigation and Ancillary Information Facility

• Icy Documentation
– Icy Reference Guide
» Principal documentation showing how to call Icy wrappers.
» Each Icy wrapper has an HTML page containing usage
examples serving as the Icy “module header”.
– Icy Required Reading
– Provides background information essential for programming
with Icy.
• See the “IDL_Interface” tutorial for details

Introduction to the SPICE Toolkit 16

 N IF Matlab Toolkit (1)
Navigation and Ancillary Information Facility

“Mice,” the Matlab Toolkit

• Mice provides a Matlab-callable “wrapper”
interface for many CSPICE wrapper routines
– Example:
» CSPICE: spkezr_c ( targ, et, ref, abcorr, obs, state, &ltime );
» Mice: [state, ltime] = cspice_spkezr( targ, et, ref, abcorr,
obs)
• By necessity all Mice Toolkit packages include the
complete CSPICE Toolkit.
– Additional Mice software components are:
» Matlab interface wrappers (implemented in Matlab wrapper
scripts calling the ANSI C based interface library)
» Mice cookbook programs (implemented in Matlab script)

Introduction to the SPICE Toolkit 17

 N IF Matlab Toolkit (2)
Navigation and Ancillary Information Facility

• Mice Documentation
– Mice Reference Guide
» Principal documentation showing how to call Mice
wrappers
– Each Mice wrapper script has a documentation header
containing usage examples, serving as SPICE “module
header”, available from the help command. This
documentation also exists as an HTML page.
• Mice Required Reading
– Provides background information essential for programming
with Mice
• See the “Matlab_Interface” tutorial for details

Introduction to the SPICE Toolkit 18

 N IF Toolkit Contents
Navigation and Ancillary Information Facility

• Software
– Subroutine libraries, with source code
» SPICELIB (Fortran)
» CSPICE (C)
» Icy (C)
» Mice (C and Matlab scripts)
– Executable programs
» Application and utility programs
» A few example programs (called “cookbook” programs)
– Installation/build scripts (normally you do NOT need to use these)
• Documentation
– Available in plain text and HTML

• Example Data
– Sample kernel files (supplied only for use with cookbook example programs, not
valid for general use).

Introduction to the SPICE Toolkit 19

 N IF Toolkit Characteristics
Navigation and Ancillary Information Facility

• Computations are identical in all languages.

• For a given computer and operating system, all Toolkits use
identical kernel files.
– Refer to the “Porting Kernels” tutorial for information about
using kernels received from a machine different from what you
are using.
• Code is well tested before being released to users.
• New Toolkits are always backwards compatible.
– An application that worked when linked against an older
Toolkit will link and work, without need for changes, using a
new Toolkit.
– Past functionality is never changed or removed, except that:
» enhancements of existing routines are allowed.
» NAIF reserves the right to fix bugs.
• Extensive user-oriented documentation is provided.
– Includes highly documented source code.
Introduction to the SPICE Toolkit 20
 N IF Toolkit Versions
Navigation and Ancillary Information Facility

• Toolkit Version
– SPICE Toolkits have an associated Version number
» Example: “N0067” (also written as “N67”)
– The version number applies to all language implementations for
all supported platforms.

• When does NAIF release a new SPICE Toolkit version?

» Not according to a fixed schedule
» Primarily driven by availability of significant new capabilities
• For example, addition of the digital shape kernel subsystem
(DSK)
» On rare occasion a Toolkit update is released to fix bugs,
improve documentation, or satisfy an urgent request from a
flight project.

Introduction to the SPICE Toolkit 21

 N IF Toolkit Library Overview
Navigation and Ancillary Information Facility

• Toolkit libraries contain a broad set of capabilities related to

the computations needed for determining “observation
geometry” and time conversions.
– Examples appear on the next several pages

• Not all functionality is present in all four language versions

of the Toolkit library.
– The Fortran (Toolkit) and C (CSPICE) Toolkits provide almost
identical functionality.
– The IDL (Icy) and Matlab (Mice) Toolkits duplicate most but not
all of the functionality available in the C Toolkits.
» We add additional interfaces as time permits.

Introduction to the SPICE Toolkit 22

 N IF Toolkit Library Capabilities (1)
Navigation and Ancillary Information Facility

• Kernel read access

– “Load” kernels
– Get state or position vectors (SPK)
– Get orientation of planets, natural satellites, etc. (PCK)
– Get body shape parameters or physical constants (PCK)
– Get orientation of spacecraft or spacecraft instruments or structures
(CK, FK)
– Get instrument parameters (e.g., FOV) (IK)
– Get digital shape data (DSK)
– Query binary EK files (EK-ESQ)
• Kernel write access for binary kernels
– SPK writers
– CK writers
– PCK writers (only for binary PCK files)
– DSK writers

Introduction to the SPICE Toolkit 23

 N IF Toolkit Library Capabilities (2)
Navigation and Ancillary Information Facility

• Additional ephemeris functions

– Classical osculating elements
– Two-body Keplerian propagation
– NORAD two line elements sets (TLE) propagation
» Current SPICE implementation of the NORAD propagator based on
Vallado 2006 [2].
– Light time and Stellar aberration computation
• Frame transformations
– Obtain 3x3 matrices for frame transformations of positions
– Obtain 6x6 matrices for frame transformations of states
• Time conversions
– Conversion between standard systems: TDB, TT (TDT), UTC
– Conversion between SCLK and other systems
– Parsing and formatting
• Geometry finder calculations
– Find times or time spans when a specified geometric condition is met
– Find times or time spans when a specified geometric parameter is
within a given range (by performing two searches), or is at a maximum
or minimum

Introduction to the SPICE Toolkit 24

 N IF Toolkit Library Capabilities (3)
Navigation and Ancillary Information Facility

• Math
– Vector/Matrix operations
– Rotations, Euler angles, quaternions
– Coordinate conversion (systems: latitudinal, cylindrical, rectangular,
RA and DEC, spherical, geodetic, planetographic)
– Geometry: ellipsoids, ellipses, planes
– High-level functions: illumination angles, sub-observer point, sub-solar
point, surface intercept point.
• Constants
– Julian date of epoch J2000, SPD (seconds per day), PI, etc.
• Strings
– Parsing: find tokens, words
– Numeric conversion
– Pattern matching
– Replace marker, substring
– Suffix, prefix
– Case conversion
– Find first/last non-blank character, first/last printing character

Introduction to the SPICE Toolkit 25

 N IF Toolkit Library Capabilities (4)
Navigation and Ancillary Information Facility
• Arrays
– Sorting, finding order vector, reordering
– Searching: linear, binary
– Insertion and deletion
• Name/ID code conversion
– Bodies
– Frames
– Surfaces
• I/O support
– Logical unit management (for Fortran toolkits)
– Open, read, write text files
– Kernel pool API
• Exception handling
– Control exception handling behavior: mode, set message, assign
output device.
• Advanced data types
– Cells, Sets
– Windows (sometimes called schedules)
– Symbol Tables
– Planes, Ellipses
Introduction to the SPICE Toolkit 26
 N IF Toolkit Directory Structure (1)
Navigation and Ancillary Information Facility

• The directory structures for the four kinds of Toolkits are

almost identical. However…
– The CSPICE, Icy, Mice, and JNISpice Toolkits also have a directory for
include files.
– The names for application source code directories in CSPICE, Icy, Mice,
and JNISpice differ slightly from those in the Fortran toolkit.
– Icy, Mice, and JNISpice include additional directories for :
» Icy/Mice/JNISpice source code
» Icy/Mice cookbook programs

• The top level directory name for each Toolkit is:

– “toolkit” for Fortran Toolkits.
– “cspice” for C Toolkits.
– “icy” for IDL Toolkits.
– “mice” for Matlab Toolkits
– “JNISpice” for Java Toolkits

Introduction to the SPICE Toolkit 27

 N IF Toolkit Directory Structure (2)
Navigation and Ancillary Information Facility

• The next level is comprised of:

– data
» Cookbook example kernels (use ONLY for training with cookbook programs).
– doc
» Text documents — *.req, *.ug, spicelib.idx/cspice.idx, whats.new,
dscriptn.txt, version.txt.
» Subdirectory containing HTML documentation, called “html”.
• The “html” subdirectory contains a single file — the top level HTML documentation
index called “index.html” — and a number of subdirectories, one for each of the
various groups of documents in HTML format (API Reference Guide pages, User’s
Guide pages, etc.).
– etc
» In most Toolkits this directory is empty.
– exe
» Executables for some SPICE application and utility programs:
• brief, chronos, ckbrief, commnt, dskbrief, dskexp, frmdiff, inspekt,
mkdsk, mkspk, msopck, spacit, spkdiff, spkmerge, tobin, toxfr, version.
» Executables for the several cookbook example programs:
• simple, states, subpt, tictoc

Introduction to the SPICE Toolkit 28

 N IF Toolkit Directory Structure (3)
Navigation and Ancillary Information Facility
– include (applies only to CSPICE, Icy, Mice, and JNISpice)
» API header files.
• File to include in callers of CSPICE is SpiceUsr.h
– lib
» Toolkit libraries:
• For Fortran Toolkits
– spicelib.a or spicelib.lib (public modules; use these)
– support.a or support.lib (supporting modules; don’t use these)
• For C Toolkits
– cspice.a or cspice.lib (public modules; use these)
– csupport.a or csupport.lib (supporting modules; don’t use these)
• For Icy Toolkits:
– icy.so or icy.dll (shared object library)
– icy.dlm (dynamically loadable module)
– cspice.a or cspice.lib, and csupport.a or csupport.lib
• For Mice Toolkits:
– mice.mex* (shared object library)
– cspice.a or cspice.lib, and csupport.a or csupport.lib
• For JNISpice Toolkits:
– libJNISpice.so or libJNISpice.lib (shared object library)
– cspice.a or cspice.lib, and csupport.a or csupport.lib
– src
» Source code directories for executables and libraries
• Files have type *.f, *.for, *.inc, *.pgm, *.c, *.h, *.x, *.pro, *.m, *.java, *.class, *.html
• *.h files appearing here are not part of the user API

Introduction to the SPICE Toolkit 29

 N IF Toolkit Application Programs
Navigation and Ancillary Information Facility

• SPICE Toolkit application programs are available to:

– create most binary kernel types
– compare or analyze certain kernel types
– do various kinds of time conversions
– and more…
– See the toolkit_apps tutorial for details

• Some additional application programs are available

only from the NAIF website:
– http://naif.jpl.nasa.gov/naif/utilities.html
– See the non_toolkit_apps tutorial for details

Introduction to the SPICE Toolkit 30

 N IF Toolkit Utility Programs
Navigation and Ancillary Information Facility

• SPICE Toolkit utility programs are available to:

– add comments to binary kernels
» commnt
– read comments from binary kernels
» commnt, spacit
» inspekt (only for EK/ESQ files)
– summarize coverage of binary kernels
» brief, ckbrief, dskbrief, spacit
– merge or subset SPK files
» spkmerge
– indicate current Toolkit version
» version
– port binary SPICE kernels between incompatible systems (infrequently
needed)
» tobin, toxfr, spacit
» bingo (available only from the NAIF webpage)
– port text SPICE kernels between incompatible systems
» bingo (available only from the NAIF webpage)
• See the toolkit_apps tutorial for details

Introduction to the SPICE Toolkit 31

 N IF Toolkit Documentation (1)
Navigation and Ancillary Information Facility

• All Toolkits include documentation in plain text and HTML

formats.
– Plain text documents are located under the “doc” directory
– HTML documents are located under the “<toolkit_name>/doc/html”
(Unix) or “<toolkit name>\doc\html” (Windows) directory
» “index.html” is the top level index… your starting point
• All Toolkits include the following kinds of documents
– Module headers
» They act as primary functional specification: I/O, exceptions,
particulars defining behavior of module
» They contain code examples
» A standard format is used for each routine or entry point
» Location of HTML Module Headers:
• Use the “API Reference Guide” link from the top level index
» Location of plain text Module Headers:
• Fortran: the top comment block in the source code files under “src/spicelib”
• C: the top comment block in the source code files under “src/cspice”
• IDL: Icy Module Headers are not available in plain text format
• Matlab: accessible via “help function_name” command

Introduction to the SPICE Toolkit continues on next page 32

 N IF Toolkit Documentation (2)
Navigation and Ancillary Information Facility

- “Required Reading” documents

» Extensive technical references for principal subsystems
• Provide many low-level details
• Provide code examples
» HTML versions are accessible using the “Required Reading
Documents” link from the top level index.
» Plain text versions are located under “doc” and have extension
“.req”
» Not all Required Readings were adapted for all languages
• Some of the Required Reading documents provided with CSPICE are based upon
Fortran SPICE
• Some of the Required Readings for Icy or Mice toolkits are based upon CSPICE
– User’s Guides
» Tell how to use the utility and application programs.
» HTML versions are accessible using the “User’s Guide
Documents” link from the top level index.
» Plain text versions are located under “doc” and have extension
“.ug.”

Introduction to the SPICE Toolkit 33

 N IF Toolkit Documentation (3)
Navigation and Ancillary Information Facility

• Other documents
– Permuted Index
» Maps phrases describing functionality to corresponding module
names and file names
» Shows names of all entry points in Fortran toolkit APIs
» HTML version is accessible using the “Permuted Index” link from
the top level index.
» Plain text version is located under “doc” and has extension “.idx”:
• Fortran: spicelib.idx
• C: cspice.idx
• IDL: icy.idx and cspice .idx
• Matlab: mice.idx and cspice.idx

– Toolkit Description
» Describes the directory structure and contents of an installed
Toolkit
» Customized based on set of delivered products and platform
» HTML version is accessible using the “Toolkit Contents” link from
the top level index.
» Plain text version is “doc/dscriptn.txt”
continues on next page
Introduction to the SPICE Toolkit 34
 N IF Toolkit Documentation (4)
Navigation and Ancillary Information Facility

– Introduction to SPICE
» HTML document containing a brief introduction to the Toolkit and
SPICE system; accessible using the “Introduction to the SPICE
System” link from the top level index.
– What’s New in SPICE
» Describes new features and bug fixes in each Toolkit release,
covering the last 20 years.
» Plain text version is “doc/whats.new”.
» HTML version is accessible using the “What’s New in SPICE” link
from the top level index.
– Toolkit Version Description
» Indicates Toolkit version
» Plain text version is “doc/version.txt”
» Not available in HTML

• You can also use Google to view any of the Toolkit documents
– E.g., search on the API name (e.g. spkezr, spkezr_c, or cspice_spkezr (for Icy and
Mice) in combination with naif and spice
– E.g. search on the document name (e.g. CK Required Reading, spkdiff user’s guide)

Introduction to the SPICE Toolkit 35

 N IF
Navigation and Ancillary Information Facility

Backup

Introduction to the SPICE Toolkit 36

 N IF Supported Environments
Navigation and Ancillary Information Facility

• NAIF ports the SPICE Toolkit to many popular environments.

– Each environment is characterized by
» Language
» Hardware type (platform)
» Operating System
» Compiler
» Selected compilation options

• NAIF provides SPICE Toolkit packages for each supported

environment.
– If you cannot find a package built for the environment of interest to you,
contact NAIF.

• The list of supported environments slowly evolves.

– Old ones no longer supportable are terminated.
– New ones are added based on user interest and available NAIF
resources.

Introduction to the SPICE Toolkit 37

 N IF Supported Environments – Fortran – N0067
Navigation and Ancillary Information Facility

Product Name Operating System Compiler

Mac/Intel, OS-X, Intel FORTRAN, 64bit OS X 10.15 Intel Fortran 2021.4.0
Mac/Intel, OS-X, gfortran, 64bit OS X 10.15 gfortran 9.1
PC, CYGWIN, gfortran, 64bit Windows/Cygwin 10.0 gfortran 11.2
PC, Linux, Intel FORTRAN, 32bit Red Hat Linux (RHE7) Intel Fortran 13.1

PC, Linux, Intel FORTRAN, 64bit Red Hat Linux (RHE7) Intel Fortran 13.1

PC, Linux, g77, 32bit Red Hat Linux (RHE6) g77 3.4

PC, Linux, gfortran, 32bit Red Hat Linux (RHE7) gfortran 7.3
PC, Linux, gfortran, 64bit Red Hat Linux (RHE7) gfortran 7.3
PC, Windows, Intel FORTRAN, 32bit Windows 10 Intel Fortran 2021.4.0
PC, Windows, Intel FORTRAN, 64bit Windows 10 Intel Fortran 2021.4.0
Sun/SPARC, Solaris, SUN FORTRAN, 32bit Solaris 10 Sun FORTRAN 95 8.8

The OS and compiler versions listed above were used to build and test N0067
Fortran SPICE Toolkit distribution packages. These packages are expected to
work on/with newer OS and compiler versions.

Introduction to the SPICE Toolkit 38

 N IF Supported Environments – C – N0067
Navigation and Ancillary Information Facility

Product Name Operating System Compiler

Mac/Intel, OS-X, Apple C. 32bit OS X 10.15 Apple C 12.0

Mac/M1, OS-X, Apple C, 64bit OS X 12.0 Apple C 13.0

PC, CYGWIN, gCC, 64bit Windows/Cygwin 10.0 gcc 11.2
PC, Linux, gCC, 32bit Red Hat Linux (RHE7) gcc 7.3
PC, Linux, gCC, 64bit Red Hat Linux (RHE7) gcc 7.3
PC, Windows, Microsoft Visual C, 32bit Windows 10 MS Visual Studio 16.11 C

PC, Windows, Microsoft Visual C, 64bit Windows 10 MS Visual Studio 16.11 C

Sun/SPARC, Solaris, gCC, 32bit Solaris 10 gcc 3.4

Sun/SPARC, Solaris, gCC, 64bit Solaris 10 gcc 3.4

Sun/SPARC, Solaris, SUN C, 32bit Solaris 10 Sun C 5.15

Sun/SPARC, Solaris, SUN C, 64bit Solaris 10 Sun C 5.15

The OS and compiler versions listed above were used to build and test N0067
CSPICE Toolkit distribution packages. These packages are expected to work
on/with newer OS and compiler versions.

Introduction to the SPICE Toolkit 39

 N IF Supported Environments - IDL
Navigation and Ancillary Information Facility

Product Name Operating System Compiler, IDL

Mac/Intel, OS-X, Apple C/IDL, 64bit OS X 10.15 Apple C 12.0, IDL 8.7
PC, Linux, gcc/IDL, 64bit Red Hat Linux (RHE7) gcc 7.3, IDL 8.8
PC, Windows, Microsoft Visual C/IDL, 64bit Windows 10 MS Visual Studio 16.11 C, IDL 8.8

The OS, compiler, and IDL versions listed above were used to build and test
N0067 Icy Toolkit distribution packages. These packages are expected to work
on/with newer OS, compiler, and IDL versions.

Introduction to the SPICE Toolkit 40

 N IF Supported Environments - MATLAB
Navigation and Ancillary Information Facility

Product Name Operating System Compiler, MATLAB

Mac/Intel, OS-X, Apple C, 64bit OS X 10.15 Apple C 12.0.0, MATLAB R2018b
PC, Linux, gCC, 64bit Red Hat Linux (RHE7) gcc 7.3, MATLAB R2020b
PC, Windows, Microsoft Visual Windows 10 MS Visual Studio 16.11 C, MATLAB
C/Matlab, 64bit R2020b

The OS, compiler, and Matlab versions listed above were used to build and test
N0067 MiceToolkit distribution packages. These packages are expected to work
on/with newer OS, compiler, and Matlab versions.

Introduction to the SPICE Toolkit 41

 N IF Status for Other Environments
Navigation and Ancillary Information Facility

• The SPICE and CSPICE packages should function as expected on

platforms running any Linux OS (Ubuntu, Fedora, etc.), BSD OS
(OpenBSD, FreeBSD, etc.), or a Linux based OS environment
(minGW) using a standard GCC tool-chain (gfortran or gcc
compiler).
– Version 4.2 or later for gfortran; 4.0 or later for gcc

• The Mice package has been successfully built against the octave
environment (version > 3.4) on Linux and OS X. Contact NAIF if
you have questions concerning use with Octave.

Introduction to the SPICE Toolkit 42

 N IF Bibliography
Navigation and Ancillary Information Facility

[1] Feldman, S. I., D. M. Gay, M. W. Maimone, and N. L. Schryer.

1991. “Availability of F2c—a Fortran to C Converter.” SIGPLAN
Fortran Forum 10 (2): 14–15.
https://doi.org/10.1145/122006.122007.

[2] Vallado, David A., Paul Crawford, Richard Hujsak, and T. S.

Kelso. 2006. “Revisiting Spacetrack Report #3.” AIAA/AAS
Astrodynamics Specialist Conference, August.

Introduction to the SPICE Toolkit 43

N IF
Navigation and Ancillary Information Facility

“Icy”
The IDL© Interface to CSPICE

April 2023

© Harris Geospatial
 N IF Topics
Navigation and Ancillary Information Facility

• Icy Benefits
• How does it work?
• Distribution
• Icy Operation
• Vectorization
• Simple Icy Example

IDL Interface to CSPICE 2

 N IF Icy Benefits
Navigation and Ancillary Information Facility

• Ease of use: Icy operates as an extension to the IDL

language regime.
• Icy supports more than four-hundred CSPICE routines.
• Icy calls usually correspond to the call format of the
underlying CSPICE routine, returning IDL native data types.
• Icy has some capability not available in CSPICE such as
vectorization.
• CSPICE error messages return to IDL in a form usable by the
catch error handler construct.

IDL Interface to CSPICE 3

 N IF How Does It Work? (1)
Navigation and Ancillary Information Facility

• The IDL environment includes an intrinsic capability to use

external routines.
– Icy functions as an IDL Dynamically Loadable Module (DLM). A
DLM consists of a shared object library (icy.so/.dll) and a DLM
text definition file (icy.dlm).
» The shared library contains a set of IDL callable C interface routines
that wrap a subset of CSPICE wrapper calls.
» The text definition file lists the routines within the shared library
and the format for the routine’s call parameters.

continued on next page

IDL Interface to CSPICE 4
 N IF How Does It Work? (2)
Navigation and Ancillary Information Facility

• Using Icy from IDL requires you register the Icy DLM with IDL to
access the interface routines. Several means exist to do so.
– On Unix/Linux, start IDL from the directory containing icy.dlm and icy.so
– From the IDL interpreter (or from a command script), execute the
dlm_register command: IDL> dlm_register, '_path_to_directory_containing_icy.dlm_'
» Examples (Unix and Windows):
» IDL> dlm_register, '/naif/icy/lib/icy.dlm'
» IDL> dlm_register, 'c:\naif\icy\lib\icy.dlm'
– Copy icy.dlm and icy.so or icy.dll to IDL's binary directory:
{The IDL install directory}/bin/bin.user_architecture
» Examples (Unix and Windows):
» cp icy.dlm icy.so /Applications/exelis/idl/bin/bin.darwin.x86_64/
» cp icy.dlm icy.dll C:\Program Files\Exelis\idl83\bin\bin.x86_64\

– Append to the IDL_DLM_PATH environment variable the directory name

containing icy.dlm and icy.so or icy.dll:
setenv IDL_DLM_PATH "<IDL_DEFAULT>:_path_to_directory_containing_icy.dlm_"

Warning: with regards to the Icy source directory, icy/src/icy, do not invoke IDL
from the directory, do not register the directory, and do not append IDL_DLM_PATH
to the directory. This directory contains an “icy.dlm” but no “icy.so.”

continued on next page

IDL Interface to CSPICE 5
 N IF How Does It Work? (3)
Navigation and Ancillary Information Facility

When a user invokes a call to a DLM routine:

1. IDL calls…
2. the interface routine in the shared object
library, linked against…
3. CSPICE, which performs its function and
returns the result…
4. to IDL…

… transparent from the user’s perspective.

IDL Interface to CSPICE 6

 N IF Icy Distribution
Navigation and Ancillary Information Facility

• NAIF distributes the Icy package as an independent product

analogous to SPICELIB and CSPICE.
• The package includes:
– the CSPICE source files
– the Icy interface source code
– platform specific build scripts for Icy and CSPICE
– IDL versions of the SPICE cookbook programs, states, tictoc,
subpt, and simple
– an HTML based help system for both Icy and CSPICE, with the
Icy help cross-linked to CSPICE
– the Icy shared library and DLM file. The system is ready for use
after installation of these files
• You do not need a C compiler to use Icy.

IDL Interface to CSPICE 7

 N IF Icy Operation (1)
Navigation and Ancillary Information Facility

• A user may occasionally encounter an IDL math exception:

% Program caused arithmetic error: Floating underflow

– This warning occurs most often as a consequence of CSPICE

math operations.
• In all known cases, the SIGFPE exceptions caused by
CSPICE can be ignored. CSPICE assumes numeric underflow
as zero.
– A user can adjust IDL’s response to math exceptions by setting
the !EXCEPT variable:
» !EXCEPT = 0 suppresses the SIGFPE messages, and even more
(e.g. a fatal error).
» !EXCEPT = 1, the default, reports math exceptions on return to the
interactive prompt.
• NAIF recommends this be used.
» !EXCEPT = 2 reports exceptions immediately after executing the
command.
continued on next page
IDL Interface to CSPICE 8
 N IF Icy Operation (2)
Navigation and Ancillary Information Facility

• A possible irritant exists in loading kernels using the

cspice_furnsh function.
– Kernels are loaded into your IDL session, not into your IDL
scripts. This means:
» loaded binary kernels remain accessible (“active”) throughout your
IDL session
» data from loaded text kernels remain in the kernel pool (in the IDL
memory space) throughout your IDL session
– Consequence: some kernel data may be available to one of your
scripts even though not intended to be so.
» You could get incorrect results!
» If you run only one script during your IDL session, there’s no
problem.

continued on next page

IDL Interface to CSPICE 9
 N IF Icy Operation (3)
Navigation and Ancillary Information Facility

• Mitigation: two approaches

– Load all needed SPICE kernels for your IDL session at the
beginning of the session, paying careful attention to the files
loaded and the loading order (loading order affects precedence)
» Convince yourself that this approach will provide ALL of the scripts
you will run during this IDL session with the appropriate SPICE data
– At or near the end of every IDL script:
» include a call to cspice_unload for each kernel loaded using
cspice_furnsh
» or include a call to cspice_kclear to remove ALL kernel data from
the kernel pool loaded using cspice_furnsh

IDL Interface to CSPICE 10

 N IF Icy Vectorization (1)
Navigation and Ancillary Information Facility

• Several common Icy functions include use of vectorized

arguments, a capability not available in C or FORTRAN
toolkits.
– Note: IDL indexes arrays using a base value of zero as opposed
to FORTRAN, which uses a base value of one.
» Example: access the first element of an IDL 1xN array using
array[0], the second element using array[1], etc.
• Example: use Icy to retrieve state vectors and light-time
values for 1000 ephemeris times.
– Create an array of 1000 ephemeris times with step size of 10
hours, starting from July 1, 2005.

cspice_str2et, 'July 1, 2005', start

et = dindgen( 1000 )*36000.d + start

continued on next page

IDL Interface to CSPICE 11

 N IF Icy Vectorization (2)
Navigation and Ancillary Information Facility

– Retrieve the state vectors and corresponding light times from

Mars to earth at each et, in the J2000 frame, using LT+S
aberration correction:

cspice_spkezr, 'Earth', et, 'J2000', 'LT+S', 'MARS', state, ltime

– Access the ith state 6-vector corresponding to the ith ephemeris

time with the expression

state_i = state[*,i]

• Convert the ephemeris time vector et from the previous

example to UTC calendar strings with three decimal places
accuracy.
format = 'C'
prec = 3
cspice_et2utc, et, format, prec, utcstr

continued on next page

IDL Interface to CSPICE 12

 N IF Icy Vectorization (3)
Navigation and Ancillary Information Facility

– The call returns utcstr, an array of 1000 strings each ith string
the calendar date corresponding to et[i]. Access the ith string of
utcstr corresponding to the ith ephemeris time with the expression

utcstr_i = utcstr[i]

• Convert the position components of the N state vectors to

latitudinal coordinates (the first three components of a state
vector - IDL uses a zero based vector index).

cspice_reclat, state[0:2,*], radius, latitude, longitude

– The call returns three double precision variables of type

Array[1000] (vectorized scalars): radius, latitude, longitude.

IDL Interface to CSPICE 13

 N IF Simple Icy Example
Navigation and Ancillary Information Facility

• As an example of using Icy with vectorization, calculate and

plot, in the J2000 inertial frame, the trajectory of the Cassini
spacecraft from June 20 2004 to December 1 2005.
;; Construct a meta kernel, "standard.tm", which will be used to load the needed
;; generic kernels: "naif0011.tls", "de421.bsp", and "pck00010.tpc".

;; Load the generic kernels using the meta kernel, and a Cassini spk.

cspice_furnsh, ['standard.tm', '/kernels/cassini/spk/030201AP_SK_SM546_T45.bsp' ]

;; Define the number of divisions of the time interval and the time interval.
STEP = 10000
cspice_str2et, [ 'Jun 20, 2004', 'Dec 1, 2005' ] , et
times = dindgen(STEP)*(et[1]-et[0])/STEP + et[0]

cspice_spkpos, 'Cassini', times, 'J2000', 'NONE', 'SATURN BARYCENTER', pos, ltime

;; Plot the resulting trajectory.

x = pos[0,*]
y = pos[1,*]
z = pos[2,*]
iplot, x, y, z

cspice_kclear

IDL Interface to CSPICE 14

 N IF Icy Example Graphic Output
Navigation and Ancillary Information Facility

z
y

Trajectory of the Cassini spacecraft, in the J2000 frame, from June 20 2004 to Dec 1 2005

IDL Interface to CSPICE 15

N IF
Navigation and Ancillary Information Facility

“Mice”
The MATLAB© Interface to CSPICE

April 2023

© The MathWorks Inc.

 N IF Topics
Navigation and Ancillary Information Facility

• Mice Benefits
• How does it work?
• Distribution
• Mice Operation
• Vectorization
• Simple Mice Examples

MATLAB Interface to CSPICE 2

 N IF Mice Benefits
Navigation and Ancillary Information Facility

• Mice operates as an extension to the MATLAB environment.

• All Mice calls are functions regardless of the call format of
the underlying CSPICE routine, returning MATLAB native
data types.
• Mice has some capability not available in CSPICE such as
vectorization.
• CSPICE error messages return to MATLAB in the form usable
by the try...catch construct.

MATLAB Interface to CSPICE 3

 N IF How Does It Work? (1)
Navigation and Ancillary Information Facility

• The MATLAB environment includes an intrinsic capability to

use external routines.
– Mice functions as a MATLAB executable, MEX, consisting of the
Mice MEX shared object library and a set of .m wrapper files.
» The Mice library contains the MATLAB callable C interface routines
that wrap a subset of CSPICE wrapper calls.
» The wrapper files, named cspice_*.m and mice_*.m, provide the
MATLAB calls to the interface functions.
» A function prefixed with ‘cspice_’ retains essentially the same
argument list as the CSPICE counterpart.
» An interface prefixed with ‘mice_’ returns a structure, with the
fields of the structure corresponding to the output arguments of
the CSPICE counterpart.
» The wrappers include a header section describing the function call,
displayable by the MATLAB help command.

continued on next page

MATLAB Interface to CSPICE 4
 N IF How Does It Work? (2)
Navigation and Ancillary Information Facility

When a user invokes a call to a Mice function:

1. MATLAB calls…
2. the function's wrapper, which calls…
3. the Mice MEX shared object library, which
performs its function then returns the result…
4. to the wrapper, which…
5. returns the result to the user

… transparent from the user’s perspective.

MATLAB Interface to CSPICE 5

 N IF Mice Distribution
Navigation and Ancillary Information Facility

• NAIF distributes Mice as a complete, standalone package.

• The package includes:
– the CSPICE source files
– the Mice interface source code
– platform specific build scripts for Mice and CSPICE
– MATLAB versions of the SPICE cookbook programs, states, tictoc,
subpt, and simple
– an HTML-based help system for both Mice and CSPICE, with the
Mice help cross-linked to CSPICE
– the Mice MEX shared library and the M wrapper files. The system
is ready for use after installation of the library and wrapper files.
• You do not need a C compiler to use Mice.

MATLAB Interface to CSPICE 6

 N IF Mice Operation (1)
Navigation and Ancillary Information Facility

• A possible irritant exists in loading kernels using the

cspice_furnsh function.
– Kernels load into your MATLAB session, not into your MATLAB
scripts. This means:
» loaded binary kernels remain accessible (“active”) throughout your
MATLAB session
» data from loaded text kernels remain in the kernel pool (in the memory
space used by CSPICE) throughout your MATLAB session
– Consequence: some kernel data may be available to one of your
scripts even though not intended to be so.
» You could get incorrect results!
» If you run only one script during your MATLAB session, there’s no
problem.

continued on next page

MATLAB Interface to CSPICE 7

 N IF Mice Operation (2)
Navigation and Ancillary Information Facility

• Mitigation: two approaches

– Load all needed SPICE kernels for your MATLAB session at the
beginning of the session, paying careful attention to the files
loaded and the loading order (loading order affects precedence)
» Convince yourself that this approach will provide ALL of the scripts
you will run during this MATLAB session with the appropriate SPICE
data
– At or near the end of every MATLAB script:
» include a call to cspice_unload for each kernel loaded using
cspice_furnsh
» or include a call to cspice_kclear to remove ALL kernel data from
the kernel pool loaded using cspice_furnsh

MATLAB Interface to CSPICE 8

 N IF Mice Vectorization (1)
Navigation and Ancillary Information Facility

• Most Mice functions include use of vectorized arguments, a

capability not available in C or Fortran toolkits.
• Example: use Mice to retrieve state vectors and light-time
values for 1000 ephemeris times.
– Create an array of 1000 ephemeris times with a step size of 10
hours, starting from July 1, 2005:

start = cspice_str2et('July 1 2005');

et = (0:999)*36000 + start;

– Retrieve the state vectors and corresponding light times from

Mars to earth at each et in the J2000 frame with LT+S aberration
correction:

[state, ltime] = cspice_spkezr( 'Earth', et, 'J2000', 'LT+S', 'MARS');

or
starg = mice_spkezr( 'Earth', et, 'J2000', 'LT+S', 'MARS');

continued on next page

MATLAB Interface to CSPICE 9

 N IF Mice Vectorization (2)
Navigation and Ancillary Information Facility

– Access the ith state 6-vector (6x1 array) corresponding to the ith
ephemeris time with the expression

state_i = state(:,i)
or
state_i = starg(i).state

• Convert the ephemeris time vector et from the previous

example to UTC calendar strings with three decimal places of
precision in the seconds field.
format = 'C';
prec = 3;
utcstr = cspice_et2utc( et, format, prec );

– The call returns utcstr, an array of 1000 strings (dimensioned

1000x24), where each ith string is the calendar date corresponding
to et(i).
continued on next page

MATLAB Interface to CSPICE 10

 N IF Mice Vectorization (3)
Navigation and Ancillary Information Facility

– Access the ith string of utcstr corresponding to the ith ephemeris

time with the expression

utcstr_i = utcstr(i,:)

• Convert the position components (the first three components

in a state vector) of the N state vectors returned in state by
the cspice_spkezr function to latitudinal coordinates.

[radius, latitude, longitude] = cspice_reclat( state(1:3,:) );

– The call returns three double precision 1x1000 arrays (vectorized

scalars): radius, latitude, longitude.

MATLAB Interface to CSPICE 11

 N IF Simple Mice Example (1)
Navigation and Ancillary Information Facility

• As an example of using Mice, calculate and plot the trajectory

of the Cassini spacecraft, in the J2000 inertial frame, from
June 20 2004 to December 1 2005. This example uses the
cspice_spkpos function to retrieve position data.

% Construct a meta kernel, "standard.tm", which will be used to load the needed
% generic kernels: "naif0011.tls", "de421.bsp", and "pck00010.tpc".

% Load the generic kernels using the meta kernel, and a Cassini spk.

cspice_furnsh( { 'standard.tm', '/kernels/cassini/spk/030201AP_SK_SM546_T45.bsp'} )

% Define the number of divisions of the time interval.

STEP = 1000;
et = cspice_str2et( {'Jun 20, 2004', 'Dec 1, 2005'} );
times = (0:STEP-1) * ( et(2) - et(1) )/STEP + et(1);

[pos,ltime]= cspice_spkpos( 'Cassini', times, 'J2000', 'NONE', 'SATURN BARYCENTER' );

% Plot the resulting trajectory.

x = pos(1,:);
y = pos(2,:);
z = pos(3,:);

plot3(x,y,z)

cspice_kclear

continued on next page

MATLAB Interface to CSPICE 12

 N IF Simple Mice Example (2)
Navigation and Ancillary Information Facility

• Repeat the example of the previous page, except use the

mice_spkezr function to retrieve full state vectors.

% Define the number of divisions of the time interval.

STEP = 1000;

% Construct a meta kernel, "standard.tm", which will be used to load the needed
% generic kernels: "naif0009.tls", "de421.bsp", and "pck00009.tpc".

% Load the generic kernels using the meta kernel, and a Cassini spk.

cspice_furnsh( { 'standard.tm', '/kernels/cassini/spk/030201AP_SK_SM546_T45.bsp'} )

et = cspice_str2et( {'Jun 20, 2004', 'Dec 1, 2005'} );

times = (0:STEP-1) * ( et(2) - et(1) )/STEP + et(1);

ptarg = mice_spkpos( 'Cassini', times, 'J2000', 'NONE', 'SATURN BARYCENTER' );

pos = [ptarg.pos];

% Plot the resulting trajectory.

x = pos(1,:);
y = pos(2,:);
z = pos(3,:);

plot3(x,y,z)

cspice_kclear

MATLAB Interface to CSPICE 13

 N IF Mice Example Graphic Output
Navigation and Ancillary Information Facility

Trajectory of the Cassini spacecraft, in the J2000 frame, from June 20 2004 to Dec 1 2005

MATLAB Interface to CSPICE 14

N IF
Navigation and Ancillary Information Facility

Preparing for Programming

Using the SPICE Toolkits

April 2023
 N IF Setting Path to Toolkit Executables (1)
Navigation and Ancillary Information Facility

Recommended for all Toolkits

• Unix (OS X, Linux, BSD, execute the command echo $SHELL to
determine your shell name)
– csh, tcsh: Use the set command to add the location of toolkit executables to
your path.
» set path = ($path /my_directory/toolkit/exe)
» set path = ($path /my_directory/cspice/exe)
» set path = ($path /my_directory/icy/exe)
» set path = ($path /my_directory/mice/exe)
– sh, bash, zsh, dash, ksh: Assign the $PATH environment variable.
» PATH=$PATH:/my_directory/toolkit/exe
» PATH=$PATH:/my_directory/cspice/exe
» PATH=$PATH:/my_directory/icy/exe
» PATH=$PATH:/my_directory/mice/exe

Replace my_directory with the path in which you installed the toolkit on your computer.

Preparing for Programming 2

 N IF Setting Path to Toolkit Executables (2)
Navigation and Ancillary Information Facility

Recommended for all Toolkits

• Windows
– DOS shell: Use the set command to add the location of toolkit executables
to your path. Use setx for a persistent setting.
» set PATH=drive:\my_directory\toolkit\exe;%PATH%
» set PATH=drive:\my_directory\cspice\exe;%PATH%
» set PATH=drive:\my_directory\icy\exe;%PATH%
» set PATH=drive:\my_directory\mice\exe;%PATH%
– Or edit the environment variable PATH from the Advanced pane on the
System Control Panel (Control Panel->System->Advanced).

Replace drive:\my_directory with the path in which you installed the toolkit on your
computer.
Preparing for Programming 3
 N IF Unix: Build a SPICE Executable
Navigation and Ancillary Information Facility

• Assume your Toolkit distribution is installed at:

/naif/cspice/ for CSPICE (C toolkits)
/naif/toolkit/ for SPICE (Fortran toolkits)

• Compile and link an application–let’s pretend it’s named prgrm–

against the CSPICE or SPICELIB library.
– For C Linux/BSD/Unix:
$ gcc prgrm.c -I/naif/cspice/include /naif/cspice/lib/cspice.a –lm
– For C OS X:
$ clang prgrm.c -I/naif/cspice/include /naif/cspice/lib/cspice.a –lm
– For FORTRAN:
$ gfortran prgrm.f /naif/toolkit/spicelib.a
• The default SPICE library names do not conform to the UNIX
convention libname.a. So you cannot use the conventional
library path/name options –L and –l, e.g.
$ gcc … -L/path_to_libs/ -lname

unless you rename the SPICE library.

Preparing for Programming 4

 N IF Windows: C compiler settings
Navigation and Ancillary Information Facility

• The standard installation of Microsoft Visual Studio may not

update environment variables needed to use the C compiler (cl)
from the standard DOS shell.
– Visual Studio provides scripts to spawn a DOS shell with the needed
environment. Find the scripts by navigating to the menu

Programs -> Visual Studio “version”

The script for a 64-bit C/C++ environment is:

VSversion x64 Native Tools Command Prompt

The script for a 64-bit ifort environment is:

VSversion x86 Native Tools Command Prompt

Preparing for Programming 5

 N IF Windows: ifort compiler settings
Navigation and Ancillary Information Facility

• The standard installation of Intel ifort may not update

environment variables needed to use the Fortran compiler (ifort)
from the standard DOS shell.
– Intel provides batch scripts to spawn DOS shell with the needed
environment. Find the scripts by navigating to the menu

Programs -> Intel OneAPI

The script for a 32-bit ifort environment is:

Intel oneAPI command prompt for IA32 for Visual Studio

The script for a 64-bit ifort environment is:

Intel oneAPI command prompt for Intel 64 for Visual Studio

Preparing for Programming 6

 N IF Windows: Build a SPICE Executable
Navigation and Ancillary Information Facility

• Assume the SPICE distribution is installed at:

C:\naif\cspice\ for C toolkits
C:\naif\toolkit\ for Fortran toolkits

• Compile and link an application, say program, against the

CSPICE or SPICELIB library.
– For C toolkits:
> cl program.c -IC:\naif\cspice\include C:\naif\cspice\lib\cspice.lib

– For FORTRAN toolkits:

> ifort program.f C:\naif\toolkit\lib\SPICELIB.LIB

Preparing for Programming 7

 N IF Icy: Register the Icy DLM to IDL (1)
Navigation and Ancillary Information Facility
Required for “Icy”
• Unix and Windows
– Use the IDL register command:

IDL> dlm_register, '_path_to_directory_containing_icy.dlm_'

e.g.
IDL > dlm_register, '/naif/icy/lib/icy.dlm'

– Or, copy icy.dlm and icy.so (or icy.dll) to IDL's binary directory located at
{The IDL install directory}/bin/bin.user_architecture, e.g.
» For Unix, X86 architecture

cp icy.dlm icy.so /Applications/exelis/idl/bin/bin.darwin.x86_64/

» For Windows, X86 architecture

cp icy.dlm icy.dll C:\Program Files\Exelis\idl83\bin\bin.x86_64\

continued on next page

Preparing for Programming 8
 N IF Icy: Register the Icy DLM to IDL (2)
Navigation and Ancillary Information Facility

• Unix specific:
– Start the IDL application from a shell in the directory containing both
icy.dlm and icy.so.
– Append the path to your icy.dlm to the IDL_DLM_PATH environment
variable to include the directory containing icy.dlm and icy.so, e.g.:

setenv IDL_DLM_PATH "<IDL_DEFAULT>:_path_to_directory_containing_icy.dlm_"

Warning: do not invoke IDL from the Icy source directory, icy/src/icy, nor
register that directory, and do not append that directory to
IDL_DLM_PATH. This directory contains an “icy.dlm” but not “icy.so.”

continued on next page

Preparing for Programming 9
 N IF Icy: Register the Icy DLM to IDL (3)
Navigation and Ancillary Information Facility

• Windows specific:
– Set environment variable IDL_DLM_PATH from the Advanced pane
of the System Control Panel.
• Once registered as specified on earlier pages, confirm IDL
recognizes and can access Icy.
– Using the help command:

IDL> help, 'icy', /DL

**ICY - IDL/CSPICE interface from JPL/NAIF (not loaded)

» Appearance of the words “not loaded” might suggest something is wrong, but
this is expected state until you execute an Icy command.
– Execute a trivial Icy command:
IDL> print, cspice_icy('version')
% Loaded DLM: ICY.
Icy 1.4.20 25-DEC-2008 (EDW)

Preparing for Programming 10

 N IF Icy: Using the IDL IDE
Navigation and Ancillary Information Facility

Recommended for “Icy”

• Use the IDL IDE’s preferences panel to set the current working
directory to the location where you will be developing your
code.
• Optional: Place your dlm_register command in a start up
script. Specify the script using the IDL IDE’s preferences panel.

Preparing for Programming 11

 N IF Mice
Navigation and Ancillary Information Facility

Required for “Mice”

• Assume the Mice distribution is installed at C:\naif\mice\ on

Windows, or /naif/mice/ on Unix/Linux. Use of Mice from Matlab
requires the Mice source and library directories exist in the
Matlab search path. The easiest way to update the Matlab path is
with the “addpath” command.
– On Windows:
>> addpath('C:\naif\mice\lib')
>> addpath('C:\naif\mice\src\mice')

– On Unix/Linux:

>> addpath('/naif/mice/lib')
>> addpath('/naif/mice/src/mice')

Preparing for Programming 12

 N IF
Navigation and Ancillary Information Facility

Backup

• Icy programming example

• Mice programming example
• References
• Matlab 2016a MEX Change

Preparing for Programming 13

 N IF Simple Icy Example
Navigation and Ancillary Information Facility

• As an example of Icy use with vectorization, calculate and plot

the trajectory in the J2000 inertial frame of the Cassini
spacecraft from June 20, 2004 to December 1, 2005.
;; Construct a meta kernel, "standard.tm", which will be used to load the needed
;; generic kernels: "naif0009.tls", "de421.bsp", and "pck0009.tpc".

;; Load the generic kernels using the meta kernel, and a Cassini spk.

cspice_furnsh, 'standard.tm'
cspice_furnsh, '/kernels/cassini/spk/030201AP_SK_SM546_T45.bsp'

;; Define the number of divisions of the time interval and the time interval.
STEP = 10000
utc = [ 'Jun 20, 2004', 'Dec 1, 2005' ]
cspice_str2et, utc, et
times = dindgen(STEP)*(et[1]-et[0])/STEP + et[0]

cspice_spkpos, 'Cassini', times, 'J2000', 'NONE', 'SATURN BARYCENTER', pos, ltime

;; Plot the resulting trajectory.

x = pos[0,*]
y = pos[1,*]
z = pos[2,*]
iplot, x, y, z

cspice_kclear

Preparing for Programming 14

 N IF Graphic Output
Navigation and Ancillary Information Facility

Trajectory of the Cassini vehicle in the J2000 frame, for June 20, 2004 to Dec 1, 2005

Preparing for Programming 15

 N IF Simple Mice Example
Navigation and Ancillary Information Facility

• As an example of Mice use with vectorization, calculate and

plot the trajectory in the J2000 inertial frame of the Cassini
spacecraft from June 20, 2004 to December 1, 2005
% Construct a meta kernel, "standard.tm", which will be used to load the needed
% generic kernels: "naif0009.tls", "de421.bsp", and "pck0009.tpc".

% Load the generic kernels using the meta kernel, and a Cassini spk.

cspice_furnsh( { 'standard.tm', '/kernels/cassini/spk/030201AP_SK_SM546_T45.bsp'} )

% Define the number of divisions of the time interval and the time interval.
STEP = 1000;
et = cspice_str2et( {'Jun 20, 2004', 'Dec 1, 2005'} );
times = (0:STEP-1) * ( et(2) - et(1) )/STEP + et(1);

[pos, ltime]= cspice_spkpos( 'Cassini', times, 'J2000', 'NONE', 'SATURN BARYCENTER' );

% Plot the resulting trajectory.

x = pos(1,:);
y = pos(2,:);
z = pos(3,:);

plot3(x,y,z)

cspice_kclear

Preparing for Programming 16

 N IF Graphic Output
Navigation and Ancillary Information Facility

Trajectory of the Cassini vehicle in the J2000 frame, for June 20, 2004 to Dec 1, 2005

Preparing for Programming 17

 N IF References
Navigation and Ancillary Information Facility

• NAIF documents providing more information

concerning SPICE programing:
– “icy.req,” Icy Required Reading
» icy/doc/icy.req
» icy/doc/html/req/icy.html
– “mice.req,” Mice Required Reading
» mice/doc/mice.req
» mice/doc/html/req/mice.html
– “cspice.req,” CSPICE Required Reading
» cspice/doc/cspice.req
» cspice/doc/html/req/cspice.html
– “Introduction to the Family of SPICE Toolkits” tutorial

Preparing for Programming 18

 N IF Matlab 2016a MEX Change
Navigation and Ancillary Information Facility

• Mathworks changed the operation of the MEX

utility in the Matlab 2016a. Use of the
mkprodct.csh/mkprodct.bat build script included
with SPICE Toolkit N0066 or earlier will fail to
build Mice against 2016a or later. The N0067
Toolkits include a modified version of the build
scripts.
• Most Mice users should *NOT* rebuild the Mice
Toolkit.

Preparing for Programming 19

N IF
Navigation and Ancillary Information Facility

Introduction to Kernels

April 2023
 N IF Agenda
Navigation and Ancillary Information Facility

• Overview
• Kernel architecture
• Producing kernels
• Using kernels

Introduction to Kernels 2
 N IF What is a SPICE “Kernel”
Navigation and Ancillary Information Facility

“Kernel” means file

“Kernel” means a file containing ancillary data
“Kernel” means a file containing "low level" ancillary data that may be used,
along with other data and SPICE Toolkit software, to determine higher level
observation geometry parameters of use to scientists and engineers in planning
and carrying out space missions, and analyzing data returned from missions.

Introduction to Kernels 3
 N IF The Family of SPICE Kernels
Navigation and Ancillary Information Facility

• SPK • FK
– Spacecraft and Planet Ephemeris – Reference frame specifications

• PCK • SCLK
– Planetary Constants, for natural bodies – Spacecraft clock correlation data

» Orientation • LSK
» Size and shape – Leapseconds

• IK
• MK
– Instrument
– Meta-Kernel (a.k.a. “FURNSH kernel”)
• CK – Mechanism for aggregating and easily
– Orientation (“Camera-matrix”) loading a collection of kernel files

• EK
• DSK
– Events, up to three distinct components
– Digital shape kernel
» ESP: science plan
» Tesselated plate model
» ESQ: sequence » Digital elevation model (under
» ENB: experimenter’s notebook development)
• DBK
– Database mechanism
EK is rarely used » Primarily used to support the ESQ

Introduction to Kernels 4
 N IF SPICE Kernel Forms
Navigation and Ancillary Information Facility
• Binary form
– Files containing mostly data encoded in binary form
» They also contain a small amount of ASCII text
– Provide rapid access to large amounts of numeric data
– Require the use of SPICE Toolkit software to produce them
– Require the use of SPICE Toolkit software to utilize their contents
• Text form
– Files containing only printing characters (ASCII values 32-126), i.e.
human-readable text.
– Produced using a text editor
– Require the use of SPICE Toolkit software to utilize their contents

• “Transfer” form of a binary kernel

– An ASCII representation of a binary kernel
– Was used for porting the file between computers with incompatible
binary representations (e.g. PC and UNIX); no longer needed
» But it is one way to convert a non-native binary kernel into native
format, needed for modifying the kernel or improving read efficiency
Introduction to Kernels 5
 N IF Text and Binary Kernels
Navigation and Ancillary Information Facility

SPICE text kernels are: SPICE binary kernels are:

– text PCK (the most common – SPK
type of PCK) – binary PCK (has been used only
– IK for Earth, Moon and Eros)
– FK – CK
– LSK – DSK
– SCLK
– MK
– ESQ (part of the E-kernel) Rarely
– DBK (database kernel) used

Introduction to Kernels 6
 N IF
Navigation and Ancillary Information Facility

Kernel Architecture

- Text kernels
- Binary kernels
- Comments in kernels

Introduction to Kernels 7
 N IF Text Kernel Contents
Navigation and Ancillary Information Facility

• A text kernel is a plain text file of ASCII data

• It contains assignments of the form:

variable_name = value(s)

• A text kernel should also contain descriptive

comments that describe the assignments
– Comments are sometimes referred to as “meta-data”
» Don’t confuse this usage with the “meta-kernel” described
later in this tutorial

Introduction to Kernels 8
 N IF Example Text Kernel
Navigation and Ancillary Information Facility

KPL/<kernel type>
<some comments about the data >
An initial “comments” block
\begindata (Doesn't need a \begintext marker)
NAME = 'Sample text value'
NaMe = 'Keywords are case sensitive'

NUMBERS = ( 10.123, +151.241, -1D14 ) A data block

NUMBERS += ( 1.0, 1, -10 )
NUMBERS += ( 1.542E-12, 1.123125412 )

START = @2011-JAN-1

\begintext
A “comments” block
< some comments about the data >

\begindata

< more data in keyword = value syntax >

Another data block

\begintext
< etc., etc. > Another “comments” block

• The next several pages describe what you see above

• See the “Kernel Required Reading” document for details

Introduction to Kernels 9
 N IF Text Kernel Formatting
Navigation and Ancillary Information Facility
• KPL/<text kernel type>
- Its use is optional, but is highly recommended
- Must appear on the first line, starting in column 1
- Tells SPICE software what kind of kernel it is
- Text kernel types are FK, IK, PCK, SCLK, MK

• \begindata and \begintext

- Markers, on lines by themselves, which set off the beginning of
data and the beginning of comment (metadata) blocks respectively
- They need not begin in column 1
- An initial set of comments need not be preceded by a \begintext marker

• <LF> for Unix/Linux/Mac or <CR><LF> for Windows

- End of line marker (usually not visible when displaying a text kernel)
- Must be present on EVERY line in the text kernel

• Max line length, including any white space is 132 characters

Introduction to Kernels 10
 N IF Text Kernel Operators
Navigation and Ancillary Information Facility

• An assignment using the “=” operator associates one or

more values with a variable name.

• An assignment using the “+=” operator associates additional

values with an existing variable name.

• An assignment using the “@” symbol associates a calendar

date with a variable name.
– The string will be parsed and converted to an internal double precision
representation of that epoch as seconds past the J2000 epoch
» There is no time system implied
» This conversion does not need a leap seconds kernel

Introduction to Kernels 11
 N IF Variable Names and Values
Navigation and Ancillary Information Facility

• Variable names
– Max of 32 characters
– Are case sensitive (recommendation: use only upper case)
– Cannot include space, comma, parenthesis, equals sign or tab
– Recommendation: don’t use the “+” sign as the last character
• Values
– Numeric: integer, fixed point and scientific notation are allowed
– String:
» enclosed in single quotes
» maximum length of 80 characters on a given line
• SPICE has means to concatenate multiple string values to allow for values exceeding 80
characters
» string values may contain any printing ASCII character, including blank
– Time: identified by the “@” character
– Any of these three types can be provided as an n-dimensional vector of values
» Components are separated by commas or white space (but not TABs)
» Parentheses are used to enclose the vector
» Each string value in a vector is contained in single quotes
» Values in a vector must all be of the same type (numeric, string or time)
• See “Kernel Required Reading” for more information
Introduction to Kernels 12
 N IF Variable Names and Values
Navigation and Ancillary Information Facility

• A “picture” of the most basic text kernel assignment rules

132 max characters, with the non-printing system-dependent end-of-line indicator at the end*

32 max characters 80 max characters, not including the single quotes at each end

MY_NIFTY_TEXT_VARIABLE = 'Text, numbers or dates containing no more than 80 characters' <EOL>

Single quote Single quote

Any printing characters except A text string, consisting of

white space, comma, parenthesis, any printing characters Character string
equals sign, or TAB. Don't end a
name with a plus sign. NAIF ( 6378.12 6332.34 6355.8 )
strongly recommends you use ( 6378.12, 6332.34, 6355.8 ) Two forms for vectors
only upper case characters.
-12.236E5 Scientific notation
@31-JAN-2012 Dates (special handling ensues)

*Unix, Linux, OSX EOL symbol: <LF>

Introduction to Kernels *DOS/Windows EOL symbol: <CR><LF>
13
 N IF Example Binary Kernel
Navigation and Ancillary Information Facility

A binary kernel contains lots

of non-printing data.

Includes a “comment area”

where descriptive meta-data
provided as ASCII text
should be placed.

Introduction to Kernels 14
 N IF Comments In SPICE Kernels
Navigation and Ancillary Information Facility

• All SPICE kernels should contain comments–

descriptive information about the data contained
in the file.
– “Comments” are also known as “meta-data”

• See the tutorial on comments for more

information.

Introduction to Kernels 15
 N IF
Navigation and Ancillary Information Facility

Producing Kernels

Introduction to Kernels 16
 N IF Making a Text Kernel
Navigation and Ancillary Information Facility

• Text kernels may be produced using a text editor

– Text kernels must contain only printing characters (ASCII values 32-
126), i.e. human-readable text
» TAB characters are allowed but HIGHLY DISCOURAGED
» Caution: some text editors insert non-printing characters
– Text kernels must have each line terminated with the end-of-line
indicator appropriate for the operating system you are using
» For Unix, PC/Linux, Mac OSX: <LF>
» For PC/Windows: <CR><LF>
» Don’t forget to insert the end-of-line indicator on the very last line
of the kernel!
– Fortran toolkit software will detect and warn you if trying to read a
non-native text kernel. (Not needed for other languages.)
» Caution: this warning doesn’t work for a file smaller than 132
bytes
– See the BACKUP for information on converting text kernels between
these two line termination techniques
Introduction to Kernels 17
 N IF Making a Binary Kernel
Navigation and Ancillary Information Facility

• Binary kernels are made using Toolkit utility

programs, or by using Toolkit APIs built into your
own application program
• See “How Kernels are Made and Used” in the
BACKUP section for a bit more information
• See the “Making an SPK” and “Making a CK”
tutorials

Introduction to Kernels 18
 N IF
Navigation and Ancillary Information Facility

Using Kernels

Introduction to Kernels 19
 N IF Loading Kernels - 1
Navigation and Ancillary Information Facility

• To make kernels available to a program you “load” them

• When you load a text kernel:

– the file is opened
– the kernel contents are read into memory
» variable names and associated values are stored in a data structure
called the “kernel pool”
– the file is closed

• When you load a binary kernel:

– the file is opened
– for SPK, CK, binary PCK and DSK files, no data are read until a read request
is made by Toolkit software
– for ESQ files, the schema description is read, checked, and stored in memory
at load time, but no data are read until a query/fetch is made
– for all practical purposes the binary file remains open unless specifically
unloaded by you

Introduction to Kernels 20
 N IF Loading Kernels - 2
Navigation and Ancillary Information Facility

• Use the FURNSH routine to load all kernels – text and binary
– CALL FURNSH ( 'name.ext' ) (Fortran)
– furnsh_c ( "name.ext" ); (C)
– cspice_furnsh, 'name.ext' (IDL)
– cspice_furnsh ( 'name.ext' ) (MATLAB)
– spiceypy.furnsh ( 'name.ext' ) (Python using SpiceyPy)

• Best practice: don’t hard code filenames as shown above–

instead, list them in a “meta-kernel” and load the meta-
kernel using FURNSH
– CALL FURNSH ( 'meta-kernel_name' ) (Fortran example)
– Look further down for more information on meta-kernels

• Information about kernels loaded using FURNSH may

be obtained using the KTOTAL, KINFO, KDATA APIs
Introduction to Kernels 21
 N IF Run-time Translation
Navigation and Ancillary Information Facility

• Binary kernels, whether or not in native binary

format, may be read by any of the toolkits
– Accomplished by run-time translation built into Toolkit code
– Run-time translation does NOT apply to writing to an existing
binary kernel

• Text kernels may be read by any of the C, IDL and

Matlab Toolkits no matter if the end-of-line
terminator is Windows style (<CR><LF>) or
OSX/Linux style (<LF>)
– Accomplished by run-time translation built into Toolkit code
– Run-time text kernel translation does NOT work for Fortran
Toolkits: these Toolkits read text kernels only in native format

Introduction to Kernels 22
 N IF
Navigation and Ancillary Information Facility

Meta-Kernels
These help make kernel management easy!

Introduction to Kernels 23
 N IF What is a “Meta-Kernel”
Navigation and Ancillary Information Facility

• A meta-kernel is a file that lists names (and locations) of a

collection of SPICE kernels that are to be used together in a
SPICE-based application
– Loading the meta-kernel causes all of the kernels listed in it to be
loaded

• Using a meta-kernel makes it easy to manage which SPICE

files are loaded into your program. You don’t need to revise
your code–just edit your meta-kernel

• A meta-kernel is implemented using the SPICE text kernel

standards
– Refer to the Kernel Required Reading technical reference for details

• The terms “meta-kernel” and “FURNSH kernel” are used

synonymously

Introduction to Kernels 24
 N IF Sample Meta-Kernel
Navigation and Ancillary Information Facility

KPL/MK
\begindata
KERNELS_TO_LOAD = (
'/home/mydir/kernels/lowest_priority.bsp',
'/home/mydir/kernels/next_priority.bsp',
'/home/mydir/kernels/highest_priority.bsp',
'/home/mydir/kernels/leapseconds.tls',
'/home/mydir/kernels/sclk.tsc',
All the commas
'/home/mydir/kernels/c-kernel.bc', are optional
'/home/mydir/kernels+',
'/custom/kernel_data/p_constants.tpc',
)

Introduction to Kernels 25
 N IF Sample Meta-Kernel
Navigation and Ancillary Information Facility

KPL/MK
\begindata
KERNELS_TO_LOAD = (
'/home/mydir/kernels/lowest_priority.bsp',
'/home/mydir/kernels/next_priority.bsp',
'/home/mydir/kernels/highest_priority.bsp',
'/home/mydir/kernels/leapseconds.tls',
'/home/mydir/kernels/sclk.tsc',
All the commas
'/home/mydir/kernels/c-kernel.bc', are optional
'/home/mydir/kernels+',
'/custom/kernel_data/p_constants.tpc',
)

• The last file listed in this example (p_constants.tpc) demonstrates how

to use the continuation character, ‘+’, to work around the 80 character
limitation imposed on string lengths by the text kernel standards.

• See the next two pages for some important OS-specific details!
Introduction to Kernels 26
 Unix/Mac
N IF Sample Meta-Kernel
Navigation and Ancillary Information Facility

• This meta-kernel uses the PATH_VALUES and PATH_SYMBOLS

keywords to specify the directory where the kernels are located.
KPL/MK
\begindata
PATH_VALUES = ( '/home/mydir/kernels' )
PATH_SYMBOLS = ( 'KERNELS' )
KERNELS_TO_LOAD = (
'$KERNELS/lowest_priority.bsp', UNIX/MAC style path
'$KERNELS/next_priority.bsp', notation, using
'$KERNELS/highest_priority.bsp', forward slashes
'$KERNELS/leapseconds.tls',
'$KERNELS/sclk.tsc',
'$KERNELS/c-kernel.bc',
'$KERNELS/custom/kernel_data/p_constants.tpc'
)
• Although the OS environment variable notation $<name> is used to refer to the
symbols specified using the PATH_VALUES and PATH_SYMBOLS keywords,
these symbols are NOT operating system environment variables and are set and
used for substitution by SPICE only in the context of this particular meta-kernel.
• The ‘+’ continuation character described on the previous page may be used to
handle path strings that exceed 80 characters.
Introduction to Kernels 27
 Windows
N IF Sample Meta-Kernel
Navigation and Ancillary Information Facility

• This meta-kernel uses the PATH_VALUES and PATH_SYMBOLS

keywords to specify the directory where the kernels are located.
KPL/MK
\begindata
PATH_VALUES = ( 'c:\home\mydir\kernels' )
PATH_SYMBOLS = ( 'KERNELS' )
KERNELS_TO_LOAD = (
'$KERNELS\lowest_priority.bsp',
Windows style path
'$KERNELS\next_priority.bsp',
notation, using
'$KERNELS\highest_priority.bsp',
backwards slashes
'$KERNELS\leapseconds.tls',
'$KERNELS\sclk.tsc',
'$KERNELS\c-kernel.bc',
'$KERNELS\custom\kernel_data\p_constants.tpc'
)
• Although the OS environment variable notation $<name> is used to refer to the
symbols specified using the PATH_VALUES and PATH_SYMBOLS keywords,
these symbols are NOT operating system environment variables and are set and
used for substitution by SPICE only in the context of this particular meta-kernel.
• The ‘+’ continuation character described on the previous page may be used to
handle path strings that exceed 80 characters.
Introduction to Kernels 28
 N IF Limits on Loaded Kernels (N67)
Navigation and Ancillary Information Facility

• The number of all types of kernels that may be

loaded at any time is large, but limited.
– As of the version N67 Toolkits it is limited to 5,300
» Assumes each kernel has been loaded only once, and not
unloaded.
• As of the version N67 Toolkits the number of binary
kernels that may be loaded at the same time is
limited to 5000
– Binary kernel types are: SPK, binary PCK, CK and DSK
» Also the rarely used ESQ
• There are also limits on the number of keywords
and values for all loaded text kernels:
– Maximum number of keywords is 26,003
– Maximum number of numeric data items is 400,000
– Maximum number of character data items is 15,000

Introduction to Kernels 29
 N IF Kernel Precedence Rule
Navigation and Ancillary Information Facility

• The order in which SPICE kernels are loaded at run-time

determines their priority when requests for data are made
– For binary kernels, data from a higher priority file will be used in the
case when two or more files contain data overlapping in time for a given
object.
» For SPKs, CKs, and binary PCKs the file loaded last takes
precedence (has higher priority).
» For DSKs, use of priority will be specified via API calls
» Not yet supported as of N67 Toolkits
» Priority doesn’t apply to ESQ files – all data from all loaded files
are available.
– If two (or more) text kernels assign value(s) to a single keyword using
the “=” operator, the data value(s) associated with the last loaded
occurrence of the keyword are used–all earlier values are replaced with
the last loaded value(s).
– Orientation data from a binary PCK always supersedes orientation data
(for the same object) obtained from a text PCK, no matter the order in
which the kernels are loaded.

Introduction to Kernels 30
 N IF Unloading Kernels
Navigation and Ancillary Information Facility

• The unloading of a kernel is infrequently needed for

FORTRAN or CSPICE applications but is essential for Icy,
Mice, Python and similar interpreter scripts.
– Because of the way IDL and MATLAB interact with external shared
object libraries, any kernels loaded during an IDL or MATLAB session
will stay loaded until the end of the session unless they are specifically
unloaded.
• The routines KCLEAR and UNLOAD may be used to unload
kernels containing data you wish to be no longer available
to your program.
– KCLEAR unloads all kernels and clears the kernel pool
– UNLOAD unloads specified kernels
– KCLEAR and UNLOAD are only capable of unloading kernels that have
been loaded with the routine FURNSH. They will not unload any files
that have been loaded with older load routines such as SPKLEF (those
used prior to availability of FURNSH).
• Caution: unloading text kernels with UNLOAD will also
remove any kernel pool data provided through the kernel
pool run-time data insertion/update APIs (PCPOOL,
PDPOOL, PIPOOL).
Introduction to Kernels 31
 N IF Backup
Navigation and Ancillary Information Facility

• How kernels are made and used

• Why and how kernels are modified

• SPICE data structures hierarchy

• Problems making text kernels

Introduction to Kernels 32
 N IF How Kernels are Made and Used at JPL
Navigation and Ancillary Information Facility
How Made? How Used? How Made? The EK family How Used?
1 3
Text editor or Web browser or
SBP* SPK SBP* existing file, input ESP SBP*, depending
(e.g. MKSPK) via ESQ or ENB on implementation
2
Text editor 3
for text versions
PCK SBP* SBP* ESQ SBP*
SBP*
for binary versions
2 2

Browser or
Text editor IK SBP*
e-mail ENB SBP*

2 2

SBP* CK SBP* Text editor LSK SBP*

(e.g. MSOPCK)
2 3
Text editor FK SBP*
SBP* SCLK SBP*
(e.g. MAKCLK)
2
3
SBP* DSK SBP*
Text editor Meta-kernel
SBP*
(e.g. MKDSK) (FURNSH)

Who usually makes the kernels at JPL? *SBP = SPICE-based program that uses modules from the SPICE
1
NAV and NAIF This represents current practice for Toolkit. In some cases the Toolkit contains such a program already
built. In some cases NAIF may have such a ready-built program
2
NAIF most JPL missions, but is by no means a
that is not in the SPICE Toolkit. Names of a few programs
requirement. Anyone can make SPICE files. commonly used to make kernels are shown in parentheses.
3
NAIFtoorKernels
Introduction other 33
 N IF Why & How Kernels are “Modified” - 1
Navigation and Ancillary Information Facility
File Type Why Modified How Modified
-To add comments - COMMNT, SPACIT or SPICELIB module
SPK -To merge files or subset a file - SPKMERGE, DAFCAT
-To correct/revise an object ID - BSPIDMOD

PCK -To revise data values - Text editor

Text version -To add additional data items and values - Text editor

-To revise data values - Text editor

IK -To add additional data items and values - Text editor

-To add comments - COMMNT, SPACIT, or SPICELIB module

CK -To merge files - DAFCAT, CKSMRG
-To revise the interpolation interval - CKSPANIT, CKSMRG
-To subset a file - CKSLICER

FK -To revise data values - Text editor

-To add additional data items and values - Text editor

-To add comments - COMMNT, SPACIT or SPICELIB module

DSK -To merge files - DLACAT
-To modify segment attributes - DSKMOD
Introduction to Kernels 34
 N IF Why & How Kernels are “Modified” - 2
Navigation and Ancillary Information Facility

File Type Why Modified How Modified

The EK family

-To add, revise or delete “data” - (Depends on implementation)

ESP -To add comments - (Depends on implementation)

-To add additional data - Toolkit modules

-To revise data - Toolkit modules
ESQ -To delete data - Toolkit modules
-To add comments - COMMNT, SPACIT or SPICELIB module
-To merge files - (under development)
ENB -To change entry status (public <--> private) - WWW
-To delete an entry - WWW

LSK - To add a new leapsecond - Text editor

SCLK - To add comments - Text editor

Meta-kernel
(FURNSH) - To add or remove kernels to be used - Text editor
in a program

Introduction to Kernels 35
 N IF SPICE Data Structures Hierarchy
Navigation and Ancillary Information Facility

EK Family

Meta-kernel
SPK CK PCK IK FK SCLK LSK (FURNSH) DSK ENB ESP ESQ
High OR AND
Level OR

Mid
Level DLA DBK

MIME
Low including
Level DAF TEXT plain text DAS
Binary Text Binary

DAF = Double Precision Array File DSK = Digital Shape Kernel (under development)
DBK = Data Base Kernel DLA = DAS Linked Array (under development)
DAS = Direct Access, Segregated
Excepting MIME, each of these data structures is built entirely of SPICE components.
PCK files are usually text-based, but binary versions exist for the earth and moon. The ESP has been
implemented using both the ENB and ESQ mechanisms. The DBK is a SQL-like, homebrew database.
Introduction to Kernels 36
 N IF Problems Making Text Kernels
Navigation and Ancillary Information Facility

• Cutting/pasting complete, or pieces of, data

assignments or \begindata or \begintext
markers into a text kernel can cause a problem
– It may result in insertion of non-printing characters or incorrect
end-of-line terminators
– This is not a problem for comments, but it is probably best to
treat all portions of a text kernel the same
• If creating a text kernel by editing an existing one:
– first save a backup copy
– be sure you are starting with a file in native format for the
computer you are using: either Unix/Linux/Mac or Windows
– use single quotes around any string (character) values
– be sure to insert a final end-of-line marker at the end of your
last line of data or text
» Press the “return” key to accomplish this

Introduction to Kernels 37
 N IF Some Useful Tools - 1
Navigation and Ancillary Information Facility

• For a Unix or Linux (including Mac) environment

– In order to display all non-printing characters, display tab characters
as “^l”, and place a “$” character at the end of each line:
» cat -et <file name>
– How do end-of-line markers appear when displayed in a text file
using the cat -et command?
» Unix/Linux/Mac: $ (line feed)
» Windows: ^M$ (carriage return followed by line feed)
– In order to display the file type, language used, and end of line
marker
» file <file name>
» Examples using Unix and Windows (“PC”) versions of the SPICE
leapseconds kernel:
• file naif0010.tls
naif0010.tls: ASCII English text
• file naif0010.tls.pc
naif0010.tls.pc: ASCII English text, with CRLF line terminators

Introduction to Kernels 38
 N IF Some Useful Tools - 2
Navigation and Ancillary Information Facility

• For a Unix or Linux (including Mac) environment

– To convert a Unix/Linux/Mac text kernel to Windows (“DOS”)
style:
» unix2dos <filename>
– To convert a Windows (“DOS”) style text kernel to Unix/Linux/Mac
style:
» dos2unix <filename>
– Unix2dos and dos2unix are often available on Unix-based computers,
and may be easily obtained from the www
– Alternatively, to convert either style text kernel to the other style, use
the SPICE “bingo” program
» The bingo program and User Guide are available only from the
NAIF/Toolkit/Utilities web page:
• http://naif.jpl.nasa.gov/naif/utilities.html

• More information
In Wikipedia, search on “newline” or “unix2dos”

Introduction to Kernels 39
N IF
Navigation and Ancillary Information Facility

“Comments” In SPICE Kernels

Also known as “meta-data”

April 2023
 N IF What are Comments?
Navigation and Ancillary Information Facility

• Comments, also called “meta-data,” are information that

describe the context of kernel data, i.e. “data about data”
• Comments are provided inside kernels as plain text (prose)
• Examples of uses for comments:
– Data descriptions
» “This file contains representations of the trajectories for bodies X, Y
and Z over the interval from launch to landing”
– Data accuracy comments
– Data pedigree
» How and by whom the kernel was created
• The program(s) and/or steps used in creation
• Contact information for user’s questions
– email address
– phone numbers
» Data sources used as inputs when creating the kernel
– Intended kernel usage
– Names of companion files

Comments in SPICE Kernels 2

 N IF Where are Comments Stored?
Navigation and Ancillary Information Facility

• Binary kernels contain a reserved “comment area”

to hold comments

• Text kernels have comments interleaved with the

data
– Comments may be placed at the beginning of the text kernel,
before any data, and …
– Comments may be inserted between blocks of data using
\begintext and \begindata as start and end markers:

\begintext
Some comments
\begindata
Some data

Comments in SPICE Kernels 3

 N IF Adding Comments to Kernels
Navigation and Ancillary Information Facility

• Binary Kernels
– Use the commnt utility program, available in the Toolkit
– Include comment information at the time of kernel creation using SPICE
APIs (subroutines)
• Text Kernels
– Use a text editor
» Begin comment sections with a “\begintext” marker, placed alone on
a line
• (The marker is not needed for comments occurring before any data)
» End comment sections with a “\begindata” marker, placed alone on a
line
• (The marker is not needed if there are no data following the comments)

• Restrictions
– For both binary and text kernels
» Comment line length limit is 255 characters. However, NAIF recommends using
no more than 80 characters per line as this makes your comments far more
readable!
» Use only printing characters (ASCII 32 - 126)
» Manipulating binary kernel comments requires the kernel be in the native binary
format for the machine being used
– For text kernels
» Refer to “Kernel Required Reading” (kernel.req) for details
Comments in SPICE Kernels 4
 N IF Viewing Comments in Kernels
Navigation and Ancillary Information Facility

• Binary kernels:
– Use either the commnt or spacit utility program
» Both are available in all Toolkits

• Text kernels:
– Use any available text file utility, such as:
» more, cat, vi, emacs
» Notepad, TextEdit, BBEdit, Word, etc.

Comments in SPICE Kernels 5

 N IF Viewing Comments in Binary Kernels
Navigation and Ancillary Information Facility

This example shows reading the comments in

an SPK file using the “commnt” utility program
Terminal Window
Prompt> commnt -r de421.bsp | more

...

DE 421 JPL Planetary Ephemeris SPK

==================================

Original file name: de421.bsp

Creation date: Feb. 13, 2008
File created by: Dr. William Folkner (SSD/JPL)
Comments added by: Nat Bachman (NAIF/JPL)

This SPK file was released on February 13, 2008 by the Solar System
Dynamics Group of JPL's Guidance, Navigation, and Control section.

The DE 421 planetary ephemeris is described in JPL IOM 343R-08-002,

dated Feb. 13, 2008. The introduction of that memo states, in part,
that this ephemeris "represents an overall update for all

--More--

Comments in SPICE Kernels 6

 N IF Viewing Comments in Text Kernels
Navigation and Ancillary Information Facility
This example show use of the unix “more” processor to show
some of the comments at the beginning of a text kernel.

Terminal Window
prompt> more naif0008.tls

KPL/LSK

LEAPSECONDS KERNEL FILE

===============================================================

Modifications:
--------------
2005, Aug. 3 NJB Modified file to account for the leapsecond
that will occur on December 31, 2005.

1998, Jun 17 WLT Modified file to account for the leapsecond

that will occur on December 31, 1998.

1997, Feb 22 WLT Modified file to account for the leapsecond

that will occur on June 30, 1997.

…etc.

-More--(19%)
--More--(19%)

Comments in SPICE Kernels 7

N IF
Navigation and Ancillary Information Facility

Using Module Headers

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Module* Header Purpose

• FORTRAN Module Header Locations
• C Module Header Locations
• Icy Module Header Locations
• Mice Module Header Locations
• Examine a Typical Header

* “Module” = API, routine, subroutine, procedure, function

Using Module Headers 2

 N IF Module Header Purpose
Navigation and Ancillary Information Facility

• NAIF uses module “headers” to provide detailed

information describing how to use the module
– In FORTRAN, C and MATLAB Toolkits the “headers” are comment
blocks inserted in the source code
– In IDL Toolkits, where there are (currently) no source code files, the
“headers” exist as independent files

• All Toolkit distributions include hyperlinked HTML

versions of the module headers.
– All but ICY also include plain text versions

• The next charts provide the header contents and

locations

Using Module Headers 3

 N IF Module Header Contents
Navigation and Ancillary Information Facility
- Procedure or subroutine name
- Brief abstract
- Disclaimer (legalese required for JPL code; in Fortran, C, and Matlab)
- Required Reading (names of any related SPICE technical reference documents)
- Keywords (single relevant words; in Fortran and C; not really used)
- Argument type declarations, or Include files
- Brief Input and Output descriptions
- Detailed Input descriptions
- Detailed Output descriptions
- Parameter definitions, if any
- Exceptions (what happens if a problem is detected)
- Descriptions of any files used
- Particulars (details about what the module does, how it works, any limitations)
- Code usage example(s)
- Restrictions in usage of the module
- Literature references
- Author
- Version
- Index entries (brief phrases used to generate entries for the Permuted Index document)
- Revision history (in Fortran)

The source code goes here!

Using Module Headers 4

 N IF Fortran Module Header Locations
Navigation and Ancillary Information Facility

• Plain text versions:

– <path to SPICELIB>/toolkit/src/spicelib/<name.f> or <name>.for
– In most cases there is a single “header” at the top of the source
code. For cases where a FORTRAN module has multiple entry
points, there are additional “headers” at each entry point. For
example:
» “keeper.f” has entries for:
• FURNSH, KTOTAL, KINFO, KDATA, KCLEAR, and UNLOAD

• HTML versions:
– <path to SPICELIB>/toolkit/doc/html/spicelib/index.html

Using Module Headers 5

 N IF C Module Header Locations
Navigation and Ancillary Information Facility

• Plain text versions:

– <path to CSPICE>/cspice/src/cspice/<name>_c.c

• HTML versions:
– <path to CSPICE>/cspice/doc/html/cspice/index.html

Using Module Headers 6

 N IF IDL Module Header Locations
Navigation and Ancillary Information Facility

• Two sets of headers are provided

– Icy headers in HTML format:
» <path to Icy>/icy/doc/html/icy/index.html
– CSPICE headers, in text and HTML formats:
» <path to Icy>/icy/src/cspice/<name>_c.c
» <path to Icy>/icy/doc/html/cspice/index.html

• The information provided in an “Icy” header is

minimal in some cases; the corresponding CSPICE
header provides more detail
– A link to the corresponding CSPICE header is provided in the Icy
header

Using Module Headers 7

 N IF Matlab Module Header Locations
Navigation and Ancillary Information Facility

• Two sets of headers are provided

– Mice headers in HTML format:
» <path to Mice>/mice/doc/html/mice/index.html
» Also available using the Matlab help command, e.g.:
>> help cspice_str2et
– CSPICE headers, in text and HTML formats:
» <path to Mice>/mice/src/cspice/<name>_c.c
» <path to Mice>/mice/doc/html/cspice/index.html

• The information provided in a “Mice” header is

minimal in some cases; the corresponding CSPICE
header provides more detail
– A link to the corresponding CSPICE header is provided in the Mice
header

Using Module Headers 8

 N IF Examine a Typical Header
Navigation and Ancillary Information Facility

• As example, look for and examine the headers for the

modules named spkezr and str2et

FORTRAN C IDL (Icy) MATLAB (Mice)

SPKEZR spkezr_c cspice_spkezr cspice_spkezr

STR2ET str2et_c cspice_str2et cspice_str2et

spkezr is the principal ephemeris access module

str2et is a key time conversion module

Using Module Headers 9

N IF
Navigation and Ancillary Information Facility

Time Conversion and

Time Formats

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Time Systems and Kernels

• Converting Time Strings
• Converting Numeric Times
• Use of Time Format Picture
• Additional Time Conversions
• Principal Time System Interfaces

Time Conversion and Formats 2

 N IF Time Systems and Kernels
Navigation and Ancillary Information Facility

• Time inputs to and outputs from user’s programs are usually

strings representing epochs in these three time systems:
– Ephemeris Time (ET, also referred to as Barycentric Dynamical Time, TDB)
– Coordinated Universal Time (UTC). This is the default for calendar strings.
– Spacecraft Clock (SCLK)
• Time stamps in kernel files, and time inputs to and outputs from
SPICE routines reading kernel data and computing derived
geometry, are double precision numbers representing epochs in
these two time systems:
– Numeric Ephemeris Time (TDB), expressed as ephemeris seconds past J2000
» J2000 = 2000 Jan 1 12:00:00 TDB (<- NOT UTC)

– Encoded Spacecraft Clock, expressed as clock ticks since the clock start
• SPICE provides routines to convert between these string and
numeric representations.
• A time string used as an argument in a SPICE API must be provided
in quotes.
– Fortran, Matlab, IDL and Python: use single quotes
– C and JNI: use double quotes
Time Conversion and Formats 3
 N IF Converting Time Strings (1)
Navigation and Ancillary Information Facility

• UTC, TDB, or TDT (TT) String to numeric Ephemeris Time

– STR2ET ( string, ET )
» Converts virtually any time string format known to the SPICE Time
subsystem, excepting SCLK.
» Examples of acceptable string inputs:
• '1996-12-18T12:28:28'
• '1978/03/12 23:28:59.29'
use
• 'Mar 2, 1993 11:18:17.287 p.m. PDT' ple inputs all y
exam ired b
• '1996-12-18T12:28:28Z' These qu ot e requ and
gle B
the sin IDL, MATLA
, ble
• '1995-008T18:28:12' Fortran PIs. Use dou Is.
A AP
• '1993-321//12:28:28.287' Python or C and JNI
f
quotes
• '2451515.2981 JD'
• 'jd 2451700.05 TDB'
• '1988-08-13, 12:29:48 TDB'
• '1992 June 13, 12:29:48 TDT'
– Requires the LSK kernel
The SPICE Time high-level APIs interpret a calendar, DOY, or Julian
date time string without an explicit time system token, "TDB", "TT",
etc., as UTC.
Time Conversion and Formats 4
 N IF Converting Time Strings (2)
Navigation and Ancillary Information Facility

• Spacecraft Clock String to numeric Ephemeris Time

– SCS2E ( scid, string, ET )
» Converts SCLK strings consistent with SCLK parameters.
» Examples of acceptable clock string inputs:
• '5/65439:18:513' (VGR1)
• '946814430.172' (MRO)
• '1/0344476949-27365' (MSL)
– Requires a SCLK kernel and an LSK kernel

Time Conversion and Formats 5

 N IF Converting Numeric Times (1)
Navigation and Ancillary Information Facility

• Numeric Ephemeris Time to a string, where the format is

Calendar, DOY or Julian Date, and the time system is UTC,
TDB or TDT
– TIMOUT ( et, fmtpic, STRING )
» fmtpic is an output time string format specification, giving the user
great flexibility in setting the appearance of the output time string
and the time system used (UTC, TDB, TDT).
• See the next slide for examples of format pictures to produce a variety of
output time strings
• See the TIMOUT header for complete format picture syntax
• The module TPICTR may be useful in constructing a format picture
specification from a sample time string
– Requires LSK Kernel

Time Conversion and Formats 6

 N IF Converting Numeric Times (2)
Navigation and Ancillary Information Facility

Example Time Strings and the Corresponding Format Pictures

Common Time Strings Format Picture Used (fmtpic)

1999-03-21T12:28:29.702 YYYY-MM-DDTHR:MN:SC.###
1999-283T12:29:33 YYYY-DOYTHR:MN:SC ::RND
1999-01-12, 12:00:01.342 TDB YYYY-MM-DD, HR:MN:SC.### ::TDB TDB
2450297.19942145 JD TDB JULIAND.######## ::TDB JD TDB

Less Common Time Strings Format Picture Used (fmtpic)

465 B.C. Jan 12 03:15:23 p.m. YYYY ERA Mon DD AP:MN:SC ampm
04:28:55 A.M. June 12, 1982 AP:MN:SC AMPM Month DD, YYYY
Thursday November 04, 1999 Weekday Month DD, YYYY
DEC 31, 15:59:60.12 1998 (PST) MON DD, HR:MN:SC.## YYYY (PST)::UTC-8

Time Conversion and Formats 7

 N IF Converting Numeric Times (3)
Navigation and Ancillary Information Facility

• Numeric Ephemeris Time to Spacecraft Clock String

– SCE2S (scid, et, SCLKCH )
» Output SCLK string examples:
• 1/05812:00:001 (Voyager 1 and 2)
• 1/1487147147.203 (Cassini, MRO)
• 1/0101519975.65186 (MEX, VEX, Rosetta)
– Requires a SCLK kernel and an LSK kernel

Time Conversion and Formats 8

 N IF Additional Time Conversions
Navigation and Ancillary Information Facility

• Numeric Ephemeris Time to Local Solar Time String

– ET2LST( et, body, long, type, HR, MN, SC, TIME, AMPM )
– Requires SPK and PCK kernels
» To compute body position relative to the Sun and body rotation.

• Numeric Ephemeris Time to planetocentric longitude of the Sun

(Ls)
– LS = LSPCN (body, et, abcorr )
» While Ls is not a time system, it is frequently used to determine body
season for a given epoch
• LS = 0°, Spring
• LS = 90°, Summer
For the northern hemisphere
• LS = 180°, Autumn
• LS = 270°, Winter
– Requires SPK and PCK kernels

Time Conversion and Formats 9

 N IF Principal Time System Interfaces
Navigation and Ancillary Information Facility
Kernels needed

Local needs lsk

“L-sub-S” Solar
(planetocentric
Time UTC seconds
longitude of the sun) needs sclk
past J2000

Uniform time needs lsk and sclk

systems (TDT,TAI,
JED, JDTDT) LSPCN ET2LST needs pck and spk
DELTET needs no kernels
UNITIM
Time string in
UTC, TDB or TDT
Barycentric SCE2S
Dynamical Time
(TDB or ET)
(Includes lots of SCS2E
formatting flexibility)

SCE2C SCT2E
TIMOUT
ET2UTC
SCDECD
ETCAL
Spacecraft
Encoded
Clock
Spacecraft Clock
(SCLK)
(Ticks)
STR2ET
TDB string in SCENCD
calendar format
Time Conversion and Formats = Time APIs mentioned in this tutorial 10
N IF
Navigation and Ancillary Information Facility

Leapseconds and Spacecraft Clock

Kernels

LSK and SCLK

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Kernels Supporting Time Conversions

– LSK
– SCLK

• Forms of SCLK Time Within SPICE

• Backup

LSK & SCLK 2

 N IF SPICE Time Conversion Kernels
Navigation and Ancillary Information Facility

In most cases one or two kernel files are needed to

perform conversions between supported time systems.

• LSK - The leapseconds kernel is used in

conversions between ephemeris time (ET/TDB)
and Coordinated Universal Time (UTC).

• SCLK - The spacecraft clock kernel is used in

conversions between spacecraft clock time
(SCLK) and ephemeris time (ET/TDB).
– It’s possible there could be two or more clocks associated with
a given spacecraft.

Ephemeris Time, ET and Barycentric Dynamical Time, TDB, are the same
LSK & SCLK 3
 N IF The Leapseconds Kernel (LSK)
Navigation and Ancillary Information Facility

The leapseconds kernel contains a tabulation of all the

leapseconds that have occurred, plus additional terms.
• Used in ET UTC and in ET SCLK conversions.
– Subroutines using LSK: STR2ET, TIMOUT, ET2UTC, etc.
– Utility programs using LSK: spkmerge, chronos, spacit, etc.
• Use FURNSH to load it.
• NAIF updates the LSK when a new leap second is
announced by the International Earth Rotation
Service (IERS).
– The latest LSK file is always available from the NAIF server.
» The latest is LSK always the best one to use.
– Announcement of each new LSK is typically made months in
advance using the “spice_announce” system.
» http://naif.jpl.nasa.gov/mailman/listinfo/spice_announce
– New LSKs take effect ONLY on January 1st and July 1st
LSK & SCLK 4
 N IF LSK File Example
Navigation and Ancillary Information Facility

KPL/LSK

. . . <comments> . . .

\begindata

DELTET/DELTA_T_A = 32.184
DELTET/K = 1.657D-3
DELTET/EB = 1.671D-2
DELTET/M = ( 6.239996D0 1.99096871D-7 )

DELTET/DELTA_AT = ( 10, @1972-JAN-1

11, @1972-JUL-1
12, @1973-JAN-1
13, @1974-JAN-1
14, @1975-JAN-1

. . . <more leapsecond records> . . .

35, @2012-JUL-1
36, @2015-JUL-1
37, @2017-JAN-1 )

\begintext

LSK & SCLK 5

 N IF Out of Date LSKs
Navigation and Ancillary Information Facility

• An out-of-date leapseconds kernel can be used

successfully for conversions that occur at epochs
prior to the epoch of the first missing leapsecond.
– Any conversions of epochs occurring after the epoch of a
missing leapsecond will introduce inaccuracies in multiples of
one second per missed leapsecond.

• Using the latest leapseconds kernel to perform

conversions at epochs more than six months
ahead of the last leapsecond listed may result in
an error if, later on, a new leapsecond is declared
for a time prior to the epochs you processed.

LSK & SCLK 6

 N IF The Spacecraft Clock Kernel (SCLK)
Navigation and Ancillary Information Facility

• The spacecraft clock kernel is required by Toolkit utilities

and routines that utilize SCLK time.
– For example, the SPICE CK subsystem makes heavy use of spacecraft
clock time.

• Use FURNSH to load it.

• Ensure you have the correct version of the SCLK file for
your spacecraft since this kernel may be updated rather
frequently.
– SCLK files are usually maintained on a flight project server.
» For JPL operated missions they can always be found on the NAIF
server as well.
– When using a CK, “correct SCLK” means compatible with that CK.
» For reconstructed CKs, this is most likely the latest version of the
SCLK.
» For “predict” CKs, this is probably the SCLK kernel used when the
CK was produced.

LSK & SCLK 7

 N IF SCLK File Example
Navigation and Ancillary Information Facility
KPL/SCLK

. . . <comments> . . .

\begindata

SCLK_KERNEL_ID = ( @2009-12-07/18:03:04.00 )
SCLK_DATA_TYPE_74 = ( 1 )
SCLK01_TIME_SYSTEM_74 = ( 2 )
SCLK01_N_FIELDS_74 = ( 2 )
SCLK01_MODULI_74 = ( 4294967296 256 )
SCLK01_OFFSETS_74 = ( 0 0 )
SCLK01_OUTPUT_DELIM_74 = ( 1 )

SCLK_PARTITION_START_74 = ( 0.0000000000000E+00
. . . <more partition start records> . . .
2.4179319500800E+11 )

SCLK_PARTITION_END_74 = ( 2.0692822929300E+11
. . . <more partition end records> . . .
1.0995116277750E+12 )

SCLK01_COEFFICIENTS_74 = (
0.0000000000000E+00 -6.3119514881600E+08 1.0000000000000E+00
1.2098765056000E+10 -5.8393434781600E+08 1.0000000000000E+00
. . . <more coefficient records> . . .
2.4179319365000E+11 3.1330950356800E+08 9.9999997500000E-01 )

\begintext
LSK & SCLK 8
 N IF Forms of SCLK Time Within SPICE
Navigation and Ancillary Information Facility

• SCLK time in SPICE is represented in two

different ways:
– a character string
– a double precision number called “ticks”

• A SCLK character string is composed of one or

more cascading integer numbers – similar to a
digital clock.
– This form is derived from clock values represented by sets of
bits or bytes found in downlinked telemetry.

• A SCLK value encoded as a double precision

number (called “ticks”) is used within SPICE
because it’s easy to convert this to other time
systems, such as ephemeris time.
LSK & SCLK 9
 N IF Sample SCLK String
Navigation and Ancillary Information Facility

The Cassini orbiter SCLK time string consists of

three fields separated by delimiters.
Clock Field Delimiter *
Partition (not a decimal point)
Delimiter 1/1609504792.123

Partition: Accounts for

clock resets or counter Least Significant Clock Field:
roll-over. Ranges from 0 to 255. Nominally
1/256th of a second increment.

Most Significant Clock Field:

Ranges from 0 to 4294967295 (232-1). Nominally * Several SCLK delimiter
1 second increment. characters are available in
SPICE. See “SCLK Required
Reading” for details.
LSK & SCLK 10
 N IF What is a Partition?
Navigation and Ancillary Information Facility

1/1609504792.123

The portion of the SCLK string circled above

indicates the partition to which the remaining
portion of the string is related.
• A partition is a NAIF-created construct to handle spacecraft
clock rollovers or resets.
• SCLK strings not having a partition number are treated as
belonging to the first partition in which they occur.

LSK & SCLK 11

 N IF Constructing a SCLK String - 1
Navigation and Ancillary Information Facility

Usually SCLK tags in raw telemetry are represented by sets of

bits or bytes. Such tags must be converted to SCLK strings
used in SPICE. This is an example of how it is done for the
sample CASSINI SCLK string from previous slides.
• Start with a 5-byte CASSINI TLM SCLK 5F EF 18 18 7B
• The first four bytes are an unsigned
integer representing seconds
• The last byte is an unsigned byte
representing fractional seconds (as a
count of 1/256 second ticks)
• Convert integer seconds and integer
fractional second ticks to two strings '1609504792' '123'
• Concatenate strings together using a
recognized delimiter (‘.’, ‘:’, etc) '1609504792.123'
• Add the partition number and delimiter
• Optional; for most modern missions it '1/1609504792.123'
may be omitted (not so for Chandrayaan-
1 and MESSENGER)

LSK & SCLK 12

 N IF Constructing a SCLK String - 2
Navigation and Ancillary Information Facility

On modern missions SCLK tags in raw telemetry are also

often represented as DP numbers. Such tags must also be
converted to SCLK strings used in SPICE. This is an example
of how it is done for the same sample CASSINI SCLK string.
• Start with a DP number CASSINI TLM SCLK 1609504792.480469

• Convert decimal fraction to integer count of .480469 * 256

ticks = 123

• Convert integer seconds and integer '1609504792' '123'

fractional second ticks to two strings
• Concatenate strings together using a '1609504792.123'
recognized delimiter (‘.’, ‘:’, etc)
• Add the partition number and delimiter '1/1609504792.123'
• Optional; for most modern missions it
may be omitted (not so for Chandrayaan-
1 and MESSENGER)
LSK & SCLK 13
 N IF Encoded SCLK (Ticks)
Navigation and Ancillary Information Facility

The representation of SCLK time in the SPICE

system is a double precision encoding of a SCLK
string.
• Encoded spacecraft clock values represent “ticks
since spacecraft clock start.”
– The time corresponding to tick “0” is mission dependent and
does not necessarily relate to launch time. It is often an
arbitrary epoch occurring before launch.
• A tick is the smallest increment of time that a
spacecraft clock measures.
– For example, in the case of the Cassini orbiter this is nominally
1/256th of a second.
• Encoded SCLK increases continuously
independent of leapseconds, clock resets, and
clock rollovers.
LSK & SCLK 14
 N IF Additional Info on LSK and SCLK
Navigation and Ancillary Information Facility

• For more information about LSK, SCLK, and time

conversions, look at the following documents
– Time Required Reading
– SCLK Required Reading
– Time tutorial (at the end it has a nice graphic depicting time APIs)
– Most Used SPICELIB Routines
– headers for the routines mentioned in this tutorial
– CHRONOS User’s Guide
– Porting_kernels tutorial

• Related documents
– Kernel Required Reading
– CK Required Reading

LSK & SCLK 15

 N IF SCLK Interface Routines
Navigation and Ancillary Information Facility

Convert SCLK times using the following routines

SCS2E (SC, SCLKCH, ET) (SCLK String ET)

SCE2S (SC, ET, SCLKCH) (ET SCLK String)

SCT2E (SC, SCLKDP, ET) (Encoded SCLK ET)

SCE2C1 (SC, ET, SCLKDP) (ET Continuous Encoded SCLK)
SCE2T (SC, ET, SCLKDP) (ET Discrete Encoded SCLK)

SCENCD(SC, SCLKCH, SCLKDP) (Encode SCLK string to ticks)

SCDECD(SC, SCLKDP, SCLKCH) (Decode SCLK ticks to string)

1 Use SCE2C (not SCE2T) for C-kernel data access.

LSK & SCLK 16

 N IF Backup
Navigation and Ancillary Information Facility

• Examples of SCLK strings

• Dates of "recent" leapseconds

LSK & SCLK 17

 N IF Sample Galileo SCLK String
Navigation and Ancillary Information Facility

The Galileo spacecraft SCLK time string consists of

five fields separated by delimiters.
Clock Field Delimiters
Partition
Delimiter 1/16777214:90:9:7
Least Significant Clock Field:
Ranges from 0 to 7. Nominally
1/120th of a second.
Partition: Accounts for
clock resets or counter roll-
over. Intermediate Clock Field:
Ranges from 0 to 9. Nominally
Most Significant Clock Field: 1/15th of a second.
Ranges from 0 to 16777214.
Nominally 60 2/3rd second Intermediate Clock Field:
increment. Ranges from 0 to 90.
Nominally 2/3rd of a second.

LSK & SCLK 18

 N IF More Sample SCLK Strings
Navigation and Ancillary Information Facility

The following are examples of SCLK

strings* from missions using SPICE.

• Cassini • MPF • Viking 1&2

1/1334314108.134 1/559627908.058 1/32233616

• DS1 • Mariner 9 • Voyager 1&2

1/67532406.010 1/11542909 1/05812:00:001

• Galileo • Mars Odyssey • Mars Express

1/16777214:90:9:7 1/687231994.091 1/0090979196.29713

• Genesis • NEAR • Venus Express

1/666230496.204 1/40409721942 1/0033264000.50826

• MGS • Stardust • Rosetta

1/655931592.103 1/697451990.042 1/0101519975.65186

* When clock strings are used as arguments in modules they must be contained in quotes:
- Single quotes for Fortran
- Double quotes for C
- Single quotes for IDL and MATLAB

LSK & SCLK 19

 N IF Dates of New Leapseconds+
Navigation and Ancillary Information Facility

1972-JAN-1
1972-JUL-1
1973-JAN-1
1974-JAN-1
1975-JAN-1 • New leapseconds become
1976-JAN-1
1977-JAN-1
effective only on January 1st or
1978-JAN-1
1979-JAN-1
July 1st.
1980-JAN-1
1981-JUL-1 • NAIF announces every new
1982-JUL-1
1983-JUL-1 leapsecond using the
1985-JUL-1
1988-JAN-1
"spice_announce" Mailman
1990-JAN-1 system
1991-JAN-1
1992-JUL-1
1993-JUL-1
• NAIF provides a new
1994-JUL-1
1996-JAN-1
leapseconds kernels* (LSK)
1997-JUL-1
1999-JAN-1
several months before the new
2006-JAN-1 leapsecond becomes effective
2009-JAN-1
2012-JUL-1
2015-JUL-1 + Current as of April 2023
2017-JAN-1
* NAIF provides both Linux/OSX and Windows versions of the LSK
LSK & SCLK 20
N IF
Navigation and Ancillary Information Facility

An Overview of
Reference Frames
and
Coordinate Systems
in the SPICE Context

April 2023
 N IF Purpose of this Tutorial
Navigation and Ancillary Information Facility

• This tutorial provides an overview of reference

frames and coordinate systems.
– It contains conventions specific to SPICE.

• Details about the SPICE Frames subsystem are

found in other tutorials and one document:
– FK (tutorial)
– Using Frames (tutorial)
– Dynamic Frames (advanced tutorial)
– Frames Required Reading (technical reference)

• Details about SPICE coordinate systems are

found in API module headers for coordinate
conversion routines.
Frames and Coordinate Systems 2
 N IF A Challenge
Navigation and Ancillary Information Facility

• Next to “time,” the topics of reference frames and

coordinate systems present some of the largest
challenges to documenting and understanding
observation geometry. Contributing factors are …
– differences in definitions, lack of concise definitions, and
special cases
– evolution of the frames subsystem within SPICE
– the substantial frames management capabilities within SPICE

• NAIF hopes this tutorial will provide some clarity

on these subjects within the SPICE context.
– Definitions and terminology used herein may not be consistent
with those found elsewhere.

Frames and Coordinate Systems 3

 N IF SPICE Definitions
Navigation and Ancillary Information Facility

• The definitions below are used within SPICE.

• A reference frame (or simply “frame”) is specified by an

ordered set of three mutually orthogonal, possibly time
dependent, unit-length direction vectors.
– A reference frame has an associated center.
– In some documentation external to SPICE, this is called a “coordinate
frame.”

• A coordinate system specifies a mechanism for locating points

within a reference frame.

• When producing or using state (position and velocity) or

orientation (pointing) data, one needs to understand both the
reference frame and the coordinate system being used.

Frames and Coordinate Systems 4

N IF
Navigation and Ancillary Information Facility

Reference Frames
 N IF Reference Frame Conventions
Navigation and Ancillary Information Facility

• All reference frames used within SPICE are right

handed: this means X cross Y = Z
Z

Frames and Coordinate Systems 6

 N IF Reference Frame Center
Navigation and Ancillary Information Facility

• A reference frame’s center must be a SPICE ephemeris object

whose location is coincident with the origin (0, 0, 0) of the
frame.
– The center of any inertial frame is ALWAYS the solar system barycenter.*
– The center of a body-fixed frame is the center of the body.
» “Body” means a natural body: sun, planet, satellite, comet, asteroid.
» The location of the “body” center is specified using an SPK file.
– The center of a topocentric, spacecraft or instrument frame is also an
object for which the location is specified by an SPK file.

• A frame’s center may play a role in specification of states.

– The location of the origin cancels out when doing vector subtraction, but
the center is used in computing light time to the center of any non-inertial
frame being used

*True even for inertial frames associated with

accelerated bodies, such as the MARSIAU frame.
Frames and Coordinate Systems 7
 N IF Types of Reference Frames - 1
Navigation and Ancillary Information Facility

• Inertial
– Non-rotating with respect to stars
– Non-accelerating origin
» Velocity is typically non-zero, but acceleration is negligible
– Examples:
» J2000 (also known as EME 2000, and is generally used in
SPICE to refer to the ICRF)
» ECLIPJ2000

Frames and Coordinate Systems 8

 N IF Types of Reference Frames - 2
Navigation and Ancillary Information Facility

• Non-Inertial
– Accelerating, including by rotation
– Examples
» Body-fixed
• Associated with a natural body (e.g. planets, satellites)
» Topocentric
• Associated with an object on or near the surface of a natural
body (e.g. DSN station, rover)
» Spacecraft
• Associated with the main spacecraft structure (the “bus”)
» Instrument
• One or more frames are usually associated with each instrument
• Also applicable to a spacecraft antenna, solar array, etc.
» Dynamic
• A special family of frames unique to SPICE
• These have time-dependent orientation
– But this category does not include frames for which the orientation is
provided using a C-kernel (CK) or a PC-kernel (PCK)

CK ≈ spacecraft orientation; PCK ≈ natural body orientation

Frames and Coordinate Systems 9
 N IF The J2000 Inertial Frame
Navigation and Ancillary Information Facility

• The J2000* (aka EME2000) frame definition is based

on the earth’s equator and equinox, determined
from observations of planetary motions, plus other
data. Z is normal to the mean equator of date at epoch J2000
ZJ2000 TDB, which is approximately Earth’s spin axis orientation
at that epoch. (J2000 TDB is
2000 JAN 01 12:00:00 TDB, or JD 2451545.0 TDB).

Equatorial plane
Plane normal to the earth’s
spin axis, Z
Ecliptic plane
Plane defined by movement
of the earth around the sun

eg
.4 d
~23 YJ2000
Y = Z cross X
Intersection of
XJ2000 equatorial and
ecliptic planes,
called vernal
equinox

*Caution: The name “J2000” is also used to refer to the zero epoch of the ephemeris time system (ET, also known as TDB).

Fundamental Concepts 10
 N IF The ICRF Inertial Frame
Navigation and Ancillary Information Facility

• The ICRF* frame is defined by the adopted

locations of 295 extragalactic radio sources.
Z

Solar System Barycenter

ICRF = International Celestial Reference Frame

Frames and Coordinate Systems The ICRF is managed by the International Earth Rotation Service (IERS) 11
 N IF J2000 versus ICRF
Navigation and Ancillary Information Facility

• The realization of ICRF was made to coincide almost

exactly with the J2000 frame.
– The difference is very small–a rotation of less than 0.1 arc second.
– The reference frame name "J2000" is generally used in SPICE as a
label for the ICRF frame.
» In reality, any SPICE data said to be referenced to the J2000
frame are actually referenced to the ICRF frame.
• Except for attitude derived from the 1976 IAU Earth precession model and
1980 IAU Earth nutation and mean obliquity of date models
» For historical and backwards compatibility reasons, only the
name “J2000” is recognized by SPICE software as a frame
name–not “ICRF.”
– No transformation is required to convert SPICE state vectors or
orientation data from the J2000 frame to the ICRF.

Frames and Coordinate Systems 12

 N IF Body-fixed Frames
Navigation and Ancillary Information Facility

• Body-fixed frames are tied to a named

Z
body and rotate with it
– Specifications for the most common body-fixed
frames, those for the sun, the planets, many
satellites, and a few asteroids and comets, are
hard-coded in SPICE software
•
» Frame name style is “IAU_body name”
• Examples: IAU_MARS, IAU_SATURN
» To see all such names, see: •
•
• Frames Required Reading document, or
• Latest generic PCK file
– The rotation state (the orientation at time !) is Y
usually determined using a SPICE text PCK Body-fixed
containing data published by the IAU
X
» The earth and moon are special cases!
• IAU_EARTH and IAU_MOON both exist but
generally should NOT be used
• See the SPICE tutorial named “lunar-earth_pck-
fk” for the best frames to be used for those
bodies
– On very rare occasions a CK is used to provide a
body’s rotation state

Frames and Coordinate Systems 13

 N IF A Caution for Mars
Navigation and Ancillary Information Facility

• The body-fixed frame for Mars is named IAU_MARS

– This follows the SPICE naming standard for such frames

• However, there also exists in SPICE an inertial

frame associated with Mars, named “MARSIAU”
– This frame was defined 20 years ago based on old Mars rotation
constants, for use by the Mars Observer and Mars Global
Surveyor projects
– This frame has NO relationship to the similarly sounding
IAU_MARS frame, other than that they both relate to Mars

Frames and Coordinate Systems 14

 N IF Spacecraft and Instrument Frames
Navigation and Ancillary Information Facility

• Defined for spacecraft, and items attached to a

spacecraft, such as antennas, solar arrays, scan
platforms, instruments and moving parts of an
instrument (e.g. a scanning mirror)

• For those frames that are time varying (“moving”),

the frame name is usually defined in an FK and
the frame orientation data are usually provided by
a CK

• For those frames that are not moving (what we

call “fixed offset”) both the frame name and the
actual data defining the fixed orientation of the
frame are provided in an FK
Frames and Coordinate Systems 15
 Some Examples of
N IF Spacecraft and “Instrument” Frames
Navigation and Ancillary Information Facility
Position Vectors Frame Orientations
Spacecraft position relative Spacecraft frame
to planet center orientation relative to
(“spacecraft” SPK file) inertial frame
(“spacecraft” CK file)

Camera frame orientation

High gain antenna gimbal relative to spacecraft frame
position relative to (“mission” FK file)
spacecraft
(“structures” SPK file) XSC
YC High gain antenna frame
XA YSC ZSC orientation relative to high
ZA ZC gain antenna gimbal frame
High gain antenna phase (“mission” FK file)
center location relative to XC
high gain antenna gimbal YA
YSG
(“structures” SPK file) XAG Solar array gimbal frame
YAG ZSG
XSG orientation relative to
ZAG spacecraft frame
(“solar array” CK file)

Solar array gimbal position

relative to spacecraft center High gain antenna gimbal
(“structures” SPK file) frame orientation relative to
XM spacecraft frame
(“antenna” CK file)
YM

Magnetometer position ZM Magnetometer frame

relative to solar array orientation relative to solar
gimbal array gimbal frame
(“structures” SPK file) (“mission” FK file)
Frames and Coordinate Systems 16
 N IF Topocentric Frames
Navigation and Ancillary Information Facility

• Topocentric frames are

located at or near to a X points North
body's surface
• One axis is normal to a Y points West
reference spheroid, or
parallel to the gravity
gradient* Z points “up”
•
• Examples: frames defined
for telecommunications
stations, or for landers or
rovers

The graphic illustrates one example of a

topocentric frame. There is not a
standard definition–for example, the z-
axis could point down, the x-axis North,
and the y-axis East. *SPICE tools always have the “up” or “down” axis
being normal to the spheroid. But one could use
external data to determine the local gravity
Frames and Coordinate Systems gradient and construct a frame based on that. 17
 N IF Dynamic Frames
Navigation and Ancillary Information Facility

• In a dynamic frame the orientation changes with time

– Families: Two-vector, Euler, Of-date, and Product (refer to Dynamic Frames
tutorial)
– This category excludes frames for which the orientation is determined by a
PCK or CK
– Example of a two-vector dynamic frame: Geocentric Solar Ecliptic (GSE),
using instantaneous orbital angular velocity
» X = earth – sun vector
Z
» Y = component of the sun’s velocity perpendicular to X
» Z = X cross Y

– The GSE frame also

can be defined using
the mean ecliptic of
date. X Y

Ecliptic Plane
Vsun relative to earth
Y = component of Vsun perpendicular to X

Frames and Coordinate Systems 18

N IF
Navigation and Ancillary Information Facility

Coordinate Systems
 N IF SPICE Coordinate Systems
Navigation and Ancillary Information Facility

• A coordinate system specifies the method used to

locate a point within a particular reference frame.

Two examples of coordinate systems used to locate point “P”

Rectangular or Cartesian coordinates: Spherical coordinates:

X, Y, Z !, ", #

Frames and Coordinate Systems 20

 N IF Specifying Positions
Navigation and Ancillary Information Facility

Common Style SPICE Style

•
“Observer” is an Ephemeris Object
Point of

• interest
• “Target” is an Ephemeris Object

“Center” is an
Center Ephemeris Object •

Frames and Coordinate Systems 21

 N IF Many Coordinate Systems Used
Navigation and Ancillary Information Facility

• In the Planetary Science discipline there are a

number of coordinate systems in use, just as
there are quite a few reference frames in use.

• Some of these coordinate systems have well

accepted standard definitions, while others are
anything but standard.
– This means data producers and especially data users need to
pay close attention to what they are doing!

Frames and Coordinate Systems 22

 N IF Planetocentric Coordinate System
Navigation and Ancillary Information Facility
• For planets and their satellites the +Z
axis (+90 latitude) always points to the
north side of the invariable plane (the
plane whose normal vector is the
angular momentum vector of the solar Z
system)
– Planetocentric longitude increases positively
eastward (-180 to +180)
– Planetocentric latitude increases positively
northward (-90 to +90) P

• Dwarf planets*, asteroids and comets

spin in the right hand sense about their
“positive pole.”
– What the IAU now calls the “positive pole” is still Y
referred to as the “north pole” in SPICE
documentation. X
– The “positive pole” may point above or below the
invariable plane of the solar system (see above).
– This revision by the IAU Working Group (2006)
inverts what had been the direction of the north pole
for Pluto, Charon and Ida.
• Toolkit planetocentric APIs:
– LATREC, RECLAT, DRDLAT, DLATDR, XFMSTA
Frames and Coordinate Systems
*The dwarf planets are: Ceres, Eris, Haumea, Makemake, Pluto
23
 N IF Planetodetic Coordinate System
Navigation and Ancillary Information Facility

• Planetodetic longitude is the

same as planetocentric Z

longitude
– Increases positively eastward (-180 to +180)

• Planetodetic latitude P

– Tied to a reference ellipsoid

– For a point, P, on a reference ellipsoid, the
angle measured from the X-Y plane to the
surface normal at the point of interest. For Y

points not on the ellipsoid, equals latitude at

the nearest point on the reference ellipsoid X

– Increases positively northward (-90 to +90)

• Toolkit planetodetic APIs are:
– GEOREC, RECGEO, DRDGEO, DGEODR,
XFMSTA

Frames and Coordinate Systems 24

 N IF Planetographic Coordinate System
Navigation and Ancillary Information Facility

• For planet and satellite planetographic

coordinate systems:
– Planetographic longitude is usually defined such that the
sub-observer longitude increases with time as seen by a
distant, fixed observer (0 to 360) Z

– The earth, moon and sun are exceptions; planetographic

Spin
longitude is positive east by default (0 to 360) direction
– Planetographic latitude is planetodetic latitude (-90 to +90)
– Toolkit planetographic APIs are: P
» PGRREC, RECPGR, DRDPGR, DPGRDR, XFMSTA

• For dwarf planets, asteroids and comets:

– There are multiple, inconsistent standards! (USNO, IAU, Y
PDS)
– NAIF strongly suggests you use only planetocentric or X
planetodetic coordinates for these objects

Distant Observer
Frames and Coordinate Systems *The dwarf planets are: Ceres, Eris, Haumea, Makemake, Pluto 25
 N IF Spherical Coordinates
Navigation and Ancillary Information Facility

• Longitude:
- angle from +X axis to projection of
Position Vector
position vector on X-Y plane of an object of
- increases in counter-clockwise
direction
Z interest
- see the API header for
restrictions on ranges

Colatitude
• Colatitude:
- Angle between +Z axis and Y
position vector (0 to 180)
- Other names used elsewhere are
zenith angle, inclination angle and
polar angle.

Longitude
• Toolkit spherical APIs :
– SPHREC, RECSPH,
DRDSPH, DSPHDR, XFMSTA X

Frames and Coordinate Systems 26

 An Example of
N IF Azimuth-Elevation Coordinates
Navigation and Ancillary Information Facility

• Azimuth: Position Vector

- Angle from +X axis to projection
of position vector on x-y plane,
of an object of
measured in clockwise or interest
counterclockwise direction (0 to
Z
360)
- In this example azimuth
increases in clockwise direction

• Elevation:
- Angle between position
vector and x-y plane, measured Y
positive towards +Z or -Z (-90 to
+90)
- In this example, elevation is
positive towards +Z.
Elevation

• Toolkit Azimuth-Elevation
APIs : Azimuth X
– AZLREC, RECAZL, DRDAZL,
DAZLDR, AZLCPO
– These APIs allow users to
indicate directions of increasing
azimuth and elevation
Frames and Coordinate Systems 27
 Summary of SPICE
N IF Coordinate Transformation APIs
Navigation and Ancillary Information Facility

Coordinate Systems APIs for Position APIs for Velocity Notes

Transformation Transformation
Latitudinal to/from LATREC DRDLAT More commonly called Planetocentric.

Rectangular RECLAT DLATDR

R.A. & Dec. to/from RADREC DRDLAT Same as for latitudinal except for range
of LON and RA when converting
Rectangular RECRAD DLATDR rectangular to angular.
LON: -Pi to +Pi
RA: 0 to 2 Pi

Planetographic to/from PGRREC DRDPGR Best restricted to planets, satellites and

the sun. Requires a text PCK to be
Rectangular RECPGR DPGRDR loaded to determine body spin direction.

Geodetic to/from GEOREC DRDGEO Applicable to bodies with equal

equatorial radii.
Rectangular RECGEO DGEODR
Cylindrical to/from CYLREC DRDCYL
Rectangular RECCYL DCYLDR
Spherical to/from SPHREC DRDSPH Shape must be a true sphere.

Rectangular RECSPH DSPHDR

AZ-EL to/from AZLREC DRDAZL AZ-EL measurement directions are
specified on the input.
Rectangular RECAZL DAZLDR

See also the next page re XFMSTA

Frames and Coordinate Systems 28
 Examples of Velocity
N IF Coordinate Transformations
Navigation and Ancillary Information Facility
This example is for rectangular to spherical
rtran s
Fo mple
• Using full state vector transformation API exa
CALL SPKEZR ( TARG, ET, REF, CORR, OBS, STATE, LT )
CALL XFMSTA ( STATE, 'RECTANGULAR', 'SPHERICAL', ' ', OUTSTATE )

• Using velocity-only (Jacobian) APIs

– Transform velocities from rectangular to spherical coordinates using the SPICE Jacobian
matrix routines. The SPICE calls that implement this computation are:
CALL SPKEZR ( TARG, ET, REF, CORR, OBS, STATE, LT )
CALL DSPHDR ( STATE(1), STATE(2), STATE(3), JACOBI )
CALL MXV ( JACOBI, STATE(4), SPHVEL )
– After these calls, the vector SPHVEL contains the velocity in spherical coordinates:
specifically, the derivatives
( d (r) / dt, d (colatitude) / dt, d (longitude) /dt )
– Caution: coordinate transformations often have singularities, so derivatives may not exist
everywhere.
» Exceptions are described in the headers of the SPICE Jacobian matrix
routines.
» SPICE Jacobian matrix routines signal errors if asked to perform an invalid
computation.
• Note: Using XFMSTA for velocity transformations is slower than
using the Jacobian API

Frames and Coordinate Systems 29

N IF
Navigation and Ancillary Information Facility

Ephemeris Subsystem
SPK
Focused on reading SPK files

April 2023
 N IF First… clear your mind!
Navigation and Ancillary Information Facility

• SPK is probably unlike any previous ephemeris or

trajectory representation you’ve used or heard
about.
• We think you’ll find it to be more capable than
other ephemeris system architectures.
– As such, it’s also a bit more complicated to grasp.

• Don’t panic! Shortly you’ll be reading SPK files

like a pro.

SPK Subsystem 2
 N IF
Navigation and Ancillary Information Facility

Overview of
SPICE Ephemeris Data

SPK Subsystem 3
 N IF A Picture is worth …
Navigation and Ancillary Information Facility

• We’ll start with a mostly pictorial view of

ephemeris data and SPK files, just to ease you
into this topic.

SPK Subsystem 4
 N IF SPICE Ephemeris Data
Navigation and Ancillary Information Facility

• An SPK file contains ephemeris (trajectory) data for

“ephemeris objects.”
– “Ephemeris” means position and velocity as a function of time
» Position + velocity is often referred to as “state”

• “Ephemeris objects” are spacecraft, planets, satellites, comets

and asteroids.
– But the following are also ephemeris objects:
» the center of mass of our solar system (solar system barycenter)
» the center of mass of a planet/satellite system (planet barycenter)
» a rover on the surface of a body
» a camera on top of a mast on a lander
» a transmitter cone on a spacecraft
» a deep space communications antenna on the earth

SPK Subsystem 5
 N IF Examples of SPICE Ephemeris Objects
Navigation and Ancillary Information Facility

Asteroid

Comet

The head and the tail of Antenna

every blue arrow are located feed cone
Solar
at “ephemeris objects.” system
Sun • barycenter*

Spacecraft

Earth

.... Lander or
rover
*A barycenter is the center •
of mass of a system of
Communications
•
bodies, such as Saturn
plus all of Saturn's Station
satellites, or, the sun and Satellite
all the planets, satellites,
comets and asteroids in Planet's
the solar system. Planetary mass
system center
SPK Subsystem barycenter* 6
 N IF Imagine Some Ephemeris Data
Navigation and Ancillary Information Facility

epoch_1, x1, y1, z1, vx1, vy1, vz1

epoch_2, x2, y2, z2, vx2, vy2, vz2
epoch_3, x3, y3, z3, vx3, vy3, vz3 Perhaps this is an ASCII table or an
epoch_4, x4, y4, z4, vx4, vy4, vz4 Excel spreadsheet containing rows of
.................. etc. ................... time-tagged Cartesian state vectors.
.................. etc. ...................
epoch_n, xn, yn, zn, vxn, vyn, vzn “epoch” = time

It may not be written inside the table or spreadsheet, but

perhaps an interface agreement somehow tells you:
– what object this ephemeris is for
– what is the name of the reference frame in which the data are given
– what is the center of motion of the object
– what time system is being used for the epochs
– what are the start and stop times of the file
» meaning, what are “epoch_1” and “epoch_n”

SPK Subsystem 7
 N IF Imagine a Simple Ephemeris File
Navigation and Ancillary Information Facility

epoch_1, x1, y1, z1, vx1, vy1, vz1

epoch_2, x2, y2, z2, vx2, vy2, vz2
epoch_3, x3, y3, z3, vx3, vy3, vz3
epoch_4, x4, y4, z4, vx4, vy4, vz4 We’ll represent that simple ephemeris
.................. etc. ................... data shown on the previous page as a
.................. etc. ................... “block” like this.
epoch_n, xn, yn, zn, vxn, vyn, vzn

SPK Subsystem 8
 N IF Imagine a Simple Ephemeris File
Navigation and Ancillary Information Facility

epoch_1, x1, y1, z1, vx1, vy1, vz1

epoch_2, x2, y2, z2, vx2, vy2, vz2
epoch_3, x3, y3, z3, vx3, vy3, vz3
epoch_4, x4, y4, z4, vx4, vy4, vz4 We’ll represent that simple ephemeris file
.................. etc. ................... as a “block” like this.
.................. etc. ...................
epoch_n, xn, yn, zn, vxn, vyn, vzn This becomes the basis of
a “segment” in an SPK file.

SPK Subsystem 9
 N IF An SPK “Segment”
Navigation and Ancillary Information Facility

Target, Ref Frame ID, Center of Motion, Tstart, Tstop

epoch_1, x1, y1, z1, vx1, vy1, vz1

epoch_2, x2, y2, z2, vx2, vy2, vz2
epoch_3, x3, y3, z3, vx3, vy3, vz3 One segment
epoch_4, x4, y4, z4, vx4, vy4, vz4
.................. etc. ...................
.................. etc. ...................
epoch_n, xn, yn, zn, vxn, vyn, vzn

We insert some meta-data (a.k.a segment descriptor) into the segment:

– what is the object this ephemeris is for – SPICE calls this the “target”
– what is the ID of the reference frame in which the data are given
– what is the center of motion for the target
– the start and stop times of the file, Tstart and Tstop
» meaning, what are “epoch_1” and “epoch_n”

SPK Subsystem 10
 N IF A Simple SPK File
Navigation and Ancillary Information Facility

Some other stuff

Target, Ref Frame ID, Center of Motion, Tstart, Tstop

epoch_1, x1, y1, z1, vx1, vy1, vz1

epoch_2, x2, y2, z2, vx2, vy2, vz2
epoch_3, x3, y3, z3, vx3, vy3, vz3 One segment
epoch_4, x4, y4, z4, vx4, vy4, vz4
.................. etc. ...................
.................. etc. ...................
epoch_n, xn, yn, zn, vxn, vyn, vzn

• This very simple SPK file is made up of a single segment

containing ephemeris data:
– for a single object (perhaps a spacecraft, an asteroid, or …whatever),
– given in a single reference frame,
– having a single center of motion,
– with data spanning from Tstart to Tstop
SPK Subsystem 11
 N IF A More Substantial SPK File
Navigation and Ancillary Information Facility

Some other stuff

Target, Ref Frame ID, Center of Motion, T1, T2

epoch-1, x1, y1, z1, vx1, vy1, vz1

Target, Ref Frame ID, Center of Motion, T3, T4
epoch-2, x2, y2, z2, vx2, vy2, vz2
epoch-3, x3, y3, z3, vx3, vy3, vz3
epoch-1,
epoch-4, x4, x1, y1,
z4, z1,
y4,Frame vx4, vx1,
vy4,ofvy1,
vz4 vz1
epoch-2, x2, y2, z2, vx2, vy2, vz2T5, T6
Target, Ref ID, Center Motion,
.................. etc. ...................
epoch-3, x3, y3, z3, vx3, vy3, vz3
.................. etc. ...................
epoch_1, x1, z4,y1, vx4,
z1, vx1, vy1,
epoch-4,
epoch-n,epoch_2,xn, x4, yn, y4,zn, vxn, vyn, vy4,vznvz4 vz1
.................. etc. x2,...................
y2, z2, vx2, vy2, vz2
epoch_3,
.................. etc.x3,...................
y3, z3, vx3, vy3, vz3
epoch_4,
epoch-n, xn, yn, x4, zn,y4, vxn,
z4, vx4, vyn,vy4,
vzn vz4
.................. etc. ...................
.................. etc. ...................
epoch_n, xn, yn, zn, vxn, vyn, vzn

• This more substantial SPK is made up of multiple segments

containing ephemeris data:
– for a single object (perhaps a spacecraft, an asteroid, or …???),
– given in a single reference frame (“coordinate frame”),
– having a single center of motion,
SPK Subsystem – with data spanning from T1 to T6 12
 N IF An Even More Substantial SPK File
Navigation and Ancillary Information Facility

Some other stuff

Target, Ref Frame ID, Center of Motion, T1, T2

Target, Ref Frame ID, Center of Motion, T1, T2

epoch-1, x1, y1, z1, vx1, vy1, vz1
epoch-2, x2,Ref
Target, y2,Framez2, ID,vx2,
Center vy2, vz2 T3, T4
of Motion,
epoch-1, x1, y1, z1, vx1, vy1, vz1
epoch-3,
epoch-2, x3,x2,
Target, y3,
Refy2,z3,z2,
Frame vx3,vx2,
ID, vy3,
Center ofvz3
vy2, vz2 T3, T4
Motion,
epoch-4,epoch-1,x4, x1, z4,
y4, y1,vx4, z1, vx1,
vy4, vy1,
vz4 vz1
epoch-3,
epoch-2, x3, x2,
Target,
y3, z3, vx3, vy3,
y2, z2, vx2, vy2, vz2 T5, T6
Ref Frame ID, Center
vz3
of Motion,
..................
epoch-4, epoch-1, etc.
x4, ...................
x1, z4,
y4, y1,vx4,z1, vx1,
vy4, vy1,
vz4vz3vz1
epoch-3,
..................
epoch-2, etc.x3,
Target, y3,
x2, Ref z3,
...................vx3,
y2, z2, vx2, vy2,
Frame ID, vy3,
Center vz2 T5, T6
of Motion,
..................
epoch-4, epoch-1,etc.
x4, ...................
x1,
y4, y1,
z4, z1,
vx4, vx1,
vy4, vy1,
vz4 vz1
epoch-n, xn, yn, x3,
epoch-3, zn, y3,vxn,z3,vyn, vx3, vznvy3, vz3
..................
epoch-2,etc.
.................. ...................
etc.x2, y2, z2, vx2, vy2, vz2
...................
epoch-n, epoch-4, epoch_1,
xn, x4,
yn, x1,vxn,
y4,
zn, z4,y1,vx4,z1, vy4,
vyn, vx1,
vzn vy1, vz1
vz4
epoch-3,
..................
epoch_2, etc.x3, y3, z3, vx3,
...................
x2, y2, z2, vx2, vy2,vy3, vz3vz2
..................
epoch-4, etc.
x4, x3,...................
y4, y3, z4, z3,
vx4, vy4, vz4vz3
epoch-n, xn, yn,
epoch_3, zn, vxn, vyn,vx3, vzn
vy3,
.................. etc.
.................. ...................
etc. ...................
epoch-n, epoch_4, xn, yn, x4,zn, y4,vxn,z4, vx4,
vyn, vy4,
vzn vz4
.................. etc. ...................
.................. etc. ...................
epoch-n, xn, yn, zn, vxn, vyn, vzn
.................. etc. ...................
epoch_n, xn, yn, zn, vxn, vyn, vzn

• This even more substantial SPK contains multiple segments having:

– several objects (targets)
– several reference frames
– several centers of motion
– several pairs of start and stop times
SPK Subsystem 13
 N IF SPK “Type” Info in each Segment
Navigation and Ancillary Information Facility

Some other stuff

Target, Ref Frame ID, Center of Motion, T1, T2, Type 13 • Each segment can contain a
different type of ephemeris data
epoch_1, x1, y1, z1, vx1, vy1, vz1 (as long as it’s been built into
epoch_2, x2, y2, z2, vx2, vy2, vz2
epoch_3, x3, y3, z3, vx3, vy3, vz3 the SPK subsystem). Examples:
epoch_4, x4, y4, z4, vx4, vy4, vz4 – Discrete state vectors
– Chebyshev polynomials
– Difference lines (unique to JPL)
Target, Ref Frame ID, Center of Motion, T3, T4, Type 2 – Etc., etc.

MID, RADIUS, X coefs, Y coefs, Z coefs • Each segment has the SPK Type
MID, RADIUS, X coefs, Y coefs, Z coefs stored in its meta-data record
MID, RADIUS, X coefs, Y coefs, Z coefs (a.k.a. segment descriptor)
(some time tag info)
• Toolkit software knows how to
Target, Ref Frame ID, Center of Motion, T5, T6, Type 1 evaluate each Type – no worries
for you!
First set of difference line coefs
Second set of difference line coefs
epoch_1
epoch_2

SPK Subsystem 14
 SPK Data are Continuous
N IF Within a Segment
Navigation and Ancillary Information Facility

Cassini, Ref Frame ID, Saturn bc, T1, T2, Type 13

epoch_1, x1, y1, z1, vx1, vy1, vz1

epoch_2, x2, y2, z2, vx2, vy2, vz2
epoch_3, x3, y3, z3, vx3, vy3, vz3
epoch_4, x4, y4, z4, vx4, vy4, vz4

• Within the time bounds (T1, T2) of a single segment,

SPICE software will return a result–a state vector
consisting of position and velocity–at any epoch… not
just at the discrete epochs of the ephemeris records
(epoch_1, epoch_2, epoch_3, epoch_4)

• In the example above, SPICE will return the position and

velocity (the state) of the Cassini spacecraft relative to
the Saturn barycenter at any time t where: T1 ≤ t ≤ T2

SPK Subsystem 15
 N IF Chaining and Frame Transformation
Navigation and Ancillary Information Facility

• Next we’ll discuss “chaining” and “frame

transformations”… features of the SPK
subsystem that make it rather unique.

SPK Subsystem 16
 N IF Your Question
Navigation and Ancillary Information Facility

Huygens Probe

Titan

Deep Space Station 14

You would like to obtain the

position of the Huygens Probe
relative to DSS14 corrected for
light time and stellar aberration
in the station’s topocentric
frame, as shown by the red
Earth
vector

SPK Subsystem 17
 N IF Your Dilemma
Navigation and Ancillary Information Facility

Huygens Probe

You have available only

files containing the
ephemeris data represented
by the orange vectors.
Titan

Deep Space Station 14

Saturn Barycenter

Saturn

Earth Barycenter

Earth
Solar System Barycenter

Sun

SPK Subsystem 18
 N IF Not a Problem
Navigation and Ancillary Information Facility

Huygens Probe
You could carefully add
together the A, B, C, D, E
A and F vectors to obtain
the DSS14-Probe vector.
But it's easier if you let
SPICE do this for you.
B Titan

Deep Space Station 14

Saturn Barycenter

Saturn
F
Earth Barycenter
C
E

D
Earth
Solar System Barycenter

Sun

SPK Subsystem 19
N IF SPICE Chains SPK Data
Navigation and Ancillary Information Facility

• SPICE automatically searches across all loaded SPK files to

find the segments needed to compute the vectors needed to
obtain the result the customer has asked for. SPICE chains
these together using addition and subtraction.
– In this example the user wants the position of the Huygens probe
sitting on the surface of Titan as seen from Deep Space Station 14.
– SPICE computes this by chaining the gold, blue and violet chunks.

Probe
Huygens Probe
SPK File
Titan-centered position
≈
DSN Stations
DSS-63 DSS-62 DSS-61 DSS-15 DSS-14 DSS-13 DSS-12 SPK File
Earth-centered positions
≈

Satellite
Titan Tethys Enceladus Mimas SPK File
Saturn barycenter-centered positions
≈

Planet
Uranus BC Saturn BC Earth BC Earth Venus BC Mercury BC
SPK File
Solar system barycenter-centered positions,
except for Earth, which is centered on the
Earth barycenter
Solar System
Barycenter
20
 N IF Maybe It's Not "Simple Addition"
Navigation and Ancillary Information Facility

• What if the A, B, C, D, E and F vectors shown two

pages ago are given with respect to several
different reference frames? (This is the normal
situation!)
– Before you can add the vectors together you need to rotate
them into a common reference frame.
– This may not be very easy to accomplish on your own.
– Once the addition is complete you may need to rotate the
resultant vector into the reference frame appropriate for the job
you are doing.

SPK Subsystem 21
 SPICE Automates
N IF Frame Transformation
Navigation and Ancillary Information Facility

• As part of the “chaining” process just mentioned…

– position vectors are automatically rotated into a consistent reference frame
– the final vector is rotated into the output reference frame requested by the user

Reference Frames Used Ephemeris Segments Used

Titan Huygens Probe

International Celestial
Reference Frame (after landing)
(J2000)

Titan body-fixed frame Saturn Barycenter

(IAU_TITAN)
The position of the Huygens
International Terrestrial Probe relative to DSS-14, at time
Reference Frame
(ITRF93)
Deep Space t, given in the DSS-14
DSS-14 topocentric Station 14 topocentric reference frame, is
reference frame determined using a single
(DSS-14_TOPO)
SPICE Toolkit API.
Earth
Solar
System
Barycenter

tax
n syn
Earth barycenter
Fortra re
he
used A single SPKPOS API does it all for positions! SPKEZR API does it for states.
CALL SPKPOS ('HUYGENS_PROBE', t, 'DSS-14_TOPO', 'CN+S', 'DSS-14', POSITION, LT)
22
 N IF SPK Segment Order and Priority
Navigation and Ancillary Information Facility

• Within a single SPK file…

– The segments in an SPK file need not be ordered according to
time or body.
– But segment order does imply priority. If two segments from
the same SPK file both contain data for a given target and time
that satisfy a request, the SPK system selects the segment for
which the physical location is positioned later in the file.
» The centers of motion, frames and SPK types are irrelevant
to this selection.

• If using two or more SPK files…

– Segments from SPK files loaded later have higher priority: if
two segments from two different SPK files both contain data
for a given target and time, the SPK system selects the
segment from the SPK file that was loaded later.
» The centers of motion, frames and SPK types are irrelevant
to this selection.

SPK Subsystem 23
 N IF Details
Navigation and Ancillary Information Facility

• Now for some details.

• There’s quite a lot… don’t feel you need to grasp

all of this immediately.

SPK Subsystem 24
 Reading an SPK:
N IF Observers and Targets
Navigation and Ancillary Information Facility

• When you read an SPK file you specify which ephemeris

object is to be the “target” and which is to be the “observer.”
• The SPK system returns the state of the target relative to the
observer.
– The computed position data point from the “observer” to the “target.”
– The computed velocity is that of the “target” relative to the “observer.”

Observer Target

velocity vector position vector velocity vector

position vector

Target Observer

• Any ephemeris object can be a target or an observer!

SPK Subsystem 25
 N IF SPK File Coverage - 1
Navigation and Ancillary Information Facility

• The time period over which an SPK file provides data for an
ephemeris object is called the “coverage” or “time coverage”
for that object.
– An SPK file’s coverage for an object consists of one or more time
intervals.
– Often the coverage for all objects in an SPK file is a single, common time
interval.
SPK file containing data for one object with no
data gaps
FILE START FILE END

SPK file containing data for one object, with

two data gaps FILE START FILE END

SPK file containing data for three objects, each

having different data gaps

FILE START FILE END

SPK file containing data for three objects, each

having different coverage but with no data gaps

FILE START FILE END

SPK file containing data for several objects, each

having the same coverage and with no data gaps

FILE START FILE END

SPK Subsystem 26
 N IF SPK File Coverage - 2
Navigation and Ancillary Information Facility

• For any request time within any time interval comprising the
coverage for an object (i.e. the three green stripes shown
below), the SPK subsystem can return a vector representing
the state of that object relative to its center of motion.
– The SPK system will automatically interpolate ephemeris data to
produce a Cartesian state vector at the request time.
– To a user’s program, the ephemeris data appear to be continuous over
each time interval, even if the data stored inside the SPK file are
discrete.
• The SPK subsystem will not return a result for a request time
falling within a data gap.
– Data gaps can only occur between segments.
“Results” will be returned by the SPK reader API for
any request time falling within these three intervals.

Segment 1 Segment 2 Segment 3

FILE START FILE END

Note: each of the green stripes A SPICE error will be signaled

above consists of one or more by the SPK subsystem for any
segments. request time falling within these
two data gaps
SPK Subsystem 27
 Reference Frames Used in
N IF Writing and Reading SPKs
Navigation and Ancillary Information Facility

• All ephemeris data have an associated reference frame

– The frame specification is input by the SPK producer and is stored in
the segment’s meta-data
» This input frame must be one “known” to the SPICE system
– The frame may be different across segments

• A program reading an SPK file specifies relative to what

reference frame the output state or position vectors are to
be given; you’re not stuck with using the frame the SPK
producer used
– This output frame you select must be known to your program
» “Known” means either a built-in frame (hard coded in SPICE) or
one specified in a Frames Kernel
» The user’s program may need to have access to additional SPICE
data in order to construct the specified frame

SPK Subsystem 28
 N IF SPK Data Type Concept
Navigation and Ancillary Information Facility

SPK files may contain various mathematical representations of

ephemeris data ("data types"), but the high-level user interfaces (SPK
"readers") are type-independent:
Some SPK reader APIs do not return velocity

Cartesian state vector

at the requested time X, Y, Z, dX, dY, dZ
The most used SPK reader APIs are these:

SPKEZR (to get position and velocity)

SPK "Reader" Modules SPKPOS (to get position only)
SPKGEO (a low-level SPK reader)

SPK SPK SPK SPK SPK SPKSPK

Type 3Type 4 Type 5 Type 8 Type 10 TypeType
12 13
Chebyshev Hermite
Polynomials
Weighted Space Command Interpolation of
(separate ones Two-body Two-line Elements unequally spaced
for position and Motion discrete
velocity) state vectors
SPK Subsystem 29
 N IF Why Have Multiple Data Types?
Navigation and Ancillary Information Facility

• To allow an SPK producer to choose an ephemeris

representation well-suited for her/his application. For
example:
– Weighted two-body extrapolation (Type 5) yields compact files;
may be used with sparse data. Only accurate for motion that is
well approximated by the two-body model.
– SPK files based on sliding-window Lagrange and Hermite
interpolation (Types 9 and 13) are easy to create. Position can
be made arbitrarily accurate with sufficiently small time
separation of states.
– Chebyshev polynomials (Types 2, 3, 14) yield the best
combination of evaluation speed and accuracy. But the file
creator must do more work to use these data types.

• To replicate data originally provided in another format.

– Types 1, 2, 3, 8, 10, 14, 15, 17 and 18 were developed to enable
accurate duplication of data obtained from original ephemeris
developers.

SPK Subsystem 30
 N IF Widely Used SPK Data Types
Navigation and Ancillary Information Facility
• Type 1 (Modified divided difference arrays)
– Used by JPL orbit determination software for spacecraft ephemerides

• Type 2 (Chebyshev polynomials for position, velocity given by

differentiation)
– Used for JPL planetary ephemerides

• Type 3 (Separate Chebyshev polynomials for position and

velocity)
– Used for JPL satellite ephemerides

• Type 5 (Weighted two-body extrapolation)

– Used for comets and asteroids, as well as for sparse data sets where a
piecewise two-body approximation is acceptable

• Type 10 (Space command two-line elements)

– Used for some earth orbiters

• Types 9 and 13 (Sliding-window Lagrange and Hermite

interpolation of unequally-spaced states)
– Used by many non-JPL ephemeris producers and by MKSPK users

• Type 18, 19 (Sliding window Hermite or Lagrange interpolation)

SPK Subsystem – Used in SPKs made by ESA planetary missions (through Rosetta) 31
 N IF Barycenters
Navigation and Ancillary Information Facility

• A barycenter is the center of mass of a “system” of

bodies, about which they orbit
– SPICE documentation doesn't refer to the center of mass of an
individual object, such as a planet, as the object's "barycenter."

• For planets
– A planet and its satellites orbit the planet system’s barycenter
» For example, the planet Jupiter (599) and each of Jupiter’s satellites (501 - 5xx)
orbit the Jupiter system barycenter (5)

– Because Mercury and Venus have no satellites, their barycenters (1 and 2)

are at exactly the same locations as their mass centers (199 and 299)
» Therefore SPICE ephemeris objects 199 and 299 as well as 1 and 2 are found in a
planet ephemeris file

– Because the masses of Phobos and Deimos are so small compared to the
mass of Mars, the mass center for Mars (499) was treated as being located at
the Mars barycenter (4)
» Starting in 2013 with the JPL planetary ephemeris named DE430 this is
no longer the case; there is a very small offset of about 20 cm

• For the solar system

– Planet system barycenters (i.e. 1 through 9) and the sun (10) orbit the solar
system barycenter (0)

SPK Subsystem 32
 N IF Barycenter Offset Magnitude
Navigation and Ancillary Information Facility

Body Mass System Barycenter offset from Offset as % of

Center Barycenter body mass center (km)* body radius*

Sun (10) SSB (0) 1,378,196 198%

Mercury (199) M. BC (1) 0 0

Venus (299) V. BC (2) 0 0

Earth (399) E. BC (3) 4942 77%

Mars (499) M. BC (4) 0.0002 ~0

Jupiter (599) J. BC (5) 220 0.3%

Saturn (699) S. BC (6) 312 0.5%

Uranus (799) U. BC (7) 43 0.17%

Neptune (899) N. BC (8) 74 0.3%

Pluto (999)** P. BC (9) 2080 172%

* Estimated maximum values over the time range 2000-2050.
** For ephemeris purposes, Pluto is still treated as a planet.
SPK Subsystem 33
 N IF SPK File Contents
Navigation and Ancillary Information Facility

• A single SPK file can hold data for one ephemeris

object, or for many ephemeris objects

• The ephemeris objects in a given SPK file need not

all be of the same type
– One might find data for a spacecraft, some planets, and some satellites all
in one file, split across multiple segments

• This is illustrated in the next three charts

SPK Subsystem 34
 Examples of Generic
N IF SPK File Contents
Navigation and Ancillary Information Facility

Planet Ephemeris Asteroid Ephemeris Merged Planet4 and Satellite Ephemeris

10 Sun
0 Solar System BC 2000001 Ceres 5 Jupiter BC 5
1 Merc. BC 34 Earth BC
1991 Mercury Notes: 104 Sun
2 Venus BC (1) Mercury and Venus planet
locations are included in planet
3994 Earth
2991 Venus ephemerides since there are no 501 Io
3 Earth BC satellite ephemerides for these 502 Europa
planets.
3012 Moon (2) The Moon and Earth locations are 503 Ganymede
3992 Earth included in each planetary 504 Callisto
ephemeris because of historical
4 Mars BC ephemeris production techniques. 505 Amalthea
5 Jupiter BC (3) The Sun’s location is included in 514 Thebe
6 Saturn BC each planetary ephemeris because
of historical ephemeris production
515 Adrastea
7 Uranus BC techniques. 516 Metis
8 Neptune BC (4) For user convenience, NAIF often
merges into a planet’s satellite
599 Jupiter
9 Pluto BC* ephemeris files the locations of the
103 Sun earth, the earth barycenter and the
sun.
(5) Jupiter BC is the center of motion
* For ephemeris purposes, Pluto only for Jovian satellites, not for
is still treated as a planet. Earth BC, Sun, or Earth.

The objects in blue italic font are the center of motion for the remaining objects in
each file. There is no ephemeris data present for these centers of motion.
SPK Subsystem 35
 Examples of a
N IF Flight Project's SPK File Contents
Navigation and Ancillary Information Facility

This made-up example shows four collections of SPK files for the Cassini mission

Cassini Orbiter Huygens Probe Planets Satellites - 1

6 = Saturn bc 6 = Saturn bc 0 = solar system bc 6 = Saturn bc

-82 = Cassini S/C -150 = Huygens Probe 3 = Earth barycenter 601 = Mimas
6 = Saturn barycenter 602 = Enceladus
399 = Earth mass center 603 = Tethys
301 = Moon 604 = Dione
605 = Rhea
606 = Titan
607 = Hyperion
608 = Iapetus
One object Multiple objects 609 = Phoebe
699 = Saturn mass center
One object
Multiple objects

610 = Janus
611 = Epimetheus
:
• The user’s program must “load” as many of these SPK files 617 = Pandora
as needed to satisfy her/his requirements. 699 = Saturn mass center
Multiple objects
• Sometimes a project NAV team combines (merges) several of
these collections before releasing them, making the user’s job easier.
Satellites - 2
• Objects in blue font are the centers of motion for the remaining objects;
these don’t have ephemeris data included in the file.
See the next page for a graphical representation of this collection of SPKs
SPK Subsystem 36
 Possible* SPK File Time Coverages
N IF for the Previous Example
Navigation and Ancillary Information Facility

Each bar represents a separate file (SPK kernel)

Planet:

Satellite - 1:
(Major satellites)

Satellite - 2:
(Minor satellites)

Orbiter :

Huygens Probe :

cruise phase orbit phase

Time line:
Launch Orbit Probe End of
Insertion Release Mission
* Note: This was not the real Cassini scenario–it is simply an illustration
SPK Subsystem of some of the possibilities for ephemeris delivery on a planetary mission. 37
 SPKs for Objects Located on
N IF the Surface of a Natural Body
Navigation and Ancillary Information Facility

• An SPK file may contain positions of tracking

stations, observatories, rovers, etc.
– The object could be stationary or moving
– Usually such SPKs contain ephemeris data given in the body-fixed
reference frame

• One reads this file the same as for any other SPK file
– Use the name or NAIF ID of the antenna, observatory or rover as
the “target” or “observer” in an SPK reader argument list
– Also requires use of a SPICE PCK file if you request vectors to be
returned in an inertial frame such as J2000; the PCK is needed to
rotate body-fixed vectors to the J2000 frame

SPK Subsystem 38
 N IF
Navigation and Ancillary Information Facility

Using SPK Files

SPK Subsystem 39
 N IF Retrieving Position or State Vectors
Navigation and Ancillary Information Facility

• To retrieve position or state vectors of ephemeris objects

one often needs two kinds of SPICE kernels
– Ephemeris kernel(s) (SPK)
– Leapseconds kernel (LSK)
» The LSK is used to convert between Coordinated Universal Time
(UTC) and Barycentric Dynamical Time (TDB, also called Ephemeris
Time, ET)
• This conversion is done outside of the SPK subsystem
• Retrieving ephemeris data from an SPK file is usually called
“reading” the file
– This term is not very accurate since the SPK “reader” software also
performs interpolation, and may chain together data from multiple
sources, do frame transformations, and perform aberration corrections
• State and position vectors retrieved from an SPK file by the
SPK “reader” routines are Cartesian (rectangular) vectors
of the form:
– X,Y, Z, dX, dY, dZ for a state vector (km, km/sec)
– X, Y, Z for a position vector (km)

SPK Subsystem 40
 N IF Retrieving a State Vector
Navigation and Ancillary Information Facility
tax
n syn
Initialization…typically done once per program execution Fortra re
he
used
Tell your program which SPICE files to use (“loading” files)
CALL FURNSH ('spk_file_name') It’s better to replace these
CALL FURNSH ('leapseconds_file_name') two calls with a single call to
a “furnsh kernel” containing
the names of all kernel files
to load.
Loop... do as many times as you need to

Convert UTC time to ephemeris time (TDB), if needed

CALL STR2ET ( 'utc_string', tdb)

Retrieve state vector from the SPK file at your requested time
CALL SPKEZR (target, tdb, 'frame', 'correction', observer, state, light time)

inputs outputs

Now use the returned state vector in other SPICE routines to compute
observation geometry of interest.
SPK Subsystem 41
 N IF Arguments of SPKEZR - 1
Navigation and Ancillary Information Facility

INPUTS
• TARGET and OBSERVER: Character names* or NAIF IDs for the
end point and origin of the state vector (Cartesian position and
velocity vectors) to be returned.
– The position component of the requested state vector points from the observer
to the target.
• TDB: The time at the observer’s location at which the state vector
is to be computed. The time system used is Ephemeris Time (ET),
now generally called Barycentric Dynamical Time (TDB).

• FRAME: The SPICE name for the reference frame in which the
output state vector is to be given. SPK software will automatically
convert ephemeris data to the frame you specified, if needed.
SPICE must know the named frame, either built-in or specified
using a Frames Kernel.

* Character names work for the target and observer inputs only if built into SPICE or if registered using the
SPICE ID-body name mapping facility. Otherwise use the SPICE numeric ID enclosed in quotes.
SPK Subsystem 42
 N IF Arguments of SPKEZR - 2
Navigation and Ancillary Information Facility

• CORRECTION: Specification of what kind of aberration correction(s),

if any, to apply in computing the output state vector.
– Use LT+S to obtain the apparent state of the target as seen by the observer. LT+S
invokes light time and stellar aberration corrections. (CN+S is better in some
cases.)
– Use NONE to obtain the uncorrected (aka “geometric”) state, as given by the source
SPK file or files.
See the header for subroutine SPKEZR, the document SPK Required
Reading, or the “Fundamental Concepts” tutorial for details. See the
backup charts for examples of aberration correction magnitudes.
OUTPUTS

• STATE: This is the Cartesian state vector you requested. It contains

6 components: three for position (x,y,z) and three for velocity (dx,
dy, dz) of the target with respect to the observer. The position
component of the state vector points from the observer to the target.
• LIGHT TIME: The one-way light time between the (optionally
aberration-corrected) position of target and the geometric position
of the observer at the specified epoch. (Generally not needed.)

LT + S = light time plus stellar aberration

SPK Subsystem CN + S = converged Newtonian light time plus stellar aberration 43
 N IF A Simple Example of Retrieving a State Vector
Navigation and Ancillary Information Facility
tax
n syn
Fortra re
he
used
Initialization - typically do this just once per program execution
It’s better to replace these
CALL FURNSH ( 'NAIF0012.TLS' ) two calls with a single call
CALL FURNSH ( 'CASSINI_MERGED.BSP' ) loading a “furnsh kernel”
containing the names of all
kernel files to load.
Repeat in a loop if/as needed to solve your particular problem
CALL STR2ET ('2004 NOV 21 02:40:21.3', TDB )
CALL SPKEZR ('TITAN', TDB, 'J2000', 'LT+S', 'CASSINI',
STATE, LT )

(Insert additional code here to make derived computations such as spacecraft sub-latitude
and longitude, lighting angles, etc. Use more SPICE subroutines to help.)

In this example we get the state (STATE) of Titan as seen from the Cassini spacecraft at the UTC epoch 2004
NOV 21 02:40:21.3. The state vector is returned in the J2000 inertial reference frame, which in SPICE is the
same as the ICRF frame. The state vector has been corrected for both light time and stellar aberration (LT+S).
The one-way light time (LT) is also returned, just in case it could be useful.

A SPICE leapseconds file (NAIF0012.TLS) is used, as is a SPICE ephemeris file (CASSINI_MERGED.BSP)

containing ephemeris data for Cassini (-82), Saturn barycenter (6), Saturn mass center (699),
Saturn's satellites (6xx) and the sun (10).

SPK Subsystem 44
 N IF Retrieving a Position Vector
Navigation and Ancillary Information Facility

• SPKPOS is the position-only analog of SPKEZR

– The arguments of SPKPOS are identical to those of SPKEZR, except that
SPKPOS returns a 3-component position vector instead of a 6-component
state vector
– SPKPOS executes more quickly than SPKEZR when stellar aberration
corrections are used
– SPKPOS can be used when reference frame transformations of velocity
are not possible due to absence of C-kernel angular velocity data

SPK Subsystem 45
 A Slightly More Complex Example
N IF Kernel Data Needed
Navigation and Ancillary Information Facility

• To get state vectors referenced to a non-inertial

reference frame, or when the data within the SPK
file are provided in a non-inertial frame, typically
more kernels will be needed.
– To get the state of an object relative to a body in the body’s IAU
body-fixed reference frame you’ll need:
» PCK file containing orientation data for the body
» SPK(s) for the object and body
» LSK
– To get the state of an object in a spacecraft-fixed reference frame
you’ll need:
» FK, CK and SCLK for the spacecraft
» SPK(s) for the spacecraft and object
» LSK

SPK Subsystem 46
 A Slightly More Complex Example
N IF Retrieving a State Vector
Navigation and Ancillary Information Facility

Obtain the state of Titan relative to Cassini in the Titan body-fixed reference frame
Initialization...typically once per program execution
tax
n syn
Fortra re
Tell your program which SPICE files to use (“loading” files) used
he

CALL FURNSH ('CASSINI_MERGED.BSP') It’s better to replace these three

CALL FURNSH ('NAIF0012.TLS') calls with a single call loading a
“furnsh kernel” containing the
CALL FURNSH ('NAIF0011.TPC') names of all kernel files to load.
Loop... do as many times as you need

Convert UTC time to ephemeris time (TDB), if needed

CALL STR2ET ( '2004 NOV 21 02:40:21.3', TDB)
Get state vector from SPK file at requested time, in satellite’s IAU body-fixed
frame
CALL SPKEZR ('TITAN', TDB, 'IAU_TITAN', 'LT+S', 'CASSINI',
STATE, LT)

Insert additional code here to make derived computations such as

spacecraft sub-latitude and longitude, lighting angles, etc. Use
more SPICE subroutines to help.
SPK Subsystem 47
 Constant-velocity objects:
N IF Additional SPK State Computation APIs
Navigation and Ancillary Information Facility

• The SPK subsystem contains routines for computing the state

of an ephemeris object with respect to a fixed point or one
moving with constant, non-zero velocity, in a specified
reference frame.
– The point may act as either the target or the observer.
– The center of motion of the point must be an ephemeris object.
• The SPK routines providing this capability are:
– SPKCPT (SPK, constant position target)
– SPKCPO (SPK, constant position observer)
– SPKCVT (SPK, constant velocity target)
– SPKCVO (SPK, constant velocity observer)
• These routines may provide a convenient alternative to
creating SPK files for surface points:
– when there’s a need to compute the locations on the fly
– when the number of surface points is large

SPK Subsystem 48
 N IF Manipulating and Using SPK Files
Navigation and Ancillary Information Facility

• You can subset an SPK, or merge two or more SPKs

– The subset or merge may be keyed off of objects, or time, or both
– Merging only portions of SPKs is possible

• You can read data from just one, or many* SPK files in
your application program
– Don’t forget the precedence rule: data in a later loaded file take
precedence over data from an earlier loaded file

• You can convert an SPK that is in non-native binary

format to native binary format if you need to add data or
comments
* The allowed number of simultaneously loaded DAF- and DAS-based files
is set to 5000 in N67 Toolkits. “DAF” is the acronym for Double Precision
SPK Subsystem
Array File. SPKs are based on the DAF architecture.
49
 N IF Understanding an SPK File
Navigation and Ancillary Information Facility

• The SPK producer should have provided descriptive

meta-data inside an SPK file, in the “comment area”
– The comments should say when, why, how and for what purpose
the file was made
– Additional useful information could also be provided by the
producer
» Example: when and why any data gaps are present

• These comments may be extracted using an API

(subroutine) or viewed using a SPICE utility program.
– API: DAFEC
– Utility program: commnt –r <spk_file_name>

SPK Subsystem 50
 N IF SPK Utility Programs
Navigation and Ancillary Information Facility

• The following SPK utility programs are included in the

Toolkit:
BRIEF summarizes coverage for one or more SPK files
SPACIT generates segment-by-segment summary of an SPK file
COMMNT reads, appends, or deletes comments in an SPK file
MKSPK converts ephemeris data provided in a text file into an SPK file
SPKDIFF compares two SPK files
SPKMERGE subsets an spk, or merges one or more SPK files or pieces

• These additional SPK utility programs are provided on the

NAIF Web site (https://naif.jpl.nasa.gov/naif/utilities.html)
SPY validates, inspects, and analyses SPK files
PINPOINT creates an SPK file for fixed locations (ground stations, etc)
BSPIDMOD alters body IDs in an SPK file
DAFMOD alters body or frame IDs in an SPK file
DAFCAT concatenates together SPK files
BFF displays binary file format of an SPK file
BINGO converts SPK files between big- and little-endian formats

SPK Subsystem 51
 N IF Summarizing an SPK File - 1
Navigation and Ancillary Information Facility

• A summary of the contents and time coverage of an SPK file can be made
using the SPICE Toolkit utility “brief”
– See the brief User’s Guide for details

% brief 070413BP_SCPSE_07097_07121.bsp

Summary for: 070413BP_SCPSE_07097_07121.bsp

Bodies: CASSINI (-82) PLUTO BARYCENTER (9) TETHYS (603)

MERCURY BARYCENTER (1) SUN (10) DIONE (604)
VENUS BARYCENTER (2) MERCURY (199) RHEA (605)
EARTH BARYCENTER (3) VENUS (299) TITAN (606)
MARS BARYCENTER (4) MOON (301) HYPERION (607)
JUPITER BARYCENTER (5) EARTH (399) IAPETUS (608)
SATURN BARYCENTER (6) MARS (499) PHOEBE (609)
URANUS BARYCENTER (7) MIMAS (601) SATURN (699)
Note, the default
NEPTUNE BARYCENTER (8) ENCELADUS (602) time system is
ET, not UTC!
Start of Interval (ET) End of Interval (ET)
-------------------------------- --------------------------------
2007 APR 07 16:22:23.000 2007 MAY 01 09:34:03.000

SPK Subsystem 52
 N IF Summarizing an SPK File - 2
Navigation and Ancillary Information Facility

• Use of the “-c” option when using the brief utility will show
you the center of motion for each object
– This is often useful in diagnosing an SPK chaining problem
» See the “Problems” section at the end of this tutorial for more information
% brief -c 070413BP_SCPSE_07097_07121.bsp

Bodies: CASSINI (-82) w.r.t. SATURN BARYCENTER (6)

MERCURY BARYCENTER (1) w.r.t. SOLAR SYSTEM BARYCENTER (0)
VENUS BARYCENTER (2) w.r.t. SOLAR SYSTEM BARYCENTER (0)
EARTH BARYCENTER (3) w.r.t. SOLAR SYSTEM BARYCENTER (0)
MARS BARYCENTER (4) w.r.t. SOLAR SYSTEM BARYCENTER (0)
JUPITER BARYCENTER (5) w.r.t. SOLAR SYSTEM BARYCENTER (0)
SATURN BARYCENTER (6) w.r.t. SOLAR SYSTEM BARYCENTER (0)
URANUS BARYCENTER (7) w.r.t. SOLAR SYSTEM BARYCENTER (0)
NEPTUNE BARYCENTER (8) w.r.t. SOLAR SYSTEM BARYCENTER (0)
PLUTO BARYCENTER (9) w.r.t. SOLAR SYSTEM BARYCENTER (0)
SUN (10) w.r.t. SOLAR SYSTEM BARYCENTER (0)
MERCURY (199) w.r.t. MERCURY BARYCENTER (1)
VENUS (299) w.r.t. VENUS BARYCENTER (2)
MOON (301) w.r.t. EARTH BARYCENTER (3)
EARTH (399) w.r.t. EARTH BARYCENTER (3)
MARS (499) w.r.t. MARS BARYCENTER (4)
MIMAS (601) w.r.t. SATURN BARYCENTER (6)
ENCELADUS (602) w.r.t. SATURN BARYCENTER (6)
TETHYS (603) w.r.t. SATURN BARYCENTER (6)
DIONE (604) w.r.t. SATURN BARYCENTER (6)
RHEA (605) w.r.t. SATURN BARYCENTER (6)
TITAN (606) w.r.t. SATURN BARYCENTER (6)
HYPERION (607) w.r.t. SATURN BARYCENTER (6)
IAPETUS (608) w.r.t. SATURN BARYCENTER (6)
PHOEBE (609) w.r.t. SATURN BARYCENTER (6)
SATURN (699) w.r.t. SATURN BARYCENTER (6)
Start of Interval (ET) End of Interval (ET)
----------------------------- -----------------------------
SPK Subsystem 2007 APR 07 16:22:23.000 2007 MAY 01 09:34:03.000 53
 N IF Summarizing an SPK File - 3
Navigation and Ancillary Information Facility
• A detailed summary of an SPK can be made using the Toolkit utility
named “SPACIT”
• See the SPACIT User’s Guide for details
Summary for SPK file: sat240.bsp
Leapseconds File : /kernels/gen/lsk/leapseconds.ker
Summary Type : Entire File

--------------------------------------------------------------------------------
Segment ID : SAT240
Target Body : Body 601, MIMAS
Center Body : Body 6, SATURN BARYCENTER
Reference frame: Frame 1, J2000
SPK Data Type : Type 3
Description : Fixed Width, Fixed Order Chebyshev Polynomials: Pos, Vel
UTC Start Time : 1969 DEC 31 00:00:00.000
UTC Stop Time : 2019 DEC 02 00:00:00.000
ET Start Time : 1969 DEC 31 00:00:41.183
ET Stop time : 2019 DEC 02 00:01:05.183
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
Segment ID : SAT240
Target Body : Body 602, ENCELADUS
Center Body : Body 6, SATURN BARYCENTER
Reference frame: Frame 1, J2000
SPK Data Type : Type 3
Description : Fixed Width, Fixed Order Chebyshev Polynomials: Pos, Vel
UTC Start Time : 1969 DEC 31 00:00:00.000
UTC Stop Time : 2019 DEC 02 00:00:00.000
ET Start Time : 1969 DEC 31 00:00:41.183
ET Stop time : 2019 DEC 02 00:01:05.183
--------------------------------------------------------------------------------
:
(This is a partial output; not all data could be displayed on this chart)
SPK Subsystem 54
 N IF Summarizing an SPK File - 4
Navigation and Ancillary Information Facility

Summarizing an SPK at the API Level

• Call SPKOBJ to find the set of objects for which a specified SPK
provides data.
– INPUT: an SPK file name and initialized SPICE integer “Set” data structure. The set may
optionally contain ID codes obtained from previous calls.
– OUTPUT: the input set, to which have been added (via set union) the ID codes of objects
for which the specified SPK provides coverage.
CALL SPKOBJ ( SPK, IDSET )
• Call SPKCOV to find the window of times for which a specified SPK file
provides coverage for a specified body:
– INPUT: an SPK file name, body ID code and initialized SPICE double precision “Window”
data structure. The window may optionally contain coverage data from previous calls.
– OUTPUT: the input window, to which have been added (via window union) the sequence
of start and stop times of segment coverage intervals of the specified SPK, expressed as
seconds past J2000 TDB.
CALL SPKCOV ( SPK, IDCODE, COVER )
• See the headers of these routines for example programs.
• Also see the CELLS, SETS and WINDOWS Required Reading for background
information on these SPICE data types.

SPK Subsystem 55
 N IF Additional Information on SPK
Navigation and Ancillary Information Facility

• For more information about SPK, look at the following:

– The on-line SPK tutorial
– Most Used Routines document
– SPK Required Reading document
– Headers of the subroutines mentioned
– Using Frames tutorial
– BRIEF and SPKDIFF User’s Guides
• Related documents:
– NAIF_IDS Required Reading
– Frames Required Reading
– Time Required Reading
– Kernel Required Reading

SPK Subsystem 56
 N IF Backup
Navigation and Ancillary Information Facility

• Problems Using SPK Files

• Don’t Mix Planet Ephemerides
• Effect of Aberration Corrections
• Examples of Retrieving State Vectors
• SPK File Structure

SPK Subsystem 57
 N IF Problems Using SPK Files - 1
Navigation and Ancillary Information Facility

• The file, or files, you loaded do not contain data for both your
target and observer bodies
– You may have loaded the wrong file, or assumed the file contains data
that it doesn’t
– You may not have loaded all the files needed
• The file, or files, you loaded do not cover the time at which
you requested a state vector
– This could occur if you’ve been given a file coverage summary in
calendar ET form and you mistook this for UTC
( ET = UTC + DELTAET, where DELTAET is about 69 seconds as of 1/20)
– This could occur if you are requesting a light-time corrected state and the
SPK files being used do not have data at the time that is one-way light-
time away* from your ET epoch of interest
» * Earlier, for the receive case; later, for the transmission case
• In the above situations you’ll get an error message like the
following:
SPICE(SPKINSUFFDATA) - -
Insufficient ephemeris data has been loaded to
compute the state of xxx relative to yyy.
SPK Subsystem 58
 N IF Problems Using SPK Files - 2
Navigation and Ancillary Information Facility

• You have requested aberration-corrected states

but the SPK file or files you loaded do not contain
sufficient data to relate both your target and
observer bodies back to the solar system
barycenter, which is required for this calculation.
– You may not have loaded all the files needed
– You may have assumed the file contains data that it doesn’t

• In the above situations you’ll get an error

message like the following:

SPICE(SPKINSUFFDATA) - -
Insufficient ephemeris data has been loaded to
compute the state of xxx relative to yyy.

SPK Subsystem 59
 N IF Problems Using SPK Files – 3a
Navigation and Ancillary Information Facility

• An infrequent problem occurs when your SPK file(s)

contain data for both target and observer, and cover
the period of interest, but ephemeris data for an
intermediate body needed to chain the target and
observer together is missing.
– Example: You load a spacecraft SPK containing ephemeris for
Cassini (-82) relative to the solar system barycenter (0), and you
load a satellite SPK containing the ephemeris for Titan (606) and
Saturn (699) relative to the Saturn barycenter (6). But you forgot to
load a planet SPK file that contains data for the Saturn barycenter
(6) relative to the solar system barycenter (0). The SPK software
cannot “connect” Cassini to Titan or to Saturn. (See the drawing
on the next page.)
– In this case, knowing what is the “Center Body” of movement for
each target body is important; this is shown in SPACIT, and also
in BRIEF summaries when the -c command line option is used.
– This problem is illustrated on the next page.
SPK Subsystem 60
 Problems Using SPK Files - 3b
N IF (drawing)
Navigation and Ancillary Information Facility
Saturn
These vectors obtained
from a satellite
ephemeris SPK

+ Cassini spacecraft during

interplanetary cruise

Titan

This vector obtained from a

cruise phase spacecraft SPK

In this example the

absence of a planet
Solar System
ephemeris SPK means the
This vector cannot be obtained Barycenter
Cassini-Titan and Cassini-
Saturn vectors shown here
from either the spacecraft or +
satellite SPKs; a planet
cannot be determined
ephemeris SPK is needed.
because the Saturn
Barycenter-to-Solar System
Barycenter vector is not
available.
Sun
Given…
available in SPK files
not available in SPK files
Therefore…
can’t be computed
SPK Subsystem 61
 N IF Problems Using SPK Files - 4
Navigation and Ancillary Information Facility

• You see an error message to the effect that pole

RA (right ascension) data cannot be found
– You are requesting results in a body-fixed frame, but you
have not loaded a SPICE PCK file that defines this frame.

SPK Subsystem 62
 N IF Problems Using SPK Files - 5
Navigation and Ancillary Information Facility

• Segment Masking: You've loaded sufficient data to chain

together the target and observer, but the SPK subsystem can't
make the connection.
– This can happen when a high-priority segment that can't be connected to
both target and observer "masks" a lower-priority segment that can be
connected.
– Example: you want the state of earth as seen from the Galileo orbiter at a
specified ephemeris time ET1.
» You have loaded SPK files providing:
• the state of the Galileo orbiter relative to the asteroid Gaspra
• the state of the orbiter relative to the sun
• the state of the earth relative to the earth-moon barycenter
• the states of the sun and earth-moon barycenter relative to the solar system barycenter
» If an SPK segment for the orbiter relative to Gaspra covering ET1 has
higher priority than the segment for the orbiter relative to the sun
covering ET1, no connection between the orbiter and the earth will be
made.
» Solution:
• Load an SPK file providing the ephemeris of Gaspra relative to the sun or the solar system
barycenter (for a time interval containing ET1)

SPK Subsystem 63
 N IF Problems Using SPK Files - 6
Navigation and Ancillary Information Facility

• Other missing data… not obvious.

– You may need CK (and SCLK), FK or PCK data to construct
your requested output frame.
• Mistaking ET for UTC, or vice-versa: very common
• Using light time corrections requires target
ephemeris data at the light time-corrected epoch.
– If you’re working near the beginning of an SPK file, the light
time-corrected epoch may occur earlier than available data.

SPK Subsystem 64
 N IF Problems Using SPK Files - 7
Navigation and Ancillary Information Facility

• You’ve assumed that:

negative sign

state (observer, target) = - state (target, observer)

• This is NOT true unless you have requested geometric states in

both cases (i.e. no light time or stellar aberration corrections
are applied)

SPK Subsystem 65
 N IF Problems Using SPK Files - 8
Navigation and Ancillary Information Facility

• SPK reading efficiency can be impacted by any of

several circumstances.
– This won't result in erroneous results… just slow performance.
– This sort of problem does not occur very often.
– For details, read some of the backup charts in the tutorial named
Making an SPK–those titled "SPK Reading: Efficiency Issues."

SPK Subsystem 66
 N IF Don’t Mix Planet Ephemerides-1
Navigation and Ancillary Information Facility
S.S.Barycenter

S.S.Barycenter
• With each new version of the
JPL planetary ephemeris, the
solar system barycenter moves
with respect to the planets

• Changes in relative planet

positions are much smaller
than changes in the planet
locations relative to the solar
system barycenter Earth

Mars

SPK Subsystem 67
 N IF Don’t Mix Planet Ephemerides-2
Navigation and Ancillary Information Facility

S.S.Barycenter
• SPICE allows you to “load”
different planetary
ephemerides (or portions
of them)
» You can potentially
subtract the solar system
barycenter-relative
positions from different Result of mixing
ephemerides to get ephemerides
relative states
• Don’t mix planetary
ephemerides
• For JPL flight projects, a
consistent set of Earth
Mars
ephemerides is provided to
the mission team

SPK Subsystem 68
 N IF Effect of Aberration Corrections - 1
Navigation and Ancillary Information Facility

• Angular offsets between corrected and uncorrected position

vectors over the time span 2004 Jan 1 to 2005 Jan1
– Mars as seen from MEX:
» LT+S vs NONE: .0002 to .0008 degrees
» LT vs NONE: .0006 to .0047 degrees
– Earth as seen from MEX:
» LT+S vs NONE: .0035 to .0106 degrees
» LT vs NONE: .0000 to .0057 degrees
– MEX as seen from Earth:
» LT+S vs NONE: .0035 to .0104 degrees
» LT vs NONE: .0033 to .0048 degrees
– Sun as seen from Mars:
» LT+S vs NONE: .0042 to .0047 degrees
» LT vs NONE: .0000 to .0000 degrees

SPK Subsystem 69
 N IF Effect of Aberration Corrections - 2
Navigation and Ancillary Information Facility

• Angular offsets between corrected and uncorrected position

vectors over the time span 2004 Jan 1 to 2008 Jan1
– Saturn as seen from CASSINI:
» LT+S vs NONE: .0000 to .0058 degrees
» LT vs NONE: .0001 to .0019 degrees
– Titan as seen from CASSINI:
» LT+S vs NONE: .0000 to .0057 degrees
» LT vs NONE: .0000 to .0030 degrees
– Earth as seen from CASSINI:
» LT+S vs NONE: .0000 to .0107 degrees
» LT vs NONE: .0000 to .0058 degrees
– CASSINI as seen from Earth:
» LT+S vs NONE: .0000 to .0107 degrees
» LT vs NONE: .0000 to .0059 degrees
– Sun as seen from CASSINI:
» LT+S vs NONE: .0000 to .0059 degrees
» LT vs NONE: .0000 to .0000 degrees

SPK Subsystem 70
 N IF Examples of Retrieving State Vectors – 1
Navigation and Ancillary Information Facility

• Example: find the geometric state of the MGS orbiter relative

to Mars at the observation epoch ET, expressed in the J2000
reference frame.
x – CALL SPKEZR ( 'MGS', ET, 'J2000', 'NONE', 'MARS', STATE, LT )
t ran synta
Fo r – The SPK subsystem locates an SPK segment containing the ephemeris
here
used of the orbiter relative to Mars covering epoch ET, interpolates the
ephemeris data at ET, and returns the interpolated state vector.
• Example: find the geometric state of Titan relative to the
earth at epoch ET, expressed in the J2000 reference frame.
– CALL SPKEZR ( 'TITAN', ET, 'J2000', 'NONE', 'EARTH', STATE, LT )
– The SPK subsystem looks up and interpolates ephemeris data to yield:
» The state of the earth relative to the earth-moon barycenter (A)
» The state of the earth-moon barycenter relative to the solar system
barycenter (B)
» The state of Titan relative to the Saturn system barycenter at ET (C)
» The state of the Saturn system barycenter relative to the solar
system barycenter at ET (D)
– SPKEZR then returns the state vector
» C+D–(A+B)

SPK Subsystem 71
 N IF Examples of Retrieving State Vectors – 2
Navigation and Ancillary Information Facility

• Example: find the apparent state of the Cassini orbiter

relative to the DSN station DSS-14, expressed in the
topocentric reference frame centered at DSS-14, at a specified
observation epoch ET.
– CALL SPKEZR ( 'CASSINI', ET, 'DSS-14_TOPO',
'LT+S', 'DSS-14', STATE, LT )
– The SPK subsystem looks up and interpolates ephemeris data to yield:
» The state of DSS-14 relative to the earth in the ITRF93 terrestrial
reference frame (A)
» The state at ET of the earth relative to the earth-moon barycenter in
the J2000 reference frame (B)
» The state at ET of the earth-moon barycenter relative to the solar
system barycenter in the J2000 frame (C)
» The state at the light time-corrected epoch ET-LT of the Cassini
orbiter relative to the Saturn system barycenter (other centers are
possible) in the J2000 frame (D)

continued on next page

SPK Subsystem 72
 N IF Examples of Retrieving State Vectors – 3
Navigation and Ancillary Information Facility

» The state at ET-LT of the Saturn system barycenter relative

to the solar system barycenter in the J2000 frame (E)
– The SPK subsystem also looks up transformation matrices to
map states:
» From the J2000 frame to the ITRF93 terrestrial (earth body-
fixed) frame at the observation epoch ET (T1)
» From the ITRF93 terrestrial frame to the DSS-14-centered
topocentric frame (T2)
– SPKEZR then computes the J2000-relative, light-time corrected
observer-target state vector
» E + D – ( (T1)-1 *A + B + C))
– SPKEZR corrects this vector for stellar aberration
» Call the result "V_J2000_apparent"
– and finally returns the requested state vector in the DSS-14
topocentric reference frame
» STATE = T2 * T1 * V_J2000_apparent

SPK Subsystem 73
 N IF SPK File Structure
Navigation and Ancillary Information Facility

• A description of the SPK file structure is shown

near the beginning of the “Making an SPK”
tutorial.

SPK Subsystem 74
N IF
Navigation and Ancillary Information Facility

Planetary Constants Kernel

PCK

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Overview
• Text PCK Orientation Models
• Binary PCK Orientation Models
• PCK reference frames
• PCK Shape Models
• Using PCKs
• Interface Routines
• PCK Precedence Rules
• PCK Utility Programs

PCK Subsystem 2
 N IF Overview
Navigation and Ancillary Information Facility

• The Planetary Constants Kernel (PCK)

subsystem comprises both text and binary
kernels.

– Text PCKs provide orientation and shape models for

the sun, planets, natural satellites and a few
asteroids and comets.

– Binary PCKs are used only when very high accuracy

orientation data are available.
» Currently available only for the earth and the moon
» One still needs to use a text-style PCK to get shape data

PCK Subsystem 3
 N IF Text PCKs - 1
Navigation and Ancillary Information Facility

• Text PCK files contain size, shape and orientation data

associated with natural solar system bodies: planets, satellites,
and a few comets and asteroids.
– Some additional kinds of data might also be included.
• NAIF creates and distributes a “generic” text PCK based on the
latest IAU/IAG Report.*
– The reports are issued about once every three years, and so might not
contain the very latest available results.
• SPICE PCK software is designed to use these data to compute
orientation of body-fixed, body-centered frames.
– These frames have a name style of “IAU_body-name”
• NAIF also provides a “masses” PCK, containing GM values for
the Sun and planetary systems.
– Values from this file are typically used with SPICE osculating element
routines, and in using the MKSPK application to make a Type 5 SPK file.
• Text PCKs are sometimes produced by flight projects and
others–not only by NAIF.

* “Report of the IAU/IAG Working Group on cartographic coordinates and rotational

PCK Subsystem elements: <year issued>”; published in Celestial Mechanics and Dynamical Astronomy 4
 N IF Text PCKs - 2
Navigation and Ancillary Information Facility

• The SPICE text kernel mechanism is used to implement

PCK files.
– Kernel variables contain the mathematical terms appearing in rotation
or shape models. For example:
BODY699_POLE_RA = ( 40.589 -0.036 0. )
BODY699_POLE_DEC = ( 83.537 -0.004 0. )
BODY699_PM = ( 38.90 810.7939024 0. )
BODY699_RADII = ( 60268 60268 54364 )
– Users may easily inspect data in text PCKs.
– Users may (carefully!) modify text PCKs with a text editor.
» Data or comments may be added, deleted, or changed.
» Comments should be added to explain changes.
– The user may include additional kernel variables to change the base
frame or reference epoch.
– Kernel variable names are case-sensitive.
» NAIF uses only upper case for variable names; we suggest you do the
same.
PCK Subsystem 5
 N IF Text PCK Orientation Models - 1
Navigation and Ancillary Information Facility

• For the sun, planets and a few major asteroids:

– PCK models use low-degree (typically linear) polynomials to represent
RA and DEC of the pole (body-fixed +Z-axis) as a function of time.
– The prime meridian is also represented by a low-degree polynomial.
– For a few planets, trigonometric polynomial terms are used to more
accurately represent precession and nutation of the pole.

R = rotation of the body about its rotational axis

P = precession of the bodies’ rotational axis
N = nutation of the bodies’ rotational axis

• For natural satellites:

– In addition to low-degree polynomials for the spin axis and prime
meridian, trigonometric polynomial terms are used to more accurately
represent precession and nutation.
– A few satellites have chaotic rotation and so are not modeled.
PCK Subsystem 6
 N IF Text PCK Orientation Models - 2
Navigation and Ancillary Information Facility

• The default base frame for PCK orientation models

is the International Celestial Reference Frame
(ICRF), as defined by the International Earth
Rotation Service (IERS).
– For historical and backwards compatibility reasons, the
reference frame name "J2000" is generally used in SPICE as a
label for the ICRF frame, even though J2000 and ICRF are, in
fact, not identical. (The difference is under 0.1 arc second.)
– The default base frame for selected objects may be overridden
using text kernel assignments.
• The default epoch PCK orientation models is J2000
TDB.
– This epoch also can be overridden for selected objects using
text kernel assignments.

PCK Subsystem 7
 N IF Text PCK Orientation Models - 3
Navigation and Ancillary Information Facility
• Body-fixed frames provided in text PCKs have +Z axes
consistent with planetocentric coordinate systems. The +X
axes of these frames coincide with planetocentric longitude 0.

• For planets and satellites the +Z axis (+90 LAT) always points
to the north side of the invariable plane – the plane whose
normal vector is the angular momentum vector of the solar
system.
– Planetocentric longitude increases positively eastward
– Planetocentric latitude increases positively northward

• Dwarf planets*, asteroids and comets spin in the right hand

sense about their “positive pole.”
– What the IAU now calls the “positive pole” is still referred to as the “north pole” in
SPICE documentation.
– The “positive pole” may point above or below the invariable plane of the solar
system (see above).
– This revision by the IAU Working Group (2006) inverts what had been the direction of
the north pole for Pluto, Charon and Ida.

*The dwarf planets are: Ceres, Pluto, Haumea, Makemake, Eris

PCK Subsystem 8
 N IF Binary PCK Orientation Models
Navigation and Ancillary Information Facility

• When available, the SPICE system can store high-

accuracy orientation model data in binary PCKs.
• Binary PCKs are limited to storing orientation data.
– Applications that require shape data must also load a text PCK.
• Orientation data from a binary PCK always supersede
orientation data for the same object obtained from a text
PCK, no matter the order in which the kernels are loaded.
• Binary PCKs for the earth and the moon are available
from the NAIF server.
– The accuracy of these is much better than what is
provided in the generic text PCK.
– See the tutorial "lunar-earth_pck-fk" for details.

PCK Subsystem 9
 Location of Text PCK
N IF Reference Frame Specifications
Navigation and Ancillary Information Facility

• Many PCK reference frame specifications are built into

SPICE. Examples are IAU_SATURN and IAU_TITAN.
– To use these, load a text PCK file containing orientation data for
the body of interest.
» Typically this is the current generic text PCK
– Be very cautious about using IAU_EARTH and IAU_MOON; the binary
PCKs for these two bodies offer much more accuracy.
– Data for a small number of comets and asteroids are included.

• Other PCK frames are not built-in and must be defined in

a frames kernel that is loaded by your program.
Examples are body fixed frames for asteroids or “newer”
natural satellites.
– See the Frames Required Reading technical reference for information on
creating frame kernels that specify PCK reference frames.
PCK Subsystem 10
 Location of Binary PCK
N IF Reference Frame Specifications
Navigation and Ancillary Information Facility

• Special high-accuracy earth and lunar body-fixed

frames are realized using binary PCKs.
– These frames are named:
» For the earth: ITRF93
» For the moon: MOON_PA and MOON_ME

• To use high-accuracy earth or moon orientation,

load the appropriate binary PCK and allied FK.
– See the special tutorial “lunar-earth_pck-fk” for details on these.

PCK Subsystem 11
 N IF PCK Shape Models
Navigation and Ancillary Information Facility
• PCK shape models are nominally triaxial ellipsoids
– For many bodies, the two equatorial axes have the same value;
these bodies have a spheroidal shape.
– For some bodies, one or more radii have not been determined.
– See the DSK tutorial for information about other kinds of shape
models available within SPICE.

• Although many bodies are in fact modeled as spheres or

spheroids, SPICE usually deals with the general, triaxial
case.
– Exception: SPICE supports geodetic coordinate transformations
only for bodies modeled as spheres or spheroids.
» RECGEO, GEOREC, DGEODR, DRDGEO and XFMSTA are the modules
performing these transformations.
– Exception: SPICE supports planetographic coordinate
transformations only for bodies modeled as spheres or
spheroids.
» PGRREC, RECPGR, DPGRDR, DRDPGR and XFMSTA are the modules
PCK Subsystem
supporting these transformations. 12
 N IF Using PCK Data
Navigation and Ancillary Information Facility

• PCK orientation data are usually accessed using frame

subsystem or ephemeris subsystem APIs.
– Example: Get the IAU_SATURN body-fixed reference frame to J2000
position or state transformation matrix at ET:
» CALL PXFORM ( 'IAU_SATURN', 'J2000', ET, RMAT ) or t ran
F
a m ples
» CALL SXFORM ( 'IAU_SATURN', 'J2000', ET, XFORM ) ex

– Example: Get the state of Saturn relative to Cassini in the IAU_SATURN

body-fixed reference frame:
» CALL SPKEZR ( 'SATURN', ET, 'IAU_SATURN', 'LT+S', 'CASSINI', STATE, LT )

• PCK shape data are usually accessed using APIs needing

size and shape data such as SUBPT, SUBSLR, ILUMIN,
etc.

PCK Subsystem 13
 N IF Interface Routines - 1
Navigation and Ancillary Information Facility

• Call FURNSH to load PCKs.

– CALL UNLOAD or KCLEAR to unload them.
• Call SXFORM to return a state transformation.
– Returns 6x6 matrix (attitude and angular velocity)
» CALL SXFORM ( FROM, TO, ET, XFORM )
• Call PXFORM to return a position transformation. or t ran
F
a m ples
– Returns 3x3 matrix (attitude only) ex
» CALL PXFORM ( FROM, TO, ET, RMAT )
• Get state of Saturn relative to Cassini in the IAU_SATURN
body-fixed reference frame:
– CALL SPKEZR ( 'SATURN', ET, 'IAU_SATURN', 'LT+S', 'CASSINI', STATE, LT )
• Get state of Cassini relative to the DSN station DSS-13 in the
J2000 inertial reference frame:
– CALL SPKEZR ( 'CASSINI', ET, 'J2000', 'LT+S', 'DSS-13', STATE, LT )
» An Earth PCK must be loaded in order for this call to work, even though the
requested output reference frame is inertial.
• That’s because, in the course of its work, this call must convert the position of the
DSN station relative to the Earth’s center from an Earth-fixed, earth-centered
frame to the J2000 frame.

PCK Subsystem 14
 N IF Interface Routines - 2
Navigation and Ancillary Information Facility
ran
Fort ples
m
exa

• Call BODVRD or BODVCD to retrieve constants associated with a

body. For example:
– CALL BODVRD ( 'SATURN', 'RADII', 3, N, RADII )
– CALL BODVCD ( 699, 'RADII', 3, N, RADII )

– These calls retrieve values associated with the variable BODY699_RADII.

– The variable name is case-sensitive, so the string, RADII, above must be in upper case.

• You can use general kernel pool fetch routines to fetch data
assigned to any non-standard names.
– GCPOOL, for character data
– GDPOOL, for double precision data
– GIPOOL, for integer data

PCK Subsystem 15
 N IF PCK Precedence Rules
Navigation and Ancillary Information Facility

• In text PCKs, assignments are of two types:

» “Direct”: variable name = value(s)
» “Incremental”: variable name += value(s)
– The last direct assignment made to a given variable replaces any/all
previous assignments for that variable.
– Incremental assignments simply add additional values to an existing
variable.
» The variable will be newly created if it didn’t already exist.
• The sets of rotation model keywords that apply to the same
body may be different in different PCKs and may “interfere”
with each other
– NAIF recommends unloading any text PCK that is meant to be
overridden by another text PCK loaded later to prevent data from the
first PCK remaining in the POOL and being used erroneously.
• Orientation data from a binary PCK always supersede
orientation data (for the same object) obtained from a text
PCK, no matter the order in which the kernels have been
loaded.
PCK Subsystem 16
 N IF PCK Utility Programs
Navigation and Ancillary Information Facility

• These utilities are included in the Toolkit.

BRIEF summarizes coverage for one or more binary PCK files
SPACIT generates segment-by-segment summary of a binary PCK file
COMMNT reads, appends, or deletes comments in a binary PCK file
FRMDIFF samples a PCK-based frame or compares orientation of two PCK-
based frames (binary or text PCKs)

• These additional utilities are provided on the NAIF Web

site (http://naif.jpl.nasa.gov/naif/utilities.html).
BFF displays binary file format of a binary PCK file
BINGO converts binary PCK files between big-endian and little-endian formats

PCK Subsystem 17
 N IF Additional Information on PCK
Navigation and Ancillary Information Facility

• For more information about PCKs, look at the

following:
– Most Used Routines document
– PCK Required Reading document
– Headers of the routines mentioned
– Lunar/Earth High-Precision PCK/FK tutorial
– BRIEF and FRMDIFF User’s Guides

• Related documents:
– Frames Required Reading
– Kernel Required Reading
– NAIF_IDS Required Reading
– Time Required Reading

PCK Subsystem 18
N IF
Navigation and Ancillary Information Facility

“Camera-matrix” Kernel
CK
(Orientation or Attitude Kernel)

Focused on reading CK files

April 2023
 N IF CK File Contents - 1
Navigation and Ancillary Information Facility

• A CK file holds orientation data for a spacecraft or a moving

structure on the spacecraft
– “Orientation data” Þ quaternions, from which orientation matrices are
formed by SPICE software. These matrices are used to rotate position
vectors from a base reference frame (the “from” frame) into a second
reference frame (the “to” frame)
» In SPICE this is often called the “C-matrix or “Camera matrix”
– Optionally may include angular velocity of the “to” frame with respect to
the “from” frame
» Angular velocity vectors are expressed relative to the “from” frame.

• A CK file should also contain comments–sometimes called

metadata–that provide some details about the CK such as:
– the purpose for this particular CK
– when and how it was made
– what time span(s) the data cover

C-Kernel 2
 N IF CK File Contents - 2
Navigation and Ancillary Information Facility

• A single CK file can hold orientation data for

one, or for any combination of spacecraft or
spacecraft moving structures
– Some examples
1. Huygens Probe
2. Cassini Orbiter and its CDA instrument mirror
3. Mars Express Orbiter, PFS scanner, Beagle Lander
4. MRO orbiter, MRO high gain antenna, MRO solar arrays

• But in most cases CKs contain data for just one

structure

C-Kernel 3
 N IF C-Kernel Varieties - 1
Navigation and Ancillary Information Facility

• “Reconstruction” CK (also called “definitive” CK)

– A CK file can be made from downlinked orientation telemetry returned
from a spacecraft or other structure
– A CK might also be made from some process that improves upon the
pointing determined from downlinked telemetry ("C-smithing")
– Most often used for science data analysis or spacecraft performance
analysis

• “Predict” CK
– A CK file can be made using information that predicts what the
orientation will be some time in the future
» Input data usually come from a modeling program, or a set of
orientation rules
– Most often used for science observation planning, quick-look
science data analysis, engineering assessments and software
testing
» If of known high quality, it might be used to substitute for
any data gaps in reconstruction CKs
» In some cases the predict meets the reconstruction accuracy
requirements; thus a true reconstruction CK is not generally
produced
C-Kernel 4
 N IF C-Kernel Varieties - 2
Navigation and Ancillary Information Facility

• Knowledge of CK variety–“reconstruction” or
“predict”–might be implicit in the file naming
schema, and/or might be provided in the comment
section, but is not available using a SPICE API

• It is inadvisable that both “reconstruction” and

“predict” data be combined in a single file

C-Kernel 5
 N IF CK Data Types
Navigation and Ancillary Information Facility

The underlying orientation data are of varying types, but

the user interface to each of these CK types is the same.

Rotation matrix and Angular Velocity

Any CK Reader Module

CK CK CK CK CK
Type 1* Type 2 Type 3 Type 4* Type 5 6
Discrete Piecewise Constant Linear Chebyshev ESOC
Points Angular Velocity Interpolation Polynomials DDID

Discrete data “Continuous” data

type types
* types 1 and 4 are rarely used
C-Kernel 6
 N IF Kernel Data needed
Navigation and Ancillary Information Facility

• To obtain orientation one needs at least three SPICE kernel types:

CK, SCLK, and LSK.

– CK contains spacecraft or other structure orientation.

– SCLK and LSK contain time correlation coefficients used to convert between
encoded spacecraft clock time (SCLK) and ephemeris time (ET).
» Sometimes an LSK is not needed in this conversion, but it’s best to have
it available as it is usually needed for other purposes.

• One may also need an FK if planning to access CK data via high

level SPICE interfaces (PXFORM, SXFORM, SPKPOS, etc).

– FK associates reference frames with CK data via CK IDs.

C-Kernel 7
 N IF What SPICE Routines Access CKs?
Navigation and Ancillary Information Facility

• High-level SPICELIB routines are used more often than the

“original” CK readers to access CK data. These high-level
routines are:
– Position or state transformation matrix determination
» PXFORM, PXFRM2: return a rotation matrix (3x3) from one frame
to another, either of which can be a CK-based frame or have CK-
based frames as “links” in its chain
» SXFORM: return a state transformation matrix (6x6) from one
frame to another, either of which can be a CK-based frame or have
CK-based frames as “links” in its chain
– Position or state vector determination
» SPKPOS: return a position vector (3x1) in a specified frame, which
can be a CK-based frame or have CK-based frames as “links” in
its chain
» SPKEZR: return a state vector (6x1) in a specified frame, which
can be a CK-based frame or have CK-based frames as “links” in
its chain
• Use of the above mentioned routines is discussed in the FK,
Using Frames, and SPK tutorials
• The “original” CK access routines are CKGP and CKGPAV
– Use of these routines is described in the BACKUP section of this
tutorial
C-Kernel 8
 N IF An Example of Project CK Files
Navigation and Ancillary Information Facility

CASSINI HUYGENS CASSINI

SPACECRAFT PROBE CDA MIRROR

-82000 -150000 -82791

A user’s program must be able to load as many of these files as

needed to satisfy his/her requirements. It is strongly recommended
that users’ programs have the flexibility to load a list of CK files
provided to the program at run time; this is easily accomplished
using the Toolkit's FURNSH routine.

C-Kernel 9
 N IF Sample* CK File Coverage - 1
Navigation and Ancillary Information Facility

Cassini
orbiter CK:

Huygens
probe CK:

Cassini
instrument
mirror CK:
cruise phase orbit phase

Launch Orbit Probe End of

Time line: Insertion Release Mission
* Note: This is not an actual Cassini/Huygens scenario; it is a highly simplified illustration
of some of the possibilities for orientation delivery on a planetary mission.
C-Kernel 10
 N IF Sample CK Data Coverage - 2
Navigation and Ancillary Information Facility

Even though a project's CK production process may suggest that CK files provide
continuous coverage for the interval of time for which they were generated, in
reality this is rarely the case. CK files very often contain gaps in coverage! An
example of this is depicted below.
Time

Coverage of … Tstart Tstop

a CK file:
as appears in file name/comments

CK file segments:
as appears in ckbrief/spacit summary

CK segments having data gaps:

(CK Types 2 - 6)
data gaps data gaps
within a segment within a segment

The blue line segments represent interpolation intervals – times when

pointing will be returned. For attitude requests within gaps, high level
SPICE APIs will signal an error.
C-Kernel 11
 N IF What is an Interpolation interval?
Navigation and Ancillary Information Facility

• An interpolation interval is a time period for which routines

that access CKs can compute and return pointing.
– For CK Types 3, 5 and 6 the pointing is computed by interpolating
between the attitude data points that fall within the interval.
– For CK Type 2 the pointing within each interval is computed by
extrapolating from a single attitude and associated angular velocity.
– For CK Type 4 the pointing is computed by evaluating polynomials
covering the interval.
– For CK Type 1 (discrete pointing instances) the notion of an
interpolation interval is not relevant.

• The time periods between interpolation intervals are gaps

during which CK access routines are not able to compute
pointing.

• The interpolation intervals in Type 3 CK segments can be

modified without changing the actual pointing data.
– The CKSPANIT and CKSMRG programs are used to make these
changes.
C-Kernel 12
 N IF How are Requests Falling in Gaps Handled?
Navigation and Ancillary Information Facility

• When using high-level SPICE routines* in a

fashion that requires CK data, if the time of your
requested computation falls within a CK gap
(thus, outside of a CK interpolation interval), the
routine will signal an error.
– Usually this is a frame-related error
• If using a low-level CK reader, CKGP or CKGPAV,
valid pointing data will not be returned and the
reader's "found flag" will be set to false.
– Be sure to check the "found flag!"

* For example: SPKEZR, SPKPOS, SXFORM, PXFORM, SINCPT

C-Kernel 13
 N IF Obtaining Coverage of a CK File
Navigation and Ancillary Information Facility

• High-level subroutine interfaces allow for obtaining CK coverage

information.
– Call CKOBJ to find the set of structures for which a specified CK provides data.
» INPUT: a CK file name and initialized SPICE integer “Set” data structure.
The set may optionally contain ID codes obtained from previous calls.
» OUTPUT: the input set, to which have been added (via set union) the ID
codes of structures for which the specified CK provides coverage.
CALL CKOBJ ( CK, IDS )
– Call CKCOV to find the window of times for which a specified CK file provides
coverage for a specified structure:
» INPUT: a CK file name, structure ID code, flag indicating whether angular
rates are needed, flag indicating whether coverage on segment or interval
level is to be returned, tolerance, output time system, and initialized SPICE
double precision “Window” data structure. The window may optionally
contain coverage data from previous calls.
» OUTPUT: the input window, to which have been added (via window union)
the sequence of start and stop times of coverage intervals of the specified
CK, expressed as encoded SCLK or ET seconds past J2000.
CALL CKCOV ( CK, ID, NEEDAV, LEVEL, TOL, TIMSYS, COVER)
• See the headers of these routines for example programs.
• Also see the CELLS, SETS and WINDOWS Required Reading for
background information on these SPICE data types.
C-Kernel 14
 N IF Using CKCOV
Navigation and Ancillary Information Facility

• When using high-level routines* that need

orientation data from a C-kernel, it's often a good
idea to first determine what are the valid
interpolation intervals in your CK using CKCOV.
– If using multiple CKs, all of which are needed to construct a
frame chain, call CKCOV for each one and then intersect the
coverage windows. (wnintd is the SPICE intersection API.)
• Then check each time of interest for your
geometry calculations against the window of valid
intervals before proceeding onwards.

* For example: SPKEZR, SPKPOS, SXFORM, PXFORM, SINCPT

C-Kernel 15
 N IF Determine Coverage Using Utilities
Navigation and Ancillary Information Facility

• Three Toolkit utility programs can provide various

kinds of CK summaries, including listings of gaps
or of interpolation intervals
– CKBRIEF
– FRMDIFF
– SPACIT

C-Kernel 16
 N IF Summarizing a CK File - 1
Navigation and Ancillary Information Facility

• A summary of a CK can be made using CKBRIEF

– At your command prompt, type the program name followed by the names of
CK, LSK and SCLK files (given in any order)
– The basic summary based on segment coverage does not show gaps within
segments.

% ckbrief 07102_07107ra.bc naif0008.tls cas00106.tsc

CKBRIEF-Version 6.1.0, June 27, 2014-Toolkit Version N0067

Summary for: 07102_07107ra.bc

Object: -82000
Interval Begin ET Interval End ET AV
------------------------ ------------------------ ---
2007-APR-12 00:01:06.462 2007-APR-17 00:01:03.726 Y

C-Kernel 17
 N IF Summarizing a CK File - 2
Navigation and Ancillary Information Facility

• A summary of interpolation intervals within a CK can be made with

CKBRIEF, using its ‘-dump’ option

% ckbrief –dump 07102_07107ra.bc naif0008.tls cas00106.tsc

CKBRIEF Ver 3.2.0, 2006-11-02. SPICE Toolkit Version: N0061.

Summary for: 07102_07107ra.bc

Segment No.: 1

Object: -82000
Interval Begin ET Interval End ET AV
------------------------ ------------------------ ---
2007-APR-12 00:01:06.462 2007-APR-12 05:58:02.576 Y
2007-APR-12 05:58:22.576 2007-APR-12 21:34:26.221 Y
. . .
C-Kernel continued on next page 18
 N IF Summarizing a CK File - 3
Navigation and Ancillary Information Facility
continued from previous page

• A summary of interpolation intervals within a CK can also be made

using FRMDIFF, using its ‘-t dumpc’ option
• A summary of gaps between interpolation intervals in a CK can be
made using FRMDIFF, using its ‘-t dumpg’ option

% frmdiff -t dumpg \
–k cas_v40.tf naif0008.tls cas00106.tsc \
-f 'YYYY-DOYTHR:MN:SC ::RND' \
07102_07107ra.bc
#
# . . . <FRMDIFF report header> . . .
#
# gap_start, gap_stop, gap_duration_sec, gap_duration_string
2007-102T05:56:57 2007-102T05:57:17 19.999 0:00:00:19.999
2007-102T21:33:21 2007-102T21:33:41 19.999 0:00:00:19.999
2007-102T21:34:57 2007-102T21:35:25 27.999 0:00:00:27.999
. . .
C-Kernel 19
 N IF Summarizing a CK file - 4
Navigation and Ancillary Information Facility

• A detailed summary of a CK can be made using SPACIT. See the

SPACIT User's Guide for details.

--------------------------------------------------------------
Segment ID : CASSINI ATT: -Y TO TITAN, +Z - VELCTY
Instrument Code: -82000
Spacecraft : Body -82, CAS
Reference Frame: Frame 1, J2000
CK Data Type : Type 3
Description : Continuous Pointing: Linear Interpolation
Available Data : Pointing and Angular Velocity
UTC Start Time : 2005 FEB 15 07:59:59.999
UTC Stop Time : 2005 FEB 15 08:59:59.998
SCLK Start Time: 1/1487147147.203
SCLK Stop Time : 1/1487150747.209
--------------------------------------------------------------
. .
. .
etc. etc.

C-Kernel 20
 N IF CK Utility Programs
Navigation and Ancillary Information Facility

• The following CK utility programs are included in the Toolkit:

CKBRIEF summarizes coverage for one or more CK files
SPACIT generates segment-by-segment summary of a CK file
COMMNT reads, appends, or deletes comments in an CK file
MSOPCK converts attitude data provided in a text file into a CK file
FRMDIFF samples or compares orientation of CK-based frames
• These additional CK utility programs are provided on the
NAIF Web site (https://naif.jpl.nasa.gov/naif/utilities.html)
CKSLICER subsets a CK file
CKSMRG merges segments in a type 3 CK file (*)
DAFCAT concatenates together CK files (*)
CKSPANIT modifies interpolation interval information in a Type 3 CK file
DAFMOD alters structure or frame IDs in a CK file
PREDICKT creates a CK file representing an orientation profile
described by a set of orientation rules and a schedule
BFF displays binary file format of a CK file
BINGO converts CK files between IEEE and PC binary formats
(*) DAFCAT and SKSMRG are frequently used together to first merge many CK files into a
single file using DAFCAT and then merge segments inside the merged file using CKSMRG.

C-Kernel 21
 N IF Additional Information on CK
Navigation and Ancillary Information Facility

• For more information about CK, look at the

following documents
– The on-line version of this tutorial, including a BACKUP
section that highlights typical problems encountered
– CK Required Reading
– headers for the CKGP and CKGPAV routines
– Most Used SPICELIB Routines
– CKBRIEF and FRMDIFF User’s Guides
– Frames tutorials: FK and Using Frames don’t miss these
– Porting kernels tutorial
• Related documents
– SCLK Required Reading
– Time Required Reading
– Frames Required Reading
– NAIF IDs Required Reading
– Rotations Required Reading
C-Kernel 22
 N IF Backup
Navigation and Ancillary Information Facility

• The meaning of Tolerance

• Examples of Problems Encountered When Using

the CK Subsystem

• Using the CK “reader” APIs

C-Kernel 23
 N IF The Meaning of Tolerance - 1
Navigation and Ancillary Information Facility

• The low level CKGP and CKGPAV routines use a

time tolerance, “tol,” measured in ticks, in
executing pointing lookups.
– No matter whether your CK is a discrete type (Type 1) or a
continuous type (Types 2 - 6), if pointing information is not
found within +/- tol of your pointing request time, no pointing
will be returned and the “found flag” will return as “FALSE.”
– For Type 1 (discrete) CKs, the pointing instance nearest* to
your request time will be returned, as long as it is within tol of
your request time.
» If the nearest pointing instances on each side of your
request time are equidistant from your request time, the
instance with the later time tag will be selected.
– For Types 2 - 6 (continuous pointing), pointing for exactly your
request time will be returned if this time falls anywhere within
an interpolation interval.
– For all Types, the time tag associated with the pointing data will
also be returned.
• See the next three charts for graphic depictions.
*Ignoring segment priority
C-Kernel 24
 N IF The Meaning of Tolerance - 2
Navigation and Ancillary Information Facility

When reading a Type 1 CK containing discrete pointing instances

SCLKDP TOL
\ /
| |
|/ \
“+” marks your request [---+---]
. . .
Available data (0----0--0--0--0--0---0--0--0--0-----0--0--0)

A SPICELIB CK reader returns this pointing instance

• “0” is used to represent discrete pointing instances (quaternions)

• “()” are used to represent the end points of a segment within a CK file
• SCLKDP is the time at which you have requested pointing
• TOL is the time tolerance you have specified in your pointing request
• The quaternions occurring in the segment need not be evenly spaced in
time
C-Kernel 25
 N IF The Meaning of Tolerance - 3
Navigation and Ancillary Information Facility

When reading a Type 2, 3, 4, 5 or 6 CK (continuous pointing), with a

“pointing request” that falls within a span of continuous pointing (an
“interpolation interval”)
SCLKDP
\ TOL
| /
|/\
“+” marks your request [--+--]
. . .
Available data (==----=============---======------===--)

A SPICELIB CK reader returns pointing at precisely the requested epoch

• “==” is used to indicate interpolation intervals of continuous pointing

• “()” are used to represent the end points of a segment within a CK file
• SCLKDP is the time at which you have requested pointing
• TOL is the time tolerance you have specified in your pointing request; for
this particular case it does not come into play
• The quaternions occurring in the periods of continuous pointing need
not be evenly spaced in time
C-Kernel 26
 N IF The Meaning of Tolerance - 4
Navigation and Ancillary Information Facility

When reading a Type 2, 3, 4, 5 or 6 CK (continuous pointing), with a

“pointing request” that is NOT within a span of continuous pointing (an
“interpolation interval”)
SCLKDP
\ TOL
| /
|/\
“+” marks your request [--+--]
. . .
Available data (--==============----======------===--)

A SPICELIB CK reader returns pointing at the epoch closest to

the request time, if this is within TOL of that request time.

• “==” is used to indicate interpolation intervals of continuous pointing

• “()” are used to represent the end points of a segment within a CK file
• SCLKDP is the time at which you have requested pointing
• TOL is the time tolerance you have specified in your pointing request
• The quaternions occurring in the periods of continuous pointing need not
be evenly spaced in time
C-Kernel 27
 N IF Problems using CK - 1
Navigation and Ancillary Information Facility

• The file or files you loaded do not contain

orientation data for the object of interest.
– Make sure the ID that you use in a call to CKGP or CKGPAV
matches one in the CK file(s) you have loaded.
– Make sure the frame that you specify in a call to SXFORM,
PXFORM, SPKEZR, or SPKPOS is transformable to one
available in the loaded CK files.

• One of the low-level routines, CKGP or CKGPAV,

returns a transformation matrix and/or angular
velocity that does not appear correct.
– Probably the FOUND flag is “FALSE” and you are using data
left over from a previous query. Remember to always check the
FOUND flag! (If the FOUND flag is “TRUE” but the data seem
bad, contact the data producer.)

C-Kernel 28
 N IF Problems using CK - 2
Navigation and Ancillary Information Facility
• The file, or files, you loaded do not cover the time at
which you requested orientation
– Check file coverage on the segment level by summarizing the file(s)
using CKBRIEF or SPACIT
– Check interpolation interval coverage using CKBRIEF with option
“-dump,” or by examining comments provided in the comment area
of the file - you may be asking for data within a coverage gap (your
request time is outside of interpolation intervals)
• One of the high-level routines (SPKEZR, SPKPOS,
SXFORM, PXFORM, SINCPT) signals an error
– These routines read CK files using tolerance = 0
» For discrete CKs (Type 1) the orientation of a CK-based frame
will be computed only if the time provided to a Frames routine
exactly matches one of the times stored in the CK file;
otherwise an error will be signaled.
» For continuous CKs (all but Type 1) the orientation of a CK-
based frame will be computed only if the time provided to a
frame routine falls within one of the interpolation intervals
defined by the CK file; otherwise an error will be signaled.
C-Kernel 29
 N IF Problems using CK - 3
Navigation and Ancillary Information Facility

• You’ve confirmed not having any of the

previously described problems, but the FOUND
flag returns as “FALSE” when using CKGPAV, or
SXFORM or SPKEZR signals a frame related error.
– You are using a SPICE routine that requires angular velocity as
well as orientation, but the CK segments available at your
requested epoch don’t contain angular velocity.
» Routines requiring AV are: CKGPAV, SXFORM, SPKEZR
» Routines not requiring AV are: CKGP, PXFORM, SPKPOS

C-Kernel 30
 N IF Problems using CK - 4
Navigation and Ancillary Information Facility

• The FOUND flag returns as “TRUE” when using CKGPAV but

returned angular velocity does not appear correct.
– While many sources of angular rate data, for example spacecraft
telemetry, specify it relative to the spacecraft frame, SPICE CK files
store it, and CKGPAV returns it, with respect to the base frame. So the
sense of returned angular velocity in a CK may be unexpected.

• The FOUND flag returns as “TRUE” when using

CKGP/CKPGAV but the quaternion computed from the
returned transformation matrix via a call to M2Q does not
appear correct.
– The quaternion returned by M2Q follows the SPICE style, which is
different from the quaternion styles used by some other sources of
orientation data, for example most spacecraft telemetry.
» See the headers of the M2Q and Q2M routines, and the Rotations
Required Reading technical reference document for more details.
» NAIF prepared a “white paper” explaining differences between
various quaternion styles commonly used in space applications:
• https://naif.jpl.nasa.gov/pub/naif/misc/Quaternion_White_Paper/Quaterni
ons_White_Paper.pdf

C-Kernel 31
 N IF Problems using CK - 5
Navigation and Ancillary Information Facility

• You’re trying to use a CK file that is not properly

formatted for your computer
– You can read only a binary CK file with the CK subroutines; you
can’t read a “transfer format” file
» Although not required, binary CK files often have a name like
“xxxxxx.bc”
» Although not required, transfer format CK files often have a
name like “xxxxxx.xc”
– If using Toolkit Version N0051 or earlier you must have the proper
kind of CK binary file for your computer (a native binary file)
» PC (Windows or Linux) and Mac OSX use the IEEE Little-endian
binary standard
» Sun and very old Mac (Motorola cpu) use the IEEE Big-endian
binary standard
» The pair of utility programs named TOBIN and TOXFR, or the
utility program SPACIT, can be used to port CK files between
computers having incompatible binary standards

C-Kernel 32
 N IF One Example of How To Read a CK File
Navigation and Ancillary Information Facility

Initialization ... typically once per program run

Tell your program which SPICE files to use (“loading” files)
CALL FURNSH( 'lsk_file_name' )
Better yet, use a “furnsh kernel”
CALL FURNSH( 'sclk_file_name' ) to load all the needed files.
CALL FURNSH( 'ck_file_name' )

Loop ... do as often as you need

Convert UTC to SCLK ticks *
CALL STR2ET( 'utc_string', tdb )
CALL SCE2C ( spacecraft_id, tdb, sclkdp )

Get rotation matrix, or rotation matrix and angular velocity at requested time
or
CALL CKGP (instid,sclkdp,tol,'ref_frame',cmat, clkout,found)
CALL CKGPAV (instid,sclkdp,tol,'ref_frame',cmat,av,clkout,found)
inputs outputs

* Although most spacecraft have a single on-board clock and this clock has the same ID as the spacecraft, the user
should know which SCLK was used to tag data in a CK file in order to specify the correct ID in a call to SCE2C.

C-Kernel 33
 N IF Arguments of CKGPAV
Navigation and Ancillary Information Facility
Inputs
instid NAIF ID for the spacecraft, instrument or other structure for which the
orientation is to be returned
sclkdp the time at which the orientation matrix and angular velocity are to be
computed. The time system used is encoded spacecraft clock time (SCLK).
The units are ticks since the zero epoch of the clock
tol* the tolerance, expressed as number of SCLK ticks, to be used in searching
for and computing the orientation data
ref_frame the name of the reference frame with respect to which the orientation is to
be computed. This is also called the “base” or “from” frame.
Outputs
cmat the 3x3 rotation matrix that you requested
av the angular velocity that you requested
clkout the exact time for which the orientation and angular velocity was
computed
found the logical flag indicating whether the orientation and angular velocity data
were found. Note that if the loaded CK file(s) do not contain angular
velocity data, CKGPAV will return a FALSE found flag even if orientation
could have been computed. If “found” is .FALSE., then the values of the
output arguments “cmat” and “av” are undefined and should not be used!
Always check the FOUND flag returned by CKGPAV and CKGP!

* tol is explained in detail earlier in these backup slides

C-Kernel 34
N IF
Navigation and Ancillary Information Facility

Frames Kernel
FK

April 2023
 N IF Background
Navigation and Ancillary Information Facility

• First, reminders of what SPICE means by:

– reference frame
– coordinate system

Frames Subsystem 2
 N IF What is a Reference Frame?
Navigation and Ancillary Information Facility

• Within SPICE, a reference frame is specified by three

orthogonal axes
Z

• It may be fixed in space (not rotating, not accelerating)

– This is called an inertial frame
• It may be changing its orientation in space
– This is called a non-inertial frame
• Every frame has a name and a numeric ID assigned to it
– You’ll use the name as an argument in calling Toolkit APIs
• Every frame has an associated center location

Frames Subsystem 3
 N IF What is a Coordinate System?
Navigation and Ancillary Information Facility

• Within SPICE, a coordinate system is the method used to

specify a vector within a reference frame. Examples:

Rectangular Spherical Cylindrical

coordinates coordinates coordinates
X, Y, Z !, ", # $, Z, R

Frames Subsystem 4
 N IF Introduction
Navigation and Ancillary Information Facility

What does the SPICE FRAMES subsystem do?

1. It establishes relationships between reference frames used
in geometry computations – it "chains frames together” in
a frame tree.

2. It connects frames with the sources of their orientation

specifications.
– In some cases those data are included in the Frames kernel
itself. In other cases they are provided in other types of
kernels.

Based on these relationships and the orientation source

information, the frames subsystem allows SPICE software to
compute rotations between neighboring frames in the frame
tree, and to combine these rotations in the right order, thus
providing an ability to compute the orientation of any frame in
the tree with respect to any other frame in the tree, at any time.
Frames Subsystem 5
 N IF Sample Frame Tree
Navigation and Ancillary Information Facility
Inertial
J2000
frame
PCK-based
Saturn PCK-based transformation
Body-fixed transformation
frame Earth
Body-fixed
frame
PCK-based
transformation
Titan
CK based body-fixed
transformation frame

Topocentric
ISS NAC Frame at the
instrument landing site
frame

Fixed offset
transformation
Cassini
spacecraft
frame

Frames Subsystem 6
 N IF Frame Names
Navigation and Ancillary Information Facility

• Frame names are character strings used to

identify frames to Toolkit APIs

• Examples of frame names:

– J2000
– IAU_MARS
– DAWN_SPACECRAFT
– MEX_OMEGA
– DSS-14_TOPO

Frames Subsystem 7
 N IF Where to Find the Names of Frames?
Navigation and Ancillary Information Facility

• Refer to the “NAIF IDs” Tutorial for an introduction to

reference frame names and IDs

• Refer to the FRAMES.REQ document for the list of NAIF

“built in” (hard coded) inertial and body-fixed frames

• Refer to a mission’s Frames Kernel (FK) file for a list of

frames defined for the spacecraft, its subsystems and
instruments

• Refer to an earth stations FK for a list of frames defined for

the DSN and other stations

• Refer to the moon FKs for names and descriptions of the

body-fixed frames defined for the moon

Frames Subsystem 8
 N IF Frame Classes and Examples
Navigation and Ancillary Information Facility
Frame class Frame Examples (with real frame names)

Inertial • Earth Equator/Equinox of Epoch (ICRF, also called J2000 in SPICE)

• Planet Equator/Equinox of Epoch (MARSIAU, ...)
• Ecliptic of Epoch (ECLIPJ2000, ...)

Body-fixed • Solar system body IAU frames (IAU_MARS, IAU_SATURN, …)

• High accuracy Earth frames (ITRF93, …)
• High accuracy Moon frames (MOON_PA, MOON_ME)

CK-based • Spacecraft (CASSINI_SC_BUS, …)

• Moving parts of an instrument (MPL_RA_JOINT1, ...)

Fixed Offset • Instrument mounting alignment (CASSINI_ISS_NAC, …)

• Topocentric (DSS-14_TOPO, …)

Dynamic • Geomagnetic
• Geocentric Solar Equatorial
• Planet true equator and equinox of date

Switch • Spacecraft frame switching between reconstructed and predicted CK frames

• Nominal attitude profile frame switching between dynamic frames
Frames Subsystem 9
 N IF Frame Class Specifications
Navigation and Ancillary Information Facility

Frame class Frame Defined in: Orientation data provided in:

Inertial Toolkit software Toolkit software

Body-fixed Toolkit software or FK PCK (text or binary style)

CK based FK CK

Fixed offset FK FK

Dynamic FK Toolkit software, or computed

using FK, SPK, CK, and/or PCK
Switch FK Toolkit software, or computed
using FK, SPK, CK, and/or PCK

Frames Subsystem 10
 N IF Frames Kernel File Overview
Navigation and Ancillary Information Facility

• Uses the SPICE text kernel standards

• Loaded using the FURNSH routine
• Usually contains comprehensive information about the
defined frames in the comment section(s) of the file
• Contains frame definition information consisting of a set of
keywords in the data sections of the file. Below are examples
defining a CK-based frame and a fixed-offset frame.
CK-based Frame Example Fixed-offset Frame Example
FRAME_DAWN_SPACECRAFT = -203000 FRAME_DAWN_FC1 = -203110
FRAME_-203000_NAME = 'DAWN_SPACECRAFT' FRAME_-203110_NAME = 'DAWN_FC1'
FRAME_-203000_CLASS = 3 FRAME_-203110_CLASS = 4
FRAME_-203000_CLASS_ID = -203000 FRAME_-203110_CLASS_ID = -203110
FRAME_-203000_CENTER = -203 FRAME_-203110_CENTER = -203
CK_-203000_SCLK = -203 TKFRAME_-203110_RELATIVE = 'DAWN_SPACECRAFT'
CK_-203000_SPK = -203 TKFRAME_-203110_SPEC = 'ANGLES'
TKFRAME_-203110_UNITS = 'DEGREES'
TKFRAME_-203110_ANGLES = ( 0.0, 0.0, 0.0 )
TKFRAME_-203110_AXES = ( 1, 2, 3 )

• These examples are discussed in detail in the next few slides

Frames Subsystem 11
 N IF Frame Definition Details - 1
Navigation and Ancillary Information Facility

Frame definition for the DAWN spacecraft Frame definition for the DAWN Framing Camera #1
FRAME_DAWN_SPACECRAFT = -203000 FRAME_DAWN_FC1 = -203110
FRAME_-203000_NAME = 'DAWN_SPACECRAFT' FRAME_-203110_NAME = 'DAWN_FC1'
FRAME_-203000_CLASS = 3 FRAME_-203110_CLASS = 4
FRAME_-203000_CLASS_ID = -203000 FRAME_-203110_CLASS_ID = -203110
FRAME_-203000_CENTER = -203 FRAME_-203110_CENTER = -203
CK_-203000_SCLK = -203 TKFRAME_-203110_RELATIVE = 'DAWN_SPACECRAFT'
CK_-203000_SPK = -203 TKFRAME_-203110_SPEC = 'ANGLES'
TKFRAME_-203110_UNITS = 'DEGREES'
TKFRAME_-203110_ANGLES = ( 0.0, 0.0, 0.0 )
TKFRAME_-203110_AXES = ( 1, 2, 3 )

• The Frame ID, shown in red in the two examples

above, is an integer number used by the SPICE
system as a “handle” in buffering and retrieving
various parameters associated with a frame. In an FK
it “glues together” the keywords defining the frame.

Frames Subsystem 12
 N IF Frame Definition Details - 2
Navigation and Ancillary Information Facility

Frame definition for the DAWN spacecraft Frame definition for the DAWN Framing Camera #1
FRAME_DAWN_SPACECRAFT = -203000 FRAME_DAWN_FC1 = -203110
FRAME_-203000_NAME = 'DAWN_SPACECRAFT' FRAME_-203110_NAME = 'DAWN_FC1'
FRAME_-203000_CLASS = 3 FRAME_-203110_CLASS = 4
FRAME_-203000_CLASS_ID = -203000 FRAME_-203110_CLASS_ID = -203110
FRAME_-203000_CENTER = -203 FRAME_-203110_CENTER = -203
CK_-203000_SCLK = -203 TKFRAME_-203110_RELATIVE = 'DAWN_SPACECRAFT'
CK_-203000_SPK = -203 TKFRAME_-203110_SPEC = 'ANGLES'
TKFRAME_-203110_UNITS = 'DEGREES'
TKFRAME_-203110_ANGLES = ( 0.0, 0.0, 0.0 )
TKFRAME_-203110_AXES = ( 1, 2, 3 )

• These keywords
FRAME_<name> = <id>
FRAME_<id>_NAME = <name>
establish the association between the name and the ID
of the frame.

Frames Subsystem 13
 N IF Frame Definition Details - 3
Navigation and Ancillary Information Facility

Frame definition for the DAWN spacecraft Frame definition for the DAWN Framing Camera #1
FRAME_DAWN_SPACECRAFT = -203000 FRAME_DAWN_FC1 = -203110
FRAME_-203000_NAME = 'DAWN_SPACECRAFT' FRAME_-203110_NAME = 'DAWN_FC1'
FRAME_-203000_CLASS = 3 FRAME_-203110_CLASS = 4
FRAME_-203000_CLASS_ID = -203000 FRAME_-203110_CLASS_ID = -203110
FRAME_-203000_CENTER = -203 FRAME_-203110_CENTER = -203
CK_-203000_SCLK = -203 TKFRAME_-203110_RELATIVE = 'DAWN_SPACECRAFT'
CK_-203000_SPK = -203 TKFRAME_-203110_SPEC = 'ANGLES'
TKFRAME_-203110_UNITS = 'DEGREES'
TKFRAME_-203110_ANGLES = ( 0.0, 0.0, 0.0 )
TKFRAME_-203110_AXES = ( 1, 2, 3 )

• The FRAME…CLASS keyword specifies the method

by which the frame is related to its base frame
• This keyword is set to:
1, for inertial frames
2, for PCK-based frames
3, for CK-based frames
4, for fixed-offset frames
Frames Subsystem
5, for dynamic frames 14
 N IF Frame Definition Details - 4
Navigation and Ancillary Information Facility

Frame definition for the DAWN spacecraft Frame definition for the DAWN Framing Camera #1
FRAME_DAWN_SPACECRAFT = -203000 FRAME_DAWN_FC1 = -203110
FRAME_-203000_NAME = 'DAWN_SPACECRAFT' FRAME_-203110_NAME = 'DAWN_FC1'
FRAME_-203000_CLASS = 3 FRAME_-203110_CLASS = 4
FRAME_-203000_CLASS_ID = -203000 FRAME_-203110_CLASS_ID = -203110
FRAME_-203000_CENTER = -203 FRAME_-203110_CENTER = -203
CK_-203000_SCLK = -203 TKFRAME_-203110_RELATIVE = 'DAWN_SPACECRAFT'
CK_-203000_SPK = -203 TKFRAME_-203110_SPEC = 'ANGLES'
TKFRAME_-203110_UNITS = 'DEGREES'
TKFRAME_-203110_ANGLES = ( 0.0, 0.0, 0.0 )
TKFRAME_-203110_AXES = ( 1, 2, 3 )

• The FRAME…CLASS_ID is the number that connects a frame with the

orientation data for it.
– For body-fixed frames the CLASS_ID is the ID of the natural body. It is used as input to
PCK routines called by the Frame subsystem to compute orientation of the frame.
» The Frame ID and CLASS_ID are not the same for the body-fixed frames defined in
the Toolkit but they can be the same for frames defined in FK files.
– For CK-based frames the CLASS_ID is the CK structure ID. It is used as input to CK
routines called by the Frame subsystem to compute orientation of the frame.
» Usually the CLASS_ID of a CK-based frame is the same as the frame ID, but this is
not required.
– For fixed offset and dynamic frames the CLASS_ID is the ID that is used to retrieve the
frame definition keywords.
» The CLASS_ID of a fixed offset or dynamic frame is the same as the frame ID.
Frames Subsystem 15
 N IF Frame Definition Details - 5
Navigation and Ancillary Information Facility

Frame definition for the DAWN spacecraft Frame definition for the DAWN Framing Camera #1
FRAME_DAWN_SPACECRAFT = -203000 FRAME_DAWN_FC1 = -203110
FRAME_-203000_NAME = 'DAWN_SPACECRAFT' FRAME_-203110_NAME = 'DAWN_FC1'
FRAME_-203000_CLASS = 3 FRAME_-203110_CLASS = 4
FRAME_-203000_CLASS_ID = -203000 FRAME_-203110_CLASS_ID = -203110
FRAME_-203000_CENTER = -203 FRAME_-203110_CENTER = -203
CK_-203000_SCLK = -203 TKFRAME_-203110_RELATIVE = 'DAWN_SPACECRAFT'
CK_-203000_SPK = -203 TKFRAME_-203110_SPEC = 'ANGLES'
TKFRAME_-203110_UNITS = 'DEGREES'
TKFRAME_-203110_ANGLES = ( 0.0, 0.0, 0.0 )
TKFRAME_-203110_AXES = ( 1, 2, 3 )

• The FRAME…CENTER specifies the ephemeris object

at which the frame origin is located
– It is used ONLY to compute the light-time corrected
orientation of the frame

Frames Subsystem 16
 N IF Frame Definition Details - 6
Navigation and Ancillary Information Facility

Frame definition for the DAWN spacecraft Frame definition for the DAWN Framing Camera #1
FRAME_DAWN_SPACECRAFT = -203000 FRAME_DAWN_FC1 = -203110
FRAME_-203000_NAME = 'DAWN_SPACECRAFT' FRAME_-203110_NAME = 'DAWN_FC1'
FRAME_-203000_CLASS = 3 FRAME_-203110_CLASS = 4
FRAME_-203000_CLASS_ID = -203000 FRAME_-203110_CLASS_ID = -203110
FRAME_-203000_CENTER = -203 FRAME_-203110_CENTER = -203
CK_-203000_SCLK = -203 TKFRAME_-203110_RELATIVE = 'DAWN_SPACECRAFT'
CK_-203000_SPK = -203 TKFRAME_-203110_SPEC = 'ANGLES'
TKFRAME_-203110_UNITS = 'DEGREES'
TKFRAME_-203110_ANGLES = ( 0.0, 0.0, 0.0 )
TKFRAME_-203110_AXES = ( 1, 2, 3 )

• Additional frame definition keywords may be required depending

on the frame class
– For CK frames, CK…SCLK and CK…SPK keywords identify the
spacecraft clock ID and physical object ID associated with the CK
structure ID
– For fixed-offset frames, TKFRAME_* keywords specify the base
frame and the fixed orientation with respect to this frame
– For dynamic frames, additional keywords depend on the dynamic
frame family

Frames Subsystem 17
 N IF APIs Using the Frames Subsystem
Navigation and Ancillary Information Facility

SXFORM, PXFORM, return state or position

and PXFRM2 transformation matrix
CALL SXFORM( 'FROM_FRAME_NAME', 'TO_FRAME_NAME', ET, MAT6x6 )
CALL PXFORM( 'FROM_FRAME_NAME', 'TO_FRAME_NAME', ET, MAT3X3 )
CALL PXFRM2( 'FROM_FRAME_NAME', 'TO_FRAME_NAME', ETFROM, ETTO, MAT3X3 )

SPKEZR and SPKPOS return state or position

vector in specified frame
CALL SPKEZR( BOD, ET, 'FRAME_NAME', CORR, OBS, STATE, LT )
CALL SPKPOS( BOD, ET, 'FRAME_NAME', CORR, OBS, POSITN, LT )

And high level SPICE APIs that take a frame

name as input – SINCPT, TANGPT, SUBPNT, …
The above are FORTRAN examples, using SPICELIB APIs.
The same interfaces exist for the other supported languages (CSPICE, Icy, Mice).

Frames Subsystem 18
 N IF CK-Based Frames “Must Know”
Navigation and Ancillary Information Facility
These are VERY IMPORTANT points you must understand!

• The frames routines (SPKEZR, SPKPOS, SXFORM, PXFORM) all read CK

files using tolerance = 0
– For discrete CKs (Type 1) the orientation of a CK-based frame will be computed only if the
time provided to a Frames routine exactly matches one of the times stored in the CK file;
otherwise an error will be signaled.
– For continuous CKs (Types 2 – 6) the orientation of a CK-based frame will be computed only
if the time provided to a Frames routine falls within one of the interpolation intervals defined
by the CK file; otherwise an error will be signaled.
• Using SPKEZR or SXFORM requires CKs that contain angular rate data
– Since these routines return a state vector (6x1) or state transformation matrix (6x6), angular
rate must be present in the CK in order to compute vectors and matrices; if angular rate is
not present an error will be signaled.
– SPKPOS and PXFORM, which return a position vector (3x1) and a position transformation
matrix (3x3) respectively, can be used when angular rate data are NOT present in a CK.
• Ephemeris time input to Frames routines is converted to SCLK to access
CKs
– SCLK and LSK kernels must be loaded to support this conversion.
– The SCLK ID is specified in one of the CK frame definition keywords; if not, it’s assumed to
be the Frame ID divided by 1000.

Frames Subsystem 19
 Frame Tree Example:
N IF ASPERA Instrument on Mars Express
Navigation and Ancillary Information Facility

"J2000" <-inertial
|
+-----------------------------------------------------+
| | |
|<-pck | |<-pck
| | |
V | V
"IAU_MARS" | "IAU_EARTH"
MARS BODY-FIXED |<-ck EARTH BODY-FIXED
--------------- | ----------------
V
"MEX_SPACECRAFT"
+-----------------------------------------------------+
| |
|<-fixed |<-fixed
| |
V V
"MEX_ASPERA_URF" "MEX_ASPERA_IMA_URF"
----------------- --------------------
| |
|<-ck |<-fixed
| |
V V
"MEX_ASPERA_SAF" "MEX_ASPERA_IMA"
--------------------------------------------- ... ----------------
| | |
|<-fixed |<-fixed |<-fixed
| | |
V V V
"MEX_ASPERA_ELS" "MEX_ASPERA_NPI" "MEX_ASPERA_NPD1"
---------------- ---------------- ----------------

Blue text indicates frame class

Frames Subsystem 20
 N IF FK Utility Programs
Navigation and Ancillary Information Facility

• The following FK and frames utility programs are included in

the Toolkit
FRMDIFF samples orientation of a frame or compares orientation of
two frames
CKBRIEF summarizes coverage for one or more CK files
BRIEF summarizes coverage for one or more binary PCK files

• These additional FK and frames utility programs are

provided on the NAIF Web site
(https://naif.jpl.nasa.gov/naif/utilities.html)
PINPOINT creates SPK and topocentric frames FK files for fixed
locations (ground stations, etc)
BINGO converts FK files between UNIX and DOS text formats

Frames Subsystem 21
 N IF Additional Information on FK
Navigation and Ancillary Information Facility

• For more information about FK and frames, look

at the following documents
– The on-line version of this tutorial
– Frames Required Reading
– Using Frames Tutorial
– Dynamic Frames Tutorial
– NAIF IDs Tutorial
– Headers for the routines mentioned in this tutorial
– Most Used SPICELIB Routines
– FRMDIFF User’s Guide
– Porting Kernels tutorial
• Related documents
– CK Required Reading
– PCK Required Reading
– SPK Required Reading
– Rotations Required Reading
Frames Subsystem 22
N IF
Navigation and Ancillary Information Facility

Using the Frames Subsystem

April 2023
 N IF What is the Power of Frames?
Navigation and Ancillary Information Facility

• The “power” of the Frames capability stems from the

SPICE system’s ability to construct complex reference
frame transformations with no programming effort
required of you
– But it’s crucial that you select and load the needed kernels

• The principal benefit from the Frames capability is

obtained through the main SPK subsystem interfaces
(SPKEZR and SPKPOS), the Frames subsystem interfaces
(SXFORM, PXFORM, PXFRM2), and high-level derived
geometry APIs (SINCPT, TANGPT, SUBPNT, …).

• The remaining pages illustrate typical use of frames

• Several VERY IMPORTANT usage issues are mentioned in

the Frames tutorial; be sure to also read that.
Using Frames 2
 N IF Offset Between Instruments
Navigation and Ancillary Information Facility

Required Kernels:
Misalignment •Generic LSK
angle between ISS •Mission FK
ISS NAC camera boresights •Camera IK(s)
CASSINI Frame
NAC Boresight

ISS WAC Angle between boresights

Frame WAC Boresight
S/C
Frame
ISS = Imaging Science System

Compute the angular separation between the Cassini ISS

Narrow Angle Camera and Wide Angle Camera boresights:

C Retrieve the matrix that transforms vectors from NAC to WAC frame
CALL PXFORM( 'CASSINI_ISS_NAC', 'CASSINI_ISS_WAC', ET, MAT )
C Transform NAC boresight to WAC frame and find separation angle
ran
CALL MXV ( MAT, NAC_BORESIGHT_nac, NAC_BORESIGHT_wac ) Fort ple
ANGLE = VSEP( NAC_BORESIGHT_wac , WAC_BORESIGHT_wac ) exam
Using Frames 3
 N IF Angular Constraints
Navigation and Ancillary Information Facility

Required Kernels:
J2000 •Generic LSK
Sun Frame
Sun direction •Mission FK
CASSINI Solar System
in the NAC frame •Spacecraft SCLK
Barycenter
ISS NAC
Frame
•Camera IK
•Planetary
Angle between
NAC Boresight
Ephemeris SPK
S/C
Frame
and Sun direction •Spacecraft SPK
•Spacecraft CK
Saturn System
Barycenter
NAC Boresight

Check whether the angle between the camera boresight and the
direction to the Sun is within the allowed range:
CALL SPKPOS( 'SUN', ET, 'CASSINI_ISS_NAC', 'LT+S', 'CASSINI', SUNVEC, LT )
ANGLE = VSEP( NAC_BORESIGHT_nac, SUNVEC )
ran
IF ( ANGLE .LE. CONSTRAINT ) WRITE(*,*) 'WE ARE IN TROUBLE!' Fort ple
xam e
Using Frames 4
 N IF Angles at the Surface
Navigation and Ancillary Information Facility
J2000 Solar System Barycenter Required Kernels:
Frame •Generic LSK
Saturn System
Barycenter •Generic PCK
Sun •Mission FK
•Planetary
Solar Saturn Ephemeris SPK
Sun Direction EL •Satellite
In Local Level Solar Ephemeris SPK
Frame AZ •Landing Site SPK
Titan
Local Level
Titan‘s IAU Cassini
Frame at the Spacecraft
probe Landing Body-fixed
Site frame

Compute solar azimuth and elevation at the Huygens probe landing site
CALL SPKPOS('SUN',ET, 'HUYGENS_LOCAL_LEVEL', 'LT+S', 'HUYGENS_PROBE',SUNVEC,LT)
CALL RECAZL( SUNVEC, .TRUE., .FALSE., RANGE, AZ, EL )

ran
Fort ple
exam

Using Frames 5
 N IF Relative Position of Sensors
Navigation and Ancillary Information Facility

Required Kernels:
MAG+Y •Generic LSK
frame •Mission FK
MAG-Y position relative to MAG+Y •Structure
Locations SPK
•Spacecraft SCLK
•Solar Array CK
+Y Gimbal
frame
MAG-Y
frame S/C Frame
-Y Hinge -Y Gimbal
frame frame

Find the position of one MGS MAG sensor with respect to the other in
the MGS s/c frame. Also find the relative orientation of the sensors:
CALL SPKPOS('MGS_MAG-Y', ET, 'MGS_SPACECRAFT', 'NONE', 'MGS_MAG+Y’, POSVEC, LT)
CALL PXFORM('MGS_MAG_+Y_SENSOR', 'MGS_MAG_-Y_SENSOR', ET, MAT) rtran Fo p le
exam
Using Frames 6
 N IF Manipulators - 1
Navigation and Ancillary Information Facility
MGS
Required Kernels:
•Generic LSK
•Mission FK
S/C Frame •Spacecraft SCLK
•HGA IK
HGA Hinge HGA •Planetary
frame frame Ephemeris SPK
Mars HGA Gimbal
frame •Spacecraft SPK
J2000 MGS HGA •Spacecraft CK
Frame off-pointing •HGA CK
angle
Sun

SSB Earth
J2000 HGA = High Gain Antenna
Frame

Compute the angle between the direction to Earth and the MGS
HGA boresight:
CALL SPKEZR( 'EARTH', ET, 'MGS_HGA', 'LT+S', 'MGS', EARTH_STATE, LT )
ANGLE = VSEP( HGA_BORESIGHT, EARTH_STATE )
ran
Fort ple
exam
Using Frames 7
 N IF Manipulators - 2
Navigation and Ancillary Information Facility
RA J2
Dig Location SSI Frame Required Kernels:
Frame in SSI Frame •Generic LSK
SSI Camera •Mission FK
RA Scoop head Frame
Frame •Lander SCLK
•Structure
RA J1 Locations SPK
Dig Location Frame
MVACS •Lander SPK
in Surface fixed
frame Frame •Lander CK
•SSI CK
•RA CK

Surface-fixed
Frame

Compute the soil digging location in the MPL surface-fixed and ran
Fort ple
camera left eye frames: exam

CALL SPKPOS( 'MPL_RA_SCOOP',ET,'MPL_SURFACE_FIXED','NONE','MPL_SURF’,POS1,LT )

CALL SPKPOS( 'MPL_RA_SCOOP',ET,'MPL_SSI_LEFT', 'NONE','MPL_SSI’, POS2,LT )
Using Frames 8
N IF
Navigation and Ancillary Information Facility

“High Accuracy” Orientation

and
Body-fixed Frames
for the
Moon and Earth

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Introduction
• Earth binary PCKs
• Lunar binary PCKs
• Lunar Frames Kernel
– Frame specifications
– Frame alias names
• Binary PCK file format
• Using Binary PCKs
– Precedence rules
– Utilities
• Backup
– Earth and Moon frame association kernels

Special PCK and FK for Earth and Moon 2

 N IF Introduction-1
Navigation and Ancillary Information Facility

• Having read about “standard” PCKs and FKs in

other tutorials you may want to learn about
several “special” PCKs and FKs dealing with the
Earth and the Moon.

• While it is ultimately up to you, in most cases you

should use the PCK and FK kernels described
here when working with the Earth or the Moon.
– If you need only “low accuracy” Earth or Moon orientation
information, for instance for a visualization tool, then the
standard text-style PCK data may be used.

Special PCK and FK for Earth and Moon 3

 N IF Introduction-2
Navigation and Ancillary Information Facility

• NAIF provides “high accuracy” orientation data for the Earth and
the Moon in binary PCKs.
– For the Earth, three versions are made:
» High accuracy, frequently updated file
• Contains high accuracy historical data and fairly accurate, short-term predict data
» High accuracy, infrequently updated historical file
» Lower accuracy long term predict file
– For the Moon, a single, long-term file is made upon release of an official new JPL
“Developmental Ephemeris” (DE).
» Contains accurate historical and predictive lunar orientation data
• To use these kernels:
– Select binary PCK(s) having properties and time coverage that meet your needs
» Unlike text PCKs, the time span covered by binary PCKs is limited
– Load the PCK(s) using FURNSH
– For the Moon, also load the lunar FK
– Reference the Earth body-fixed frame using the name ‘ITRF93’
» CAUTION: ‘IAU_EARTH’ cannot be used to reference high-accuracy Earth orientation data
– Reference a lunar body-fixed frame using one of these names:
» ‘MOON_ME’ (Moon Mean Earth/Rotation axis frame)
» ‘MOON_PA’ (Moon Principal Axes frame)
» CAUTION: ‘IAU_MOON’ cannot be used to reference high-accuracy lunar orientation data

Special PCK and FK for Earth and Moon 4

N IF
Navigation and Ancillary Information Facility

Earth Binary PCKs

 N IF High Accuracy Earth Rotation Model
Navigation and Ancillary Information Facility

• The ITRF93 high accuracy Earth rotation model takes into

account:
– Precession: 1976 IAU model due to Lieske.
– Nutation: 1980 IAU model, with IERS corrections due to Herring et al.
– True sidereal time using accurate values of TAI-UT1
– Polar motion
• It is more accurate than the IAU rotation models found in
text PCKs.
– See the plot on the next slide comparing orientation of the ITRF93 frame to that
of the IAU_EARTH frame.
» IAU_EARTH frame orientation error is ~0.06 degrees (~1 milliradian), or
~6km on a great circle!
• The highest accuracy is obtainable only for past epochs.
– Unpredictable variations of UT1-TAI and polar motion limits the accuracy of
predicted earth orientation. See plot on page 8.

Special PCK and FK for Earth and Moon 6

 N IF IAU_EARTH vs ITRF93 Comparison Plot
Navigation and Ancillary Information Facility

Difference between the ‘IAU_EARTH’ frame and the ‘ITRF93’ frame

Special PCK and FK for Earth and Moon 7

 N IF Earth Predicted vs Reconstructed ITRF93 Plot
Navigation and Ancillary Information Facility

Difference between predicted and reconstructed orientation of ITRF93 frame

Special PCK and FK for Earth and Moon 8

 N IF Data Source for Earth High Accuracy Model
Navigation and Ancillary Information Facility

• Binary Earth PCKs represent the orientation of an

Earth ITRFxx body-fixed reference frame relative
to the ICRF.
– ITRF frames are defined by the International Earth Rotation
Service (IERS).
– Currently only the ITRF93 frame is supported within SPICE.
» An update to a more modern version is planned.
– Source data come from a JPL Earth Orientation Parameters
(EOP) file.

ICRF = International Celestial Reference Frame, often referred to in SPICE as the “J2000”
frame, and also often referred to as the EME 2000 frame. This is an inertial frame.

ITRF = International Terrestrial Reference Frame

Special PCK and FK for Earth and Moon 9

 N IF Earth PCK Production Scheme
Navigation and Ancillary Information Facility

• Three versions of the high accuracy binary Earth PCK are

produced
– “The latest,” using each new release by JPL of a reconstructed EOP file
» Covers well into the past and approximately two months into the future
beyond the production date
» Accuracy of the future data degrades rapidly past the production date
» Produced several times per week using an automated script
– Long term predict, for uses beyond two months from the production date, and
where the highest accuracy is not required
» Produced infrequently
» Covers several years into the past and approximately 75 years into the
future
» Accuracy at epochs in the future is low compared to that for past epochs,
but any of it is far better than what is obtained from the IAU rotation model
for the Earth (‘IAU_EARTH’) provided in any text PCK
– History file, containing only high accuracy historical data
• All are in the pck directory under generic_kernels on the NAIF
server: https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/
– Read the “aareadme” file to see the file naming schema and more details

Special PCK and FK for Earth and Moon 10

 N IF Accurate Earth Surface Locations
Navigation and Ancillary Information Facility

• High accuracy determination of surface locations

relative to an inertial frame involves motions in
addition to Earth rotation, including:
– tectonic plate motion
– tidal effects
– relativistic effects
• From the list of effects above…
– Tectonic plate motion is accounted for in NAIF's DSN and some
non-DSN station SPK files.
» This helps ONLY station locations, not other surface
objects.
– The other two non-rotational effects affecting surface locations
are not accounted for by any PCK, or by any other SPICE
component. But the magnitude of these is under one meter.

Special PCK and FK for Earth and Moon 11

 N IF Kernel Usage Summary: Earth
Navigation and Ancillary Information Facility

• To use high accuracy Earth orientation data

– Load one or more binary Earth PCKs
» If a long-term predict is used, load that kernel *before*
loading any kernel containing reconstructed data so that
the reconstructed data have precedence during the overlap
period.
– If your application uses any of the old, pre-N0062 APIs that
make use of the default Earth body-fixed frame (see backup
slides), load an Earth frame association kernel making ITRFxx
the default Earth body-fixed frame.
» But best to switch to use the “new” APIs that require you to
specify which frame to use.
• The new APIs are: ILUMIN, ILLUMF, ILLUMG, SINCPT, SUBPNT,
SUBSLR

• If you’re using SPICE to access Earth size and

shape information, you’ll also need to load a text
PCK file containing these data.
– Typically use the latest generic text PCK: pck000xx.tpc

Special PCK and FK for Earth and Moon 12

N IF
Navigation and Ancillary Information Facility

Lunar Binary PCKs

 N IF High Accuracy Lunar Rotation Model
Navigation and Ancillary Information Facility

• The high accuracy lunar rotation models available

in binary PCKs are more accurate than the IAU
rotation model found in a text PCK (‘IAU_MOON’).
– For the time period of 2000-2020 the difference is approximately:
» Worst case: ~0.0051 degrees, or ~155m on a great circle
» Average: ~0.0024 degrees, or ~73m on a great circle
– The error is due to truncation of the libration series in the IAU
model
– See the plot in the following chart comparing the IAU lunar
rotation model to the integrated DE-421 model.

Special PCK and FK for Earth and Moon 14

 N IF IAU_Moon vs MOON_ME Comparison Plot
Navigation and Ancillary Information Facility

Difference between the IAU_Moon frame and the Moon_ME frame (equivalent
to the Moon_ME_DE421 frame)

Special PCK and FK for Earth and Moon 15

 N IF Data Sources for High Accuracy Models
Navigation and Ancillary Information Facility

• Data for lunar orientation come from JPL’s

DE/LExxx planet/lunar ephemeris files.
– Binary lunar PCKs represent the orientation of the Moon’s
“principal axis” reference frame–referred to as
MOON_PA_Dexxx–relative to the ICRF*.

ICRF = International Celestial Reference Frame, often referred to in SPICE as the “J2000”
frame, and also often referred to as the EME 2000 frame. This is an inertial frame.

JPL-produced planet/lunar ephemeris files are sometimes referred to as “DE/LExxx” but

more often are referred to as simply “DExxx.”

Special PCK and FK for Earth and Moon 16

 N IF Lunar Rotation Model Effects-1
Navigation and Ancillary Information Facility

• The high accuracy lunar orientation model obtained from the

DE440 lunar ephemeris represents the result of a simultaneous
numerical integration of lunar rotation and orbit, and of orbits of
the planets.
– The DE440 integration model includes*:
» Relativistic equations of motion for Moon and planets.
» Rotating Sun’s relativistic Lense-Thirring effect.
» Solar radiation pressure on lunar orbit.
» The gravity field of the Earth has zonal coefficients J2 through J5. The
coefficient J2 is a quadratic function of time.
» Degree-2 tides on Earth depend on zonal, diurnal, and semidiurnal Love
numbers with phase shifts for tidal dissipation. The diurnal and semidiurnal
phase shifts depend on tidal period.
» The degree-2 through degree-6 gravity field of the Moon comes from GRAIL.
» The Moon has a solid lunar mantle and a fluid core.
» Torques on the Moon are from the Earth, Sun, and planets Mercury through
Saturn.
» Dissipation in the Moon depends on one tidal phase shift and one
core/mantle interface parameter. The tidal Love number comes from GRAIL.
» Torques on Moon from Earth J2 interacting with lunar degree-2 figure.
» Torque from an oblate lunar core/mantle interface.

*Description provided by Dr. Ryan S. Park (JPL)

Special PCK and FK for Earth and Moon 17

 N IF Lunar Rotation Model Effects-2
Navigation and Ancillary Information Facility

• The high accuracy lunar orientation model obtained from the

DE440 lunar ephemeris represents the result of a simultaneous
numerical integration of lunar rotation and orbit, and of orbits of
the planets.
– Parameters fit to lunar laser data for DE440 include*:
» Initial conditions for the lunar orbit and orientation.
» GM of Earth+Moon, which adjusts the mean lunar distance.
» Lunar moment of inertia differences (C–A)/B and (B–A)/C.
» Dissipation parameters for tides on Earth and Moon plus lunar core/mantle
interface.
» Locations of five laser retroreflector sites.
» Thermal expansion and contraction of retroreflectors.
– The best lunar range data of recent years have uncertainties < 1 cm. Our weighted
rms residual is 9 mm.

*Description provided by Dr. Ryan S. Park (JPL)

Special PCK and FK for Earth and Moon 18

N IF
Navigation and Ancillary Information Facility

Lunar Frames Kernel

 N IF Lunar Frames Kernel
Navigation and Ancillary Information Facility

• A lunar frames kernel is available from NAIF. It has four

functions.
1. Make two lunar frames–Principal Axes (PA) and Mean Earth/rotation
axis (ME)–known to the SPICE system.
» Within SPICE their names are MOON_PA_DExxx and MOON_ME_DExxx
» These frames are unique to a particular JPL-produced planetary and lunar
ephemeris (e.g. DE421).
» Special case for DE440: ME frame is MOON_ME_DE440_ME421, which is
closely aligned with MOON_ME_DE421.
2. Connect the MOON_PA_DExxx frame name to the high accuracy lunar
orientation PCK data that implement the PA orientation.
3. Provide specifications for implementing the rotation between the PA
frame and the ME frame.
» Makes the MOON_ME_Dexxx* frame available to SPICE.
4. Provide generic frame names, aliased to the MOON_PA_DExxx and
MOON_ME_Dexxx* frame names.
» The generic frame names are simply MOON_PA and MOON_ME.
» The generic names need not be changed in your programs when the
MOON_PA_DExxx and MOON_ME_Dexxx* names change due to use of
new defining data.
» The DE-specific frames to which these aliases “point” will be updated
by NAIF whenever a new binary lunar orientation PCK is produced.
NAIF will release a new lunar FK at that time.

Special PCK and FK for Earth and Moon 20

 N IF Kernel Usage Summary: Moon
Navigation and Ancillary Information Facility

• To use high accuracy Moon orientation data

– Load the current binary lunar PCK
– Load the current lunar FK
– If your application uses any of the old, pre-N0062 APIs that
make use of the default lunar body-fixed frame (see Backup),
load a Moon frame association kernel making either MOON_ME
or MOON_PA the default lunar body-fixed frame.
» But best to switch to use the “new” APIs that require you to
specify which frame to use.
• The new APIs are ILLUMF, ILLUMG, ILUMIN, SINCPT, SUBPNT, SUBSLR

• If you’re using SPICE to access Moon size and

shape information, you’ll also need to load a text
PCK file containing these data.
– Typically use the latest generic text PCK, such as pck00010.tpc

Special PCK and FK for Earth and Moon 21

 N IF Lunar PCK/FK Summary
Navigation and Ancillary Information Facility

Which kernels are needed to access each of the three lunar

body-fixed reference frames providing lunar orientation?
Example of
moon_pa_de440_200625
file name moon_220930.tf pck00010.tpc
.bpc

Lunar Generic
Kernel(s) Lunar text
needed binary FK
PCK PCK

Orientation of Orientation of Orientation of

Your MOON_DEnnn_ME* IAU_MOON
objective MOON_DEnnn_PA
frame frame frame

Frame name to be
used in SPICE MOON_PA MOON_ME IAU_MOON
software

Usually a bad
choice for the
Special PCK and FK for Earth and Moon Moon! 22
N IF
Navigation and Ancillary Information Facility

Binary PCK File Format

 N IF Binary PCK File Format
Navigation and Ancillary Information Facility
• SPICE binary PCK files are used to accommodate high
accuracy rotation models.
– Just as for SPKs and CKs, the data are held in SPICE Double Precision
Array files (DAF)
– Multiple types are supported
» Type 2: Chebyshev polynomials are used to represent Euler
angles giving orientation as a function of time. Rates are obtained
by differentiating polynomials. Coverage intervals have fixed
length.
• Used for the Earth and the Moon
» Type 3: Separate sets of Chebyshev polynomials are used to
represent Euler angles and their rates. Coverage intervals have
variable length.
• Used only for Eros
» Type 20: Chebyshev polynomials representing Euler angle rates
• Provided to accurately represent “EPM” orientation data produced by the Russian
Institute of Applied Astronomy (Ephemeris of the Planets and Moon)
– Binary PCKs include a “comment area” for storing descriptive
metadata
» Access the comment area using the Toolkit’s commnt utility
program
– Binary PCKs support high-speed direct access
» Chebyshev polynomials are fit to source Euler angles; these
evaluate very quickly
Special PCK and FK for Earth and Moon 24
N IF
Navigation and Ancillary Information Facility

Using Binary PCKs

 Precedence Rules
N IF for Text and Binary PCKs
Navigation and Ancillary Information Facility

• If two (or more) binary PCKs with functionally equivalent

data are loaded, a later loaded file takes precedence.
• Loading one text PCK that supersedes another can lead to
errors if data from the “old” PCK remain in the kernel pool.
– It’s essential to unload the old text PCK before loading the new one.
» Use UNLOAD or KCLEAR to unload the old text PCK.
– This problem doesn’t apply to binary PCKs.
• If both a binary and a text PCK provide orientation for the
same frame, data available from the binary PCK always take
precedence over data available from the text PCK.
– This is independent of file loading order
– Note: the binary PCKs discussed in this tutorial define Earth-fixed and
Moon-fixed frames different from those defined by a text PCK (e.g.
pck00010.tpc), so there will be no conflict.

Special PCK and FK for Earth and Moon 26

 N IF Tools for use with Binary PCKs
Navigation and Ancillary Information Facility

• Use the commnt utility to access a binary PCK comment

area
– Read, extract or insert metadata
• Use the brief or spacit utility to summarize a binary PCK
– brief is easier to use; spacit provides more information
• Non-native binary PCKs can be read without first being
converted to the native binary form
– Converting a non-native binary PCK to native form will also speed up
data access somewhat. Use toxfr/tobin or bingo.
» toxfr and tobin are available in each Toolkit; bingo is available
only from the NAIF website

Special PCK and FK for Earth and Moon 27

N IF
Navigation and Ancillary Information Facility

Backup
Association Frames Kernels
for the Earth and the Moon
 N IF Association FKs: Introduction
Navigation and Ancillary Information Facility

• In most SPICE modules that deal with one or more reference frames
the name(s) of that/those frame(s) must be provided as input
argument(s), for example:
– CALL SPKEZR (target, time, frame, observer, correction,
state, lighttime)
• Many years ago the SPICE developers assumed there would be only
one body-fixed reference frame associated with each natural body
during a program run.
– Thus a specific body-fixed frame name would rarely be needed as an input to
modules dealing with body-fixed frames
– Instead, SPICE could use the body-fixed frame associated with a given body simply
by knowing the body name or ID
» For most bodies SPICE associates the body with a body-fixed frame named
IAU_<body name> (example: IAU_MOON)
» This is known as the default body-fixed frame
• This was a bad assumption… at least for the Earth and the Moon!
– Multiple body-fixed frames exist for the Earth and the Moon
– The default body-fixed frames for the Earth and the Moon, for which the defining
data are provided in a generic text PCK (taken from an IAU report), are inaccurate
(for the Moon) and very inaccurate (for the Earth) representations of the actual
orientations of these bodies

Special PCK and FK for Earth and Moon 29

 N IF Better Choice for the Default
Navigation and Ancillary Information Facility

• For the Earth and the Moon there are other

choices for body-fixed frame that are almost
certainly better than the default body-fixed frame
conjured up by SPICE

Body SPICE Default Body-fixed Frame Better choice

Earth IAU_Earth ITRF93

ITRFxx (in the future)

Moon IAU_Moon Moon_PA or

Moon_ME

Special PCK and FK for Earth and Moon 30

 N IF The Problem
Navigation and Ancillary Information Facility

• The SPICE modules that make use of the default body-fixed

reference frame are these Old: still available, but better to use those noted below
– LSPCN, ET2LST, ILLUM, SRFXPT, SUBPT, SUBSOL (and their C, Icy and Mice
equivalents)
– Your code might overtly call one of these, or it could call one indirectly through use
of a parameterized dynamic frame
• NAIF rules regarding stability of our software offerings prevent us
from changing the designs of those modules
– So we have provided you means to change the default body-fixed frame associated
with any solar system body of interest to you. See the next several pages.
• However, starting with the version N62 Toolkits, a new set of
modules is available for those calculations where precision body
orientation is important.
– These modules require the user to name the desired body-fixed frame, rather than
using a default body-fixed frame
New: safer to use, and offer improved
– The new modules are these: accuracy in some cases
» ILUMIN, ILLUMF, ILLUMG, SINCPT, SUBPNT, SUBSLR

Special PCK and FK for Earth and Moon 31

 Changing the Default Body-Fixed
N IF Frame Name in the Older APIs
Navigation and Ancillary Information Facility

• All bodies for which a body-fixed frame is defined by the IAU, and
where the defining data are found in a SPICE text PCK file, have an
associated default body-fixed frame name within SPICE:
– The name pattern is: IAU_<body name>
– Examples: IAU_MARS, IAU_MOON, IAU_EARTH

• A different default body-fixed frame name can be assigned within a

program by placing the following assignment in any text kernel
that is loaded into the program:
OBJECT_<body name>_FRAME = '<new default frame name>'
– Example: OBJECT_MOON_FRAME = 'MOON_ME'
• NAIF offers three “association FKs” to accomplish this.
– See next page.

Special PCK and FK for Earth and Moon 32

 Using Association FKs to Change
N IF the Default Frame in the Older APIs
Navigation and Ancillary Information Facility

• For the Earth and the Moon, changing the default body-fixed frame
name as described on the previous page can be accomplished by
loading the appropriate “association” frame kernel provided by
NAIF. The association kernels available are shown below
– For the Earth:
» earth_assoc_itrf93.tf
– For the Moon: (pick one or the other–not both)
» moon_assoc_me.tf
» moon_assoc_pa.tf
• These kernels are available on the NAIF server
– For the Earth:
» https://naif.jpl.nasa.gov/pub/naif/generic_kernels/fk/planets/
– For the Moon:
» https://naif.jpl.nasa.gov/pub/naif/generic_kernels/fk/satellites/

Special PCK and FK for Earth and Moon 33

 N IF Lunar FK/PCK/Association FK Usage
Navigation and Ancillary Information Facility

Which additional kernel is needed to use the indicated frame in

those (older) SPICE APIs* that use a default (assumed) frame?
Pick one or the other.

MOON_PA MOON_ME IAU_MOON

Usually a bad
File name moon_assoc_me.tf choice for the
moon_assoc_pa.tf Moon!
PA ME no
Association Association additional
FK** FK** kernels

* LSPCN, ET2LST, ILLUM, SRFXPT, SUBPT, SUBSOL But best to use the
replacements for these
(and their C, Icy and Mice equivalents) four, which don’t use a
default body-fixed frame:
• ILUMIN, ILLUMF, ILLUMG
• SINCPT
**Any version of one or the other of these kernels is good indefinitely; • SUBPNT
you do not need to use the latest instance offered on the NAIF server. • SUBSLR

Special PCK and FK for Earth and Moon 34

N IF
Navigation and Ancillary Information Facility

Dynamic Reference Frames

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Overview of Dynamic Reference Frames

• Terminology
• Rationale for Dynamic Frames
• How to Use a Dynamic Frame
• Parameterized Dynamic Reference Frames
• Defining Dynamic Reference Frames
– Two-Vector Frames
– "Of-Date" Frames
– Euler Frames
and two special cases for any of these families...
– Frozen Dynamic Frames
– Inertial Dynamic Frames
• Backup
Dynamic Frames 2
 N IF What are Dynamic Frames
Navigation and Ancillary Information Facility

• Dynamic reference frames ("dynamic frames"

for short) have time-dependent orientation.
– CK- and PCK-based frames are not considered to be
dynamic frames although they are time-varying.
– Some examples are given on the next page.
• Dynamic frames are specified using a frames
kernel (FK).
• The dynamic frames capability is an extension to
the original SPICE frames subsystem.
• This capability enables SPICE users to conveniently
use a wide variety of frames that are not "built in" to
SPICE.

Dynamic Frames 3
 N IF Examples of Dynamic Frames
Navigation and Ancillary Information Facility

• Geocentric Solar Ecliptic (GSE)

• Solar Magnetic (SM)
• Spacecraft-centered roll-celestial frame
• Geocentric Solar Magnetospheric (GSM)
• Geomagnetic (MAG)
– Using constant north centered geomagnetic dipole
– Using dipole direction defined by time-dependent Euler angles
• Geocentric Solar Equatorial (GSEQ)
• Solar Equatorial frame for any ephemeris object
• Orbital frame for any ephemeris object
• Earth mean equator and equinox of date
• Earth true equator and equinox of date
• Earth mean ecliptic and equinox of date
• Nadir-oriented frame for planetary orbiter
• Radial, tangential, normal (RTN)
Dynamic Frames 4
 N IF Rationale
Navigation and Ancillary Information Facility

• Why should SPICE offer dynamic frames

implemented using a frames kernel? Instead…
– a user could build a C-kernel for any frame.
– SPICE could provide a limited number of "built-in" dynamic
frames which wouldn't require a frames kernel.
– users can create their own routines to implement dynamic
frames.
• Benefits of using a SPICE FK for this purpose
– Convenience: using a formula rather than a C-kernel avoids C-
kernel creation, dissemination, storage, and consistency issues.
– Flexibility: the dynamic frame mechanism enables creation of a
vast variety of reference frames.
– Integration: once defined, and once supporting kernels are
loaded, dynamic frames may be referenced in SPICE API calls.
– Correct implementation: extensive testing done by NAIF, and
perhaps further verified by a user, seems less likely to result in an
error.
Dynamic Frames 5
 N IF Using a Dynamic Frame
Navigation and Ancillary Information Facility

• Using a dynamic frame in a SPICE-based program is

straightforward.
– At program initialization:
» Load the needed dynamic frame kernel to make the
frame definition known to SPICE.
• Note: a single dynamic frames kernel likely contains many
dynamic frame specifications.
» Load any kernels on which the dynamic frame depends.
• Some dynamic frames require the use of SPK, FK, PCK,
CK, or SCLK SPICE kernels.
– Then, in calls to SPICE routines, refer to the dynamic frame
by name just as you would do with other kinds of frame
names, such as "J2000."

Dynamic Frames 6
 N IF Examples of Using Dynamic Frames
Navigation and Ancillary Information Facility

• Find the 6x6 matrix to transform states from the J2000 frame to
the Geocentric Solar Ecliptic (GSE) frame at the TDB epoch
given by ET1.
CALL SXFORM( 'J2000', 'GSE', ET1, XFORM )

• Look up the state of Jupiter relative to the Earth in the GSE

frame:
CALL SPKEZR( 'JUPITER', ET1, 'GSE',
'NONE', 'EARTH', STATE, LT )

• You can use dynamic frames any place in SPICE where a frame
name is used.
– However, some restrictions apply to use of dynamic frames in
SPICE kernels (see “Limitations” in the backup slides).

Dynamic Frames 7
 N IF Terminology - 1
Navigation and Ancillary Information Facility

• "Frame" is an abbreviation for "reference frame."

• A frame can be defined as a set of three mutually
orthogonal, unit-length vectors.
– These vectors are called "basis vectors." The lines containing
the basis vectors are the "axes" of the frame.
– The basis vectors indicate the "positive" axis directions; we label
these vectors +X, +Y, and +Z. The negatives of these vectors are
labeled -X, -Y, and -Z.
– We number the axes as follows:
X = axis 1; Y = axis 2; Z = axis 3
• All of the frames we'll deal with are "right-handed":
this means +Z is the cross product +X x +Y.
• A reference frame's orientation is defined relative to
another specified frame: the "base frame."

Dynamic Frames 8
 N IF Terminology - 2
Navigation and Ancillary Information Facility

• When we say that a frame is "time-dependent" or "time-

varying," we mean:
– The orientation of the frame is time-dependent.
– Equivalently, the rotation between the frame and its base frame is time-
dependent.

• By "evaluating" a frame or "evaluating the orientation of a

frame," we mean computing the rotation between the frame
and its base frame.
– Because of their time-dependent nature, an epoch is required in order to
evaluate a dynamic frame.

• In the SPICE system, frames are considered to have "centers."

– The center of a frame is always an ephemeris object, something whose
location can be specified with an SPK file.
– Frame centers come into play when light time corrections are used: the
apparent orientation of a time-dependent frame as seen by an observer is
affected by the one-way light time between the frame's center and the
observer.
Dynamic Frames 9
 N IF Terminology - 3
Navigation and Ancillary Information Facility

• When we say that a vector is "aligned" with another vector,

we mean that the angular separation between the two vectors
is zero.

• We use the terms "defining a frame" and "specifying a frame"

interchangeably. Both refer to creating a frame definition in a
frames kernel (FK).

• The notation [theta]n

indicates a frame rotation of theta radians (unless other units
are specified) about axis n, where n is one of {1, 2, 3}. This
transformation rotates vectors by –theta radians about axis n.

Dynamic Frames 10
 Creating a Frames Kernel
N IF Defining Dynamic Frames
Navigation and Ancillary Information Facility

• To define dynamic frames using a frames kernel, a

fairly detailed understanding of the SPICE dynamic
frames capability is required.
• A good understanding of the basic SPICE system
(in particular, the SPK and frames subsystems) is
also a prerequisite.
• See the Frames Required Reading document for the
most detailed documentation available.
• The rest of this tutorial is concerned with:
– explaining the SPICE dynamic frames capability
– showing how to create dynamic frames kernels
» We present many dynamic frame definition examples

Dynamic Frames 11
 N IF Types of Dynamic Frames
Navigation and Ancillary Information Facility

• NAIF envisages providing two types of dynamic

frames:
– parameterized
– scripted

• As of now only the parametrized type is

implemented within SPICE; the rest of this tutorial
focuses on this type.

Dynamic Frames 12
 N IF Parameterized Dynamic Frames
Navigation and Ancillary Information Facility

• Parameterized dynamic frames are defined using formulas.

– The code implementing the formulas is built into SPICE.
– The parameters used in the formulas are specified in a frames kernel.

• Parameterized dynamic frames are grouped into frame

"families". Each family corresponds to a distinct, parameterized
geometric formula providing a frame definition. The families are:
– Two-Vector frames
– Of-date frames
– Euler frames

Dynamic Frames 13
 N IF Defining Parameterized Dynamic Frames
Navigation and Ancillary Information Facility

• Parameterized dynamic frames are defined using

"keyword=value" assignments in a frames kernel (FK).
• The following items must be specified in the frame definition:
– Frame name
– Frame ID code
» The range 1400000-2000000 is reserved for people outside of the NAIF group
– Class ( = 5 for dynamic frames)
– Class ID code ( = frame ID code for dynamic frames)
– Frame center ( = name or NAIF ID code for central body)
– Frame definition style ( = 'PARAMETERIZED')
– Base frame name ( called “relative”)
» The frame definition specifies a rotation from the dynamic frame to the base
(relative) frame.
– Frame family
– Family-specific assignments

continued on next page

Dynamic Frames 14
 N IF Defining Parameterized Dynamic Frames
Navigation and Ancillary Information Facility

continued from previous page

– Rotation state
» Possible states are 'ROTATING' and 'INERTIAL'.
• A frame is treated as rotating or inertial for the purpose of velocity transformations.

» The default dynamic frame rotation state is 'ROTATING'.

• For rotating two-vector and Euler frames, the rotation state assignment can be
omitted from the frame definition.
• For "of-date" frames, the frame definition must either specify the rotation state or
designate the frame as "frozen" at a specified epoch (but not both).
– Freeze epoch
» The presence of this optional assignment in a frames kernel indicates that the
frame orientation, relative to the base frame, is held constant ("frozen") at the
specified epoch.
» Most dynamic frames are not frozen.

Dynamic Frames 15
 N IF What’s Next?
Navigation and Ancillary Information Facility

• In the next approximately 35 pages we’ll provide

implementation details and examples of frames
belonging to each of the parameterized dynamic
frame families:
– Two-Vector frames
– "Of-Date" frames
– Euler frames
– Product frames
• We’ll also explain the optional frame attributes
which can be assigned to frames belonging to the
above families:
– “Frozen”
– “Inertial”

Dynamic Frames 16
 N IF Two-Vector Frame Concepts - 1
Navigation and Ancillary Information Facility

• Two-vector frames are defined using two time-

dependent vectors: the "primary" and "secondary"
vectors.
– Each vector may be defined by a variety of geometric means:
» Position vector
» Target near point vector
» Velocity vector
» Constant vector
• The user associates specified positive or negative
axes of the two-vector frame with the primary and
secondary vectors.
– Two-vector frames are always right-handed and have orthogonal
axes, so two non-parallel vectors and associations of axes with these
vectors suffice to define the orientation of a frame.

Dynamic Frames 17
 N IF Two-Vector Frame Concepts - 2
Navigation and Ancillary Information Facility

• Primary Vector
– A specified positive or negative axis of the two-vector frame is
aligned with this vector.
» The frame kernel creator assigns to this vector one of the axis
designations { +X, -X, +Y, -Y, +Z, -Z }.
– Two degrees of freedom of the frame orientation are removed by
association of an axis with the primary vector. The third degree
of freedom is the frame's rotation about the primary vector.
– Example: a frame's -X axis is aligned with the primary vector:

Y
-X
Primary Vector
Z

Dynamic Frames 18
 N IF Two-Vector Frame Concepts - 3
Navigation and Ancillary Information Facility

• Secondary Vector
– A specified positive or negative axis of the two-vector frame is aligned
with the component of the secondary vector orthogonal to the primary
vector.
» The frame kernel creator associates with this vector one of the
axis designations { +X, -X, +Y, -Y, +Z, -Z }, where the axis is
orthogonal to that associated with the primary vector.
– Example, continued: the frame's +Y axis is associated with the
secondary vector. The component of the secondary vector
orthogonal to the primary vector is aligned with the frame's +Y axis.
The secondary vector thus lies in the frame's X-Y plane.

-X Y
Primary Vector
Secondary Vector
Z
Component of secondary
X vector orthogonal to primary
vector
Dynamic Frames 19
 N IF Two-Vector Frame Concepts - 4
Navigation and Ancillary Information Facility

• Secondary Vector, continued

– Typically the secondary vector itself is not orthogonal to the
primary vector.
– However, the secondary vector must be linearly independent
of the primary vector.
» Near-degenerate geometry can lead to extreme loss of precision.
• This problem can be difficult to diagnose.
» SPICE enforces independence using a default angular separation
tolerance of 1 milliradian. The angular separation of the primary
and secondary vectors may not differ from 0 or Pi radians by less
than this tolerance.
» A frame kernel creator can specify a different tolerance value.
The frame kernel assignment for this is:
FRAME_<frame_ID>_ANGLE_SEP_TOL = <tolerance>

where the tolerance is given in radians.

– Designers of two-vector frames should ensure that the primary
and secondary vectors can't become nearly parallel for any
realistic evaluation epoch.
Dynamic Frames 20
 N IF Two-Vector Frame Concepts - 5
Navigation and Ancillary Information Facility

• In the next several pages we’ll describe methods

for specifying the primary and secondary vectors
used in creating a dynamic frame.

Dynamic Frames 21
 N IF Two-Vector Frame Concepts - 6
Navigation and Ancillary Information Facility

• Using a Position Vector

– Defined by the position of one ephemeris object relative
to another. The frame kernel creator specifies:
» the target
» the observer
» the aberration correction
• The vector may optionally be corrected for light time and
stellar aberration.
– The epoch at which the position vector is computed is
supplied via a call to a SPICE API:
» as an input to an SPK routine, e.g. SPKEZR, SPKPOS.
» as an input to a frame system routine, e.g. SXFORM,
PXFORM.
– The reference frame relative to which the vector is
expressed is not specified by the frame kernel creator.
» SPICE automatically selects this frame.
Dynamic Frames 22
 N IF Two-Vector Frame Concepts - 7
Navigation and Ancillary Information Facility

• Using a Target Near Point Vector

– Defined as the vector from an observer to the nearest point on a
specified extended target body to that observer. The frame
kernel creator specifies:
» the target
» the observer
» the aberration correction
• The vector may optionally be corrected for one-way light time
and stellar aberration.
• When one-way light time correction is used, both the position
and orientation of the target body are corrected for light time.
– The extended target body is modeled as a triaxial ellipsoid.
» Size and shape data are given by a PCK.
– The epoch is supplied via a SPICE API call.
– The reference frame relative to which the vector is expressed is
not specified by the frame kernel creator.
» SPICE automatically selects this frame.
Dynamic Frames 23
 N IF Two-Vector Frame Concepts - 8
Navigation and Ancillary Information Facility

• Using a Velocity Vector

– Defined by the velocity of a target ephemeris object relative to
an observing ephemeris object. The frame kernel creator
specifies:
» the target
» the observer
» the velocity reference frame
• This frame may be distinct from the base frame.
• Different velocity frame choices can lead to radically different
two-vector frame definitions.
» the aberration correction
• The velocity vector may optionally be corrected for one-way
light time and stellar aberration.
• Use of light time correction also implies evaluation of the
velocity vector's frame at a light time corrected epoch: the
epoch is corrected for light time between the velocity frame's
center and the observer, if the velocity frame is non-inertial.
– The epoch is supplied via a SPICE API call.
Dynamic Frames 24
 N IF Two-Vector Frame Concepts - 9
Navigation and Ancillary Information Facility

• Using a Constant Vector

– The vector is constant in a frame specified by the kernel
creator.
» The constant vector's frame may be time-dependent.
» This frame may be distinct from the base frame.
– The vector may be specified in a variety of coordinate
systems.
» Cartesian
» Latitudinal
» Right ascension/declination (RA/DEC)
– An observer may optionally be associated with a constant
vector for the purpose of defining aberration corrections.
» The orientation of the constant vector's frame may
optionally be corrected for one-way light time between the
frame's center and the observer: if the frame is non-
inertial, it is evaluated at a light time corrected epoch.
continued on next page
Dynamic Frames 25
 N IF Two-Vector Frame Concepts - 10
Navigation and Ancillary Information Facility
continued from previous page

» A constant vector may optionally be corrected for

stellar aberration due to motion of observer relative to
solar system barycenter.
• Stellar aberration can be specified without light time
correction; the string indicating stellar aberration
correction alone is ‘S’
– The epoch is supplied via a SPICE API call, as for position
vectors.
» If the constant vector's frame is time-dependent, that
frame is evaluated at this epoch, optionally adjusted
for light time.

Dynamic Frames 26
 N IF Two-Vector Frame Examples - 1
Navigation and Ancillary Information Facility

Nadir-Oriented Spacecraft-Centered Frame

Primary vector: spacecraft nadir direction
Y = Z x X, completing the vector. Aligned with nadir frame's -Z axis.
right-handed frame.
Nadir vector can be
Y defined to point to
either:
• closest point to spacecraft
on ellipsoid
• center of mass of orbited
body

Secondary vector: spacecraft velocity

Z relative to S/C center of motion in the
X J2000 frame. Associated with nadir
frame's +X axis.

Normalized component of secondary

vector orthogonal to primary vector is
aligned with the nadir frame's +X axis.

See the next page for the FK specifications for this frame.
Dynamic Frames 27
 N IF Two-Vector Frame Examples - 2
Navigation and Ancillary Information Facility

Nadir-Oriented Spacecraft-Centered Frame: Frame kernel specification.

The -Z axis points from the spacecraft toward the closest point on Mars.

The component of the inertially referenced spacecraft velocity

vector orthogonal to Z is aligned with the +X axis.

The +Y axis is the cross product of the +Z axis and the +X axis.

\begindata

FRAME_<frame_name> = <frame_ID> Definitions

FRAME_<frame_ID>_NAME = <frame_name>
FRAME_<frame_ID>_CLASS = 5 <frame_ID> = integer frame ID
FRAME_<frame_ID>_CLASS_ID = <frame_ID> code
FRAME_<frame_ID>_CENTER = <orbiter_ID> <frame_name> = user-specified
FRAME_<frame_ID>_RELATIVE = 'J2000' frame name
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED' <orbiter_ID> = NAIF ID code of
FRAME_<frame_ID>_FAMILY = 'TWO-VECTOR' spacecraft
FRAME_<frame_ID>_PRI_AXIS = '-Z' <orbiter_ID/name> = NAIF ID code or
FRAME_<frame_ID>_PRI_VECTOR_DEF = 'TARGET_NEAR_POINT' name of spacecraft
FRAME_<frame_ID>_PRI_OBSERVER = <orbiter_ID/name>
FRAME_<frame_ID>_PRI_TARGET = 'MARS'
FRAME_<frame_ID>_PRI_ABCORR = 'NONE'
FRAME_<frame_ID>_SEC_AXIS = 'X'
FRAME_<frame_ID>_SEC_VECTOR_DEF = 'OBSERVER_TARGET_VELOCITY'
FRAME_<frame_ID>_SEC_OBSERVER = 'MARS'
FRAME_<frame_ID>_SEC_TARGET = <orbiter_ID/name>
FRAME_<frame_ID>_SEC_ABCORR = 'NONE'
FRAME_<frame_ID>_SEC_FRAME = 'J2000'

Dynamic Frames 28
 N IF Two-Vector Frame Examples - 3
Navigation and Ancillary Information Facility

Spacecraft "View Frame"

Secondary vector:
spacecraft position relative to center of motion.
Associated with view frame's +Y axis in frame
kernel.
X = Y x Z, completing the
right-handed frame. X
("Out of plane" direction)

Z
Primary vector: spacecraft
Y velocity relative to center of
motion in J2000 frame. Aligned
Normalized component of secondary with view frame's +Z axis in
vector orthogonal to primary vector
frame kernel. ("Down track"
is aligned with the view frame's +Y
direction)
axis. ("In plane" direction)

See the next page for the FK specifications for this frame.
Dynamic Frames 29
 N IF Two-Vector Frame Examples - 4
Navigation and Ancillary Information Facility

Spacecraft "View Frame": Frame kernel specification.

The +Z axis is aligned with the J2000-referenced velocity of the

spacecraft relative to Mars.

The component of the spacecraft position orthogonal to +Z is aligned

with the +Y axis.

The +X axis is the cross product of the +Y axis and the +Z axis.
Definitions
\begindata
<frame_ID> = integer frame ID
FRAME_<frame_name> = <frame_ID> code
FRAME_<frame_ID>_NAME = <frame_name> <frame_name> = user-specified
FRAME_<frame_ID>_CLASS = 5 frame name
FRAME_<frame_ID>_CLASS_ID = <frame_ID> <orbiter_ID> = NAIF ID code of
FRAME_<frame_ID>_CENTER = <orbiter_ID> spacecraft
FRAME_<frame_ID>_RELATIVE = 'J2000' <orbiter_ID/name> = NAIF ID code or
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED' name of spacecraft
FRAME_<frame_ID>_FAMILY = 'TWO-VECTOR'
FRAME_<frame_ID>_PRI_AXIS = 'Z'
FRAME_<frame_ID>_PRI_VECTOR_DEF = 'OBSERVER_TARGET_VELOCITY'
FRAME_<frame_ID>_PRI_OBSERVER = 'MARS'
FRAME_<frame_ID>_PRI_TARGET = <orbiter_ID/name>
FRAME_<frame_ID>_PRI_ABCORR = 'NONE'
FRAME_<frame_ID>_PRI_FRAME = 'J2000'
FRAME_<frame_ID>_SEC_AXIS = 'Y'
FRAME_<frame_ID>_SEC_VECTOR_DEF = 'OBSERVER_TARGET_POSITION'
FRAME_<frame_ID>_SEC_OBSERVER = 'MARS'
FRAME_<frame_ID>_SEC_TARGET = <orbiter_ID/name>
FRAME_<frame_ID>_SEC_ABCORR = 'NONE'
Dynamic Frames 30
 N IF Two-Vector Frame Examples - 5
Navigation and Ancillary Information Facility

Geocentric Solar Ecliptic Frame (GSE)

Primary vector: position of sun relative to earth.

Aligned with GSE frame's +X axis.

Z = X x Y,
completing the
right-handed frame
X

Y
Normalized component
of secondary vector
Secondary vector: velocity of sun orthogonal to primary
relative to earth in J2000 frame. vector is aligned with the
Associated with GSE frame's +Y axis in
GSE frame’s +Y axis.
frame kernel.

Dynamic Frames
See the next page for the FK specifications for this frame.
31
 N IF Two-Vector Frame Examples - 6
Navigation and Ancillary Information Facility
Geocentric Solar Ecliptic (GSE) frame:

+X is parallel to the geometric earth-sun position vector.

+Y axis is the normalized component of the geometric earth-sun velocity

vector orthogonal to the GSE +X axis.

+Z axis is parallel to the cross product of the GSE +X axis

and the GSE +Y axis.

\begindata

FRAME_GSE = <frame_ID> Definition

FRAME_<frame_ID>_NAME = 'GSE' <frame_ID> = integer frame
FRAME_<frame_ID>_CLASS = 5 ID code
FRAME_<frame_ID>_CLASS_ID = <frame_ID>
FRAME_<frame_ID>_CENTER = 399
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'TWO-VECTOR'
FRAME_<frame_ID>_PRI_AXIS = 'X'
FRAME_<frame_ID>_PRI_VECTOR_DEF = 'OBSERVER_TARGET_POSITION'
FRAME_<frame_ID>_PRI_OBSERVER = 'EARTH'
FRAME_<frame_ID>_PRI_TARGET = 'SUN'
FRAME_<frame_ID>_PRI_ABCORR = 'NONE'
FRAME_<frame_ID>_SEC_AXIS = 'Y'
FRAME_<frame_ID>_SEC_VECTOR_DEF = 'OBSERVER_TARGET_VELOCITY'
FRAME_<frame_ID>_SEC_OBSERVER = 'EARTH'
FRAME_<frame_ID>_SEC_TARGET = 'SUN'
FRAME_<frame_ID>_SEC_ABCORR = 'NONE'
FRAME_<frame_ID>_SEC_FRAME = 'J2000'

Dynamic Frames 32
 N IF Two-Vector Frame Examples - 7
Navigation and Ancillary Information Facility

Geocentric Solar Magnetospheric Frame (GSM)

Secondary vector: North geomagnetic centered
dipole in IAU_EARTH frame. Associated with
GSM frame's +Z axis in frame kernel.

Normalized
Z component of
secondary vector
orthogonal to
primary vector is
aligned with the
Primary vector: position of sun relative to earth. GSM frame’s +Z
Aligned with GSM frame's +X axis. axis

Y = Z x X,
completing the
right-handed frame

See the next page for the FK specifications for this frame.
Dynamic Frames 33
 N IF Two-Vector Frame Examples - 8
Navigation and Ancillary Information Facility
Geocentric Solar Magnetospheric (GSM) frame:

+X is parallel to the geometric earth-sun position vector.

+Z axis is normalized component of north centered geomagnetic dipole

vector orthogonal to GSM +X axis.

+Y completes the right-handed frame.

\begindata

FRAME_GSM = <frame_ID>
FRAME_<frame_ID>_NAME = 'GSM' Definition
FRAME_<frame_ID>_CLASS = 5 <frame_ID> = integer frame
FRAME_<frame_ID>_CLASS_ID = <frame_ID> ID code
FRAME_<frame_ID>_CENTER = 399
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'TWO-VECTOR'
FRAME_<frame_ID>_PRI_AXIS = 'X'
FRAME_<frame_ID>_PRI_VECTOR_DEF = 'OBSERVER_TARGET_POSITION'
FRAME_<frame_ID>_PRI_OBSERVER = 'EARTH'
FRAME_<frame_ID>_PRI_TARGET = 'SUN'
FRAME_<frame_ID>_PRI_ABCORR = 'NONE'
FRAME_<frame_ID>_SEC_AXIS = 'Z'
FRAME_<frame_ID>_SEC_VECTOR_DEF = 'CONSTANT'
FRAME_<frame_ID>_SEC_FRAME = 'IAU_EARTH'
FRAME_<frame_ID>_SEC_SPEC = 'LATITUDINAL'
FRAME_<frame_ID>_SEC_UNITS = 'DEGREES'
FRAME_<frame_ID>_SEC_LONGITUDE = 288.43
FRAME_<frame_ID>_SEC_LATITUDE = 79.54

Dynamic Frames 34
 N IF Two-Vector Frame Examples - 9
Navigation and Ancillary Information Facility

Spacecraft-Centered Roll-Celestial Frame

Secondary vector: Lock star direction in J2000 frame, corrected
for stellar aberration due to spacecraft motion. Associated with
Roll-Celestial frame's +X axis in frame kernel.

Normalized
component of
X secondary vector
orthogonal to
primary vector is
aligned with the SCR
frame’s +X axis
Primary vector: position of earth relative to
spacecraft. Aligned with Roll-Celestial frame's
+Z axis. Y = Z x X,
completing the
right-handed frame
Dynamic Frames See the next page for the FK specifications for this frame. 35
 N IF Two-Vector Frame Examples - 10
Navigation and Ancillary Information Facility
Spacecraft-centered roll-celestial frame:

+Z is parallel to the geometric earth-sun position vector.

+X axis is normalized component of star direction orthogonal to Z axis. The star

direction is corrected for stellar aberration due to motion of the spacecraft.

+Y completes the right-handed frame. Definitions

\begindata <frame_ID> = integer frame ID
FRAME_<frame_name> = <frame_ID> code
FRAME_<frame_ID>_NAME = <frame_name> <frame_name> = user-specified
FRAME_<frame_ID>_CLASS = 5 frame name
FRAME_<frame_ID>_CLASS_ID = <frame_ID> <spacecraft_ID> = NAIF ID code of
FRAME_<frame_ID>_CENTER = <spacecraft_ID> spacecraft
FRAME_<frame_ID>_RELATIVE = 'J2000' <spacecraft_ID/name> = NAIF ID code or
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED' name of spacecraft
FRAME_<frame_ID>_FAMILY = 'TWO-VECTOR'
FRAME_<frame_ID>_PRI_AXIS = 'Z'
FRAME_<frame_ID>_PRI_VECTOR_DEF = 'OBSERVER_TARGET_POSITION'
FRAME_<frame_ID>_PRI_OBSERVER = <spacecraft_ID/name>
FRAME_<frame_ID>_PRI_TARGET = 'EARTH'
FRAME_<frame_ID>_PRI_ABCORR = 'NONE'
FRAME_<frame_ID>_SEC_AXIS = 'X'
FRAME_<frame_ID>_SEC_VECTOR_DEF = 'CONSTANT'
FRAME_<frame_ID>_SEC_FRAME = 'J2000'
FRAME_<frame_ID>_SEC_SPEC = 'RA/DEC'
FRAME_<frame_ID>_SEC_UNITS = 'DEGREES'
FRAME_<frame_ID>_SEC_RA = <star right ascension in degrees>
FRAME_<frame_ID>_SEC_DEC = <star declination in degrees>
FRAME_<frame_ID>_SEC_OBSERVER = <spacecraft_ID/name>
FRAME_<frame_ID>_SEC_ABCORR = 'S'
Dynamic Frames 36
 N IF "Of-Date" Frames - 1
Navigation and Ancillary Information Facility

• Of-date frames are associated with user-specified

bodies and are based on user-selected dynamical
models.
– Implementations of these models are built into SPICE.
• The currently supported "of-date" frame families
are
– Mean Equator and Equinox of Date
– True Equator and Equinox of Date
– Mean Ecliptic and Equinox of Date
• Currently the Earth is the only supported body for
of-date dynamic frames.

Dynamic Frames 37
 N IF "Of-Date" Frames - 2
Navigation and Ancillary Information Facility

• The supported types of models are:

– Precession
– Nutation
– Mean obliquity

• The of-date frame implementation is intended to be

flexible…
– The set of supported bodies can grow over time.
– The set of supported models can grow over time.
» SPICE is not forever locked into using a single hard-
coded implementation, such as the 1976 IAU precession
model.

Dynamic Frames 38
 N IF "Of-Date" Frames - 3
Navigation and Ancillary Information Facility

• Mean Equator and Equinox of Date Family

– For all reference frames in this family…
» The frame's relationship to the J2000 frame is given
by a precession model.
» The frame kernel creator selects a precession model
from those built into the SPICE software.
• Currently supported only for the Earth, and only the
1976 IAU precession model (Lieske model)
» The frame kernel creator must either specify the
frame's rotation state or must designate the frame
“frozen” at a specified “freeze epoch” (but not both).

Dynamic Frames 39
 N IF "Of-Date" Frames - 4
Navigation and Ancillary Information Facility

Earth mean equator and equinox of date frame:

+Z axis is perpendicular to the mean equator of date and points north.

+X axis is parallel to the cross product of the +Z axis and

the north-pointing vector normal to the mean ecliptic of date.

+Y axis completes the right-handed frame.

\begindata Definitions
<frame_ID> = integer frame ID
FRAME_<frame_name> = <frame_ID> code
FRAME_<frame_ID>_NAME = <frame_name> <frame_name> = user-specified
FRAME_<frame_ID>_CLASS = 5 frame name
FRAME_<frame_ID>_CLASS_ID = <frame_ID>
FRAME_<frame_ID>_CENTER = 399
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'MEAN_EQUATOR_AND_EQUINOX_OF_DATE'
FRAME_<frame_ID>_PREC_MODEL = 'EARTH_IAU_1976'
FRAME_<frame_ID>_ROTATION_STATE = 'ROTATING'
This is currently the
only allowed value for
precession model.

Dynamic Frames 40
 N IF "Of-Date" Frames - 5
Navigation and Ancillary Information Facility

• True Equator and Equinox of Date Family

– For all reference frames in this family…
» The frame's relationship to the J2000 frame is given
by a precession model and a nutation model.
» The frame kernel creator selects models from those
built into the SPICE software.
• Currently supported only for the Earth
• Currently only the 1976 IAU precession model (Lieske model)
is allowed.
• Currently only the 1980 IAU nutation model is allowed.
» The frame kernel creator must either specify the
frame's rotation state or must designate the frame
“frozen” at a specified “freeze epoch” (but not both).

Dynamic Frames 41
 N IF "Of-Date" Frames - 6
Navigation and Ancillary Information Facility

Earth true equator and equinox of date frame:

+Z axis is perpendicular to the true equator of date and points north.

+X axis is parallel to the cross product of the +Z axis and

the north-pointing vector normal to the mean ecliptic of date.

+Y axis completes the right-handed frame.

\begindata Definitions
<frame_ID> = integer frame ID
FRAME_<frame_name> = <frame_ID> code
FRAME_<frame_ID>_NAME = <frame_name> <frame_name> = user-specified
FRAME_<frame_ID>_CLASS = 5 frame name
FRAME_<frame_ID>_CLASS_ID = <frame_ID>
FRAME_<frame_ID>_CENTER = 399
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'TRUE_EQUATOR_AND_EQUINOX_OF_DATE'
FRAME_<frame_ID>_PREC_MODEL = 'EARTH_IAU_1976'
FRAME_<frame_ID>_NUT_MODEL = 'EARTH_IAU_1980'
FRAME_<frame_ID>_ROTATION_STATE = 'ROTATING' These are currently the
only allowed values for
precession model and
nutation model.

Dynamic Frames 42
 N IF "Of-Date" Frames - 7
Navigation and Ancillary Information Facility

• Mean Ecliptic and Equinox of Date Family

– For all reference frames in this family…
» The frame's relationship to the J2000 frame is given
by a precession model and an obliquity model.
» The frame kernel creator selects models from those
built into the SPICE software.
• Currently supported only for the Earth.
• Currently only the 1976 IAU precession model (Lieske model)
is allowed.
• Currently only the 1980 IAU mean obliquity model is allowed.
» The frame kernel creator must either specify the
frame's rotation state or must designate the frame
"frozen" at a specified "freeze epoch."

Dynamic Frames 43
 N IF "Of-Date" Frames - 8
Navigation and Ancillary Information Facility

Earth mean ecliptic and equinox of date frame:

+Z axis is perpendicular to mean ecliptic of date and points toward

ecliptic north.

+X axis is parallel to the cross product of the north-pointing

vector normal to mean equator of date and the +Z axis.

+Y axis completes the right-handed frame. Definitions

<frame_ID> = integer frame ID
\begindata code
<frame_name> = user-specified
FRAME_<frame_name> = <frame_ID> frame name
FRAME_<frame_ID>_NAME = <frame_name>
FRAME_<frame_ID>_CLASS = 5
FRAME_<frame_ID>_CLASS_ID = <frame_ID>
FRAME_<frame_ID>_CENTER = 399
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'MEAN_ECLIPTIC_AND_EQUINOX_OF_DATE'
FRAME_<frame_ID>_PREC_MODEL = 'EARTH_IAU_1976'
FRAME_<frame_ID>_OBLIQ_MODEL = 'EARTH_IAU_1980'
FRAME_<frame_ID>_ROTATION_STATE = 'ROTATING' These are currently the
only allowed values for
precession model and
obliquity model.

Dynamic Frames 44
 N IF Euler Frames - 1
Navigation and Ancillary Information Facility

• Euler frames are defined by a time-dependent

rotation relative to a base frame.
– The rotation from an Euler frame to its base frame is given by three
Euler angles.
– Each angle is given by a separate polynomial.
» The polynomials may have different degrees.
» The independent variable is a time offset, in TDB seconds,
from an epoch specified by the frame kernel creator.
» The units associated with the angles are specified by the
frame kernel creator.
» The sequence of rotation axes is specified by the frame kernel
creator.
• The central axis must differ from the other two.
• The rotation from the Euler frame to the base frame is
[angle_1]axis_1 [angle_2]axis_2 [angle_3]axis_3

Dynamic Frames 45
 N IF Euler Frames - 2
Navigation and Ancillary Information Facility

• Five examples
– Dynamic version of earth magnetospheric frame (MAG)
» Latitude and longitude of the north centered geomagnetic
dipole are given by polynomials.
– Spinning spacecraft frame
» The base frame could be a:
• Built-in inertial frame
• C-kernel frame
• Roll-celestial frame (using lock star)
• Nadir frame
– Topocentric frames for tracking stations for which crustal plate
motion is modeled
» The frame rotation keeps the frame orientation consistent with
the changing station location.

continued on next page

Dynamic Frames 46
 N IF Euler Frames - 3
Navigation and Ancillary Information Facility

– Mean or true body equator and body equinox of date frame,

where the body is a planet or satellite other than the earth
» The base frame is an IAU_<body> frame.
» The Euler frame "removes" the body's rotation about the
spin axis.
– Variation on supported "of date" frame
» An existing supported "of date" frame is used as the base
frame.
» Perturbations to the "of date" frame are expressed using
Euler angles.

Dynamic Frames 47
 N IF Euler Frames - 4
Navigation and Ancillary Information Facility
As an example, we construct an Euler frame called IAU_MARS_EULER. Frame
IAU_MARS_EULER is mathematically identical to the PCK frame named IAU_MARS.
The PCK data defining the underlying IAU_MARS frame are:

BODY499_POLE_RA = ( 317.68143 -0.1061 0. )

BODY499_POLE_DEC = ( 52.88650 -0.0609 0. )
BODY499_PM = ( 176.630 350.89198226 0. )

Relative to the angles used to define the IAU_MARS frame, the angles for our
Euler frame definition are reversed and the signs negated. Angular units are
degrees. Rate units are degrees/second, unlike the PCK units of degrees/day.

angle_3 is 90 + RA angle_1 is -90 - RA

PCK: angle_2 is 90 - Dec Euler Frame: angle_2 is -90 + Dec
angle_1 is PM angle_3 is - PM

\begindata
FRAME_IAU_MARS_EULER = <frame_ID>
FRAME_<frame_ID>_NAME = 'IAU_MARS_EULER' Definition
FRAME_<frame_ID>_CLASS = 5 <frame_ID> = integer frame ID
FRAME_<frame_ID>_CLASS_ID = <frame_ID> code
FRAME_<frame_ID>_CENTER = 499
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'EULER'
FRAME_<frame_ID>_EPOCH = @2000-JAN-1/12:00:00
FRAME_<frame_ID>_AXES = ( 3 1 3 )
FRAME_<frame_ID>_UNITS = 'DEGREES'
FRAME_<frame_ID>_ANGLE_1_COEFFS = ( -47.68143 0.33621061170684714E-10 )
FRAME_<frame_ID>_ANGLE_2_COEFFS = ( -37.1135 -0.19298045478743630E-10 )
FRAME_<frame_ID>_ANGLE_3_COEFFS = ( -176.630 -0.40612497946759260E-02 )

Dynamic Frames 48
 N IF Product Frames - 1
Navigation and Ancillary Information Facility

• Product frames are defined by a product of one or

more frame transformations.
– Each factor in the product is a transformation from one frame
known to the SPICE system to another such frame. The factor
transformations may be time-dependent.
• Product frames are a generalization of TK (class 4,
constant-offset) frames.
• A product frame implementing the transformation
from a frame BASE to a frame PRODUCT has the
form

PRODUCT TO_1 TO_2 TO_N

T = T * T … * T
BASE FROM_1 FROM_2 FROM_N

Dynamic Frames 49
 N IF Product Frames - 2
Navigation and Ancillary Information Facility

• In the implementation of the product above, the

factor transformations are applied in right-to-left
order.
• The ``from'' and ``to'' frames of a product frame
definition may be completely arbitrary. The only
restriction on these frames is that the transformation
from each ``from'' frame to its corresponding ``to''
frame must be computable by SPICE at the time the
product frame is used.
• Because product frames are parameterized dynamic
frames, limits on recursion depth for dynamic frames
imply that while the factors may be dynamic frames,
they may not be dynamic frames that require a level
of recursion in order to evaluate their orientation.

Dynamic Frames 50
 N IF Product Frames - 3
Navigation and Ancillary Information Facility

• A product frame is specified in a frame kernel using

assignments of the following form. The "from" and
"to" frames must be specified by name:
FRAME_<frame_name> = <frame_ID>
FRAME_<frame_ID>_NAME = <frame_name>
FRAME_<frame_ID>_CLASS = 5
FRAME_<frame_ID>_CLASS_ID = <frame_ID>
FRAME_<frame_ID>_CENTER = <center ID or name>
FRAME_<frame_ID>_RELATIVE = '<frame_name>'

FRAME_<frame_ID>_FAMILY = 'PRODUCT'

FRAME_<frame_ID>_FROM_FRAMES = ( '<from_frame_1>'
'<from_frame_2>'
…
'<from_frame_N>' )

FRAME_<frame_ID>_TO_FRAMES = ( '<to_frame_1>'
'<to_frame_2>'
…
'<to_frame_N>' )

Dynamic Frames 51
 N IF Frozen Dynamic Frames - 1
Navigation and Ancillary Information Facility

• A frozen dynamic frame is a "Snapshot" of a

dynamic frame at a specified epoch.
– The frame is frozen relative to the base frame specified by
the frame kernel creator in the frame kernel definition.
– The rotation from the frozen frame to the base frame is
constant.
– The rotation is not frozen with respect to inertial frames
unless the base frame is inertial.
– A frame is designated frozen by the presence of a "freeze
epoch" specification in the frame definition, for example:
FRAME_<FRAME_ID>_FREEZE_EPOCH = @1949-DEC-31/22:09:46.861901

– The freeze epoch is specified using SPICE text kernel rules.

» The “@” syntax is used.
» The time system is assumed to be TDB.

Dynamic Frames 52
 N IF Frozen Dynamic Frames - 2
Navigation and Ancillary Information Facility

Frozen version of Earth mean equator and equinox of date frame:

+Z axis is perpendicular to the mean equator of date and points north.

+X axis is parallel to the cross product of the +Z axis and the

vector normal to the mean ecliptic of date.

+Y axis completes the right-handed frame.

\begindata Definitions
<frame_ID> = integer frame ID
FRAME_<frame_name> = <frame_ID> code
FRAME_<frame_ID>_NAME = <frame_name> <frame_name> = user-specified
FRAME_<frame_ID>_CLASS = 5 frame name
FRAME_<frame_ID>_CLASS_ID = <frame_ID>
FRAME_<frame_ID>_CENTER = 399
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'MEAN_EQUATOR_AND_EQUINOX_OF_DATE'
FRAME_<frame_ID>_PREC_MODEL = 'EARTH_IAU_1976'
FRAME_<frame_ID>_FREEZE_EPOCH = @1949-DEC-31/22:09:46.861901

Dynamic Frames 53
 N IF Inertial Dynamic Frames - 1
Navigation and Ancillary Information Facility

• Inertial dynamic frames are specified by setting

the rotation state to 'INERTIAL' in the rotation
state assignment:
FRAME_<FRAME_ID>_ROTATION_STATE = 'INERTIAL'
– The 'INERTIAL' state implies the frame is treated as inertial for
the purpose of velocity transformations.
– The state transformation between any inertial frame and
"inertial dynamic frame" has a zero derivative block: the state
transformation matrix has the form

R(t) | 0
-------|------
Derivative
block
0 | R(t)

where R(t) is a time-dependent rotation.

continued on next page

Dynamic Frames 54
 N IF Inertial Dynamic Frames - 2
Navigation and Ancillary Information Facility

– In contrast, for any rotating frame R(t), the state

transformation between any inertial frame and R(t) has a
corresponding matrix of the form
R(t) | 0
-------|------
dR(t)/dt| R(t)

– The inertial rotation state:

» simplifies velocity transformations – velocities are
transformed by a rotation.
» may be useful for maintaining consistency with other
dynamic frame implementations.
» only makes sense if the "inertial" dynamic frame
actually rotates very slowly!

Dynamic Frames 55
 N IF Inertial Dynamic Frames - 3
Navigation and Ancillary Information Facility

Inertial version of Earth true equator and equinox of date frame:

+Z axis is perpendicular to the true equator of date and points north.

+X axis is parallel to the cross product of the +Z axis and the

vector normal to the mean ecliptic of date.

+Y axis completes the right-handed frame.

\begindata Definitions
<frame_ID> = integer frame ID
FRAME_<frame_name> = <frame_ID> code
FRAME_<frame_ID>_NAME = <frame_name> <frame_name> = user-specified
FRAME_<frame_ID>_CLASS = 5 frame name
FRAME_<frame_ID>_CLASS_ID = <frame_ID>
FRAME_<frame_ID>_CENTER = 399
FRAME_<frame_ID>_RELATIVE = 'J2000'
FRAME_<frame_ID>_DEF_STYLE = 'PARAMETERIZED'
FRAME_<frame_ID>_FAMILY = 'TRUE_EQUATOR_AND_EQUINOX_OF_DATE'
FRAME_<frame_ID>_PREC_MODEL = 'EARTH_IAU_1976'
FRAME_<frame_ID>_NUT_MODEL = 'EARTH_IAU_1980'
FRAME_<frame_ID>_ROTATION_STATE = 'INERTIAL' These are currently the
only allowed values for
precession model and
nutation model.

Dynamic Frames 56
 N IF Backup
Navigation and Ancillary Information Facility

• Numerical Issues
• Limitations

Dynamic Frames 57
 N IF Numerical Issues - 1
Navigation and Ancillary Information Facility

• Two-vector frame derivatives may be inaccurate. Let R(t)

represent a time-dependent rotation:
– If R(t) depends on CK data, dR(t)/dt may be inaccurate because CK rates
frequently have low accuracy.
– If R(t) depends on velocity vectors, then dR(t)/dt depends on acceleration
determined via numerical differentiation. Typically such derivatives suffer
loss of accuracy.
» However, if velocities are "well-behaved," numerically derived
acceleration can be quite good. Example: GSE frame.
– If R(t) depends on position vectors, the velocities associated with those
vectors by the SPK system may not be mathematically consistent with the
positions. This can happen for SPK types with separate polynomials for
position and velocity, such as types 3, 8, 9, and 14.
– If R(t) depends on aberration-corrected vectors, the associated velocities
may be inaccurate due to accuracy limitations of the aberration
corrections applied to velocities by the SPK system.

Dynamic Frames 58
 N IF Numerical Issues - 2
Navigation and Ancillary Information Facility

• Recommendations
– Avoid using aberration corrections in two-vector frame definitions
if accurate velocity transformations are required.
– Be aware of the accuracy of the data on which two-vector frames
are based.

Dynamic Frames 59
 N IF Limitations - 1
Navigation and Ancillary Information Facility

• Simulated recursion:
– ANSI Fortran 77 doesn't support recursion, so the SPICE dynamic
frame system implements limited, simulated recursion.
» Two levels of recursion are supported for selected SPK and
Frames System routines.
– Users must avoid requesting "deeper" recursion than the SPICE
dynamic frame system can support.
» When defining dynamic frames:
• Choose J2000 as the base frame for two-vector frames.
• Except for Euler frames, avoid using dynamic frames as base
frames.
• Try to avoid choosing a dynamic frame as the frame associated
with a velocity or constant vector.
» In SPK, CK, or PCK kernels, don't use two-vector frames as
the base frame relative to which ephemeris or attitude data
are specified.
• "Of-date" or Euler frames are OK for this purpose.

Dynamic Frames 60
 N IF Limitations - 2
Navigation and Ancillary Information Facility

• Run-time efficiency:
– Dynamic frame evaluation typically requires more computation
than is needed for CK- or PCK-based frames.
» For example, evaluation of a two-vector frame may involve
several SPK calls.
» Euler frames are an exception: these are fairly efficient as
long as they don't have a base frame that requires a lot of
computation to evaluate.
– To minimize the performance penalty:
» use J2000 as the base frame for two-vector frames.
» use the simplest frames possible for association with velocity
or constant vectors in two-vector frame definitions.
• Prefer non-dynamic frames to dynamic frames and inertial
frames to non-inertial frames where there is a choice.

Dynamic Frames 61
N IF
Navigation and Ancillary Information Facility

Instrument Kernel
IK

April 2023
 N IF Purpose
Navigation and Ancillary Information Facility

• The Instrument Kernel serves as a repository for

instrument-specific geometry information useful
within the SPICE context.
– Always included:
» If an instrument has a field-of-view (FOV), specifications for
an instrument’s size, shape, and orientation
– Other possibilities:
» Timing parameters
» Optical parameters
» Detector geometric parameters
» Optical distortion parameters
• An antenna or solar array or other structure for
which pointing is important can also use the IK
• Note: instrument mounting alignment data are
specified in a mission’s Frames Kernel (FK)
Instrument Kernel 2
 N IF I-Kernel Structure
Navigation and Ancillary Information Facility

• An I-Kernel is a SPICE text kernel. The format and structure

of a typical I-Kernel is shown below.
KPL/IK
Comments describing the keywords and values
to follow, as well as any other pertinent
information.

\begindata
Keyword = Value(s) Assignment
Keyword = Value(s) Assignment

\begintext

More descriptive comments.

\begindata
Keyword = Value(s) Assignment
\begintext

More descriptive comments.

Instrument Kernel etc … 3
 N IF I-Kernel Contents (1)
Navigation and Ancillary Information Facility

• The requirements on keywords in an IK are the following:

– Keywords must begin with INS[#], where [#] is replaced with the NAIF
instrument ID code (which is a negative number)
– The total length of the keyword must be less than or equal to 32 characters
– Keywords are case-sensitive (Keyword != KEYWORD)

• Examples of IK keywords, with descriptions:

– INS-94031_FOCAL_LENGTH MGS MOC NA focal length
– INS-41220_IFOV MEX HRSC SRC pixel angular size
– INS-41130_NUMBER_OF_SECTORS MEX ASPERA NPI number of sectors

• In general SPICE does not require any specific keywords to be

present in an IK
• One exception is a set of keywords defining an instrument’s FOV, if the
SPICE Toolkit’s GETFVN or GETFOV routine is planned to be used to
retrieve the FOV attributes

Instrument Kernel 4
 N IF I-Kernel Contents (2)
Navigation and Ancillary Information Facility

• IKs should contain extensive comments regarding:

– Instrument overview
– Reference source(s) for the data included in the IK
– Names/IDs assigned to the instrument and its parts
– Explanation of each keyword included in the file
– Description of the FOV and detector layout
– Where appropriate, descriptions of the algorithms in which parameters
provided in the IK are used, and even fragments of source code
implementing these algorithms
» For example optical distortion models or timing algorithms

• These comments exist primarily to assist users in integrating

I-Kernel data into their applications
– One needs to know the keyword name to get its value(s) from the IK data
– One needs to know what each value means in order to use it properly

Instrument Kernel 5
 N IF I-Kernel Interface Routines
Navigation and Ancillary Information Facility

• As with any SPICE kernel, an IK is loaded using FURNSH

CALL FURNSH ( 'ik_file_name.ti' ) {Better yet, use a FURNSH kernel}

• By knowing the name and type (DP, integer, or character) of a

keyword of interest, the value(s) associated with that keyword can be
retrieved using G*POOL routines
CALL GDPOOL ( NAME, START, ROOM, N, VALUES, FOUND )for DP values
CALL GIPOOL ( NAME, START, ROOM, N, VALUES, FOUND )for integer values
CALL GCPOOL ( NAME, START, ROOM, N, VALUES, FOUND )for character strings

• When an instrument’s FOV is defined in the IK using a special set of

keywords discussed later in this tutorial, the FOV shape, reference
frame, boresight vector, and boundary vectors can be retrieved by
calling the GETFVN and GETFOV routines
CALL GETFVN ( INSNAM, ROOM, SHAPE, FRAME, BSIGHT, N, BOUNDS)
CALL GETFOV ( INSTID, ROOM, SHAPE, FRAME, BSIGHT, N, BOUNDS)
FORTRAN examples are shown; underlined items are outputs
Instrument Kernel 6
 N IF FOV Definition Keywords (1)
Navigation and Ancillary Information Facility

• The following keywords defining FOV attributes for the

instrument with NAIF ID (#) must be present in the IK if the
SPICE Toolkit’s GETFNV or GETFOV module will be used

– Keyword defining shape of the FOV

INS#_FOV_SHAPE = 'CIRCLE' or 'ELLIPSE' or

'RECTANGLE' or 'POLYGON'

– Keyword specifying the reference frame in which the boresight vector

and FOV boundary vectors are specified

INS#_FOV_FRAME = 'frame name'

– Keyword defining the boresight vector

INS#_BORESIGHT = ( X, Y, Z )

continued on next page

Instrument Kernel 7
 N IF FOV Definition Keywords (2)
Navigation and Ancillary Information Facility

– Keyword(s) defining FOV boundary vectors, provided in either of

two ways

1) By specifying boundary vectors explicitly

INS#_FOV_CLASS_SPEC = 'CORNERS'
INS#_FOV_BOUNDARY_CORNERS = ( X(1), Y(1), Z(1),
… … …
X(n), Y(n), Z(n) )

where the FOV_BOUNDARY_CORNERS keyword provides an

array of vectors that point to the "corners" of the instrument
field of view.

Note: Use of the INS#_FOV_CLASS_SPEC keyword is optional

when explicit boundary vectors are provided.

continued on next page

Instrument Kernel 8
 N IF FOV Definition Keywords (3)
Navigation and Ancillary Information Facility

2) By providing half angular extents of the FOV (possible only for circular,
elliptical or rectangular FOVs)

INS#_FOV_CLASS_SPEC = 'ANGLES'
INS#_FOV_REF_VECTOR = ( X, Y, Z )
INS#_FOV_REF_ANGLE = halfangle1
INS#_FOV_CROSS_ANGLE = halfangle2
INS#_FOV_ANGLE_UNITS = 'DEGREES' or
'RADIANS' or …

where the FOV_REF_VECTOR keyword specifies a reference vector that,

together with the boresight vector, define the plane in which the half
angle given in the FOV_REF_ANGLE keyword is measured. The other half
angle given in the FOV_CROSS_ANGLE keyword is measured in the plane
normal to this plane and containing the boresight vector.

Instrument Kernel 9
 N IF FOV Definition Keywords (4)
Navigation and Ancillary Information Facility

• When explicit boundary vectors are provided, they must be listed

in either clockwise or counter-clockwise order, not randomly
• Neither the boresight nor reference vector has to be co-aligned
with one of the FOV frame’s axes
– But for convenience, each is frequently defined to be along one of the FOV axes
• None of the boresight, corner or reference vector has to be a unit
vector
– But these frequently are defined as unit vectors
• When a FOV is specified using the half angular extents method,
the boresight and reference vectors have to be linearly
independent but they don’t have to be perpendicular
– But for convenience the reference vector is usually picked to be normal to the
boresight vector
• Half angular extents for a rectangular FOV specify the angles
between the boresight and the FOV sides, i.e. they are for the
middle of the FOV
• The next several pages show examples of FOV definitions

Instrument Kernel 10
 N IF Circular Field of View
Navigation and Ancillary Information Facility

Consider an instrument with a circular field of view.

14.03 O
X

Boundary (0,1,4)
Subtended field of Corner
view angle Vector
14.03 = arc tan (1/4) Z
Y

Boresight
X
Vector
(0,0,0)
Instrument
focal point
Instrument Kernel 11
 N IF Circular FOV Definition
Navigation and Ancillary Information Facility

The following sets of keywords and values describe this

circular field of view:
Specifying boundary vectors explicitly:
INS-11111_FOV_SHAPE = 'CIRCLE'
INS-11111_FOV_FRAME = 'FRAME_FOR_INS-11111'
INS-11111_BORESIGHT = ( 0.0 0.0 1.0 )
INS-11111_FOV_BOUNDARY_CORNERS = ( 0.0 1.0 4.0 )

Specifying half angular extents of the FOV:

INS-11111_FOV_SHAPE = 'CIRCLE'
INS-11111_FOV_FRAME = 'FRAME_FOR_INS-11111'
INS-11111_BORESIGHT = ( 0.0 0.0 1.0 )
INS-11111_FOV_CLASS_SPEC = 'ANGLES'
INS-11111_FOV_REF_VECTOR = ( 0.0 1.0 0.0 )
INS-11111_FOV_REF_ANGLE = 14.03624347
INS-11111_FOV_ANGLE_UNITS = 'DEGREES'

Instrument Kernel 12
 N IF Elliptical Field of View
Navigation and Ancillary Information Facility

Consider an instrument with an elliptical field of view.

14.03 O
X 26.57 O
Boresight
Boundary Vector
Corner (0,1,4)
Subtended field of Vectors
view angle Z
14.03 = arc tan (1/4) Y
26.57 = arc tan (2/4)
(-2,0,4)

X
(0,0,0)
Instrument
focal point
Instrument Kernel 13
 N IF Elliptical FOV Definition
Navigation and Ancillary Information Facility

The following sets of keywords and values describe this

elliptical field of view:
Specifying boundary vectors explicitly:
INS-22222_FOV_SHAPE = 'ELLIPSE'
INS-22222_FOV_FRAME = 'FRAME_FOR_INS-22222'
INS-22222_BORESIGHT = ( 0.0 0.0 1.0 )
INS-22222_FOV_BOUNDARY_CORNERS = ( 0.0 1.0 4.0
-2.0 0.0 4.0 )

Specifying half angular extents of the FOV:

INS-22222_FOV_SHAPE = 'ELLIPSE'
INS-22222_FOV_FRAME = 'FRAME_FOR_INS-22222'
INS-22222_BORESIGHT = ( 0.0 0.0 1.0 )
INS-22222_FOV_CLASS_SPEC = 'ANGLES'
INS-22222_FOV_REF_VECTOR = ( 0.0 1.0 0.0 )
INS-22222_FOV_REF_ANGLE = 14.03624347
INS-22222_FOV_CROSS_ANGLE = 26.56505118
INS-22222_FOV_ANGLE_UNITS = 'DEGREES'

Instrument Kernel 14
 N IF Rectangular Field of View
Navigation and Ancillary Information Facility

Consider an instrument with a rectangular field of view.

14.03 O
X 26.57 O

Boundary (2,1,4)
Corner
(-2,1,4)
Subtended field of Vectors
view angle Y Z
14.03 = arc tan (1/4)
26.57 = arc tan (2/4)

X Boresight
Vector
(2,-1,4) (-2,-1,4)
(0,0,0)
Instrument
focal point
Instrument Kernel 15
 N IF Rectangular FOV Definition
Navigation and Ancillary Information Facility

The following sets of keywords and values describe this

rectangular field of view:
Specifying boundary vectors explicitly:
INS-33333_FOV_SHAPE = 'RECTANGLE'
INS-33333_FOV_FRAME = 'FRAME_FOR_INS-33333'
INS-33333_BORESIGHT = ( 0.0 0.0 1.0 )
INS-33333_FOV_BOUNDARY_CORNERS = ( 2.0 1.0 4.0
-2.0 1.0 4.0
-2.0 -1.0 4.0
2.0 -1.0 4.0 )
Specifying half angular extents of the FOV:
INS-33333_FOV_SHAPE = 'RECTANGLE'
INS-33333_FOV_FRAME = 'FRAME_FOR_INS-33333'
INS-33333_BORESIGHT = ( 0.0 0.0 1.0 )
INS-33333_FOV_CLASS_SPEC = 'ANGLES'
INS-33333_FOV_REF_VECTOR = ( 0.0 1.0 0.0 )
INS-33333_FOV_REF_ANGLE = 14.03624347
INS-33333_FOV_CROSS_ANGLE = 26.56505118
INS-33333_FOV_ANGLE_UNITS = 'DEGREES'
Instrument Kernel 16
 N IF Polygonal Fields of View
Navigation and Ancillary Information Facility

Consider an instrument with a trapezoidal field of view.

Boundary
Corner (1,1,4) (-1,1,4)
Vectors
Y Z

X Boresight
Vector
(2,-1,4) (-2,-1,4)
(0,0,0)
Instrument
focal point

Instrument Kernel 17
 N IF Polygonal FOV Definition
Navigation and Ancillary Information Facility

The following sets of keywords and values describe this

polygonal field of view:
Specifying boundary vectors explicitly:
INS-44444_FOV_SHAPE = 'POLYGON'
INS-44444_FOV_FRAME = 'FRAME_FOR_INS-44444'
INS-44444_BORESIGHT = ( 0.0 0.0 1.0 )
INS-44444_FOV_BOUNDARY_CORNERS = ( 1.0 1.0 4.0
-1.0 1.0 4.0
-2.0 -1.0 4.0
2.0 -1.0 4.0 )

• A polygonal FOV cannot be specified using half angular extents.

Instrument Kernel 18
 N IF IK Utility Programs
Navigation and Ancillary Information Facility

• No IK utility programs are included in the Toolkit

• Two IK utility programs are provided on the NAIF

website (https://naif.jpl.nasa.gov/naif/utilities.html)
OPTIKS displays a field-of-view summary for all FOVs defined
in a collection of IK files.
BINGO converts IK files between UNIX and DOS text formats

Instrument Kernel 19
 N IF Additional Information on IK
Navigation and Ancillary Information Facility

• The best way to learn more about IKs is to

examine some found in the NAIF Node archives.
– Start looking here:
https://naif.jpl.nasa.gov/naif/data_archived.html
• NAIF does not yet have an “I-Kernel Required
Reading” document
• But information about IKs is available in other
documents:
– headers of the GETFVN and GETFOV routines
– Kernel Required Reading
– OPTIKS User’s Guide
– Porting_kernels tutorial
– NAIF IDs Tutorial
– Frames Required Reading

Instrument Kernel 20
 N IF Backup
Navigation and Ancillary Information Facility

• IK file example

• Computing angular extents from corner

vectors returned by GETFOV

Instrument Kernel 21
 N IF Sample IK Data
Navigation and Ancillary Information Facility

The following LEMMS1 FOV definition was taken

from the Cassini MIMI IK (cas_mimi_v11.ti):
Low Energy Magnetospheric Measurements System 1 (LEMMS1)

Since the MIMI_LEMMS1 detector's FOV is circular and it's diameter is 15.0
degrees, looking down the X-axis in the CASSINI_MIMI_LEMMS1 frame, we have:
(Note we are arbitrarily choosing a vector that terminates in the Z=1
plane.)

^ Y
| ins
|
| /|
| / |
| / |
| / o |
|/ 7.50 |
x--------------->
X \ | Z
ins \ | ins
\ |
\ |
\|

|-- 1.0 --|

continues
Instrument Kernel 22
 N IF Sample IK Data
Navigation and Ancillary Information Facility

FOV definition from the Cassini MIMI IK (continued):

The Y component of one 'boundary corner' vector is:

Y Component = 1.0 * tan ( 7.50 degrees )

= 0.131652498

The boundary corner vector as displayed below is

normalized to unit length:
\begindata

INS-82762_FOV_FRAME = 'CASSINI_MIMI_LEMMS1'
INS-82762_FOV_SHAPE = 'CIRCLE'
INS-82762_BORESIGHT = (

0.0000000000000000 0.0000000000000000 +1.0000000000000000

)
INS-82762_FOV_BOUNDARY_CORNERS = (

0.0000000000000000 +0.1305261922200500 +0.9914448613738100

\begintext

Instrument Kernel 23
 N IF Circular FOV Angular Size
Navigation and Ancillary Information Facility

The angular separation between the boundary

corner vector and the boresight is the angular size.
FORTRAN EXAMPLE

C Retrieve FOV parameters.

CALL GETFOV(-11111, 1, SHAPE, FRAME, BSGHT, N, BNDS)

C Compute the angular size.

ANGSIZ = VSEP( BSGHT, BNDS(1,1) )

C EXAMPLE

/* Define the string length parameter. */

#define STRSIZ 80

/* Retrieve the field of view parameters. */

getfov_c(-11111, 1, STRSIZ, STRSIZ, shape, frame,
bsght, &n, bnds);

/* Compute the angular separation. */

angsiz = vsep_c( bsght, &(bnds[0][0]));

Instrument Kernel 24
 N IF Elliptical FOV Angular Size - 1
Navigation and Ancillary Information Facility

The angular sizes are the angular separations

between the boresight and the boundary vectors.
FORTRAN EXAMPLE

C Retrieve the FOV parameters from the kernel pool.

CALL GETFOV(-22222, 2, SHAPE, FRAME, BSGHT, N, BNDS)

C Compute the angular separations.

ANG1 = VSEP( BSGHT, BNDS(1,1) )
ANG2 = VSEP( BSGHT, BNDS(1,2) )

C The angle along the semi-major axis is the larger

C of the two separations computed.
LRGANG = MAX( ANG1, ANG2)
SMLANG = MIN( ANG1, ANG2)

Instrument Kernel 25
 N IF Elliptical FOV Angular Size - 2
Navigation and Ancillary Information Facility

C EXAMPLE

/* Define the string length parameter. */

#define STRSIZ 80

/* Retrieve the FOV parameters from the kernel pool. */

getfov_c(-22222, 2, STRSIZ, STRSIZ, shape, frame,
bsght, &n, bnds);

/* Compute the angular separations. */

ang1 = vsep_c( bsght, &(bnds[0][0]));
ang2 = vsep_c( bsght, &(bnds[1][0]));

/* The angle along the semi-major axis is the larger of the

two separations computed. */
if ( ang1 > ang2 ) {
lrgang = ang1; smlang = ang2; }
else {
lrgang = ang2; smlang = ang1; }

Instrument Kernel 26
 N IF Rectangular FOV Angular Size - 1
Navigation and Ancillary Information Facility

The angular extents of the FOV are computed by

calculating the angle between the bisector of
adjacent unit boundary vectors and the boresight.

Bisectors

sml_ang

lrg_ang

(0,0,0)
Subtended field of view
Instrument angles

Instrument Kernel 27
 N IF Rectangular FOV Angular Size - 2
Navigation and Ancillary Information Facility

FORTRAN EXAMPLE

C Retrieve FOV parameters from the kernel pool.

CALL GETFOV(-33333, 4, SHAPE, FRAME, BSGHT, N, BNDS)

C Normalize the 3 boundary vectors

CALL UNORM(BNDS(1,1), UNTBND(1,1), MAG)
CALL UNORM(BNDS(1,2), UNTBND(1,2), MAG)
CALL UNORM(BNDS(1,3), UNTBND(1,3), MAG)

C Compute the averages.

CALL VADD(UNTBND(1,1), UNTBND(1,2), VEC1)
CALL VSCL(0.5, VEC1, VEC1)

CALL VADD(UNTBND(1,2), UNTBND(1,3), VEC2)

CALL VSCL(0.5, VEC2, VEC2)

C Compute the angular separations

ANG1 = VSEP( BSGHT, VEC1 )
ANG2 = VSEP( BSGHT, VEC2 )

C Separate the larger and smaller angles.

LRGANG = MAX( ANG1, ANG2)
SMLANG = MIN( ANG1, ANG2)

Instrument Kernel 28
 N IF Rectangular FOV Angular Size - 3
Navigation and Ancillary Information Facility
C EXAMPLE

/* Define the string length parameter. */

#define STRSIZ 80

/* Retrieve the FOV parameters from the kernel pool. */

getfov_c(-33333, 4, STRSIZ, STRSIZ, shape, frame,
bsght, &n, bnds);

/* Normalize the 3 boundary vectors. */

unorm_c(&(bnds[0][0]), &(untbnd[0][0]), &mag);
unorm_c(&(bnds[1][0]), &(untbnd[1][0]), &mag);
unorm_c(&(bnds[2][0]), &(untbnd[2][0]), &mag);

/* Compute the averages */

vadd_c(&(untbnd[0][0]), &(untbnd[1][0]), vec1);
vscl_c(0.5, vec1, vec1);
vadd_c(&(untbnd[1][0]), &(untbnd[2][0]), vec2);
vscl_c(0.5, vec2, vec2);

/* Compute the angular separations. */

ang1 = vsep_c( bsght, vec1);
ang2 = vsep_c( bsght, vec2);

/* Separate the larger and smaller angles. */

if ( ang1 > ang2 ) {
lrgang = ang1; smlang = ang2; }
else {
lrgang = ang2; smlang = ang1; }
Instrument Kernel 29
N IF
Navigation and Ancillary Information Facility

Reading FKs and IKs

April 2023
 N IF See The Real Stuff
Navigation and Ancillary Information Facility

• It may be useful for the student to examine a few existing Frames Kernels
and Instrument Kernels to get a better understanding of the FK and IK
tutorial information.

• NAIF suggests you use your browser to examine some of the following
“real life” kernels. (You may use http in place of ftp.)

• DEEP IMPACT:
– https://naif.jpl.nasa.gov/pub/naif/pds/data/di-c-spice-6-v1.0/disp_1000/data/fk/
– https://naif.jpl.nasa.gov/pub/naif/pds/data/di-c-spice-6-v1.0/disp_1000/data/ik/
• CASSINI:
– https://naif.jpl.nasa.gov/pub/naif/pds/data/co-s_j_e_v-spice-6-v1.0/cosp_1000/data/fk/
– https://naif.jpl.nasa.gov/pub/naif/pds/data/co-s_j_e_v-spice-6-v1.0/cosp_1000/data/ik/
• MESSENGER:
– https://naif.jpl.nasa.gov/pub/naif/pds/data/mess-e_v_h-spice-6-v1.0/messsp_1000/data/fk/
– https://naif.jpl.nasa.gov/pub/naif/pds/data/mess-e_v_h-spice-6-v1.0/messsp_1000/data/ik/
• MARS EXPRESS:
– https://naif.jpl.nasa.gov/pub/naif/pds/data/mex-e_m-spice-6-v2.0/mexsp_2000/DATA/FK/
– https://naif.jpl.nasa.gov/pub/naif/pds/data/mex-e_m-spice-6-v2.0/mexsp_2000/DATA/IK/

Reading FKs and IKs 2

N IF
Navigation and Ancillary Information Facility

Derived Quantities

April 2023
 N IF What are Derived Quantities?
Navigation and Ancillary Information Facility

• Derived quantities, what we often call “observation

geometry,” are produced using data from SPICE kernels
and Toolkit software.
– These are the primary reason that SPICE exists!

• The SPICE Toolkit contains many routines that assist with

the computations of derived quantities.
– Some are fairly low level, some are quite high level.
– More are being added as time permits.

DSK
CK
PCK Altitude = 138.3
Phase = 22.4
SPK Toolkit APIs LAT = 56
LON = 129

SPICE Kernels Your Program Derived Quantities

• Examples follow on the next several pages.

Derived Quantities 2
 N IF High-level Geometric Computations
Navigation and Ancillary Information Facility

• Geometric Parameter
– Determine a geometric quantity or condition at a specified time.

• Geometry Finder (GF)

– Find times, or time spans, when a specified “geometric event”
occurs, or when a specified “geometric condition” exists.
» This is such a large topic that a separate tutorial
(“geometry_finder”) has been written for it.

Derived Quantities 3
 N IF Examples of Geometric Parameters - 1
Navigation and Ancillary Information Facility

• Illumination angles (phase, incidence, emission)

– ILLUMF, ILLUMG, ILUMIN*
• Sub-solar point
– SUBSLR*
• Sub-observer point
– SUBPNT*
• Surface intercept point
– SINCPT*, DSKXV, DSKXSI
• Tangent point
– TANGPT
• Phase angle between body centers
– PHASEQ
• Angular separation between two objects
– TRGSEP
* These routines supersede the now deprecated
routines ILLUM, SUBSOL, SUBPT and SRFXPT
Derived Quantities 4
 N IF Examples of Geometric Parameters - 2
Navigation and Ancillary Information Facility

• Longitude of the sun (Ls), an indicator of season

– LSPCN
• Limb points on an ellipsoid or DSK
– LIMBPT
• Terminator points on an ellipsoid or DSK
– TERMPT
• Surface points at specified longitude, latitude coordinates
– LATSRF
• Outward surface normal on extended object
– SRFNRM
• Azimuth and elevation of a target as seen from a constant
position observer
– AZLCPO

Derived Quantities 5
 N IF Examples of Geometric Conditions
Navigation and Ancillary Information Facility

• Ray in field-of-view?
– FOVRAY
• Ephemeris object within field-of-view?
– FOVTRG
• Determine occultation condition
– OCCULT

Derived Quantities 6
 N IF Examples of Geometry Finder Searches
Navigation and Ancillary Information Facility

• Find times when:

– ray is in field-of-view
» GFRFOV
– ephemeris object is within field-of-view
» GFTFOV
– object is in occultation or transit
» GFOCLT
– object is at periapse
» GFDIST
– latitude and longitude are in specified ranges
» GFPOSC
– solar incidence angle is below a specified limit
» GFILUM
• For more GF functionality, see the GF tutorial.
Derived Quantities 7
 N IF Geometry Related to Objects
Navigation and Ancillary Information Facility

Function Routine
• Ellipsoids
– nearest point – NEARPT, DNEARP
– surface ray intercept – SURFPT
– surface normal – SURFNM, EDNMPT
– point on surface – EDPNT
– limb – EDLIMB
– slice with a plane – INELPL
– altitude of ray w.r.t. to ellipsoid – NPEDLN
• Planes
– intersect ray and plane – INRYPL
• Ellipses
– project onto a plane – PJELPL
– find semi-axes of an ellipse – SAELGV
• Lines
– nearest point on line or segment – NPLNPT, NPSGPT

Derived Quantities 8
 N IF Position Coordinate Transformations
Navigation and Ancillary Information Facility

Coordinate Transformation Routine

– Transform state vector General purpose
between two coordinate – XFMSTA state transformation API
systems (except Az-El)

– Latitudinal to/from – LATREC

Rectangular RECLAT
– Planetographic to/from – PGRREC
Rectangular RECPGR
– R.A. Dec to/from – RADREC
Rectangular RECRAD
– Geodetic to/from – GEOREC
Single purpose APIs
Rectangular RECGEO
– Cylindrical to/from – CYLREC
Rectangular RECCYL
– Spherical to/from – SPHREC
Rectangular RECSPH
– Azimuth-Elevation to/from – AZLREC
Rectangular RECAZL
Derived Quantities 9
 N IF Velocity Coordinate Transformations
Navigation and Ancillary Information Facility

Coordinate Transformation Routine

– Transform state vector General purpose
between two coordinate – XFMSTA state transformation API
systems (except Az-El)

– Latitudinal to/from – DRDLAT

Rectangular DLATDR
– Planetographic to/from – DRDPGR
Rectangular DPGRDR
– R.A. Dec to/from – DRDLAT
Rectangular DLATDR
– Geodetic to/from – DRDGEO
Single purpose APIs
Rectangular DGEODR
– Cylindrical to/from – DRDCYL
Rectangular DCYLDR
– Spherical to/from – DRDSPH
Rectangular DSPHDR
– Azimuth-Elevation to/from – DRDAZL
Rectangular DAZLDR
Derived Quantities 10
 Examples of Velocity
N IF Coordinate Transformations
Navigation and Ancillary Information Facility
This example is for rectangular to spherical

• Using full state vector transformation API

CALL SPKEZR ( TARG, ET, REF, CORR, OBS, STATE, LT )
CALL XFMSTA ( STATE, 'RECTANGULAR', 'SPHERICAL', ' ', OUTSTATE )
• Using velocity-only (Jacobian) APIs
– Transform velocities from rectangular to spherical coordinates using the SPICE
Jacobian matrix routines. The SPICE calls that implement this computation are:
CALL SPKEZR ( TARG, ET, REF, CORR, OBS, STATE, LT )
CALL DSPHDR ( STATE(1), STATE(2), STATE(3), JACOBI )
CALL MXV ( JACOBI, STATE(4), SPHVEL )
– After these calls, the vector SPHVEL contains the velocity in spherical
coordinates: specifically, the derivatives
( d (r) / dt, d (colatitude) / dt, d (longitude) /dt )
– Caution: coordinate transformations often have singularities, so derivatives may
not exist everywhere.
» Exceptions are described in the headers of the SPICE Jacobian
matrix routines.
» SPICE Jacobian matrix routines signal errors if asked to perform
an invalid computation.

Derived Quantities 11
 N IF Vectors
Navigation and Ancillary Information Facility

• Function • Routine
– <v,w> – VDOT, DVDOT
– vxw – VCROSS, DVCRSS
– v/||v|| – VHAT, DVHAT
– v x w / || v x w|| – UCROSS, DUCRSS
– v+w – VADD, VADDG
– v-w – VSUB, VSUBG
– av [+ bw [+ cu]] – VSCL, [VLCOM, [VLCOM3]]
– angle between v and w – VSEP
– ||v|| – VNORM
v |
v
||
w VPROJ, VPERP
v

v TWOVEC, FRAME

w
Derived Quantities 12
 N IF Matrices
Navigation and Ancillary Information Facility

Selected Matrix-Vector Linear Algebra Routines

• Function • Routine
– Mxv – MXV
– MxM – MXM
– Mt x v – MTXV
– Mt x M – MTXM
– M x Mt – MXMT
– vt x M x v – VTMV
– Mt – XPOSE
– M-1 – INVERT, INVSTM

M = Matrix
V = Vector
X = Multiplication
T = Transpose
Derived Quantities 13
 N IF Matrix Conversions
Navigation and Ancillary Information Facility

Function Routines
ax ay az
bx by bz EUL2M, M2EUL
Transform between cx cy cz

3x3 rotation matrix

Euler angles
ax ay az
bx by bz 0
cx cy cz EUL2XF, XF2EUL
Transform between ax ay az ax ay az RAV2XF, XF2RAV
Euler angles and Euler angle rates bx by bz bx by bz
or gx gy gz cx cy cz
rotation matrix and angular velocity 6x6 state transformation
vector matrix

ax ay az
bx by bz
RAXISA, AXISAR
cx cy cz ROTATE, ROTMAT
Transform between
Rotation axis 3x3 rotation matrix
and angle
ax ay az

(Q0,Q1,Q2,Q3) bx by bz
cx cy cz
Q2M, M2Q
SPICE Style Transform between
3x3 rotation matrix
Quaternion
Derived Quantities 14
 Examples of Computing
N IF Derived Quantities
Navigation and Ancillary Information Facility

• On the next several pages we present examples of

using some of the “derived quantity” APIs.

• Explore the “Most Used SPICE APIs” document to

learn more.

Derived Quantities 15
 N IF Computing Illumination Angles
Navigation and Ancillary Information Facility

• Given the direction of an instrument boresight in

a body-fixed frame, return the illumination angles
(incidence, phase, emission) at the boresight’s
surface intercept on an object, with the object’s
shape modeled by a tri-axial ellipsoid or by DSK
data.
incidence
phase
instrument emission
boresight
direction
•
Observer target-observer
vector

Derived Quantities 16
 N IF Computing Illumination Angles
Navigation and Ancillary Information Facility

• CALL GETFOV to obtain

boresight direction vector
incidence
• CALL SINCPT to find
instrument
phase
emission intersection of boresight
boresight
direction
direction vector with surface
• • CALL ILUMIN to determine
Observer target-observer
vector
illumination angles

Derived Quantities 17
 N IF Computing Tangent Point
Navigation and Ancillary Information Facility

• Given the direction of an instrument boresight,

compute the “tangent point” – the point on the
boresight ray nearest to the target's surface
modeled by a tri-axial ellipsoid.

Tangent
point
• CALL GETFOV to obtain
Nearest
surface
boresight direction vector
instrument point
boresight • CALL TANGPT to find the
direction
tangent point on the ray and
•
Observer target-observer the point on the surface
vector
nearest to it

Derived Quantities 18
 N IF Computing Ring Plane Intercepts
Navigation and Ancillary Information Facility

• Determine the intersection of the apparent line of sight vector

between Earth and Cassini with Saturn’s ring plane and determine
the distance of this point from the center of Saturn.

Derived Quantities 19
 N IF Computing Ring Plane Intercepts-2
Navigation and Ancillary Information Facility

This computation is for the reception case,

when radiation is received at the Earth at a
given epoch “ET”.
• CALL SPKEZR to get light time corrected position of spacecraft as
seen from Earth at time ET in J2000 reference frame SCVEC.
This simplified computation
ignores the difference • CALL SPKEZR to get light time corrected position of center of Saturn
between the light time from at time ET as seen from Earth in J2000 frame SATCTR.
Saturn to the Earth and the • CALL PXFORM to get rotation from Saturn body-fixed coordinates to
light time from the ring J2000 at light time corrected epoch. The third column of this matrix
intercept point to the Earth. gives the pole direction of Saturn in the J2000 frame SATPOL.
• CALL NVP2PL and use SATCTR and SATPOL to construct the ring
The position and
plane RPLANE.
orientation of Saturn could
be re-computed using the • CALL INRYPL to intersect the Earth-spacecraft vector SCVEC with
light time from Earth to the the Saturn ring plane RPLANE to produce the intercept point X.
intercept; the intercept • CALL VSUB to get the position of the intercept with respect to Saturn
could be re-computed until XSAT (subtract SATCTR from X) and use VNORM to get the distance
convergence is attained.
of XSAT from the center of Saturn.

Derived Quantities 20
 N IF Computing Ring Plane Intercepts-3
Navigation and Ancillary Information Facility
• Create a dynamic frame with one axis pointing from Earth to the
light time corrected position of the Cassini orbiter. Use the CN
correction for this position vector. (This gives us a frame in
which the direction vector of interest is constant.)
• Temporarily change the radii of Saturn to make the polar axis
length 1 cm and the equatorial radii 1.e6 km. This can be done
either by editing the PCK or by calling BODVCD to fetch the
original radii, then calling PDPOOL to set the kernel pool variable
containing the radii to the new values. This flat ellipsoid will be
An
used to represent the ring plane.
alternate
• Use SINCPT to find the intercept of the Earth-Cassini ray with the
approach flat ellipsoid. Use the CN correction. SINCPT returns both the
intercept in the IAU_SATURN frame and the Earth-intercept
vector. Use VNORM to get the distance of the intercept from
Saturn’s center.
• Restore the original radii of Saturn. If PDPOOL was used to
update the radii in the kernel pool, use PDPOOL again to restore
the radii fetched by BODVCD.
Derived Quantities 21
 N IF Computing Occultation Events
Navigation and Ancillary Information Facility

• Determine when the spacecraft will be occulted by

an object (such as a natural satellite) as seen from
an observer (such as Earth).

Spacecraft
Direction to motion
the observer

A body
such as
a satellite

Derived Quantities 22
 N IF Find Occultation Ingress/Egress
Navigation and Ancillary Information Facility
• Select a start epoch, stop epoch and
step size.
– Start and stop epochs can bracket multiple
occultation events
– Step size should be smaller than the shortest
occultation duration of interest, and smaller
than the minimum interval between
occultation events that are to be
distinguished, but large enough to solve the
problem with reasonable speed.
• Insert search interval into a SPICE
window. This is the “confinement
Direction to
Spacecraft window.”
motion
the observer • CALL GFOCLT to find occultations, if any.
A body The time intervals, within the confinement
such as window, over which occultations occur will
a satellite be returned in a SPICE window.
– GFOCLT can treat targets as ellipsoids, DSK
shapes, or points (but at least one must be an
ellipsoid or DSK shape, and DSK shapes can
be used only with point targets).
– GFOCLT can search for different occultation
or transit geometries: full, partial, annular, or
“any.”
Derived Quantities 23
N IF
Navigation and Ancillary Information Facility

Other Useful Functions

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Overview
• Language-specific status
• File Operations
• String Manipulation
• Searching, Sorting and Other Array Manipulations
• Windows
• Symbol Tables
• Sets and Cells
• Constants and Unit Conversion
• Numerical Functions

Other Useful Functions 2

 N IF Overview
Navigation and Ancillary Information Facility

• The routines described in this tutorial originated in the

Fortran version of the the SPICE Toolkit.
• Many, but not all, of these routines have implementations in
the C, IDL, and MATLAB Toolkits.
• The descriptions include a language “identifier” or set of
identifiers prefixed to the routine’s name to indicate which
Toolkit language(s) include that routine.
– [F] available in Fortran (SPICELIB)
– [C] available in C (CSPICE)
– [I] available in IDL (Icy)
– [M] available in MATLAB (Mice)
• NAIF adds interfaces to the CSPICE, Icy and Mice Toolkits as
needed or when requested by a customer.
• CSPICE, Icy and Mice do not need all of the functionality
implemented in the Fortran Toolkit.
• NAIF does not attempt to keep track of which functions are
implemented in 3rd party toolkits such as SpiceyPy.
Other Useful Functions 3
 N IF Text I/O (1)
Navigation and Ancillary Information Facility

• Text files provide a simple,

human readable mechanism
for sharing data.

• The Toolkit contains several

utility routines to assist with – [F,C] RDTEXT: read a line of text
the creation and parsing of from a text file*
text, and with the reading and – [F] TOSTDO: write a line of text to
writing of text files. standard output
– [F,C] PROMPT: display a prompt,
wait for and return user’s
response
– [F] TXTOPN: open a new text file
returning a logical unit
– [F] WRITLN: write a line of text to
the file attached to a logical unit.

Other Useful Functions * The text file must be in native text format for your computer
4
 N IF Text I/O (2)
Navigation and Ancillary Information Facility

CALL PROMPT ( 'Filename? ', NAME )

CALL TOSTDO ( 'You specified the file: '// NAME )

Now that we have the filename, read

and process its contents Terminal Window

Filename? mydata.file
You specified the file: mydata.file
CALL RDTEXT ( NAME, LINE, EOF )

DO WHILE ( .NOT. EOF )

process the line just read

CALL RDTEXT ( NAME, LINE, EOF )

END DO

Other Useful Functions 5

 N IF File Operations
Navigation and Ancillary Information Facility

• Logical unit management - Fortran specific

– [F] RESLUN: (reserve logical unit) prohibits SPICE systems
from using specified units.
– [F] FRELUN: (free logical unit) places “reserved” units back into
service for SPICE.
– [F] GETLUN: (get logical unit) locates an unused, unreserved
logical unit.
• Determine whether or not a file exists
– [F,C,I] EXISTS
• Delete an existing file
– [F] DELFIL

Other Useful Functions 6

 N IF String Manipulation - Parsing (1)
Navigation and Ancillary Information Facility

• Breaking apart a list

– [F,C,I] LPARSE: parses a list of items delimited by a single
character.
– [F,C] LPARSM: parses a list of items separated by multiple
delimiters.
– [F,C,I,M] NEXTWD: returns the next word in a given character
string.
– [F,C,I,M] NTHWD: returns the nth word in a string and the
location of the word in the string.
– [F,C] KXTRCT: extracts a substring starting with a keyword.
• Removing unwanted parts of a string
– [F,C,I] CMPRSS: compresses a character string by removing
instances of more than N consecutive occurrences of a
specified character.
– [F] ASTRIP: removes a set ASCII characters from a string.
– [F] REMSUB: removes a substring from a string.

Other Useful Functions 7

 N IF String Manipulation - Parsing (2)
Navigation and Ancillary Information Facility

• Locating substrings
– [F] LTRIM, RTRIM: return the location of the leftmost or
rightmost non-blank character.
– [F,C] POS, CPOS, POSR, CPOSR, NCPOS, NCPOSR: locate
substring or member of specified character set searching
forward or backward.
• Pattern matching
– [F,C,I] MATCHI: matches a string against a wildcard template,
case insensitive.
– [F,C,I] MATCHW: matches a string against a wildcard template,
case sensitive.
• Extracting numeric and time data
– [F] NPARSD, NPARSI, DXTRCT, TPARTV
– [F,C,I] PRSDP, PRSINT,
– [F,C,I,M] TPARSE
• Heavy duty parsing
– [F] SCANIT
Other Useful Functions 8
 N IF String Manipulation - Parsing (3)
Navigation and Ancillary Information Facility

'a dog'
lparse or
'a dog, a cat, and a cow' lparsm 'a cat'
'and a cow'

Split on a comma

'Remove extra spaces' cmprss 'Remove extra spaces'

'Green eggs and ham'

'the cat in the hat' matchi( *g*) 'green eggs and ham'
'how the grinch stole Christmas' 'how the grinch stole Christmas'

Match any string containing a 'g'

Other Useful Functions 9

 N IF String Manipulation - Creating (1)
Navigation and Ancillary Information Facility

• Fill in the “Blank”

– [F,C,I,M] REPMC: Replace a marker with a character string.
CALL REPMC ( 'The file was: #', '#', 'foo.bar', OUT )
OUT has the value “The file was: foo.bar”
– [F,C,I,M] REPMI: Replace a marker with an integer.
CALL REPMI ( 'The value is: #', '#', 7, OUT )
OUT has the value “The value is: 7”
– [F,C,I,M] REPMD: Replace a marker with a DP number.
CALL REPMD ( 'The value is: #', '#', 3.141592654D0, 10, OUT )
OUT has the value “The value is: 3.141592654E+00”
– [F,C,I,M] REPMF: Replace a marker with a formatted DP number.
CALL REPMF ( 'The value is: #', '#', 3.1415D0, 'F', 3, OUT )
OUT has the value “The value is: 3.14”
– [F,C,I,M] REPML: Replace a marker with a logical value.
CALL REPML ( 'The value is: #', '#', .TRUE., 'u', OUT )
OUT has the value “The value is: TRUE”

Other Useful Functions 10

 N IF String Manipulation - Creating (2)
Navigation and Ancillary Information Facility

• Fill in the “Blank” (cont.)

– [F,C,I,M] REPMOT: Replace a marker with the text
representation of an ordinal number.
CALL REPMOT ( 'It was the # term.', '#', 'L', 2, OUT )
OUT has the value “It was the second term.”
– [F,C,I,M] REPMCT: Replace a marker with the text
representation of a cardinal number.
CALL REPMCT ( 'Hit # errors.', '#', 6, 'L', OUT )
OUT becomes 'Hit six errors.'
• Numeric Formatting
– [F] DPFMT: Using a format template, create a formatted string
that represents a double precision number
CALL DPFMT ( PI(), 'xxx.yyyy', OUT )
OUT becomes ' 3.1416'
– [F] DPSTR, INTSTR, INTTXT, INTORD

Other Useful Functions 11

 N IF String Manipulation - Creating (3)
Navigation and Ancillary Information Facility

• Time formatting
– [F,C,I,M] TPICTR: Given a sample time string, create a time
format picture suitable for use by the routine TIMOUT.
– [F,C,I,M] TIMOUT: Converts an input epoch to a character
string formatted to the specifications of a user's format picture.
• Changing case
– [F,C,I] UCASE: Convert all characters in string to uppercase.
– [F,C,I] LCASE: Convert all characters in string to lowercase.
• Building strings
– [F] SUFFIX: add a suffix to a string
– [F] PREFIX: add a prefix to a string
– [F] LJUCRS: left-justify, upper-case and compress

Other Useful Functions 12

 Searching, Sorting and Other Array
N IF Manipulations (1)
Navigation and Ancillary Information Facility

• Sorting arrays
– [F,C] SHELLC, SHELLI, SHELLD, ORDERI, ORDERC, ORDERD,
REORDC, REORDI, REORDD, REORDL
• Searching ordered arrays
– [F,C] BSRCHC, BSRCHI, BSRCHD, LSTLEC, LSTLEI, LSTLED,
LSTLTC, LSTLTI, LSTLTD, BSCHOI
• Searching unordered arrays
– [F,C] ISRCHC, ISRCHI, ISRCHD, ESRCHC
• Moving portions of arrays
– [F] CYCLAC, CYCLAD, CYCLAI
• Inserting and removing array elements
– [F] INSLAC, INSLAD, INSLAI, REMLAC, REMLAD, REMLAI

Other Useful Functions 13

 Searching, Sorting and Other Array
N IF Manipulations (2)
Navigation and Ancillary Information Facility

Sorted
Body A.U.1 Body A.U.1
sun 00.0 04 earth 00.983
mercury 00.455 06 jupiter 05.440
venus 00.720 05 mars 01.531
earth 00.983 02 mercury 00.455
mars 01.531 09 neptune 30.091
jupiter 05.440 orderc 10 reordc,d pluto 31.052
saturn 09.107 07 saturn 09.107
uranus 20.74 01 sun 00.000
neptune 30.091 08 uranus 20.74
pluto 31.052 03 venus 00.720

Vector of “Body” indices representing

the list sorted in alphabetical order.

1 Distance in A.U. at Jan 01, 2006.

Other Useful Functions 14

 N IF Windows
Navigation and Ancillary Information Facility

• A SPICE window is a list of disjoint intervals arranged in

ascending order.

– An interval is specified by a pair of double precision numbers,

with the second greater than or equal to the first.
• The Toolkit contains a family of routines for creating windows
and performing “set arithmetic” on them.
• SPICE windows are frequently used to specify intervals of
time when some set of user constraints are satisfied.
– Let window NotBehind contain intervals of time when Cassini is
not behind Saturn as seen from earth.
– Let window Goldstone contain intervals of time when Cassini is
above the Goldstone horizon.
– Cassini can be tracked from Goldstone during the intersection of
these two windows (Track = NotBehind * Goldstone).
• See windows.req for more information.

Other Useful Functions 15

 N IF Windows Math
Navigation and Ancillary Information Facility

Union

Intersection

Difference

Other Useful Functions 16

 N IF Symbol Tables
Navigation and Ancillary Information Facility

• SPICELIB (Fortran) supports the use of associative

arrays/hashes through the use of an abstract data type
called symbol tables.
– These are used to associate a set of names with collections of
associated values.
– Values associated with a name are exclusively character,
exclusively integer or exclusively double precision.
– Routines to manipulate a symbol table have the form SY***<T>
where <T> is the data type of the values (C, D, or I).
• Operations include:
– Insert a symbol
– Remove a symbol
– Push/Pop a value onto/off of the list of values associated with a
symbol
– Fetch/Sort values associated with a symbol
• See symbols.req for more information.

Other Useful Functions 17

 N IF Sets and Cells (1)
Navigation and Ancillary Information Facility

• Cells are arrays that “know” how many addresses are

available for use and how many are currently used.
– Routines that use cells typically have simpler interfaces than
routines that use arrays.
– See cells.req for more information.
• Sets are cells that contain no duplicate elements and whose
elements are ordered in ascending order.
– Two Sets can be: intersected, unioned, differenced, differenced
symmetrically (union - intersection)
– See sets.req for more information.
• Language support for sets and cells
– Double Precision, Integer, and Character string cell types are
supported in the Fortran and C Toolkits.
– Double Precision and Integer cell types are supported in the IDL
Toolkits (Icy).
– Sets and cells aren’t currently needed in the MATLAB Toolkits
(Mice) since MATLAB itself supports set math.

Other Useful Functions 18

 N IF Sets and Cells (2)
Navigation and Ancillary Information Facility

NAIF
Cassini
Boris MGS Other
Chuck Boris
Ed Chuck Boris Lee
Nat Ed Ed
Lee Nat

CALL UNIONC ( CASSINI, MGS, PROJECTS)

CALL DIFFC ( NAIF, PROJECTS, OTHER )

Other Useful Functions 19

 N IF Constants and Unit Conversion
Navigation and Ancillary Information Facility

• Constants are implemented in the Toolkit as functions.

– Thus the changing of a constant by NAIF requires only relinking
by the Toolkit user–not recompiling.
» Users should NOT change constant functions in the Toolkit.
• System Constants
– [F,C,I,M] DPMIN, DPMAX, INTMIN, INTMAX
• Numeric Constants
– [F,C,I,M] PI, HALFPI, TWOPI, RPD (radians/degree),
DPR(degrees/radian)
• Physical Constants
– [F,C,I,M] CLIGHT, SPD, TYEAR, JYEAR
• Epochs
– [F,C,I,M] J2000,J1950, J1900, J2100, B1900, B1950
• Simple Conversion of Units
– [F,C,I,M] CONVRT

Other Useful Functions 20

 N IF Numerical Functions (1)
Navigation and Ancillary Information Facility

• Several routines are provided to assist with numeric

computations and comparisons.
• Functions
– [F] DCBRT: cube root
– Hyperbolic Functions:
» [F] DACOSH, DATANH
– Polynomial Interpolation and Evaluation:
» [F,C,I,M] LGRESP, LGRINT, LGRIND, POLYDS, HRMESP,
HRMINT
– Chebyshev Polynomial Evaluation:
» [F,C,I,M] CHBDER, CHBVAL, CHBINT, CHBIGR

Other Useful Functions 21

 N IF Numerical Functions (2)
Navigation and Ancillary Information Facility

• Numerical Decisions
– Same or opposite sign (Boolean):
» [F] SMSGND, SMSGNI, OPSGND, OPSGNI
– Force a value into a range (bracket):
» [F,C] BRCKTD, BRCKTI
– Determine parity of integers (Boolean):
» [F] ODD, EVEN
– Truncate conditionally:
» [F] EXACT
• Arithmetic
– Greatest common divisor:
» [F] GCD
– Positive remainder:
» [F] RMAINI, RMAIND

Other Useful Functions 22

N IF
Navigation and Ancillary Information Facility

SPICE Geometry Finder (GF)

Subsystem
Searching for times when specified
geometric conditions occur

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• GF Subsystem Overview
• SPICE Windows
• GF Search Examples
• Geometric Search Types and
Constraints
• More Details
– Root finding, including step size
– Workspace
• An Example

Geometry Finder Subsystem 2

 N IF
Navigation and Ancillary Information Facility

GF Subsystem Overview

Geometry Finder Subsystem 3

 N IF Purpose
Navigation and Ancillary Information Facility

• Much SPICE software computes a geometry

parameter at a given time, t, i.e. x = f(t).
– Example: on 2011 MAR 30 14:57:08, what is the spacecraft’s altitude
above Mars?

• The Geometry Finder subsystem does the inverse: it

finds times when specified geometric events occur.
– Example: within some time bounds, when is the spacecraft’s
altitude less than 100 km?

100

Geometry Finder Subsystem 4

 N IF Some Examples
Navigation and Ancillary Information Facility

• The SPICE Geometry Finder (GF) subsystem finds

times when specified geometric events occur.
– A “geometric event” is an occurrence of a given geometric quantity
satisfying a specified condition. For example:
» Mars Express distance from Mars is at a local minimum (periapse)
» Elevation of the Cassini orbiter as seen from Deep Space Station-14 is
above a given threshold angle
» Titan is completely occulted by Saturn
» The Saturn phase angle as seen by the Cassini orbiter is 60 degrees

– Each GF search is conducted over a user-specified time window,

called the confinement window.
» The confinement window is a sequence of zero or more disjoint, closed
time intervals.

– The result of a GF search is the time window over which the

specified condition is met.
» The result window is also a sequence of zero or more disjoint, closed
time intervals.

Geometry Finder Subsystem 5

 N IF Types of GF APIs
Navigation and Ancillary Information Facility

• GF provides two primary types of event-finding APIs

– Boolean: a geometric condition (an event) is true or false
» Example: Phobos is occulted by Mars
» Example: Vesta is not in the OSIRIS instrument’s field of view
– Sometimes we call these binary conditions

– Numeric: a geometric quantity has a given value, is within a given

range or has achieved a local or global maximum or minimum
» Example: spacecraft altitude is less than X km above the
surface
» Example: angular separation of Titan from Saturn has reached
the maximum value

Geometry Finder Subsystem 6

 N IF GF High-Level API Routines
Navigation and Ancillary Information Facility

• The GF subsystem provides the following high-level API

routines; these search for events involving the respective
geometric quantities listed below
– GFDIST: observer-target distance
– GFILUM: illumination angles
– GFOCLT: occultations or transits
– GFPA: phase angle
– GFPOSC: position vector coordinates
– GFRFOV: ray is contained in an instrument’s field of view
– GFRR: observer-target range rate
– GFSEP: target body angular separation
– GFSNTC: ray-body surface intercept coordinates
– GFSUBC: sub-observer point coordinates
– GFTFOV: target body appears in an instrument’s field of view
– GFUDB: user-defined Boolean quantity (only Fortran, C and JNI)
– GFUDS: user-defined scalar quantity (only Fortran, C and JNI)

Geometry Finder Subsystem 7

 N IF The SPICE Window
Navigation and Ancillary Information Facility

• The high-level GF routines return a search result as a

SPICE window. This window specifies intervals of time
when the user’s constraints are satisfied.

• A SPICE window is a time-ordered sequence of zero or

more time intervals each having zero or non-zero length
– Intervals are “closed” – they include their endpoints.
– Intervals are disjoint – they do not share endpoints.
– Intervals may consist of single points – their length can be zero.
– A time window often consists of a single interval.

Interval 1 Interval 2 Interval n

Interval 3
(zero length)

A SPICE Window

Geometry Finder Subsystem 8

 N IF SPICE Windows Operations
Navigation and Ancillary Information Facility

• SPICE provides routines to:

– compute unions, intersections, and differences of windows

– contract each interval within a window …

» by increasing the left endpoint and decreasing the right
endpoint

• These functions allow one to create confinement

windows with known data availability, or to search
for multi-condition events

• See the next page for an example

Geometry Finder Subsystem 9

 N IF Example of Window Operations
Navigation and Ancillary Information Facility

Given an initial confinement window, restrict that window to times when required
CK and SPK data are available.
Use CKCOV and SPKCOV to find CK and SPK availability windows B and C. Then
use window intersection to obtain the confinement window with known data
availability.

Original confinement window “A”

Reconstructed pointing (CK) availability window “B”

Spacecraft ephemeris (SPK) availability window “C”

Data availability window “A1” = B intersected with C

Confinement window with data availability “A2” = A intersected with A1

Geometry Finder Subsystem 10

 N IF Using Time Windows in GF
Navigation and Ancillary Information Facility

• GF uses a SPICE window containing TDB times to:

– confine the time periods over which your search is to take place

Search Confinement Window

Geometry Finder Subsystem 11

 N IF Using Time Windows in GF
Navigation and Ancillary Information Facility

• GF uses SPICE windows containing TDB times for

input and output
– Input: confine the time bounds or time periods over which your
search is to take place
– Output: contain the time intervals that meet the search criteria
» There may be zero, one or multiple result intervals
» The result intervals can be of non-zero or zero length
• A zero-length interval is simply an epoch–an instant in time

Intervals contained in output window

Non-zero length Zero length

result intervals result intervals
(singletons)
Geometry Finder Subsystem 12
 Cascading Search
N IF Using Multiple SPICE Windows
Navigation and Ancillary Information Facility

• The result window (the output) from one search

can be used as the confinement window (the
input) for a subsequent search.
– This is often a convenient and efficient way of performing
searches for times when multiple constraints are met.
– This technique can be used to accelerate searches in cases
where an initial, fast search can be performed to produce a
small confinement window for a second, slower search.
» See the next chart and the example program “CASCADE”
in the Geometry Finder Required Reading document

Geometry Finder Subsystem 13

 N IF Cascading Search Example
Navigation and Ancillary Information Facility

Example: accelerate a solar occultation search.

First search for times when the angular separation of the Sun and Moon, as seen
from an earth station, is less than 3 degrees.
Use the result window of the angular separation search as the confinement
window of an occultation search.
Because the angular separation search is much faster than would be the
occultation search on the original confinement window, the total search time is
greatly reduced.

Original confinement window (“A”)

Result of angular separation search: second confinement window (“B”)

Window “C”: result of occultation search performed on window “B”

Geometry Finder Subsystem 14

 N IF GF Documentation
Navigation and Ancillary Information Facility

• The GF module headers contain complete

example programs for each GF API routine

• The GF Required Reading document (gf.req)

contains lots of details

• Documentation on SPICE windows:

– The WINDOWS Required Reading windows.req
– The Other Functions tutorial
– API documentation for SPICE window routines

Geometry Finder Subsystem 15

 N IF
Navigation and Ancillary Information Facility

GF Search Examples

Geometry Finder Subsystem 16

 N IF Distance is Local Maximum (or Minimum)
Navigation and Ancillary Information Facility

Find the times of apoapse of the Mars Express Orbiter (MEX)

MEX

Mars
Mars-MEX position
vector

API: GFDIST
Geometry Finder Subsystem 17
 N IF Distance Within a Range
Navigation and Ancillary Information Facility

Find the time periods when the Mars Reconnaissance Orbiter

(MRO) is within 500km of the Opportunity rover.

MRO

.. .
Opportunity
rover

Mars

API: GFDIST
Geometry Finder Subsystem 18
 N IF Range Rate Extremum
Navigation and Ancillary Information Facility

Find the time periods when the range rate of a lunar reflector,
as seen by an Earth station, attains an absolute extremum.

Lunar
Reflector

Station
Moon

Earth
API: GFRR
Geometry Finder Subsystem 19
 N IF Angular Separation Inequality Search -1
Navigation and Ancillary Information Facility

Find the time periods when the angular separation of the Mars-
to Mars Reconnaissance Orbiter (MRO) and Mars-to-
Opportunity Rover position vectors is less than 3 degrees. Both
targets are modeled as points.

Mars .. . Rover location

Angular separation of position vectors

MRO

API: GFSEP
Geometry Finder Subsystem 20
 N IF Angular Separation Inequality Search -2
Navigation and Ancillary Information Facility

Find the time periods when the angular separation of the

figures of the Moon and Sun, as seen from the Earth, is less
than 1 degree. Both targets are modeled as spheres.

Sun

Moon

Angular separation of Earth

figures

API: GFSEP
Geometry Finder Subsystem 21
 N IF Occultation/Transit Search
Navigation and Ancillary Information Facility

Find the ingress and egress times of an occultation of Phobos by

Mars, as seen from Earth. Phobos and Mars are modeled as triaxial
ellipsoids; a spacecraft is modeled as a point target.

Point target
Phobos in in occultation Phobos in
annular partial transit
transit
Point target
in transit
Mars Earth

Phobos in full
Phobos in occultation
partial
occultation API: GFOCLT
Geometry Finder Subsystem 22
 N IF Target in Field of View
Navigation and Ancillary Information Facility

Find the time periods when Titan appears in the FOV of the
Cassini ISS Narrow Angle Camera (NAC). The target shape is
modeled as an ellipsoid. (Point targets are also supported.)

Titan

Cassini Camera FOV

The FOV shape may

be any of:
Rectangle
Cassini
Circle
orbiter
Ellipse
Polygon

API: GFTFOV
Geometry Finder Subsystem 23
 N IF Ray in FOV Search
Navigation and Ancillary Information Facility

Find the time periods when a star appears in the FOV of the
Cassini ISS Narrow Angle Camera (NAC). The target direction is
modeled as a ray, optionally corrected for stellar aberration.

Cassini ISS NAC FOV

•
The FOV shape may
be any of:
Rectangle
Cassini
Circle
orbiter
Ellipse
Polygon

API: GFRFOV
Geometry Finder Subsystem 24
 N IF Position Coordinate Local Extremum Search
Navigation and Ancillary Information Facility

Find the time(s) at which the planetocentric latitude

of the Earth-Sun vector, expressed in the J2000
frame, is at a local maximum.

J2000 Z
Earth-Sun direction
Point of
Unit sphere max latitude

Planetocentric
Latitude
Path of sub-solar point
on unit sphere (in red)
J2000 X
J2000 Y

API: GFPOSC
Geometry Finder Subsystem 25
 N IF Position Coordinate Equality Search
Navigation and Ancillary Information Facility

Find the time(s) at which the Z component of the

Earth-Sun vector, expressed in the J2000 frame, is 0.

J2000 Z

Path of sub-solar point

on unit sphere (in red) J2000 Y

Earth-Sun direction at epoch

of J2000 equator crossing
J2000 X

API: GFPOSC
Geometry Finder Subsystem 26
 N IF Position Coordinate Inequality Search -1
Navigation and Ancillary Information Facility

Find the time periods when the elevation of the DSS-13 to

Mars Reconnaissance Orbiter (MRO) spacecraft vector,
expressed in the DSS-13 topocentric frame, is greater
than 6 degrees.

DSS-13_TOPO Z
DSS-13_TOPO X

Direction to MRO

6 deg. elevation

DSS-13_TOPO Y

API: GFPOSC
Geometry Finder Subsystem 27
 N IF Position Coordinate Inequality Search -2
Navigation and Ancillary Information Facility

Find the time periods when the Lunar Reconnaissance Orbiter’s

(LRO) off-nadir angle of the +Z axis exceeds 5 degrees.

LRO s/c frame +X axis

LRO

LRO s/c frame +Y axis

Moon
Colatitude of LRO-Moon position
vector in LRO s/c frame

LRO s/c frame +Z axis

API: GFPOSC
Geometry Finder Subsystem 28
 N IF Sub-Observer Point Coordinate Equality Search
Navigation and Ancillary Information Facility

Find the time(s) at which the planetocentric latitude

of the sub-spacecraft point, using the “near point”
definition, is 25 degrees.
Body-fixed Z

Outward surface
Path of sub-spacecraft normal direction at
Spacecraft
point (in red) sub-spacecraft point

Planetocentric
latitude = 25 deg.
Body-fixed Y

Body-fixed X
API: GFSUBC
Geometry Finder Subsystem 29
 N IF Surface Intercept Coordinate Equality Search
Navigation and Ancillary Information Facility

Find the time(s) at which the planetographic

longitude of a given camera boresight surface
intercept is 45 degrees.
Body-fixed Z

Spacecraft
Path of boresight
intercept (in red) Camera boresight
direction at epoch of
meridian crossing

Body-fixed Y

Planetographic
Body-fixed X longitude = 45 deg.

API: GFSNTC
Geometry Finder Subsystem 30
 N IF Surface Intercept “Box” Search
Navigation and Ancillary Information Facility

Find the time periods when the planetographic longitude of a camera boresight
surface intercept is between -70 and -45 degrees, and the intercept latitude is
between 0 and 30 degrees.
The solution requires four (cascading) inequality searches.

Body-fixed Z

Spacecraft
Path of boresight
Planetographic Latitude intercept (in red) Camera boresight
0 to 30 deg. direction

Body-fixed Y

Planetographic Longitude
Body-fixed X -45 to -70 deg.
API: GFSNTC
Geometry Finder Subsystem 31
 N IF Surface Intercept Coordinate Equality Search
Navigation and Ancillary Information Facility

Find the time at which the ring plane intercept of the Cassini to DSS-13
vector, corrected for transmission light time (stellar aberration
correction is unnecessary), has radius 300000km.
The solution requires a dynamic frame for which one axis points along
the radiation path.
IAU_SATURN Z Cassini orbiter

IAU_SATURN X s
iu
ra
d Cassini to DSS-13
t
cep radiation direction
ter
In
IAU_SATURN Y
“Ring plane” ellipsoid: 1cm
thick, radius 600000 km,
Path of radiation centered at Saturn’s center
Earth intercept (in red)

DSS-13
API: GFSNTC
Geometry Finder Subsystem 32
 N IF User-Defined Quantity Extremum Search
Navigation and Ancillary Information Facility

Find the time periods when the angular separation of the

geometric and apparent positions of Titan as seen from the
Cassini orbiter attains an absolute maximum.

Apparent position of
Titan, computed using
LT+S correction

Geometric
Angular separation of
position of Cassini orbiter
Titan position vectors

API: GFUDS
Geometry Finder Subsystem 33
 N IF
Navigation and Ancillary Information Facility

Geometric Search Types and Constraints

Geometry Finder Subsystem 34

 N IF Types of Geometric Quantities
Navigation and Ancillary Information Facility

• The GF subsystem deals with two types of

geometric quantities:
– “Binary state functions”: functions of time that can
be “true” or “false.” Examples:
» Occultation state, such as: “Titan is fully occulted by
Saturn at time t”
» Visibility state: A target body or object modeled as a ray
(for example, a star) is visible in a specified instrument
FOV at time t
– Scalar numeric functions of time, for example
» Observer-target distance
» Latitude or longitude of an observer-target vector, sub-
spacecraft point, or ray-surface intercept point
» Angular separation of two target bodies as seen by an
observer
Geometry Finder Subsystem 35
 N IF Binary State Searches
Navigation and Ancillary Information Facility

• Binary state searches find times when a

specified binary state function takes the value
“true.”
– SPICE window arithmetic can be used to find the times when
a binary state function is “false.”

Geometry Finder Subsystem 36

 N IF Numeric Searches
Navigation and Ancillary Information Facility

• Numeric searches find times when a scalar numeric

quantity satisfies a mathematical constraint. The
supported constraints are:
– The function
» equals a specified reference value.
» is less than a specified reference value.
» is greater than a specified reference value.
» is at a local maximum.
» is at a local minimum.
» is at an absolute maximum.
» is at an absolute minimum.
» is at an “adjusted” absolute maximum: the function is within a
given tolerance of the absolute maximum.
» is at an “adjusted” absolute minimum: the function is within a
given tolerance of the absolute minimum.
• Examples for a Distance search follow.

Geometry Finder Subsystem 37

 N IF Solve Distance Equality
Navigation and Ancillary Information Facility

Find times at which Distance = D0

GF API input arguments defining constraint:
RELATE = '='
ADJUST = 0.D0
REFVAL = D0

Confinement
Window [ ]

D = f(t)
Distance

D0

Result
Window
[t0, t0] Time[t1, t1] [t2, t2] [t3, t3]

Time
Geometry Finder Subsystem 38
 N IF Solve Distance < Inequality
Navigation and Ancillary Information Facility

Find times during which Distance < D0

GF API input arguments defining constraint:
RELATE = '<'
ADJUST = 0.D0
REFVAL = D0

Confinement
Window [ ]

D = f(t)
Distance

D0

Result
Window
[t0, Time t1] [t2, t3]

Time
Geometry Finder Subsystem 39
 N IF Solve Distance > Inequality
Navigation and Ancillary Information Facility

Find times during which Distance > D0

GF API input arguments defining constraint:
RELATE = '>'
ADJUST = 0.D0
REFVAL = D0

Confinement
Window [ ]

D = f(t)
Distance

D0

Result
Window
[t0, t1] Time [t2, t3] [t4,t5]

Time
Geometry Finder Subsystem 40
 N IF Find Local Minima
Navigation and Ancillary Information Facility

Find times at which Distance is a local minimum.

GF API input arguments defining constraint:
RELATE = 'LOCMIN'
ADJUST = 0.D0 (REFVAL is not used in this case
but should be initialized for portability)
REFVAL = 0.D0

Confinement
Window [ ]
Distance

D = f(t)

Result
[t0,t0] [t1,t1] Window
Time
Geometry Finder Subsystem 41
 N IF Find Local Maxima
Navigation and Ancillary Information Facility

Find times at which Distance is a local maximum.

GF API input arguments defining constraint:
RELATE = 'LOCMAX'
ADJUST = 0.D0 (REFVAL is not used in this case
but should be initialized for portability)
REFVAL = 0.D0

Confinement
Not
Window [ ] Solutions

Local extrema are

always in the
Distance

interior of the
D = f(t) confinement
window,
never on the
boundary

Result
[t0,t0] Window
Time
Geometry Finder Subsystem 42
 N IF Find Absolute Minimum
Navigation and Ancillary Information Facility

Find the time at which Distance is an absolute minimum.

GF API input arguments defining constraint:
RELATE = 'ABSMIN'
ADJUST = 0.D0 (REFVAL is not used in this case

REFVAL = 0.D0 but should be initialized for portability)

Confinement
Window [ ]
Distance

D = f(t)
DMIN

Result
[t0,t0] Window
Time
Geometry Finder Subsystem 43
 N IF Find Absolute Maximum
Navigation and Ancillary Information Facility

Find the time at which Distance is an absolute maximum.

GF API input arguments defining constraint:
RELATE = 'ABSMAX'
ADJUST = 0.D0 (REFVAL is not used in this case
but should be initialized for portability)
REFVAL = 0.D0

Confinement
Window [ ]
DMAX
Distance

D = f(t)

Result
[t0,t0] Window
Time
Geometry Finder Subsystem 44
 N IF Find Adjusted Absolute Minimum
Navigation and Ancillary Information Facility

Find times at which Distance < DADJ = DMIN + ADJ0

GF API input arguments defining constraint:
RELATE = 'ABSMIN'
ADJUST = ADJ0 (ADJ0 > 0)
REFVAL = 0.D0 (REFVAL is not used in this case but should be initialized for portability)

Confinement
Window [ ]

D = f(t)
Distance

DADJ
ADJ0
DMIN Result
Window
[ t0, t1 ] [ t 2 , t3 ]

Time
Geometry Finder Subsystem 45
 N IF Find Adjusted Absolute Maximum
Navigation and Ancillary Information Facility

Find times at which Distance > DADJ = DMAX - ADJ0

GF API input arguments defining constraint:
RELATE = 'ABSMAX'
ADJUST = ADJ0 (ADJ0 > 0)
REFVAL = 0.D0 (REFVAL is not used in this case but should be initialized for portability)

Confinement
Window [ ]
DMAX
ADJ0
DADJ
Distance

D = f(t)

[ t0, t1 ]
Result
[ t2, t3 ]
Window
Time
Geometry Finder Subsystem 46
 N IF
Navigation and Ancillary Information Facility

More Details
• GF mid-level APIs
• Root Finding, including step
size selection
• Workspace
• API Example: GFDIST

Geometry Finder Subsystem 47

 N IF GF Mid-Level API Routines
Navigation and Ancillary Information Facility

• The Fortran and C SPICE Toolkits provide some mid-

level APIs that provide additional capabilities:
– Progress reporting, which can be customized by the user
– Interrupt handling which can be customized by the user
» In Fortran, no default interrupt detection is available
– User-customizable search step and refinement routines
– User-adjustable root finding convergence tolerance

• The GF mid-level search APIs are:

– GFEVNT: All scalar numeric quantity searches
– GFFOVE: Target or ray in FOV searches
– GFOCCE: Occultation searches

Geometry Finder Subsystem 48

 N IF
Navigation and Ancillary Information Facility

Root Finding

Geometry Finder Subsystem 49

 N IF Root Finding
Navigation and Ancillary Information Facility
• To produce a final or intermediate result window, the GF
subsystem must accurately locate the endpoints of the window’s
intervals. These endpoints are called “roots.”
– The green regions below (rectangles and vertical line segment) represent
intervals of a window.
– Roots are indicated by the red, vertical arrows.

• Elsewhere, “root finding” often refers to solving f(x) = 0.

• In the GF setting, roots are boundaries of time intervals over which
a specified constraint is met.
– Roots can be times when a binary state function changes values.
• Most popular root finding methods, e.g. Newton, secant, bisection,
require the user to first “bracket” a root: that is, determine two
abscissa values such that a single root is located between those
values.
• The GF subsystem solves a more difficult problem: it performs a
global search for roots. That is, given correct inputs, it finds all
roots within a user-specified confinement window.
– The user is not asked to bracket the roots.

Geometry Finder Subsystem 50

 N IF Step Size Selection
Navigation and Ancillary Information Facility

• The GF subsystem asks the user to specify a time

step (often called the“step size”) that will be used
to bracket roots.
– For binary state searches, the step size is used to
bracket the endpoints of the intervals of the result
window.
» The step size must be shorter than any event of
interest, and shorter than any interval between
events that are to be distinguished.
– For numeric searches, the step size is used to bracket
the endpoints of the intervals of the window on which
the geometric quantity is monotonically decreasing.
» The step size must be shorter than any interval on
which the function is monotonically increasing or
decreasing.
– In both cases, the step size must be large enough so the
search completes in a reasonable amount of time.

Geometry Finder Subsystem 51

 N IF Monotone Windows -1
Navigation and Ancillary Information Facility
Example: monotone windows for a distance function
Note that:
Extrema occur only at window interval boundaries.
Each window interval contains at most one root of an equality condition.
Within each window interval, the solution of an inequality is a single (possibly empty) interval.

“f(t) Increasing” Window [ ] [ ]

“f(t) Decreasing” Window [ ] [ ]
Confinement
Window [ ]

D = f(t)
Distance

D0

Time
Geometry Finder Subsystem 52
 N IF Monotone Windows-2
Navigation and Ancillary Information Facility

The shortest interval on which the function is monotonically

increasing or decreasing may be LONGER than the event of interest.
For example, consider the search for times when D < D0. The result
window consists of the interval [t0, t1] shown below.

“f(t) Increasing” Window [ ]

“f(t) Decreasing” Window [ ]
Confinement
Window [ ]

D = f(t)
Distance

D0

[ t0, t1 ]
Time
Geometry Finder Subsystem 53
 N IF Bracketing Interval Endpoints
Navigation and Ancillary Information Facility
• In the diagram below, the green boxes denote intervals of a
window.
• The start of the first interval is bracketed by the first and second
times; the end of the first interval is bracketed by the third and
fourth times. The start of the second interval is bracketed by the
fourth and fifth times.

window interval 1 window interval 2 …

step size
“delta”
t1 t2 t3 t4 t5 t6 t7
step = 3*delta
step = 2*delta

• The step size is a critical determinant of the completeness

of the solution:
– If the step size were equal to 3*delta, the first interval would not be
seen.
– If the step size were equal to 2*delta, the first and second intervals
would not be seen as distinct.

Geometry Finder Subsystem 54

 N IF Solving for Interval Endpoints
Navigation and Ancillary Information Facility

window interval 1 window interval 2

step size
“delta”
t1 t2 t3 t4 t5 t6 t7

• Once an interval endpoint is bracketed, the GF subsystem

performs a refinement search to locate the endpoint
precisely (shown by the red arrows).
– The default tolerance for convergence is 1.e-6 second.
• The refinement search is usually relatively fast compared to
the interval bracketing search.

Geometry Finder Subsystem 55

 N IF The Result Window
Navigation and Ancillary Information Facility

• For binary state searches, the window whose endpoints are

found IS the result window.
– The search is done once the endpoint refinement step has been
completed for each interval over which the state is true.
• For numeric searches, once the monotone windows have
been found, the result window still must be computed:
– Local and absolute extrema can be found without further
searching.
– Equalities, inequalities, and adjusted absolute extrema require
a second search pass in which each monotone interval is
examined.
» These searches don’t require sequential stepping and are
usually relatively fast compared to the interval bracketing search.
• Since the roots are found by a search process, they are
subject to approximation errors.
– NOTE: The geometric condition may not be satisfied at or near the
endpoints of the result window’s intervals.
• Usually data errors are large enough so that the accuracy of
the result is poorer than its precision.

Geometry Finder Subsystem 56

 N IF
Navigation and Ancillary Information Facility

Workspace

Geometry Finder Subsystem 57

 N IF Specifying Workspace Dimensions
Navigation and Ancillary Information Facility

• GF numeric scalar searches can require relatively

large amounts of memory to store intermediate
results.
– For Fortran Toolkits, user applications must declare a buffer of
workspace windows.
– For C, IDL, and MATLAB Toolkits, users need only specify the
maximum number of workspace window intervals that are needed;
these Toolkits will dynamically allocate the amount of memory
required by the specified workspace window interval count.
• In most cases, users need not accurately compute the
required amount of workspace; it’s usually safe to
specify a number much larger than the amount
actually needed.
– For example, if the result window is anticipated to contain 100
intervals, specifying a workspace window interval count of 10000 will
very likely succeed.
– See the GF Required Reading and the API documentation for details.
Geometry Finder Subsystem 58
 N IF
Navigation and Ancillary Information Facility

API Example: GFDIST

Solve for Distance Constraints

Geometry Finder Subsystem 59

 N IF API Example: GFDIST
Navigation and Ancillary Information Facility

• GFDIST finds times when a specified constraint on the

distance between two ephemeris objects is met.
– The distance is the norm of a position vector
– The position vector is defined using a subset of the inputs accepted
by SPKPOS:
» Target
» Observer
» Aberration Correction
– The constraint is a numeric relation: equality or inequality relative to
a reference value, or attainment of a local or absolute extremum.
• The search is conducted within a specified
confinement window.
• The search produces a result window which indicates
the time period, within the confinement window, over
which the constraint is met.
Geometry Finder Subsystem 60
 N IF Language Differences
Navigation and Ancillary Information Facility

• Due to use of SPICE windows, some of the GFDIST

set-up code differs substantially across languages.
– We’ll show how to perform the set-up unique to each language.
» Note: there’s no set-up to do in the MATLAB case; hence there’s
no MATLAB-specific set-up slide.
– The rest of the code is sufficiently parallel across languages to
justify showing only the Fortran code.
– Note however that the treatment of workspace differs across
languages: only in Fortran does the user application have to pass
the workspace array to the GF API routine.

Geometry Finder Subsystem 61

 N IF Fortran Set-up
Navigation and Ancillary Information Facility

Fortran constant and variable declarations

Declare confinement window, result window, and workspace array
INCLUDE 'gf.inc' Include GF parameters
… such as NWDIST

INTEGER LBCELL
PARAMETER ( LBCELL = -5 ) Choose a “large” value for window size (called “MAXWIN”
INTEGER MAXWIN here), if you’re not sure what size is required. The actual
requirement depends on underlying geometry, confinement
PARAMETER ( MAXWIN = 200000 ) window, and search step size.
DOUBLE PRECISION CNFINE ( LBCELL : MAXWIN )
DOUBLE PRECISION RESULT ( LBCELL : MAXWIN )
DOUBLE PRECISION WORK ( LBCELL : MAXWIN, NWDIST )

Initialization…typically done once per program execution

Initialize confinement and result windows. Workspace need not be initialized

here.
CALL SSIZED ( MAXWIN, CNFINE )
CALL SSIZED ( MAXWIN, RESULT )

Geometry Finder Subsystem 62

 N IF C Set-up
Navigation and Ancillary Information Facility

C constant and variable declarations

Declare confinement and result windows, as well as size of workspace.

Include CSPICE macro, typedef,
#include "SpiceUsr.h" and prototype declarations
… Choose a “large” value for window size (called “MAXWIN”
here), if you’re not sure what size is required. Actual
requirement depends on underlying geometry, confinement
#define NINTVL 100000 window, and search step size. The window size must be twice
#define MAXWIN ( 2 * NINTVL ) the maximum number of intervals the window is meant to hold.

SPICEDOUBLE_CELL ( cnfine, MAXWIN ); These macro calls declare CSPICE

SPICEDOUBLE_CELL ( result, MAXWIN ); window structures and set their
maximum sizes.

Geometry Finder Subsystem 63

 N IF IDL Set-up
Navigation and Ancillary Information Facility

IDL window creation

Choose a “large” value for window size (called
Icy windows are created dynamically: “MAXWIN” here), if you’re not sure what size is
required. Actual requirement depends on underlying
cnfine = cspice_celld ( MAXWIN ) geometry, confinement window, and search step size.
The window size must be twice the maximum number
of intervals the window is meant to hold.

The output result window is created by CSPICE_GFDIST; it

does not require a constructor call by the user application.

Geometry Finder Subsystem 64

 N IF All Languages: Additional Set-up
Navigation and Ancillary Information Facility

Initialization…typically done once per program execution

Tell your program which SPICE files to use (“loading” files)

Better yet, replace these two calls with a
CALL FURNSH ('spk_file_name') single call to a “meta-kernel” containing
the names of all kernel files to load.
CALL FURNSH ('leapseconds_file_name')

The next step is to insert times into the confinement window. The
simplest confinement window consists of a single time interval.

Convert UTC start and stop times to ephemeris time (TDB), if needed:
CALL STR2ET ( 'utc_start', tdb_0)
CALL STR2ET ( 'utc_stop', tdb_1)

Insert start and stop times into the confinement window:

CALL WNINSD ( tdb_0, tdb_1, CNFINE )

Geometry Finder Subsystem 65

 N IF Execute the Search -1
Navigation and Ancillary Information Facility
Search execution…done as many times as necessary during program execution
Choose:
– Geometric input arguments:
» Target
» Observer
» Aberration correction
– Constraint arguments:
» Relation
» Reference value, if applicable
» Adjustment value, if applicable
– Search step size
Then call GFDIST:
CALL GFDIST (target, 'correction', observer, 'relate',
refval, adjust, step, cnfine, mw, nw, work, result )

inputs Input/output output

Geometry Finder Subsystem 66

 N IF Execute the Search -2
Navigation and Ancillary Information Facility
Search execution, continued
Extract intervals from the result window:
DO I = 1, WNCARD( RESULT )

[Fetch the endpoints of the Ith interval of the result window.]

CALL WNFETD( RESULT, I, START, FINISH )
[ use START, FINISH… ]
END DO

• Note:
– The result window may be empty.
– The constraint might not be satisfied at or near the endpoints of any interval of RESULT.
» Consider using the window contraction routine WNCOND to shrink the intervals of
the result window slightly, so the constraint is met on the entire result window.
» Caution: DON’T use WNCOND for minimum, maximum, or equality searches---the
result window will disappear! (WNCOND is ok for adjusted absolute extrema search
results, though, since the result intervals are not singletons.)
» Caution: using WNCOND may not be desirable if the window is an intermediate
result: subsequent, derived results might be made less accurate.

Geometry Finder Subsystem 67

 N IF Arguments of GFDIST - 1
Navigation and Ancillary Information Facility
INPUTS
• TARGET* and OBSERVER*: Character names or NAIF IDs for the
end point and origin of the position vector (Cartesian position and
velocity vectors) whose length is the subject of the search. Below,
we’ll simply call this length “the distance.”
– The position vector points from observer to target.

• CORRECTION: Specification of what kind of aberration

correction(s), if any, to apply in computing the distance.
– Use ‘LT+S’ to use the apparent position of the target as seen by the
observer. ‘LT+S’ invokes light time and stellar aberration corrections.
– Use ‘NONE’ to use the uncorrected (aka “geometric”) position, as
given by the source SPK file or files.
See the headers of the subroutines GFDIST and SPKEZR, the document
SPK Required Reading, or the “Fundamental Concepts” tutorial for details.
See the SPK tutorial backup charts for examples of aberration correction
magnitudes.

* Character names work for the target and observer inputs only if built into SPICE or if registered using the
SPICE ID-body name mapping facility. Otherwise use the SPICE numeric ID in quotes, as a character string.
Geometry Finder Subsystem 68
 N IF Arguments of GFDIST - 2
Navigation and Ancillary Information Facility
INPUTS
• RELATE, REFVAL, ADJUST: parameters specifying a constraint to be met
by the distance.
– RELATE may be any of ‘=‘, ‘>’, ‘<‘, ‘LOCMAX’, ‘LOCMIN’, ‘ABSMAX’, ‘ABSMIN’
– If RELATE is an equality or inequality operator, REFVAL is the corresponding
double precision reference value. Units are km.
» For example, if the constraint is “distance = 4.D5 km,” then RELATE is ‘=‘
and REFVAL is 4.D5.
– If RELATE specifies an absolute maximum or minimum, ADJUST is the
adjustment value. Units are km.
» Set ADJUST to 0.D0 for a simple absolute maximum or minimum.
» Set ADJUST to a positive value ADJ for either DISTANCE > absolute max -
ADJ or DISTANCE < absolute min + ADJ.
• STEP: search step size, expressed as TDB seconds.
• CNFINE: the confinement window over which the search will be performed.
• MW, NW, WORK: the maximum capacity of each workspace window, the
number of workspace windows, and the workspace array.

OUTPUTS
• RESULT: the window of times over which the distance constraint is
satisfied.
Geometry Finder Subsystem 69
N IF
Navigation and Ancillary Information Facility

Toolkit Applications

April 2023
 N IF Toolkit Applications
Navigation and Ancillary Information Facility

Toolkit applications create or manipulate kernels, or

perform other functions such as time conversion.
Each of the following applications is included in the
Toolkits.
• Time conversion tool: chronos
• SPK generation tool: mkspk
• SPK merge and subset tool: spkmerge
• SPK comparison and sample tool: spkdiff
• CK generation tool: msopck
• Frame comparison tool: frmdiff
• DSK generation tool: mkdsk
• DSK export tool: dskexp
• Kernel summary tools: brief, ckbrief, dskbrief, spacit
• Comments manipulation tools: commnt, spacit
• File format converters: tobin, toxfr

Toolkit Applications 2
 N IF Using Toolkit Apps
Navigation and Ancillary Information Facility

• All of these apps are meant to be used as

operating system shell executables
– One generally cannot run these within IDL or MATLAB
» In some cases you can run from within IDL or
MATLAB, but this is not recommended:
• In IDL, use the “spawn” command
• In MATLAB, use the “system” command

Toolkit Applications 3
 N IF CHRONOS
Navigation and Ancillary Information Facility

chronos provides a flexible interface to the SPICE

Toolkit time conversion capabilities.

chronos supports time conversion between the

following time systems/types and using the
indicated time types for those systems.

Supported Time Systems --> Supported Time Types

------------------------------ ---------------------------
Universal Coord. Time (UTC) --> SCET, ERT, ETT, LT
Ephemeris Time (ET) --> SCET, ERT, ETT, SECONDS, LT
S/C On-board Clock Time (SCLK) --> SCLK, HEX, TICKS
Local Solar Time (LST) --> LST, LSUN

ERT = Earth Received Time

ETT = Earth Transmit Time
Toolkit Applications 4
 N IF CHRONOS - Input/Output Matrix
Navigation and Ancillary Information Facility

Input System/Type Output System/Type

----------------- -----------------
UTC / SCET (*) UTC / SCET (*)
UTC / ERT UTC / ERT
UTC / ETT UTC / ETT
ET / SCET (*) UTC / LT
ET / ERT ET / SCET (*)
ET / ETT ET / ERT
ET / SECONDS ET / ETT
SCLK / SCLK (*) ET / SECONDS
SCLK / HEX ET / LT
SCLK / TICKS SCLK / SCLK (*)
LST / LST SCLK / HEX
SCLK / TICKS
LST / LST (*)
(*) default input/output types LST / LSUN

Toolkit Applications 5
 N IF CHRONOS - Miscellaneous
Navigation and Ancillary Information Facility

• chronos normally converts one input time per

execution, but can run in batch mode to speed up
conversion for multiple input times.
• OS shell alias capabilities can be used to define
shortcuts for commonly used time conversions.
• chronos has an extensive user's guide.

Toolkit Applications 6
 N IF CHRONOS - Usage
Navigation and Ancillary Information Facility
Terminal Window
$ chronos
...
CHRONOS Usage
------------------------------------------------------------------

To convert time from one supported system/type to another:

% CHRONOS -SETUP <setup file name OR kernel file name(s)>

-FROM <"from" time system>
[-FROMTYPE <"from" time type>]
-TO <"to" time system>
[-TOTYPE <"to" time type>]
[-FORMAT <output time format picture>]
-TIME <input time> | -BATCH
[-SC <sc ID>] Items in square
[-CENTER <cental body ID>] brackets are optional
[-LANDINGTIME <UTC time of the landing>]
[-SOL1INDEX <index of the first SOL>]
[-NOLABEL]
[-TRACE]

Toolkit Applications 7
 N IF CHRONOS - Example
Navigation and Ancillary Information Facility
Terminal Window
$ cat chronos.cas
Sample CHRONOS setup file for Cassini
\begindata
KERNELS_TO_LOAD = ( 'naif0007.tls', 'cas00085.tsc' )
SPACECRAFT_ID = -82
\begintext

$ chronos -setup chronos.cas -from utc -to et -time 1999 JAN 12 12:00
1999-01-12, 12:01:04.184 (ET/SCET)

$ chronos -setup chronos.cas -from utc -to sclk -time 1999 JAN 12 12:00
1/1294833883.185 (SCLK/SCLK)

$ chronos -setup naif0007.tls cas00085.tsc -sc -82 -from sclk -to utc -time
1/1294833883.185
1999-01-12 11:59:59.998 (UTC/SCET)

$ chronos -setup naif0007.tls cas00085.tsc -sc -82 -from sclk -to utc -time
1/1294833883.185 -format 'YYYY-DOYTHR:MN:SC ::RND' -nolabel
1999-012T12:00:00

Toolkit Applications 8
 N IF MKSPK
Navigation and Ancillary Information Facility

• mkspk may be used to generate an SPK file from

any of several types of data, such as discrete
state vectors, classical orbital elements, and
NORAD two-line elements.
• Use of this program is discussed in a separate
tutorial about making SPK files, and in the mkspk
User’s Guide.

Toolkit Applications 9
 N IF SPKMERGE
Navigation and Ancillary Information Facility

• The contents of an SPK file or set of SPK

files may be merged or subsetted using
spkmerge
– You can extract an interval of time of interest from a
single SPK file or a set of SPK files.
– You can extract data for one or more objects from a
single SPK file or a set of SPK files.
– You can combine both the time and object selection
mechanisms for the greatest flexibility.

Toolkit Applications 10
 N IF SPKMERGE - Precedence Rule
Navigation and Ancillary Information Facility

• SPK files created with spkmerge have no

overlapping ephemeris data. The order in
which the source files are specified
determines precedence when source files
have overlapping coverage for a body of
interest.
– IMPORTANT NOTE: Data from an earlier specified source
file take precedence over data from a later specified
source file when the new (merged) file is created. This is
different from the usual SPICE precedence rules.

Toolkit Applications 11
 N IF SPKMERGE - Example
Navigation and Ancillary Information Facility
Terminal Window
$ cat spkmerge_cas_example.cmd
;This command file directs spkmerge to take data for
;Cassini, the Sun, the Earth, the Moon, and the Earth-
;Moon barycenter and place them into a single SPK.

leapseconds_kernel = naif0007.tls
spk_kernel = output.bsp
bodies = -82, 10, 301, 399, 3
source_spk_kernel = de403s.bsp
source_spk_kernel = 990825A_SCEPH_EM52_JP0.bsp

$ spkmerge
SPKMERGE -- SPK Merge Tool, Version 3.2, SPICE Toolkit N0057

Enter the name of the command file

> spkmerge_cas_example.cmd

Creating output.bsp

Toolkit Applications 12
 N IF SPKDIFF
Navigation and Ancillary Information Facility

• spkdiff is a command line program for computing the difference

between trajectories of two objects obtained from a set of SPK
kernels, or for sampling (“dumping”) the trajectory of an object
• In comparison mode, spkdiff compares trajectories by
computing a set of geometric states for a specified body, center
and frame over an interval of time with a fixed time step using a
set of kernels, then computing another set of geometric states
for the same or different body, center, and frame at the same
times using the same or another set of kernels, and then
subtracting the corresponding states from each other
– Depending of the requested output type spkdiff prints to the screen:
» only the maximum differences,
» a complete table of differences, or
» a statistical analysis of the differences
• In sampling mode, spkdiff computes a set of states for a
specified body relative to another body in a specified reference
frame over a specified interval with a specified step

Toolkit Applications 13
 N IF SPKDIFF - Usage
Navigation and Ancillary Information Facility
Terminal Window
% spkdiff

... The program usage is:

% spkdiff [options] <first SPK name> <second SPK name>

% spkdiff [options] <SPK name>
% spkdiff [options]

Options are shown below. ...

-k <supporting kernel(s) name(s)>

-b1 <first body name or ID>
-c1 <first center name or ID>
-r1 <first reference frame name>
-k1 <additional supporting kernel(s) for first SPK>
-b2 <second body name or ID>
-c2 <second center name or ID>
-r2 <second reference frame name>
-k2 <additional supporting kernel(s) for second SPK>
-b <interval start time>
-e <interval stop time>
-s <time step in seconds>
-n <number of states: 2 to 1000000 (default: 1000)>
-f <output time format (default: TDB seconds past J2000)>
-d <number of significant digits: 6 to 17 (default: 14)>
-t <report type: basic|stats|dump|dumpvf|dumpc|dumpg (def.: basic|dump)>

Toolkit Applications 14
 N IF SPKDIFF – Basic Output Example
Navigation and Ancillary Information Facility
Terminal Window
$ spkdiff mro_psp.bsp mro_psp_rec.bsp
# Comparison of 1000 'J2000'-referenced geometric states
#
# of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4)
# from SPK 'mro_psp.bsp'
#
# with 1000 'J2000'-referenced geometric states
#
# of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4)
# from SPK 'mro_psp_rec.bsp'
#
# evenly-spaced with 2617.6524668123 second (0d 0h 43m 37.652467s) step size
# within the time interval
#
# from '2007 APR 01 00:01:05.185 TDB' (228657665.18565 TDB seconds)
# to '2007 MAY 01 06:25:00.000 TDB' (231272700.00000 TDB seconds)
#
Relative differences in state vectors:
maximum average
Position: 8.4872836561757E-05 1.2312974450656E-05
Velocity: 8.5232570159796E-05 1.2314285182022E-05

Absolute differences in state vectors:

maximum average
Position (km): 3.1341344106404E-01 4.5090516995222E-02
Velocity (km/s): 2.8848827480682E-04 4.2085874877127E-05

Toolkit Applications 15
 N IF SPKDIFF – Dump Output Example
Navigation and Ancillary Information Facility
Terminal Window
$ spkdiff -t dumpvf mro_psp.bsp mro_psp_rec.bsp | more
# Comparison of 1000 'J2000'-referenced geometric states
#
# of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4)
# from SPK 'mro_psp.bsp'
#
# with 1000 'J2000'-referenced geometric states
#
# of 'MARS RECON ORBITER' (-74) relative to 'MARS BARYCENTER' (4)
# from SPK 'mro_psp_rec.bsp'
#
# evenly-spaced with 2617.6524668123 second (0d 0h 43m 37.652467s) step size
# within the time interval
#
# from '2007 APR 01 00:01:05.185 TDB' (228657665.18565 TDB seconds)
# to '2007 MAY 01 06:25:00.000 TDB' (231272700.00000 TDB seconds)
#
# time, down_track_p_diff, normal_to_plane_p_diff, in_plane_p_diff, down_track_v
_diff, normal_to_plane_v_diff, in_plane_v_diff
2.2865766518565E+08 +4.2593079332056E-02 -9.0540866105197E-05 -3.9705894066565E-04 -8.0803561182349E-08
-1.0394439243989E-07 -3.9614350816493E-05
2.2866028283812E+08 +4.2172435702119E-02 +2.3672255851626E-06 -1.1475679619731E-04 +1.3970238250217E-07
+1.4080506259574E-07 -3.9250157214024E-05
2.2866290049059E+08 +4.4830247467488E-02 +9.1590974014175E-05 -7.3802870365833E-04 +5.7800410436763E-07
-1.1724240528272E-07 -4.2099832045985E-05
2.2866551814305E+08 +4.5968515669515E-02 -1.3529652839857E-04 -7.5686845133612E-05 -4.7565892258325E-07
+3.4127364997784E-08 -4.2529268294482E-05
--More--

Toolkit Applications 16
 N IF MSOPCK
Navigation and Ancillary Information Facility

• msopck is a program for making CK files from

orientation provided in a text file as a time tagged,
space-delimited table
– It has a simple command line interface
– It requires all setups to be provided in a setup file that follows
the SPICE text kernel syntax
– It can process quaternions (SPICE and non-SPICE styles),
Euler angles, or matrices, tagged with UTC, SCLK, or ET
– For more details see the “Making a CK File” Tutorial

Toolkit Applications 17
 N IF FRMDIFF
Navigation and Ancillary Information Facility

• frmdiff is a command line program for sampling the orientation

of a reference frame or for computing the difference between
orientations of two reference frames based on provided set(s)
of SPICE kernels
• In sampling mode, frmdiff computes a set of transformations
from one frame to another frame over a specified interval with
a specified time step
• In comparison mode, frmdiff computes two sets of
transformations for two pairs of “from” and “to” frames and
then computes the difference in rotation and angular velocity
between these transformations over a specified interval with a
specified time step
• Depending on the execution mode and the requested output
type, frmdiff prints to the screen:
– only the maximum rotation or the maximum rotation difference,
– a complete table of rotations or differences (as angle and axis, SPICE- or
engineering-style quaternions, matrices, or Euler angles), or
– a statistical analysis of rotations or differences.
Toolkit Applications 18
 N IF FRMDIFF - Usage
Navigation and Ancillary Information Facility
Terminal Window
$ frmdiff
% frmdiff [options] <first kernel name> <second kernel name>
% frmdiff [options] <kernel name>
% frmdiff [options]
where kernel can be a CK, an FK, or a PCK. Options are shown below.
-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>
-m <frame for angular velocities: from|to>
-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>
-t <report: basic|stats|dumpaa|dumpm|dumpqs|dumpqo|dumpea|dumpc|dumpg>
-o <rotation axes order (default: z y x)>
-x <units for output angles> (only for -t dumpaa and -t dumpea)
-d <number of significant digits: 6 to 17 (default: 14)>

Toolkit Applications 19
 N IF FRMDIFF – Sampling Example
Navigation and Ancillary Information Facility
Terminal Window
$ 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...

Toolkit Applications 20
 N IF FRMDIFF – Comparison Example
Navigation and Ancillary Information Facility
Terminal Window
$ 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....

Toolkit Applications 21
 N IF MKDSK
Navigation and Ancillary Information Facility

• mkdsk is a program for making Digital Shape

Kernel (DSK) files from digital shape data provided
in a text file
– It has a simple command line interface
– It requires all setups to be provided in a setup file that follows
the SPICE text kernel syntax
– It can process shape data in one of the following formats:
» plate-vertex table
» Gaskell shape model
» vertex-facet table
» Rosetta/OSIRIS “ver” table
» ASCII height grid
– The N0067 MKDSK can output only Type 2 (plate model) DSKs
– For more details see the MKDSK User’s Guide
Toolkit Applications 22
 N IF DSKEXP
Navigation and Ancillary Information Facility

• dskexp is a program for exporting digital shape

data from a DSK file to a text file
– It has a simple command line interface
– The N0067 DSKEXP can export data only from Type 2 (plate
model) DSKs
– It can output shape data in one of the following formats
» plate-vertex table
» vertex-facet table, a.k.a. “obj”
» Rosetta/OSIRIS “ver” table
– It creates a separate output file for each DSK segment
– For more details see DSKEXP User’s Guide

Toolkit Applications 23
 N IF Kernel Summary Applications
Navigation and Ancillary Information Facility

The contents of binary kernels can be summarized

using kernel summary tools.
• brief displays the bodies and associated time
coverage in an SPK file or set of SPK files.
– brief also works on binary PCK files
• ckbrief displays the structure(s) and associated
time coverage in a CK file or set of CK files.
• dskbrief displays a summary of spatial coverage
and attributes for a DSK file or set of DSK files.
• spacit displays a segment by segment summary
of the contents of a CK, SPK, binary PCK, or
EK/ESQ file.
– spacit also identifies the SPK or CK data type present in each
segment.
– spacit does not work on DSK files.

Toolkit Applications 24
 N IF BRIEF
Navigation and Ancillary Information Facility

• brief is a command line program for summarizing

the contents of SPK or binary PCK files
• The files to be summarized can be listed on the
command line, given in a meta-kernel provided on
the command line, or provided in a list file
• brief provides command line options for
– displaying coverage boundaries as date UTC, DOY UTC, or ET
seconds past J2000 (default time format is calendar ET)
» to display time as UTC an LSK file must be provided on the
command line
– displaying centers of motion along with the bodies
– treating all input files as if they were a single file
– displaying a summary only for files covering a specified time or
time range or containing data for a specified body
– displaying a summary in tabular format or grouped by coverage
– and many others ...

Toolkit Applications 25
 N IF BRIEF - Usage
Navigation and Ancillary Information Facility
Terminal Window
$ brief
...
BRIEF is a command-line utility program that displays a summary for
one or more binary SPK or binary PCK files. The program usage is:

% brief [-options] file [file ...]

The most useful options are shown below. For the complete set of
options, run BRIEF with the -h option. The order of options is not
significant. The case of option keys is significant: they must be
lowercase as shown below.

-c display centers of motion/relative-to frames

-t display summary in a tabular format
-a treat all files as a single file
-utc display times in UTC calendar date format (needs LSK)
-utcdoy display times in UTC day-of-year format (needs LSK)
-etsec display times as ET seconds past J2000

An LSK file must be provided on the command line to display times in

UTC formats. FK file(s) must be provided on the command line to
display names of any frames that are not built into the Toolkit.

Toolkit Applications 26
 N IF BRIEF - Example
Navigation and Ancillary Information Facility
Terminal Window
$ brief de405s.bsp m01_cruise.bsp

BRIEF -- Version 4.1.0, September 17, 2021 -- Toolkit Version N0067

Summary for: de405s.bsp

Bodies: MERCURY BARYCENTER (1) SATURN BARYCENTER (6) MERCURY (199)

VENUS BARYCENTER (2) URANUS BARYCENTER (7) VENUS (299)
EARTH BARYCENTER (3) NEPTUNE BARYCENTER (8) MOON (301)
MARS BARYCENTER (4) PLUTO BARYCENTER (9) EARTH (399)
JUPITER BARYCENTER (5) SUN (10) MARS (499)
Start of Interval (ET) End of Interval (ET)
----------------------------- -----------------------------
1997 JAN 01 00:01:02.183 2010 JAN 02 00:01:03.183

Summary for: m01_cruise.bsp

Body: MARS SURVEYOR 01 ORBITER (-53)

Start of Interval (ET) End of Interval (ET)
----------------------------- -----------------------------
2001 APR 07 16:25:00.000 2001 OCT 24 05:00:00.000

Toolkit Applications 27
 N IF CKBRIEF
Navigation and Ancillary Information Facility

• ckbrief is a command line program for

summarizing the contents of CK files
• The files to be summarized can be listed on the
command line, given in a meta-kernel provided on
the command line, or provided in a list file
• ckbrief provides command line options for
– displaying coverage at interpolation interval level
– displaying coverage boundaries using UTC, DOY UTC, SCLK,
or encoded SCLK (default time format is calendar ET)
» To display times as ET, UTC, or SCLK, both an LSK file and
a SCLK file(s) must be provided on the command line
– displaying frames with respect to which orientation is provided
– displaying the names of the frames associated with CK IDs
» An FK file(s) defining these frames must be provided on
the command line
– treating all input CK files as if they were a single file
– displaying summary only for files with data for a given CK ID
– and many others ...
Toolkit Applications 28
 N IF CKBRIEF – Interval Summary
Navigation and Ancillary Information Facility

• There often are coverage gaps within a CK segment

• Using the ‘-dump’ option allows one to get a complete list of
continuous coverage intervals for each segment

Segment coverage reported Segment Coverage Reported

by ckbrief with ‘-dump’ by ckbrief without ‘-dump’

Time

Sample Type 3
CK Segment Instances of
Available
Coverage Gaps Pointing Data

Toolkit Applications 29
 N IF CKBRIEF – Usage
Navigation and Ancillary Information Facility
Terminal Window
$ ckbrief

...
CKBRIEF is a command-line utility program that displays a summary for
one or more binary CK files. The program usage is:

% ckbrief [-options] file [file ...]

The most useful options are shown below. For the complete set of
options, run CKBRIEF with the -h option. The order of options is not
significant. The option keys must be lowercase as shown below.

-dump display interpolation intervals

-rel display relative-to frames (may need FK)
-n display frames associated with CK IDs (may need FK)
-t display summary in a tabular format
-a treat all files as a single file
-utc display times in UTC calendar date format (needs LSK&SCLK)
-utcdoy display times in UTC day-of-year format (needs LSK&SCLK)
-sclk display times as SCLK strings (needs SCLK)

LSK and SCLK files must be provided on the command line to display times
in UTC, ET, or SCLK formats. FK file(s) must be provided on the command
line to display names of any frames that are not built into the Toolkit.

Toolkit Applications 30
 N IF CKBRIEF – Example
Navigation and Ancillary Information Facility
Terminal Window
$ ckbrief -sclk 981116_981228pa.bc sclk.ker

CKBRIEF -- Version 6.1.0, June 27, 2014 -- Toolkit Version N0067

Summary for: 981116_981228pa.bc

Object: -82000
Interval Begin SCLK Interval End SCLK AV
------------------------ ------------------------ ---
1/1289865849.116 1/1293514473.118 N

$ ckbrief -utc sclk.ker naif0007.tls 990817_990818ra.bc

CKBRIEF -- Version 6.1.0, June 27, 2014 -- Toolkit Version N0067

Summary for: 990817_990818ra.bc

Object: -82000
Interval Begin UTC Interval End UTC AV
------------------------ ------------------------ ---
1999-AUG-17 17:30:01.418 1999-AUG-17 23:05:42.039 N
1999-AUG-17 23:05:45.289 1999-AUG-18 06:06:05.874 N
1999-AUG-18 06:06:09.124 1999-AUG-18 11:52:17.741 N
1999-AUG-18 11:52:20.991 1999-AUG-18 13:30:00.953 N

Toolkit Applications 31
 N IF CKBRIEF - ‘-dump’ Example
Navigation and Ancillary Information Facility
Terminal Window
$ ckbrief mgs_spice_c_kernel_2004-099.bc MGS_SCLKSCET.00053.tsc naif0007.tls -dump
-rel -utc

CKBRIEF -- Version 6.1.0, June 27, 2014 -- Toolkit Version N0067

Summary for: mgs_spice_c_kernel_2004-099.bc

Segment No.: 1

Object: -94000

Interval Begin UTC Interval End UTC AV Relative to FRAME

------------------------ ------------------------ --- -----------------
2004-APR-08 00:00:59.809 2004-APR-08 06:53:47.805 Y J2000
2004-APR-08 06:54:07.805 2004-APR-08 06:54:07.805 Y J2000
2004-APR-08 06:54:19.805 2004-APR-08 06:54:35.805 Y J2000
2004-APR-08 06:54:51.805 2004-APR-08 06:54:55.805 Y J2000
2004-APR-08 06:55:07.805 2004-APR-08 06:55:07.805 Y J2000
2004-APR-08 06:55:23.805 2004-APR-08 06:55:23.805 Y J2000
2004-APR-08 06:55:35.805 2004-APR-08 11:59:55.802 Y J2000
2004-APR-08 12:00:55.802 2004-APR-08 23:59:55.795 Y J2000

Toolkit Applications 32
 N IF DSKBRIEF
Navigation and Ancillary Information Facility

• dskbrief is a command line program for

summarizing the spatial coverage and additional
attributes of Digital Shape Kernel (DSK) files
• DSK files to be summarized can be listed on the
command line or given in a meta-kernel provided
on the command line
– Additional text kernels containing body, frame, and surface
name-ID associations must also be provided to produce
complete summary output
• dskbrief provides command line options for
– generating extended, full, and segment-by-segment
summaries
– treating all input files as if they were a single file
– displaying gaps in spatial coverage
– controlling the number of significant digits in the output
– and a few others

Toolkit Applications 33
 N IF DSKBRIEF - Usage
Navigation and Ancillary Information Facility
Terminal Window
$ dskbrief -u
...
DSKBRIEF is a command-line utility program that displays a summary of
one or more binary DSK files. The program usage is:
% dskbrief [options] file [file...]
The available options are shown below. The order of options is not
significant. The option keys must be lowercase as shown below.
-a Treat all DSK files as a single file.
-gaps Display coverage gaps. Applies only when -a is used.
-ext Display extended summaries: these include data type, data
class, and time bounds. This option applies to summaries
of groups of DSK segments.
-tg Require segment time bounds to match when grouping
segments.
-seg Display a segment-by-segment summary.
-full Display a detailed summary for each segment, including
data-type-specific parameters. This option implies a
segment-by-segment summary.
-d <n> Display n significant digits of floating point values.
-v Display the version of this program.
-h Display help text.
-u Display usage text.

Toolkit Applications 34
 N IF DSKBRIEF - Example
Navigation and Ancillary Information Facility
Terminal Window
$ dskbrief ROS_CG_M004_NSPCESA_N_V1.BDS ROS_LU_M003_OSPCLAM_N_V1.BDS ../FK/ROS_V25.TF
...
Summary for: ROS_CG_M004_NSPCESA_N_V1.BDS

Body: 1000012 (CHURYUMOV-GERASIMENKO)

Surface: 11000 (ROS_CG_M004_NSPCESA_N_V1)
Reference frame: 67P/C-G_CK
Coordinate system: Planetocentric Latitudinal
Min, max longitude (deg): 0.00000 360.000
Min, max latitude (deg): -90.0000 90.0000
Min, max radius (km): 4.86351E-01 2.65365

Summary for: ROS_LU_M003_OSPCLAM_N_V1.BDS

Body: 2000021 (LUTETIA)

Surface: 1011 (ROS_LU_M003_OSPCLAM_N_V1)
Reference frame name N/A; ID code: -2260021
Coordinate system: Planetocentric Latitudinal
Min, max longitude (deg): 0.00000 360.000
Min, max latitude (deg): -90.0000 90.0000
Min, max radius (km): 33.2395 64.6538

Toolkit Applications 35
 N IF SPACIT
Navigation and Ancillary Information Facility

• spacit may be used to obtain a more detailed

summary of an SPK or CK file than that offered by
brief or ckbrief, respectively
– spacit may also be used to summarize a binary PCK or an
EK/ESQ.
– spacit is an interactive program
» It will prompt you for all needed inputs

• spacit may also be used to manage comments,

and to convert between binary and transfer format

Toolkit Applications 36
 N IF Comment Manipulation Tools
Navigation and Ancillary Information Facility

• Every kernel should contain metadata – called

“comments” – describing the file contents,
intended usage, etc.
• In binary kernels – SPKs, CKs, binary PCKs, DSKs
and EKs – comments are stored in a special area of
the file called the “comment area.”
• commnt can read, extract, add, or delete comments
stored in the comment area
– Caution: you cannot add or delete comments if the kernel file is
not in native format for the machine on which you’re working.
» You can convert a non-native binary format file to native
binary format by converting the file to “transfer format”
using toxfr and then converting it back to binary format
using tobin.
» Or use the bingo utility (available only from the NAIF
website).

Toolkit Applications 37
 N IF COMMNT
Navigation and Ancillary Information Facility

• commnt is both a command line utility and an

interactive menu-driven program
• In command line mode, commnt provides options to
– print comments to the screen
$ commnt -r kernel_file
– extract comments to a text file
$ commnt –e kernel_file text_file
– add comments from a text file
$ commnt –a kernel_file comment_file
– delete comments
$ commnt –d kernel_file
• Important
– When comments are added, they are appended at the end of the
existing comments
– Comments should be deleted ONLY if being replaced with better
comments

Toolkit Applications 38
 N IF COMMNT - Command Line Example
Navigation and Ancillary Information Facility
Terminal Window
$ commnt -r de405.bsp | more
; de405.bsp LOG FILE
;
; Created 1999-10-03/14:31:58.00.
;
; BEGIN NIOSPK COMMANDS

LEAPSECONDS_FILE = /kernels/gen/lsk/naif0007.tls
SPK_FILE = de405.bsp
SOURCE_NIO_FILE = /usr2/nio/gen/de405.nio
BODIES = 1 2 3 4 5 6 7 8 9 10 301 399 199 299 499
BEGIN_TIME = CAL-ET 1950 JAN 01 00:00:41.183
END_TIME = CAL-ET 2050 JAN 01 00:01:04.183

; END NIOSPK COMMANDS

A memo describing the creation of the DE405 generic planet ephemeris is avail
able from NAIF or from the author: Dr. Myles Standish of JPL's Solar System Dy
namics Group. Because this memo was produced using the TeX processor and inclu
des numerous equations

>>> Beginning of extract from Standish's DE405 memo <<

...

Toolkit Applications 39
 N IF COMMNT – Interactive Example
Navigation and Ancillary Information Facility
Terminal Window
$ commnt

Welcome to COMMNT Version: 6.0.0

(Spice Toolkit N0050)

COMMNT Options

( Q ) Quit.
( A ) Add comments to a binary file.
( R ) Read the comments in a binary file.
( E ) Extract comments from a binary file.
( D ) Delete the comments in a binary file.

Option: E

Enter the name of the binary file.

Filename? de405.bsp

Enter the name of the comment file to be created.

Filename? de405_comments.txt

The comments were successfully extracted.

Toolkit Applications 40
 N IF File Format Conversion Tools
Navigation and Ancillary Information Facility

• With modern Toolkits (N0052 and later) the porting of DAF-based

binary kernels* between computers having dissimilar binary
standards is usually not necessary.
– The advent of binary kernel readers that detect the binary style and do run-
time translation if needed generally makes porting unnecessary for DAF-
based types.
– Refer to the “Porting Kernels” tutorial for more on this topic.
• If true porting is needed because you must modify or append to
a kernel:
– use toxfr on the source computer and tobin on the destination computer
– or use bingo on the destination computer
» NOTE: bingo is NOT available in generic Toolkits; it must be
downloaded from the NAIF website

* DAF-based binary kernels are SPK, CK and binary PCK

Toolkit Applications 41
N IF
Navigation and Ancillary Information Facility

Non-Toolkit Applications

April 2023
 N IF Summary
Navigation and Ancillary Information Facility
• NAIF makes available a set of applications not included in the
Toolkits. This set includes programs for:
– making, modifying, validating, inspecting, and converting SPK files:
» pinpoint, dafcat, bspidmod, dafmod, spy, oem2spk, spk2oem
– making and modifying CK files
» prediCkt, ckslicer, ckspanit, dafcat, cksmrg, dafmod
– making SCLK files
» makclk
– merging and modifying DSK files
» dlacat, dskmod
– computing derived quantities
» orbnum, optics, spy
– determining SPICE kernel type and binary format, and converting between
native and non-native formats
» archtype, bff, bingo
• Executables and User’s Guides are on the NAIF server at:
– https://naif.jpl.nasa.gov/naif/utilities.html
Non-Toolkit Applications 2
 N IF Using Non-Toolkit Apps
Navigation and Ancillary Information Facility

• All of these apps are meant to be used as

operating system shell executables
– One generally cannot run these within IDL or MATLAB–
run them from an operating system shell
» In some cases you can run from within IDL or
MATLAB, but this is not recommended:
• In IDL, use the “spawn” command
• In MATLAB, use the “system” command

Non-Toolkit Applications 3
 N IF PINPOINT
Navigation and Ancillary Information Facility

• pinpoint is a program for creating SPK files and topocentric

frames FK files for objects for which the position is a constant
offset with respect to another object
– Ground stations
– Landing sites, sites along a rover path
– Relative positions of manipulator joints, etc.
• pinpoint is a command line program with the following usage:
pinpoint -def deffile -spk spkfile [-pck tkfile] [-fk fk] [flags]
– “deffile” is an input definitions file following text kernel file format and
containing a set of keywords defining ID, center, reference frame, position (as
XYZ or Gaussian Lat/Lon/Alt) and time coverage boundaries, and optionally
velocity and topocentric frame axes specifications, for one or more objects
» The contents of “deffile” are included in the comment area
– “spkfile” is an output SPK file containing a type 8 SPK segment for each of the
objects specified in the “deffile”
– “tkfile” is an optional input PCK file (needed if positions in the “deffile” are
given as Lat/Lon/Alt) or FK file (needed if one or more of the frames specified
in “deffile” is not one of the frames built into the Toolkit)
– “fk” is an optional output topocentric frames FK file
Non-Toolkit Applications 4
 N IF PINPOINT Example
Navigation and Ancillary Information Facility
Terminal Window
$ more mer1_meridiani.def

Sample PINPOINT input for MER-1 landing site coordinates.

\begindata
SITES = ( 'LS' )
LS_CENTER = 499
LS_FRAME = 'IAU_MARS'
LS_IDCODE = -253900
LS_XYZ = ( +3.3764222E+03 -3.2664876E+02 -1.1539218E+02 )
LS_BOUNDS = ( @2001-01-01-00:00:00.000, @2100-01-01-00:00:00.000 )
\begintext

$ pinpoint -def mer1_meridiani.def -spk mer1_meridiani.bsp

$ brief mer1_meridiani.bsp
Brief. Version: 2.2.0 (SPICE Toolkit N0057)

Summary for: mer1_meridiani.bsp

Body: -253900* w.r.t. MARS (499)
Start of Interval (ET) End of Interval (ET)
-------------------------------- --------------------------------
2001 JAN 01 00:00:00.000 2100 JAN 01 00:00:00.000

Non-Toolkit Applications 5
 N IF DAFCAT
Navigation and Ancillary Information Facility

• dafcat is a program for concatenating binary DAF files by simply

copying all data segments from all input files, in the order they are
provided, into the output file
– dafcat works on SPKs, CKs, and binary PCKs
» It will not merge different types of kernels together, i.e. it will not merge
SPKs with CKs, CKs with PCKs, etc.
» For merging SPKs, in most cases spkmerge should be used instead
because it provides a much more powerful and sophisticated capability
• dafcat is a command line program with the following usage
dafcat output_file
– “output_file” is the output file name and is the program’s only argument
– Input file names are provided from standard input
» this is very convenient for use with Unix shell pipes
• dafcat does not put any information into the comment area of the
output file, leaving this responsibility to the user (use commnt to do
so)

Non-Toolkit Applications 6
 N IF DAFCAT Example: SPK
Navigation and Ancillary Information Facility
Terminal Window
$ dafcat m01_merged.bsp

DAF binary files concatenation program version 1.00

spk_m_od33905-33993_rec_v1.bsp
spk_m_od33992-34065_rec_v1.bsp
^D
Concatenating files:
spk_m_od33905-33993_rec_v1.bsp
spk_m_od33992-34065_rec_v1.bsp
to:
m01_merged.bsp

$ ls -1 spk_m_od*_rec_v1.bsp | dafcat m01_merged_2.bsp

DAF binary files concatenation program version 1.00

Concatenating files:
spk_m_od32371-32458_rec_v1.bsp
...
to:
m01_merged_2.bsp

Non-Toolkit Applications 7
 N IF DAFCAT Example: CK
Navigation and Ancillary Information Facility
Terminal Window
$ dafcat m01.bc

DAF binary files concatenation program version 1.00

m01_sc_2004-04-20.bc
m01_sc_2004-04-21.bc
^D
Concatenating files:
m01_sc_2004-04-20.bc
m01_sc_2004-04-21.bc
to:
m01.bc

$ ls -1 m01_sc_2004-04-2*.bc | dafcat m01.bc

DAF binary files concatenation program version 1.00

Concatenating files:
m01_sc_2004-04-20.bc
m01_sc_2004-04-21.bc
to:
m01.bc

Non-Toolkit Applications 8
 N IF DLACAT
Navigation and Ancillary Information Facility

• dlacat is a program for concatenating binary DLA files by simply

copying all data segments from all input files, in the order they are
provided, into the output file
– Works on DSKs
• dlacat is a command line program with the following usage
dlacat output_file
– “output_file” is the output file name and is the program’s only argument
– Input file names are provided from standard input
» this is very convenient for use with Unix shell pipes
• dlacat does not put any information into the comment area of the
output file, leaving this responsibility to the user (use commnt to do
so)

Non-Toolkit Applications 9
 N IF DLACAT Example: DSK
Navigation and Ancillary Information Facility
Terminal Window
$ dlacat phoebe_shape.bds

DLA binary files concatenation program version 1.00

phoebe_shape_part1.bds
phoebe_shape_part2.bds
^D
Concatenating files:
phoebe_shape_part1.bds
phoebe_shape_part2.bds
to:
phoebe_shape.bds

$ ls -1 phoebe_shape_part?.bds | dlacat phoebe_shape_2.bds

DLA binary files concatenation program version 1.00

Concatenating files:
phoebe_shape_part1.bds
phoebe_shape_part2.bds
to:
phoebe_shape_2.bds

Non-Toolkit Applications 10
 N IF BSPIDMOD
Navigation and Ancillary Information Facility

• bspidmod is a program for altering the object IDs in a binary SPK file
– It can be used to modify IDs in an SPK file(s) produced with a “bogus” spacecraft ID (or a
simulation spacecraft ID)
– It can be used to replace “official” IDs with “bogus” IDs if two different trajectories for
the same object need to be used in the same program at the same time (for example for
comparison, such as is done by spkdiff)
– Works only in kernels in “native” binary format
• bspidmod has the following usage:
bspidmod -spki inpspk -idi inpid -ido outid -mod item -oflg
– “inpspk” is the input SPK file; “inpid” and “outid” are the current ID and new ID
– “item” indicates which IDs are to be replaced – TARGET (only target IDs are replaced),
CENTER (only center IDs are replaced), or OBJECT (both target and center IDs are
replaced)
– Replacements are made only when “inpid” matches an ID found in the input SPK
– “-oflg” flag indicating that changes should be made directly in the input file; if not
specified, the program produces an output file with name that has “_out” appended to
the name of the input file
» In order for changes to be made in the input file it must be in the native binary
format; if it is not, bingo may be used to convert it to the native binary format
– A note stating which IDs were modified is put in the comment area
Non-Toolkit Applications 11
 N IF BSPIDMOD Example
Navigation and Ancillary Information Facility
Terminal Window
$ brief mer2_crus_sim_id.bsp
Brief. Version: 2.2.0 (SPICE Toolkit N0057)

Summary for: mer2_crus_sim_id.bsp

Body: -255
Start of Interval (ET) End of Interval (ET)
-------------------------------- --------------------------------
2003 JUL 09 00:15:00.000 2004 JAN 04 04:25:42.557

$ bspidmod -spki mer2_crus_sim_id.bsp -idi -255 -ido -254 -mod target -oflg
The file mer2_crus_sim_id.bsp has been updated.

$ brief mer2_crus_sim_id.bsp
Brief. Version: 2.2.0 (SPICE Toolkit N0057)

Summary for: mer2_crus_sim_id.bsp

Body: MER-2 (-254)

Start of Interval (ET) End of Interval (ET)
-------------------------------- --------------------------------
2003 JUL 09 00:15:00.000 2004 JAN 04 04:25:42.557

Non-Toolkit Applications 12
 N IF DSKMOD
Navigation and Ancillary Information Facility

• dskmod alters selected segment attributes in a binary

DSK file:
– body, surface, or reference frame ID
– data class ID
– coordinate system bounds
– coverage start and stop times

• dskmod can modify attributes “in place” in the input

DSK or can write output to a new DSK file
• dskmod puts into the comment area a warning note
stating which items in which segments of the file were
changed
• dskmod works with files in native binary format

Non-Toolkit Applications 13
 N IF DSKMOD Example
Navigation and Ancillary Information Facility
Terminal Window
$ dskbrief phobos_2014_09_22.bds
...
Summary for: phobos_2014_09_22.bds

Body: 401 (PHOBOS)

Surface: 401 (Name not available)
...

$ dskmod -dskin phobos_2014_09_22.bds -mod SURFACE -from 401 -to 1001 -overwrite

DSKMOD Program; Ver. 1.0, 16-NOV-2021; Toolkit Ver. N0067

DSK input file: phobos_2014_09_22.bds.

The descriptor field SURFACE has been changed from 401 to 1001 in DSK segment 1.
The file phobos_2014_09_22.bds has been modified and saved as phobos_2014_09_22.bds.

$ dskbrief phobos_2014_09_22.bds
...
Summary for: phobos_2014_09_22.bds

Body: 401 (PHOBOS)

Surface: 1001 (Name not available)

Non-Toolkit Applications 14
 N IF DAFMOD
Navigation and Ancillary Information Facility

• dafmod is a program for altering selected segment attributes in a binary

SPK, CK, or PCK file
– In an SPK file it can alter the target, center, or reference frame ID
– In a CK or binary PCK file it can alter the object or reference frame ID
• dafmod is an interactive program. When executed it prompts the user for
– name of the file to be modified
– “item” to be modified
» the set of items depends on the kernel type
– “old” item value
– “new” item value
• dafmod puts into the comment area a warning note stating which items
in which segments of the file were changed
• dafmod works only on files in native binary format
– bingo may be used to convert a non-native binary kernel to native binary format

Non-Toolkit Applications 15
 N IF DAFMOD Example: SPK
Navigation and Ancillary Information Facility
Terminal Window
$ brief mer2_crus_sim_id.bsp

Summary for: mer2_crus_sim_id.bsp

Body: -255
...

$ dafmod

DAFMOD -- Version 2.0.0, January 30, 2008 -- Toolkit Version N0063

(... banner providing usage instructions ...)
1) File : mer2_crus_sim_id.bsp
2) Item : target
3) Old Value: -255
4) New Value: -254
The file mer2_crus_sim_id.bsp has been updated.

$ brief mer2_crus_sim_id.bsp

Summary for: mer2_crus_sim_id.bsp

Body: MER-2 (-254)

Non-Toolkit Applications 16
 N IF DAFMOD Example: CK
Navigation and Ancillary Information Facility
Terminal Window
$ ckbrief -rel mro_sc_pred.bc mro.tsc naif0009.tls

Summary for: mro_sc_pred.bc

...
2009-AUG-15 23:31:02.347 2009-AUG-30 00:00:58.388 Y -74900

$ dafmod

DAFMOD -- Version 2.0.0, January 30, 2008 -- Toolkit Version N0063

(... banner providing usage instructions ...)
1) File : mro_sc_pred.bc
2) Item : frame
3) Old Value: -74900
4) New Value: 16
The file mro_sc_pred.bc has been updated.

$ ckbrief -rel mro_sc_pred.bc mro.tsc naif0009.tls

Summary for: mro_sc_pred.bc

...
2009-AUG-15 23:31:02.347 2009-AUG-30 00:00:58.388 Y MARSIAU

Non-Toolkit Applications 17
 N IF SPY
Navigation and Ancillary Information Facility

• Spy is a command line program for validating, inspecting, and

analyzing SPK files
• Spy can:
– check SPK files
» Validate SPK structure
» Check sampled data for bounds violations
» Locate invalid double precision numbers
– sample data from a set of loaded kernels
» Sample position, distance, velocity, derived velocity, speed, acceleration,
acceleration magnitude, osculating elements
– dump SPK file contents
» Data
» Summary information
» Comment area
» Bookkeeping information
– find some geometric events
» Distance: find times when specified constraints on observer-target distance
are met
» Elevation: find times when specified constraints on elevation of target in
specified frame are met

Non-Toolkit Applications 18
 N IF SPY: Selected Features
Navigation and Ancillary Information Facility

• Operating modes
– Interactive, batch, shell command line
• Auxiliary files
– Start-up file, command files, log file, save file
• Interactive command support
– Command history: recall, repetition, and command editing; editor selection;
command error detection; (limited) automatic command error correction
• User default support
– Set, show, reset default values
• Input options
– Define user symbols in commands
– Embed prompts in commands
• Output options
– Dump subsets of SPK data
– Show epoch and packet deltas in data dumps
– Set sample count or density
– Set time and number formats
– Set angular units
– Set coordinate system for sampled data
– Control error diagnostic verbosity
• Online help: command language summary
Non-Toolkit Applications 19
 N IF SPY Example: Dump SPK Data
Navigation and Ancillary Information Facility
Terminal Window
Spy > dump data spk testspk.bsp segment index 13 stop packet 2;

Dump of SPK File testspk.bsp

==================================================================
Segment number 13
------------------------------
Segment Summary:

Segment ID : SPY test segment: type 18 subtype 0

Target Body : Body 1800
Center Body : Body 1899
Reference Frame : Frame 17, ECLIPJ2000
SPK Data Type : Type 18
Description : Mex/Rosetta Hermite/Lagrange Interpolation
UTC Start Time : 2000 JAN 01 11:59:05.816
UTC Stop Time : 2000 JAN 01 12:32:15.816
ET Start Time : 2000-JAN-01 12:00:10.000000 (TDB)
ET Stop Time : 2000-JAN-01 12:33:20.000000 (TDB)
DAF Begin Address: 35287
DAF End Address : 37890
------------------------------
Segment Parameters:

Packet Count : 200

Directory Count : 1
Window Size - 1 : 6
Polynomial Degree: 13
Subtype : 0
Description : Hermite interpolation, 12-element packets
------------------------------
Time Tags and Packets:

State Components: Position X, Y, Z (km)

Velocity X, Y, Z (km/s)
Velocity X, Y, Z (km/s)
Accel. X, Y, Z (km/s^2)

1 2000-JAN-01 12:00:10.000000 (TDB) 1.00103333E+03 1.00203333E+03 1.00303333E+03 1.00403333E+03 1.00503333E+03 1.00603333E+03

1.00703333E+03 1.00803333E+03 1.00903333E+03 1.01003333E+03 1.01103333E+03 1.01203333E+03
2 2000-JAN-01 12:00:20.000000 (TDB) 2.00103333E+03 2.00203333E+03 2.00303333E+03 2.00403333E+03 2.00503333E+03 2.00603333E+03
2.00703333E+03 2.00803333E+03 2.00903333E+03 2.01003333E+03 2.01103333E+03 2.01203333E+03

Non-Toolkit Applications 20
 N IF SPY Example: Sample State Vectors
Navigation and Ancillary Information Facility
Terminal Window

Spy > load naif0009.tls;

Spy > load de421.bsp;
Spy > sample states
observer earth
target moon
start time 2008 oct 28 00:00:00.000000 TDB
stop time 2008 oct 28 00:01:00.000000 TDB
frame eclipJ2000
aberration correction none
coordinates latitudinal
time format numeric E23.16
number format F13.6
step size 10.0;

Sample STATE Results

==================================================================
Target : moon
Observer : earth
Frame : eclipJ2000
Aberration Correction: none
Coordinate System : latitudinal
------------------------------
0.2784240000000000E+09 395800.315095 -156.260092 -4.660937 0.035837 0.000145 -0.000005
0.2784240100000000E+09 395800.673459 -156.258644 -4.660983 0.035836 0.000145 -0.000005
0.2784240200000000E+09 395801.031820 -156.257196 -4.661028 0.035836 0.000145 -0.000005
0.2784240300000000E+09 395801.390177 -156.255748 -4.661074 0.035836 0.000145 -0.000005
0.2784240400000000E+09 395801.748532 -156.254300 -4.661120 0.035835 0.000145 -0.000005
0.2784240500000000E+09 395802.106883 -156.252851 -4.661165 0.035835 0.000145 -0.000005
0.2784240600000000E+09 395802.465231 -156.251403 -4.661211 0.035835 0.000145 -0.000005
==================================================================

Non-Toolkit Applications 21
 N IF SPY Example: Check SPK Integrity
Navigation and Ancillary Information Facility
Terminal Window

Spy > check integrity spk testspk.bsp;

Structure Inspection of SPK File testspk.bsp

==================================================================
Segment Number 11
------------------------------
Segment Summary:

Segment ID : SPY test segment: type 15

Target Body : Body 1501
Center Body : Body 1599
Reference Frame : Frame 17, ECLIPJ2000
SPK Data Type : Type 15
Description : Two-Body with J2 Precession
UTC Start Time : 2000 JAN 01 11:59:05.816
UTC Stop Time : 2000 JAN 01 12:32:15.816
ET Start Time : 2000-JAN-01 12:00:10.000000 (TDB)
ET Stop Time : 2000-JAN-01 12:33:20.000000 (TDB)
DAF Begin Address: 35259
DAF End Address : 35274
------------------------------
%% Error: Invalid Unit Periapsis Pole Vector

The periapsis pole vector should have unit length but in fact has length 4.58257569E+04.
------------------------------
One error diagnostic and no warnings generated for SPK file testspk.bsp
==================================================================

Non-Toolkit Applications 22
 N IF OEM2SPK and SPK2OEM
Navigation and Ancillary Information Facility

• oem2spk is a program for converting a CCSDS* “Orbit

Ephemeris Message” (OEM) text file to a Type 9 or 13
SPICE SPK file
– It is a command line program using a setup file to specify conversion
parameters
– It can process OEM versions 1 and 2
– It is primarily used for exchange of spacecraft trajectories between
space agencies
• spk2oem is a program for converting a Type 1, 9 or 13
SPICE SPK to an OEM file
– It is a command line program using a setup file to specify conversion
parameters
– It performs conversion in “data-driven” or “uniform sampling” mode
• For more details see the oem2spk and spk2oem user
guides
*CCSDS = Consultative Committee on Space Data Systems
Non-Toolkit Applications 23
 N IF PREDICKT
Navigation and Ancillary Information Facility

• prediCkt is a command line program for making CK

files from a set of orientation specification rules,
using schedules defining when these rules are to be
applied
– It requires orientation and schedule specification to be provided in a
setup file that follows the SPICE text kernel syntax
– It requires all supporting kernels -- SPK, PCK, etc -- to be loaded
using a meta kernel
– For more details see the “Making a CK Tutorial”

Non-Toolkit Applications 24
 N IF CKSLICER
Navigation and Ancillary Information Facility

• ckslicer is a command line program for subsetting a CK file

• ckslicer has the following usage
ckslicer -lsk <lsk_file_name>
-sclk <sclk_file_name(s)>
-inputck <ck_file_name>
-outputck <ck_file_name>
-id <naif_id>
-timetype <utc|sclk|ticks>
-start <start_time>
-stop <stop_time>
• ckslicer is useful in the situation when only a portion of a CK
covering a short interval of time is needed (for example when the
whole CK is not needed and it takes up a lot of space) or to cut
out parts from a few CKs with the intent to merge them together
(if reconstructed CKs from different sources have too much
overlap to simply “cat” them together)
• A note stating which subset was extracted is put into the
comment area of the output CK file
Non-Toolkit Applications 25
 N IF CKSLICER Example
Navigation and Ancillary Information Facility

Terminal Window
$ dir mgs_sc_ab1_v2.bc
-rw-rw-r-- 1 naifuser 195535872 Jul 17 1999 mgs_sc_ab1_v2.bc

$ ckslicer -lsk naif0007.tls -sclk MGS_SCLKSCET.00054.tsc -inputck

mgs_sc_ab1_v2.bc -outputck mgs_sc_ab1_970915.bc -id -94000 -timetype utc -start
1997-SEP-15 18:00 -stop 1997-SEP-15 21:00

CKSLICER: Version 1.0.1 July 17, 1999; Toolkit Version N0057

$ dir mgs_sc_ab1_970915.bc
-rw-rw-rw- 1 naifuser 480256 Apr 25 10:23 mgs_sc_ab1_970915.bc

$ ckbrief mgs_sc_ab1_970915.bc naif0007.tls MGS_SCLKSCET.00054.tsc -utc

CKBRIEF Version: 2.0.0, 2001-05-16. SPICE Toolkit Version: N0057.

Summary for: mgs_sc_ab1_970915.bc

Object: -94000
Interval Begin UTC Interval End UTC AV
------------------------ ------------------------ ---
1997-SEP-15 18:00:00.001 1997-SEP-15 21:00:00.000 Y

Non-Toolkit Applications 26
 N IF CKSPANIT
Navigation and Ancillary Information Facility

• ckspanit is a command line program for modifying interpolation

interval information in type 3 CK segments
– It can also convert a type 1 CK to a type 2 or 3 CK
• ckspanit is used when one is dealing with a type 3 CK containing
many small gaps within segments. It allows you to alter the CK in
such a way that SPICE will interpolate over those gaps
• ckspanit has the following usage
ckspanit -in inp_ck -out out_ck -tol threshold [-frm fk]
– “Threshold” is the longest time interval over which interpolation is to be
permitted in the output CK file
» Must be specified in SCLK ticks
• For example if 1 tick is 1/256 of a second and interpolation over 30 second intervals is
needed, “threshold” must be set to 256*30=7680
– “fk” is an optional FK file name, needed only if the base frame in the input CK
is not one of the frames built into the Toolkit
• See also the description of cksmrg
CAUTION: before running ckspanit, make sure that interpolation over larger
gaps is appropriate for the vehicle or structure you are dealing with. And
don’t forget to add appropriate comments to the newly created CK file.
Non-Toolkit Applications 27
 N IF CKSPANIT Example
Navigation and Ancillary Information Facility
Terminal Window
$ ckbrief m01_sc_2004-04-22.bc naif0007.tls ORB1_SCLKSCET.00078.tsc -utc -dump
CKBRIEF Version: 2.0.0, 2001-05-16. SPICE Toolkit Version: N0057.
Summary for: m01_sc_2004-04-22.bc
Segment No.: 1
Object: -53000
Interval Begin UTC Interval End UTC AV
------------------------ ------------------------ ---
2004-APR-22 00:00:05.455 2004-APR-22 18:53:29.054 Y
2004-APR-22 18:55:05.054 2004-APR-22 21:44:22.979 Y
2004-APR-22 21:51:34.974 2004-APR-22 23:59:58.919 Y

$ ckspanit -in m01_sc_2004-04-22.bc -out m01_sc_2004-04-22_sp.bc -tol 153600

$ ckbrief m01_sc_2004-04-22_sp.bc naif0007.tls ORB1_SCLKSCET.00078.tsc -utc -dump

CKBRIEF Version: 2.0.0, 2001-05-16. SPICE Toolkit Version: N0057.
Summary for: m01_sc_2004-04-22_sp.bc
Segment No.: 1
Object: -53000
Interval Begin UTC Interval End UTC AV
------------------------ ------------------------ ---
2004-APR-22 00:00:05.455 2004-APR-22 23:59:58.919 Y

Non-Toolkit Applications 28
 N IF CKSMRG
Navigation and Ancillary Information Facility
• cksmrg is a command line program that merges data from Type 3
CK segments provided in a single CK file, having the same ID and
base frame
• cksmrg is used for eliminating gaps between segments (that
cannot be removed by ckspanit) and removing duplicate data
points contained in different segments
• cksmrg has the following usage
cksmrg -k|-kernels <meta kernel name|kernel file names>
-i|-input <input ck file name>
-o|-output <output ck file name>
-s|-segid <output ck segment id string>
-f|-fileid <output ck file id string>
-b|-body <body id|name>
-r|-reference <reference id|name>
-a|-av <drop|keep|make|makeavrg>
-t|-tolerance <tolerance (number units)>
[-c|-correction <time delta|cor. table file>]

CAUTION: cksmrg should not be used to merge CK segments from

different sources (e.g. predicted and reconstructed), nor should it
Non-Toolkit Applications
be used to merge overlapping predict CK segments
29
 N IF CKSMRG Example
Navigation and Ancillary Information Facility
Terminal Window
$ ckbrief m01.bc naif0007.tls ORB1_SCLKSCET.00078.tsc -utc -rel
. . .
Object: -53000
Interval Begin UTC Interval End UTC AV Relative to FRAME
------------------------ ------------------------ --- -----------------
2004-APR-20 00:00:03.622 2004-APR-20 23:59:56.288 Y MARSIAU
2004-APR-21 00:00:02.288 2004-APR-21 23:59:59.455 Y MARSIAU

$ cksmrg -k naif0007.tls ORB1_SCLKSCET.00078.tsc -i m01.bc -o m01s.bc -s

'CKSMRGed' -f 'CKSMRGed' -b -53000 -r 'MARSIAU' -a keep -t 60 seconds
. . .
(cksmrg displays quite a lot of diagnostics and progress information)
. . .

$ ckbrief m01s.bc naif0007.tls ORB1_SCLKSCET.00078.tsc -utc -rel

. . .
Object: -53000
Interval Begin UTC Interval End UTC AV Relative to FRAME
------------------------ ------------------------ --- -----------------
2004-APR-20 00:00:03.622 2004-APR-21 23:59:59.455 Y MARSIAU

Non-Toolkit Applications 30
 N IF MAKCLK
Navigation and Ancillary Information Facility

• makclk is a program for converting a SCLKSCET file to an SCLK kernel

– SCLKSCET (a.k.a. SCLKvSCET) is a time correlation file used by most JPL
missions
– It is an ASCII text file providing piece-wise linear clock correlation function as
an array of triplets consisting of the reference on-board time, the reference
UTC time, and the clock rate
– NAIF found that in many cases it is much easier to write an application to first
make a SCLKSCET file and then convert it to an SCLK kernel using makclk
than to write an application to make an SCLK kernel from “scratch”
• makclk is an interactive program prompting for a single input - the name
of the setup file
• The setup file uses KEYWORD=VALUE assignments to specify input files
(SCLKSCET, template SCLK, and LSK), output files (SCLK kernel and
log), and control parameters (spacecraft ID, partition tolerance, time
filtering flag, and rate adjustment flag)
• The makclk User’s Guide provides detailed information about the setup
file parameters and the SCLKSCET file format and contents.

Non-Toolkit Applications 31
 N IF MAKCLK Example
Navigation and Ancillary Information Facility
Terminal Window
$ more makclk.setup
SCLKSCET_FILE = flc_sclkscet.00007
OLD_SCLK_KERNEL = flc_template.tsc
FILE_NAME = flc_sclkscet.00007.tsc
NAIF_SPACECRAFT_ID = -77
LEAPSECONDS_FILE = naif0009.tls
PARTITION_TOLERANCE = 10
LOG_FILE = flc_sclkscet.00007.log

$ more flc_sclkscet.00007
(... SCLKSCET SFDU header ...)
CCSD3RE00000$$scet$$NJPL3IS00613$$data$$
*____SCLK0_____ ________SCET0________ _DUT__ __SCLKRATE__
0.000 2000-001T11:58:55.816 64.184 1.000000000
189345665.000 2006-001T00:00:00.816 64.184 0.000010000
189345666.000 2006-001T00:00:00.817 65.184 1.000000000
268620868.000 2008-188T12:53:23.211 65.184 0.999998631
276588129.000 2008-280T18:00:53.314 65.184 0.999999788
281552200.000 2008-338T04:55:23.270 65.184 1.000000029
284040077.000 2009-001T00:00:00.341 65.184 0.000010000
284040078.000 2009-001T00:00:00.342 66.184 1.000000029
287261113.000 2009-038T06:43:55.535 66.184 1.000000131
291848718.000 2009-091T09:04:01.136 66.184 1.000000166
CCSD3RE00000$$data$$CCSD3RE00000$$sclk$$

Non-Toolkit Applications 32
 N IF MAKCLK Example (continued)
Navigation and Ancillary Information Facility
Terminal Window
$ more flc_template.tsc
KPL/SCLK
\begindata
SCLK_KERNEL_ID = ( @2009-04-07/12:00 )
SCLK_DATA_TYPE_77 = ( 1 )
SCLK01_TIME_SYSTEM_77 = ( 2 )
SCLK01_N_FIELDS_77 = ( 2 )
SCLK01_MODULI_77 = ( 4294967296 256 )
SCLK01_OFFSETS_77 = ( 0 0 )
SCLK01_OUTPUT_DELIM_77 = ( 1 )
SCLK_PARTITION_START_77 = ( 0.0000000000000E+00 )
SCLK_PARTITION_END_77 = ( 1.0995116277750E+12 )
SCLK01_COEFFICIENTS_77 = ( 0.E+00 0.E+00 1.E+00 )
\begintext

$ makclk
.....
Enter the name of the command file

> flc_sclkscet.00007.setup

flc_sclkscet.00007.tsc created.

Non-Toolkit Applications 33
 N IF ORBNUM
Navigation and Ancillary Information Facility
• orbnum is a program for generating a SPICE orbit number file containing
orbit numbers and corresponding orbit start/stop times, along with some
additional derived quantities (orbital elements and coordinates of sub-
spacecraft and sub-solar points)
– The orbit number increment can be specified as occurring at one of these events:
periapsis or apoapsis, ascending or descending equatorial node crossing, min or max
value for the s/c position’s Z-coordinate, or min or max value of the s/c’s latitude
• orbnum is a command line program with the following usage
orbnum -pref pref_file -num init_orbit -file orbnum_file –d –v –audit –tdb –verbose

optional
– “pref_file” is a preferences file using text kernel syntax, specifying setup parameters
along with the kernels containing data to be used to search for orbit start and stop events,
spacecraft trajectory SPKs, center body PCK, spacecraft SCLK, etc.
– “init_orbit” is the number to be assigned to the first orbit determined using the kernels
provided; subsequent orbits are assigned by incrementing “init_orbit” by 1
– “orbnum_file” is the name of the orbit number file to be created

• An orbnum file is not considered a SPICE kernel

– It’s just a convenient, derived product that NAIF offers to make for orbital missions that
wish to have it
Non-Toolkit Applications 34
 N IF ORBNUM Example
Navigation and Ancillary Information Facility
Terminal Window
$ more mex_orbnum.setup
\begindata
TARGET = -41
OBSERVER = 499
EVENT_DETECTION_FRAME = 'MARSIAU'
EVENT_DETECTION_KEY = 'PERI'
ELEMENTS_INERTIAL_FRAME = 'MARSIAU'
ABERRATION_CORRECTION = 'NONE'
ORBIT_PARAMS = ( 'Sub Sol Lon', 'Sub Sol Lat', .. )
TEXT_KERNELS = ( 'de-245-masses.tpc', 'NAIF0007.TLS', 'mex_030722_step.tsc', ..)
BIN_KERNELS = ( 'ORMF_PSTPIX_DB_00001.bsp', 'DE405S.BSP')
SAFETY_MARGIN = 0.5
STEP_SIZE_TDB = 'DEFAULT'
\begintext

$ orbnum -pref mex_orbnum.setup -num 1 -file mex_orbnum.orb

....Loading Kernels

Start UTC (RET for default = 2004 JAN 13 15:54:19.8):<RETURN>

End UTC (RET for default = 2004 AUG 05 02:10:24.8):<RETURN>

Working, please wait.

Program Finished!

Non-Toolkit Applications 35
 N IF OPTIKS
Navigation and Ancillary Information Facility

• optiks is a command line program that generates information about

instrument fields of view (FOV) from parameters present in IK and
FK files
– FOVs must be defined using the keywords required by the GETFOV routine
• optiks is used in one of two ways
optiks [options]... kernel ...
optiks [options]... meta-kernel ...

• optiks uses a set of SPICE kernels specified on the command line;

one or more of these kernels may be a meta-kernel
• The output data are organized in three tables
– The first table lists the angular extents (size) of circular, elliptical, and
rectangular FOVs. Using command line options “-units” and “-half” the user can
select the unit of measure for the angular measurements, and whether half or
full FOV angular extents are listed.
– The second table contains FOV boresights in a user specified frame at a
particular epoch, specified using the “-epoch” option
– The third table shows FOV boundary vectors and boresights as returned from
the GETFOV API, or unitized and rotated into a user-specified frame at a
particular epoch
Non-Toolkit Applications 36
 N IF OPTIKS Example
Navigation and Ancillary Information Facility
Terminal Window
$ optiks -frame CASSINI_SC_COORD cas_iss_v09.ti cas_v37.tf naif0007.tls
cas00084.tsc
. . .
Kernels Loaded:
. . .
FOV full-angular extents computed in RADIANS

Field of View Shape Length Width

------------- ----- ------ -----
CASSINI_ISS_NAC RECTANGULAR +0.006108652382 +0.006108652382
CASSINI_ISS_NAC_RAD CIRCULAR +3.141592653590 +3.141592653590
CASSINI_ISS_WAC RECTANGULAR +0.060737457969 +0.060737457969
CASSINI_ISS_WAC_RAD CIRCULAR +3.141592653590 +3.141592653590

FOV boresights computed at epoch 2001-JAN-01 12:00

FOV boresights computed in frame CASSINI_SC_COORD
Field of View Boresight Vector
------------- ----------------
CASSINI_ISS_NAC ( +0.000575958621, -0.999999819520, -0.000170972424 )
CASSINI_ISS_NAC_RAD ( +1.000000000000, -0.000000000000, +0.000000000000 )
CASSINI_ISS_WAC ( +0.001218344236, -0.999999225446, +0.000254451360 )
CASSINI_ISS_WAC_RAD ( +1.000000000000, -0.000000000000, +0.000000000000 )

Non-Toolkit Applications 37
 N IF ARCHTYPE
Navigation and Ancillary Information Facility

• archtype is a program that displays the file architecture and type

of a SPICE kernel; it is useful for scripting applications
– To identify the architecture and type archtype uses the same mechanism as
the FURNSH routine
• archtype has a simple command line interface and requires only
one argument -- the name of a kernel file:
archtype kernel_name
• archtype prints architecture and type to standard output as two
space delimited acronyms
– Architecture can be:
» ‘DAF’ or ‘DAS’ for binary kernels
» ‘KPL’ for text kernels
– Type can be ‘SPK’, ‘PCK’, ‘IK’, ‘CK’, ‘EK’, ‘LSK’, ‘SCLK’, ‘FK’, ‘MK’, ‘DSK’
• If architecture and/or type cannot be determined, the program
displays ‘UNK’
• In order for text kernels to be recognized, the first few characters
of the file must contain ‘KPL/<type>’ (i.e. ‘KPL/IK’, ‘KPL/FK’, etc.)
Non-Toolkit Applications 38
 N IF ARCHTYPE Examples
Navigation and Ancillary Information Facility
Terminal Window
$ archtype 020514_SE_SAT105.bsp
DAF SPK

$ archtype 04135_04171pc_psiv2.bc
DAF CK

$ archtype cas00084.tsc
KPL SCLK

$ archtype cas_v37.tf
KPL FK

$ archtype cpck05Mar2004.tpc
KPL PCK

$ archtype naif0008.tls
KPL LSK

$ archtype .cshrc
UNK UNK

Non-Toolkit Applications 39
 N IF BFF
Navigation and Ancillary Information Facility

• bff is a program that displays the binary file format of one or a few
SPICE kernels
• bff has a simple command line interface requiring kernel names to
be listed on the command line:
bff kernel_name [kernel_name ...]
• bff prints the binary file format string (‘BIG-IEEE’ or ‘LTL-IEEE’) to
standard output
– When run on a single kernel, it prints only the format string
– When run on more than one kernel, it prints the format string followed by the
file name on a separate line for each file
• If an input file is not a binary kernel, the program displays the
format string ‘N/A’
• If the binary file format cannot be determined (for DAS files
produced by applications linked to SPICE Toolkit N0051, April
2000 or earlier), the program displays the format string ‘UNK’

Non-Toolkit Applications 40
 N IF BFF Examples
Navigation and Ancillary Information Facility
Terminal Window
$ bff mer2_surf_rover.bsp
BIG-IEEE

$ bff ./*.bc ./*.bsp ./*.tf ./*.xsp

BIG-IEEE ./MRO_PHX_EDL_07260_PASS1_sc_20070917181502.bc
LTL-IEEE ./070416BP_IRRE_00256_14363.bsp
LTL-IEEE ./mars_north.bsp
BIG-IEEE ./mer2_surf_rover.bsp
LTL-IEEE ./sb406-20pb.bsp
LTL-IEEE ./zero_offset.bsp
N/A ./vo.tf
N/A ./mgn06127.xsp

Non-Toolkit Applications 41
 N IF BINGO
Navigation and Ancillary Information Facility

• bingo is a program that converts:

– binary SPICE kernels between IEEE big endian and little endian formats
– text format SPICE kernels between DOS and UNIX text formats
• bingo has a simple command line interface:
bingo [option] input_kernel output_kernel
– “option” is a flag specifying the conversion direction: ‘-ieee2pc’ or ‘-pc2ieee’ for binary
kernels and ‘-unix2dos’ or ‘-dos2unix’ for text format kernels
– “input_kernel” is the input kernel file name
– “output_kernel” is the output kernel file name. If the output file already exists, the
program overwrites it.
• The conversion direction flag does not need to be specified for
DAF-based binary file conversions (SPK, CK, binary PCK) and
post-N0051 DAS-based binary file conversions (EK, DBK, DSK)
– The program automatically determines the input file format and performs conversion to
the other format
• The conversion direction flag must be specified for pre-N0051
DAS-based binary file conversions, and for text file conversions

Non-Toolkit Applications 42
 N IF BINGO Examples
Navigation and Ancillary Information Facility
Terminal Window
--- DAF-based binary kernel conversions:

$ bingo de405s_ieee.bsp de405s_pc.bsp

$ bingo de405s_pc.bsp de405s_ieee.bsp

--- Modern DAS-based binary kernel conversions:

$ bingo 10A_ieee.bdb 10A_pc.bdb

$ bingo 10A_pc.bdb 10A_ieee.bdb

--- Text kernel conversions:

$ bingo -unix2dos naif0008_unix.tls naif0008_dos.tls

$ bingo -dos2unix naif0008_dos.tls naif0008_unix.tls

Non-Toolkit Applications 43
N IF
Navigation and Ancillary Information Facility

Exception Handling

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• What Exceptions Are

• Language Dependencies
• C and Fortran Error Handling Features
• Error Messages
• Error Handling Actions
• Error Device
• Customize Error Handling
• Get Error Status
• Signal Errors
• Icy Error Handling
• Mice Error Handling
• Recommendations

Exception Handling 2
 N IF Exceptions Are… - 1
Navigation and Ancillary Information Facility

• Run-time error conditions such as:

– Files
» Required files not loaded
» Gaps in data
» Corrupted or malformed files (e.g. ftp’d in wrong mode)
– Invalid subroutine/function arguments
» String values unrecognized
» Numeric values out of range
» Data type/dimension mismatch
– Arithmetic errors
» Divide by zero, taking the square root of a negative number
– Environment problems
» Insufficient disk space for output files
» Lack of required read/write permission/privileges

Exception Handling 3
 N IF Exceptions Are… - 2
Navigation and Ancillary Information Facility

• Valid but unusual conditions, such as:

» Normalize the zero vector
» Find the rotation axis of the identity matrix
» Find the boresight intercept lat/lon for a non-intercept case
» Find a substring where the end index precedes the start index
– Such cases are normally not SPICE “Error Conditions”
– Typically must be handled by a logical branch
• Errors found by analysis tools, such as:
» Invalid SQL query
» Invalid string representing a number
– Such cases are normally not SPICE “Error Conditions”
– However, if a SPICE parsing routine failed because it couldn’t open
a scratch file, that would be an “error condition”

Exception Handling 4
 N IF SPICE “Errors”
Navigation and Ancillary Information Facility

• Most “errors” made while using SPICE result from

a mistake in how you are trying to use SPICE
code, or in how you are trying to use SPICE files
– It’s rare that a SPICE user finds an error within SPICE Toolkit
code
• The SPICE “exception handling subsystem” helps
detect user’s errors
• All “errors” detected by SPICE result in a SPICE
error message
– Such errors will not make your program crash
• A program crash indicates an error in your own
code, a corrupted SPICE kernel, or (rarely) a
SPICE bug

Exception Handling 5
 N IF Language Dependencies
Navigation and Ancillary Information Facility

• SPICELIB and CSPICE provide essentially identical error

handling capabilities.
• Icy and Mice provide similar error handling functionality;
this functionality is quite different from that of CSPICE.
– These systems do rely on CSPICE for most error detection.
– Icy and Mice provide no API for customizing underlying CSPICE error
handling behavior.
– Short, long, and traceback error messages are merged into a single,
parsable, message.
– Use IDL or MATLAB features to customize error handling…
» to prevent your program from stopping.
» to capture SPICE error messages.
• Most of this tutorial deals with SPICELIB and CSPICE error
handling.
– There is a bit on Icy and Mice near the end.

Exception Handling 6
 N IF Fortran and C Error Handling Features - 1
Navigation and Ancillary Information Facility

• Error handling in SPICE: safety first

– Trap errors where they occur; don’t let them propagate.
» Don’t let errors “fall through” to the operating system.
– Supply meaningful diagnostic messages.
» Incorporate relevant run-time data.
» Supply context in human-readable form.
– Don’t depend on callers to handle errors.
» Normally, “error flags” are not returned to callers.
– Stop unless told not to.
» Don’t try to continue by making “smart guesses.”
• Subroutine interface for error handling
– Interface routines called within SPICE may be called by users’
application programs

Exception Handling 7
 N IF Fortran and C Error Handling Features - 2
Navigation and Ancillary Information Facility

• Signal errors
– Create descriptive messages when and where an error is detected
» Short message, long message, (explanation), traceback
– “Signal” the error: set error status, output messages
» By default, CSPICE error output goes to stdout (not stderr)
• Retrieve error information
– Get status and error messages via subroutine calls
• Customize error response---actions taken when an error
occurs.
– Set error handling mode (“action”)
– Set error output device
– Set message selection
• Inhibit tracing
– To improve run-time performance (only for thoroughly debugged code)

Exception Handling 8
 N IF Error Messages
Navigation and Ancillary Information Facility

• Short message
– Up to 25 characters.
– Can easily be compared with expected value.
» Example: SPICE(FILEOPENFAILED).
• Long message
– Up to 1840 characters.
– Can contain values supplied at run time.
» Example: 'The file <sat077.bsp> was not found.'
• Traceback
– Shows call tree above routine where error was signaled.
» Not dependent on system tracing capability.
» Don’t need a “crash” to obtain a traceback.

Exception Handling 9
 N IF Error Handling Actions - 1
Navigation and Ancillary Information Facility

• ABORT
– Designed for safety.
» Output messages and traceback to your screen or stdout.
» Stop program; return status code if possible.
• RETURN
– For use in programs that must keep running.
– Attempts to return control to the calling application.
– Preserves error information so calling application can respond.
» Output messages to current error device.
» Set error status to “true”: FAILED() will return “true.”
» Set “return” status to “true”: RETURN() will return “true.”
» Most SPICE routines will return on entry. Very simple
routines will generally execute anyway.

continued on next page

Exception Handling 10
 N IF Error Handling Actions - 2
Navigation and Ancillary Information Facility

» Capture traceback at point where error was signaled.

» Inhibit error message writing and error signaling.
» Must call RESET to resume normal error handling.

Exception Handling 11
 N IF Error Device
Navigation and Ancillary Information Facility

• Destination of error messages

– Screen/stdout (default)
– Designated file
» Error diagnostics are appended to the file as errors are
encountered.
– “NULL” --- suppress output
» When the NULL device is specified, error messages can
still be retrieved using API calls.
• Limitations
– In C, cannot send messages to stderr.
– In C, writing to a file opened by means other than calling
errdev_c is possible only if CSPICE routines were used to open
the file.
» These limitations may be removed in a later version of
CSPICE.

Exception Handling 12
 N IF Customize Error Handling - 1
Navigation and Ancillary Information Facility

• Set error action

– CALL ERRACT ( 'SET', 'RETURN' )
– erract_c ( "set", LEN, "return" );
» Length argument is ignored when action is “set”; when
action is “get”, LEN should be set to the available room in
the output string, for example:
» erract_c ( "get", ACTLEN, action );
• Set error device
– CALL ERRDEV ( 'SET', 'errlog.txt' )
– errdev_c ( "set", LEN, "errlog.txt" );
• Select error messages
– CALL ERRPRT ( 'SET', 'NONE, SHORT, TRACEBACK' )
» If tracing is disabled (see next page), selecting
TRACEBACK has no effect.
– errprt_c ( "set", LEN, "none, short, traceback" );
Exception Handling 13
 N IF Customize Error Handling - 2
Navigation and Ancillary Information Facility

• Disable tracing
– Normally done to speed up execution by a few percent
– Benefit is highly dependent on application
– NAIF normally recommends users not turn tracing off
– Use TRCOFF:
» CALL TRCOFF or trcoff_c();
• Do this at the beginning of your program.
• Once disabled you cannot re-enable tracing during a program run.

Exception Handling 14
 N IF Get Error Status - 1
Navigation and Ancillary Information Facility

• Use FAILED to determine whether an error has

been signaled
– IF ( FAILED() ) THEN …
– if ( failed_c() ) { …
• Use FAILED after calling one or more SPICE
routines in a sequence
– Normally, it’s safe to call a series of SPICE routines without
testing FAILED after each call
• Use GETMSG to retrieve short or long error
messages
– CALL GETMSG ( 'SHORT', SMSG )
– getmsg_c ( "short", LEN, smsg );

Exception Handling 15
 N IF Get Error Status - 2
Navigation and Ancillary Information Facility

• Use QCKTRC or TRCDEP and TRCNAM to retrieve

traceback message
• Test value of RETURN() to determine whether
routines should return on entry
– Only relevant if user code is designed to support RETURN
mode
• Handle error condition, then reset error status:
– CALL RESET
– reset_c();
– In Icy-based applications you only need handle the error
condition; a reset is automatically performed by Icy

Exception Handling 16
 N IF Signal Errors - 1
Navigation and Ancillary Information Facility

• Create long error message

– Up to 1840 characters
– Use SETMSG
» CALL SETMSG ( 'File <#> was not found.' )
» setmsg_c ( "File <#> was not found." );
• Substitute string, integer, or d.p. values at run time
– Use ERRCH
» CALL ERRCH ( '#', 'cassini.bsp' )
» errch_c ( "#", "cassini.bsp" );
– Also can use ERRINT, ERRDP
– In Fortran, can refer to files by logical unit numbers: ERRFNM

Exception Handling 17
 N IF Signal Errors - 2
Navigation and Ancillary Information Facility

• Signal error
– Use SIGERR to signal error. Supply short error message as
input to SIGERR.
» CALL SIGERR ( 'FILE OPEN FAILED ' )
» sigerr_c ( "FILE OPEN FAILED" );
– “Signaling” error causes SPICE error response to occur
» Output messages, if enabled
» Set error status
» Set return status, if error action is RETURN
» Inhibit further error signaling if in RETURN mode
» Stop program if in abort mode
• Reset error status after handling error
– CALL RESET()
– reset_c()

Exception Handling 18
 N IF Icy Error Handling
Navigation and Ancillary Information Facility

• Error action:
– By default, a SPICE error signal stops execution of IDL scripts; a SPICE error
message is displayed; control returns to the execution level (normally the command
prompt).
– Icy sets the CSPICE shared object library’s error handling system to RETURN mode.
No other modes are used.
» The CSPICE error state is reset after detecting an error.
– Use the IDL CATCH feature to respond to error condition.
• Error status
– Value of !error_state.name
» ICY_M_BAD_IDL_ARGS - indicates invalid argument list.
» ICY_M_SPICE_ERROR - indicates occurrence of a SPICE error.
• Error message
– CSPICE short, long, and traceback error messages are merged into a single,
parsable, message.
» The merged error message is contained in the variable !error_state.msg.
» Example:
CSPICE_ET2UTC: SPICE(MISSINGTIMEINFO): [et2utc->ET2UTC->UNITIM]
The following, needed to convert between the
uniform time scales, could not be found in the
kernel pool: DELTET/DELTA_T_A, DELTET/K,
DELTET/EB, DELTET/M. Your program may have failed to load…

Exception Handling 19
 N IF Mice Error Handling
Navigation and Ancillary Information Facility
• Error action
– By default, a SPICE error signal stops execution of MATLAB scripts; a SPICE
error message is displayed; control returns to the execution level.
– Mice sets the CSPICE shared object library’s error handling system to RETURN
mode. No other modes are used.
» The CSPICE error state is reset after detecting an error.
– Use the MATLAB try/catch construct to respond to error condition.
• Error message
– CSPICE short, long, and traceback error messages are merged into a single,
parsable, message.
» Example:
??? SPICE(MISSINGTIMEINFO): [et2utc->ET2UTC->UNITIM]
The following, needed to convert between the
uniform time scales, could not be found in the
kernel pool: DELTET/DELTA_T_A, DELTET/K,
DELTET/EB, DELTET/M. Your program may have failed to load…

• Use the MATLAB function lasterror to retrieve SPICE error

diagnostics. When a SPICE error occurs:
– the “message” field of the structure returned by lasterror contains the SPICE
error message.
– the “stack” field of this structure refers to the location in the m-file from which
the Mice wrapper was called (and so is generally not useful).
– the “identifier” field of this structure currently is not set.
Exception Handling 20
 N IF Recommendations
Navigation and Ancillary Information Facility

• For easier problem solving

– Leave tracing enabled when debugging.
– Always test FAILED after a sequence of one or more
consecutive calls to SPICE routines.
– Don’t throw away error output. It may be the only useful clue as
to what’s going wrong.
» Programs that must suppress SPICE error output should
trap it and provide a means for retrieving it.
• Test FAILED to see whether an error occurred.
• Use GETMSG to retrieve error messages
• Use RESET to clear the error condition
– Use SPICE error handling in your own code where appropriate.
– When reporting errors to NAIF, have SPICE error message
output available
» Note whether error output is actually from SPICE routines,
from non-SPICE code, or was generated at the system level.

Exception Handling 21
N IF
Navigation and Ancillary Information Facility

SPICE Toolkit
Common Problems

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• Prevention
• Useful Documentation
• Reporting a Problem to NAIF

Common Problems 2
 N IF Prevention - 1
Navigation and Ancillary Information Facility

• Use a Toolkit obtained directly from NAIF and intended for your
specific environment (platform/OS/compiler/compiler options)
– Be extra careful about 32-bit versus 64-bit hardware
• Use a current Toolkit
– Newer Toolkits may have bug fixes and new features you need
» Toolkits are always backwards compatible, so you should have no problem re-
linking your “old” application to the latest Toolkit
• Read the pertinent documentation
– Tutorials, module headers, Required Reading technical reference documents,
comments inside kernels

• Use the correct kernels

– Often, but not always, this means the latest version
– Verify that contents, time coverage (if applicable) and intended use are suitable for
your work
• If you are using a Fortran Toolkit, be sure your text kernels all
use the line termination appropriate for your platform.
– Unix/Linux/OSX use <LF>; PC/Windows uses <CR><LF>
– Using the BINGO utility from the NAIF website to make the change is one solution
– Be sure the last line in your text kernel ends with an end of line termination
Common Problems continued on next page 3
 N IF Prevention - 2
Navigation and Ancillary Information Facility

• Avoid common implementation problems

– Verify use of the correct time system for your need
» e.g., TDB (also called ET), UTC, or SCLK?
– When using SCLK time tags, be sure to form your SCLK string to match
the specification within the SCLK kernel
» Make sure the fractional part is in the form that is expected
– Verify that correct reference frames are used
» e.g., MOON_PA versus MOON_ME versus IAU_MOON?
» e.g. IAU_Mars versus MARSIAU? (these are VERY different frames)
– Check definitions of geometric quantities
» e.g. Planetocentric vs. planetographic vs planetodetic coordinates
» Oblate, spherical or DSK body shape
– Check aberration corrections
» Converged Newtonian light time + stellar aberration, light time +
stellar aberration, light time only, or none?
» Target orientation corrected for light time?
– Don’t confuse an instrument reference frame ID with the ID of the
instrument itself (the object ID)

Common Problems 4
 N IF Useful Documentation
Navigation and Ancillary Information Facility

• NAIF has compiled a list of common problems, probable causes,

and solutions:
– Refer to …/doc/html/req/problems.html or …doc/req/PROBLEMS.REQ, both of
which are provided in each Toolkit package. Or, access the HTML document
corresponding to the supported language at:
» https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/problems.html
» https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/problems.html
» https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/IDL/req/problems.html
» https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/MATLAB/req/problems.html
• Some on-line tutorials (e.g. SPK and CK) include a common
problems section near the end of the tutorial
• It may be useful to read these documents BEFORE embarking on
extensive SPICE-based programming projects, since some
problems are best solved early in the software development cycle

Common Problems 5
 N IF Reporting a Problem to NAIF
Navigation and Ancillary Information Facility

• If you need help troubleshooting a programming or usage

problem, you can send email to NAIF. Try to include these
items in your email message:
– The SPICE or operating system diagnostic messages written to the
screen or to log files
– The name and version of the operating system you’re using
– The name and version of the compiler or programming environment
(gcc, gfortran, ifort, clang, IDL, Matlab, etc.)
– The Toolkit version you’re using, e.g. N0067 (also called N67)
– Names of the kernel files being used
» Include any meta-kernel you’re using
» You may need to provide the kernels themselves if these are not
available to NAIF
– Your inputs to the SPICE modules that signaled the error
– If possible, a code fragment from where the error seems to occur
• Send the email to only one person on the NAIF team
– It will get routed to the best person to provide an answer
– Contact information: https://naif.jpl.nasa.gov/naif/contactinfo.html

Common Problems 6
N IF
Navigation and Ancillary Information Facility

Obtaining SPICE Products

Available from the
NAIF and Horizons Servers
Emphasis on Kernels

April 2023
 N IF Overview
Navigation and Ancillary Information Facility

• Many SPICE products are available from the NAIF

server
– These are mostly SPICE products produced at JPL
– Access is available using the https protocol
– See the next page for URLs

• SPICE products made by other organizations are

controlled by those organizations
– Some may be available from the NAIF server
– Some may be available at other public servers, or on restricted
servers, or not at all
» The International Planetary Data Alliance (IPDA) is working
towards making large amounts of archived planetary data,
including SPICE, universally available through “all” agency
archives
– Unfortunately there is no simple rule set to describe what may
be found where
– As a general rule, NAIF has no cognizance of these products
NAIF Server 2
 N IF NAIF Server URLs
Navigation and Ancillary Information Facility

• NAIF home page

https://naif.jpl.nasa.gov
• Here you may access all official SPICE products produced by NAIF
- kernels (generic, mission operations, and PDS archived ancillary data)
- software (Toolkits and individual utility programs)
- documents
- tutorials
- programming lessons
- problem solving tips
- rules about using SPICE
- links to useful resources
- access to the WebGeocalc tool
- access to the Cosmographia visualization program

• SPICE announcements (by NAIF)

https://naif.jpl.nasa.gov/mailman/listinfo/spice_announce
For use by NAIF staff in making assorted announcements.

• SPICE discussion (by anyone)

https://naif.jpl.nasa.gov/mailman/listinfo/spice_discussion
For use by SPICE users who wish to communicate with other SPICE users
(Don’t use this if you have questions for NAIF staff)
NAIF Server 3
 N IF Getting SPICE Kernels
Navigation and Ancillary Information Facility

• The remaining charts discuss where to find the various

categories of SPICE kernel files
– Operational flight project kernels
» For active flight projects, mostly those at JPL
– PDS archived kernels
» Those that have been delivered to and reviewed and accepted by the
NAIF Node of NASA’s Planetary Data System as part of a formal
archive compliant with PDS3 or PDS4 standards
» These are the most easily used, due to the existence of furnsh
kernels (meta-kernels)!
» These cover from launch to typically 6-to-9 months behind current
time
– Generic kernels
» Not tied to any one specific mission
» Used by many flight projects and other endeavors
» Some of these are also available in the other two categories
– How to generate SPKs for comets and asteroids

NAIF Server 4
 N IF Getting Operational Project Kernels - 1
Navigation and Ancillary Information Facility

1 – Select Data

2 – Select OPS Data

3 - Select the mission

class of interest

4 – Select mission or kernel type

4a - Select the project name to get access to the 4b - Select the kernel type to get access to all kernels of
kernels folder for that project with sub-folders for all -or- that type for that project. The number tells how many
kernel types (see next page) kernels of that type are available. (see next page)

NAIF Server 5
 N IF Getting Operational Project Kernels - 2
Navigation and Ancillary Information Facility
Access to all kernels for Access to kernels of the selected
the named project type for the named project

SPK file (binary)

Detached file label

(plain text)

...

Then change to the folder containing Description of file

the kind of kernels of interest to you, naming scheme
such as SPK.

NAIF Server 6
 N IF Getting PDS Archived Kernels - 1
Navigation and Ancillary Information Facility

• The best method for obtaining PDS archived kernels

is directly from the NAIF server.
– Complete SPICE data sets exist on the NAIF server fully
expanded–not bundled in a Zip or tar file
– Unless you have reason to do otherwise, download the entire
archival data set using the "Archive Link"
» That way you’ll get all the latest data, the associated “furnsh
kernels”, and the best documentation.
– If the data set is large and you need only a portion of it based on
start/stop time, use the “subsetter” link to obtain the smaller
amount of data needed.

• Pictorial examples are shown on the next few pages.

NAIF Server 7
 N IF Getting PDS Archived Kernels - 2
Navigation and Ancillary Information Facility

1 – Select Data

2 – Select PDS Data

3 - Select PDS archives

4 – Copy or select archive link

4a – Copy link to get the whole archive using “wget” 4b - Select archive link to browse archive directory tree
https://naif.jpl.nasa.gov/pub/naif/pds/ -or- and access individual kernels, meta-kernels, and
data/co-s_j_e_v-spice-6-v1.0/cosp_1000 archive documentation (see next pages)

NAIF Server 8
 N IF Getting Archived Kernels – PDS3
Navigation and Ancillary Information Facility
Top level directory on a
PDS3 SPICE archive Select “aareadme.htm”
to access PDS3 archive
description document

Select a
kernel-type
folder to
Select “data” to access
kernel-type folders access
kernels

Select “extras” to
access “mk” folder

Select “mk” to
access meta-
kernels
NAIF Server 9
 N IF Getting Archived Kernels – PDS4
Navigation and Ancillary Information Facility

Top level directory on a

PDS4 SPICE archive

Select “document” to
access PDS4 archive
description document

Select a
kernel-type
folder to
access
kernels

Select
“spice_kernels” Select “mk” to
to access kernel- access meta-
type and “mk” kernels
folders

NAIF Server 10
 N IF Obtaining Archived Kernels - Subsetter
Navigation and Ancillary Information Facility

• Use the Subsetter tool to obtain a

part of an archive covering a period
of interest.
11
• Specify subset start and stop times
in the form
• Subsetter will:
– select just the kernels that fall within or
overlap the specified time bounds
– construct a new meta-kernels containing
the names of this subset of kernels (thus
making it easy to load the subset into
your program)
Select “subset” to obtain a subset of an archive – create a custom wget script that can be
used to download these files to a user
computer
• Run the script to download kernels
and adjust path in MK to use them

Type in subset start and stop times and click “Subset”

NAIF Server
 N IF Downloading Archived Kernels – wget
Navigation and Ancillary Information Facility

• Use GNU’s wget or a similar utility to download the

complete SPICE data set

– Example using wget on the Deep Impact mission:

» Open a terminal window
» wget -m -nH --cut-dirs=5 -nv (insert the URL of the "Archive
Link" for the SPICE data set here). For example:
• wget -m -nH --cut-dirs=5 -nv http://naif.jpl.nasa.gov/pub/naif/pds/data/di-c-spice-6-
v1.0/disp_1000/

NAIF Server 12
 N IF Getting Generic Kernels
Navigation and Ancillary Information Facility

1 – Select Data

2 – Select Generic Kernels

3 - Select Generic Kernels

4 – Select the kernel type

5 - Select Kernels of Interest

Description of folder contents and naming scheme

Latest LSK file

NAIF Server 13
 N IF Direct Access to Server Directory Tree
Navigation and Ancillary Information Facility

• Everything publicly available on the NAIF server is also

accessible by browsing its directory tree starting at
https://naif.jpl.nasa.gov/pub/naif

Operational and past

project kernel directories

... Generic kernels

Cosmographia packages
and additional materials
PDS archives and generic
WebGeocalc kernel sets
Toolkit packages

Toolkit documentation,
Toolkit utilities Tutorials and Lessons

NAIF Server 14
 N IF Horizons
Navigation and Ancillary Information Facility

• The Horizons server is an on-line ephemeris

generator for natural bodies (and more)
– It is operated by JPL’s Solar System Dynamics Group, not by NAIF
• Of primary interest to SPICE users is its ability to
generate up-to-date SPK files for comets and
asteroids
– Horizons home page:
» https://ssd.jpl.nasa.gov/horizons/
– Horizons web interface for manual generation of small body SPKs:
» https://ssd.jpl.nasa.gov/horizons/app.html#/
– Horizons telnet interface for automated (programmatic) generation
of small body SPKs:
» telnet ssd.jpl.nasa.gov 6775
» For an example script, use anonymous ftp to go to:
• ssd.jpl.nasa.gov
» and once there, look at pub/ssd/SCRIPTS/smb_spk
NAIF Server 15
N IF
Navigation and Ancillary Information Facility

Summary of Key Points

April 2023
 N IF Which Pieces of SPICE Must I Use?
Navigation and Ancillary Information Facility

• There’s not a simple answer

– Depends on what activity or mission you are working on
– Depends on what computation(s) you wish to make
• Don’t feel overwhelmed
– Many seemingly complex computations can be made using
just a few SPICE APIs
• The next several charts highlight some key points
– We assume you have already looked at the major SPICE
tutorials, or already have some familiarity with SPICE
– We assume you have successfully downloaded and installed
the SPICE Toolkit
• Consider printing this tutorial and keeping it near
your workstation

Summary of Key Points 2

 N IF Reminder of Key Subsystems
Navigation and Ancillary Information Facility

SPK: Position (and velocity) of things (“ephemeris objects”)

PCK: Size/shape/orientation of solar system bodies
For binary PCKs, only orientation is provided; use a text PCK to obtain
size/shape
See also DSK below
IK: Instrument field-of-view geometry (see also FK below)
CK: Orientation of spacecraft or spacecraft structures that rotate
FK: Definition and specification details for many reference
frames; also includes instrument mounting alignments
DSK: High fidelity shape data, better than what’s in a text PCK
(But limited availability)
LSK: Time conversion: UTC (SCET) ET (TDB)
SCLK and LSK: Time conversion: SCLK ET (TDB)

Summary of Key Points 3

 N IF Primary Kernel Interfaces - 1
Navigation and Ancillary Information Facility

Which SPICE APIs are most commonly used with a

given kernel type?

SPKEZR, SPKPOS, SXFORM, PXFORM,

SPK SPKCOV, SPKOBJ FK SPKEZR, SPKPOS

SXFORM, PXFORM, STR2ET, TIMOUT,

PCK SPKEZR, SPKPOS, LSK SCE2C, SCT2E,
BODVRD SCE2S, SCS2E

GETFVN, GETFOV, SCS2E, SCE2S

IK G*POOL SCLK SXFORM, PXFORM,
SPKEZR, SPKPOS

SXFORM, PXFORM SINCPT, LATSRF,

CK SPKEZR, SPKPOS, DSK* ILLUMF, SRFNRM,
CKCOV, CKOBJ LIMBPT, TERMPT, ...
(CKGPAV, CKGP)
* Partial implementation starting with N66 Toolkits
Notes: FURNSH is used to load (provide access to ) all SPICE kernels.
API names shown are for FORTRAN versions:
- use lower case and add an “_c” when using C
- use lower case and prepend “cspice_” when using Icy (IDL) and Mice (MATLAB)
Summary of Key Points 4
 N IF Primary Kernel Interfaces - 2
Navigation and Ancillary Information Facility

For a given high-level Toolkit API, which

kinds of kernels will or may be needed?
Kernel Type(s) Needed
API Name SPK PCK IK CK FK LSK SCLK DSK
SPKEZR, SPKPOS Y M M M L M
SXFORM, PXFORM M M M L M M
CKGP, CKGPAV M M Y M L L
GETFVN, GETFOV Y
G*POOL M M
STR2ET, TIMOUT Y
SCS2E, SCE2S Y Y
CHRONOS (time conversion app.) M M M M Y M

Yes = is needed
Likely = very likely needed
Maybe = may be needed

Summary of Key Points 5

 N IF Primary Kernel Interfaces - 3
Navigation and Ancillary Information Facility

More: for a given high-level API, which kinds

of kernels will or may be needed?
Kernel Type(s) Needed
API Name SPK PCK IK CK FK LSK SCLK DSK*
SINCPT Y L M M L L M M
TANGPT Y Y M M L L M
DSKXV, DSKXSI M M M M M M M Y
LATSRF M M M M M M
ILUMIN, ILLUMG, ILLUMF Y L M M L M M
SUBPNT, SUBSLR Y L M M L M M
GFOCLT, OCCULT Y L M M L M M
SRFNRM M M M M M M
LIMBPT Y L M M L M M
TERMPT Y Y M M L M M
Yes = is needed
* Partial implementation starting with N67 Toolkits
Likely = likely needed
Maybe = may be needed
Summary of Key Points 6
 N IF Kernel “Coverage” Cautions
Navigation and Ancillary Information Facility

• Your set of kernels must:

– contain data for all “objects” of interest
» Sometimes you must include intermediary objects that provide a
connection (recall the chaining discussion in the SPK tutorial)
– contain data covering the time span(s) of interest to you
» Watch out for data gaps within that time span
» Watch out for the difference between ET and UTC
• The difference as of 2017 January 01 is ~69.182 seconds (ET > UTC)
– contain all the kernel types needed by SPICE to answer your question
» As the previous charts show, you may need one or more kernels
that are not obvious
– be managed (loaded) properly if there are overlapping (competing)
data within the set of files you are using

Summary of Key Points 7

 N IF What Kernels are Available?
Navigation and Ancillary Information Facility

• It depends on the mission or task you are working on.

• There are typically three categories of kernel data available.
– Mission operations kernels – those used by the flight teams to fly the
mission and prepare the archival science products
» These are the most up to date, but it could be a challenge to select
the ones you need
– PDS Archived kernels – those that have been selected from (or made
from) the mission ops kernels, and then are well organized and
documented for the PDS archive.
» These data sets are well organized, well documented, and contain
helpful “furnsh” kernels (meta-kernels).
– Generic kernels – those that are used by many missions and are not tied
to any one mission
» Relevant generic kernels are usually included in the PDS Archived
and the Mission Operations kernels data sets mentioned above
– All three types can be found here: https://naif.jpl.nasa.gov/naif/data.html

• The situation might be similar for non-JPL missions, but this

is up to whatever institution is producing the kernels.
Summary of Key Points 8
 How Can I Find Possibly
N IF Useful Toolkit APIs?
Navigation and Ancillary Information Facility

• Review the previous charts

• Look at the appropriate SPICE tutorial(s)
• Look at the “Most Used xxx APIs” document
…/doc/html/info/mostused.html
• Search the permuted index:
– spicelib_idx for the FORTRAN toolkits …/doc/html/info/spicelib_idx.html
» This index also correlates entry point names with source code files.
– cspice_idx for the C toolkits …/doc/html/info/cspice_idx.html
– icy_idx for the IDL toolkits …/doc/html/info/icy_idx.html
– mice_idx for the MATLAB toolkits …/doc/html/info/mice_idx.html
• Read relevant portions of a SPICE “required reading”
technical reference document (e.g. “spk.req”)
– …/doc/html/req/spk.html for the hyperlinked html version (best)
– …/doc/spk.req for the plain text version

Summary of Key Points 9

 How Can I Understand How
N IF To Use Those APIs?
Navigation and Ancillary Information Facility

• The primary user-oriented documentation about each API is

found in the “header” located at the top of each source code
file and also in the API's HTML page in the API reference
guide.
– You can “Google” an API name to see its header
» For example: spkezr, spkezr_c, or cspice_spkezr (for Icy or Mice)
– (More documentation is found at the additional entry points for those
FORTRAN APIs that have multiple entry points.)

• Reference documentation for major subsystems is found in

like-named “required reading” documents (e.g. spk.req,
ck.req, etc.)

• The SPICE tutorials contain much helpful information.

• NAIF’s self-training materials provide an orderly approach to

learning about SPICE:
– https://naif.jpl.nasa.gov/naif/self_training.html
Summary of Key Points 10
 N IF Does NAIF Provide Any Examples?
Navigation and Ancillary Information Facility

• Nearly all API headers contain one or more working

examples
• “Most Used SPICELIB Subroutines” has code fragments
…/doc/html/info/mostused.html
• The “required reading” reference documents often contain
examples …/doc/html/req/index.html
• The “Program_<language>” tutorial contains a substantial
working example
• Some simple “cookbook” programs are found in the Toolkit
…/src/cookbook/…
• Make use of the SPICE Programming Lessons available
from the NAIF server
– https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/

Summary of Key Points 11

N IF
Navigation and Ancillary Information Facility

WebGeocalc (WGC)

https://wgc.jpl.nasa.gov:8443/webgeocalc (GUI only)

https://wgc2.jpl.nasa.gov:8443/webgeocalc (GUI and API)

April 2023
 N IF Overview
Navigation and Ancillary Information Facility

• WebGeocalc (WGC) provides a graphical user

interface (GUI) to a SPICE server running a
geometry computation engine
– The server has access to SPICE kernels containing ancillary data
• Some WGC installations also offer a
programmatic(API) interface to the WGC SPICE
geometry engine
• This tutorial covers mostly the GUI interface. The
API interface is described in a link provided in the
API-enabled version of WGC

WebGeocalc 2
 N IF Architecture
Navigation and Ancillary Information Facility

• WGC uses a client-server architecture

– The user needs only a computer running a web browser
– The browser connects via Internet to a WGC “computation
engine” running on a server
» The WGC server has access to a variety of SPICE kernel files

Internet

Your Computer WGC Server

running the WGC
SPICE Data
“geometry engine”

WebGeocalc 3
 N IF Using WebGeocalc
Navigation and Ancillary Information Facility

• WGC makes it “easy” to do many kinds of SPICE

computations
– You need not write a program using SPICE Toolkit software
– Instead, open a web browser and use standard GUI widgets to:
» select the computation desired
» select the data to be used in your computation
» specify the computation details
» press the “CALCULATE” button
– Your results, possibly including some plots, appear in your
browser window
– WGC has a good deal of built-in HELP
• WGC computations are limited in scope: the tool
cannot do nearly as much as an own-built program
that uses SPICE Toolkit APIs
– But WGC can probably do a good deal more than you first realize!
WebGeocalc 4
 N IF Purpose
Navigation and Ancillary Information Facility

• WGC can support planetary science in several ways

– Help a user check his/her own SPICE-based program under
development (the “gold bar” check)
– Help a user quickly solve a one-time space geometry problem
– Allow those unable to write a SPICE-based program to
nevertheless make some kinds of space geometry computations
– Help a science data peer reviewer do spot checks of geometry
parameters contained in an archive about to be submitted to an
archive center

WebGeocalc 5
 N IF Computations
Navigation and Ancillary Information Facility

• Three categories of SPICE computations are possible

1. Geometry Calculator
» Compute a parameter value at a given time, or over a time range
• Example: Compute the angular size of Phobos as seen from the SPIRIT Mars rover from 2009
March 10 12:00:00 to 2009 March 10 14:00:00
2. Geometric Event Finder
» Within a specified time bounds (the confinement window)…
• Find time intervals when a particular geometric condition exists
– Example: Find time intervals when Phobos is occulted by Mars as seen from Mars
Odyssey within the period 2010 June 01 to 2010 June 02
• Find time intervals when a geometry parameter is within a given range
– Example: Find time intervals when the spacecraft altitude is between 300 and 400 km
• Find time intervals when a geometry parameter has reached a local or global maximum or
minimum
– Example: Find time intervals when the angular separation of a satellite from a planet, as
seen from a spacecraft, has reached its minimum value
3. Time conversion calculator
» Convert between various time systems and time formats

• See the WGC “menu” on the next page for some details
WebGeocalc 6
 N IF Computation Menu*
Navigation and Ancillary Information Facility

WebGeocalc * Current as of March 2023; more computations will be added in the future 7
 Illustrations of Three
N IF Available Computations
Navigation and Ancillary Information Facility

Solar
Incidence
Phase
Emission
Z Surface
intercept
point
Tstop-search

X
Geometry Calculator
• 30o
Illumination Angles

Geometry Calculator Y

Angular Size
Tstart-search
Camera scanning
The GREEN trace shows when the latitude of the across the
instrument boresight surface intercept is greater than planet’s surface
30 degrees, within the time range Tstart-search to Tstop-search.

Geometric Event Finder

Surface Intercept Event Finder
WebGeocalc 8
 N IF Typical Geometry Calculator Input
Navigation and Ancillary Information Facility

• Compute the angular size of

Phobos as seen from the
Mars rover “SPIRIT” over a
two hour period on 2009
March 10.

• Use typical GUI drop-down

menus, fill-in boxes, radio
buttons and check boxes to
specify the details of the
computation you wish to
make.

WebGeocalc 9
 N IF Typical Geometry Calculator Output
Navigation and Ancillary Information Facility

Summary of your input

Angular size of
Phobos as seen
from the Mars
rover “SPIRIT”

Tabular results

WebGeocalc 10
 N IF Typical Geometry Calculator Plot
Navigation and Ancillary Information Facility

• Some Geometry Calculator computations offer

optional plots

Angular size of Phobos as seen from the Mars rover “SPIRIT”

WebGeocalc 11
 N IF Another Geometry Calculator Plot
Navigation and Ancillary Information Facility

• Some Geometry Calculator computations offer

plots using other than time on the X axis

Mars Global Surveyor sub-point on Mars

from 2008 JAN 1 00:10:00 to 2008 JAN 1 02:00:00
WebGeocalc 12
 N IF Typical Geometric Event Finder Input
Navigation and Ancillary Information Facility

• Find the times when

Phobos is occulted by
Mars as viewed from the
Mars Odyssey
spacecraft, during the
period 2010 JUN 01 to
2010 JUN 02.

• Use typical GUI drop-

down menus, fill-in
boxes, radio buttons and
check boxes to specify
the details of the
computation you wish to
make.

WebGeocalc 13
 N IF Typical Geometric Event Finder Output
Navigation and Ancillary Information Facility

Summary of your input

When is Phobos
occulted by Mars
as seen from
Mars Odyssey?

Tabular results

WebGeocalc 14
 N IF Typical Geometric Event Finder Plot
Navigation and Ancillary Information Facility

• Geometric Event Finder computations all produce

“plots” of the time intervals that satisfy your
search computations

Between June 1, 2010 and June 2, 2010, find times when Phobos is
occulted by Mars, as viewed from the Mars Odyssey spacecraft

WebGeocalc 15
 N IF Example of Time Conversion
Navigation and Ancillary Information Facility
Convert a spacecraft clock string to UTC

Spacecraft clock string

Spacecraft clock ticks

Calendar (year/month/day)
Calendar (year/day-of-year)
Julian date
Seconds past J2000
Custom format

The output is:

2011-06-20 00:00:00.044032 UTC
WebGeocalc 16
 N IF Second Example of Time Conversion
Navigation and Ancillary Information Facility
Compute a series of UTC times with a specified time step

UTC
TDB
TDT
Spacecraft clock

Calendar (year/month/day)
Calendar (year/day-of-year)
Julian date
Seconds past J2000

The output is:

2011-03-10 00:00:00.000000 UTC 2455630.500000000 JD UTC
2011-03-10 00:20:00.000000 UTC 2455630.513888900 JD UTC
2011-03-10 00:40:00.000000 UTC 2455630.527777800 JD UTC
2011-03-10 01:00:00.000000 UTC 2455630.541666700 JD UTC
etc. etc.

WebGeocalc 17
 N IF Categories of Available Data
Navigation and Ancillary Information Facility

• The JPL/NAIF Group is operating two WGC servers

– These servers provide access to three categories of SPICE kernels
» Generic SPICE kernels, not specifically tied to a single planetary
mission
» Archived SPICE kernels, from planetary missions that have been
formally ingested into NASA’s Planetary Data System
• This includes a few non-NASA missions for which NAIF provides a shadow archive
» Operations SPICE kernels, for JPL-operated planetary missions, for
three ESA planetary missions, and for a few past missions for which
an archive does not exist
• This category often includes some predictive data
• This category is the most difficult to use because…
– there are no meta-kernels for these collections
– there is sometimes a large number of kernels from which you must choose
the ones needed
– there is little readily available information to help you make your kernel
choices
– VERY IMPORTANT: Read the “About the data” webpage provided within
the tool for details
WebGeocalc 18
 N IF Kernel Selection
Navigation and Ancillary Information Facility

A scrollable drop-down
Solar System Kernels
Latest Leapseconds Kernel menu is used to select the
Latest Planetary Constants Kernel
Ground Stations Kernels kernel set(s) to be used in
Cassini Huygens
Clementine your calculation.
Dawn
Deep Impact (Primary mission)
Deep Impact (EPOXI mission)
Deep Space 1
GRAIL Use the menu to select:
Hayabusa
JUNO
- generic kernel sets
Lunar Reconnaissance Orbiter - archived mission kernel sets
MAVEN
MER1 Rover (Opportunity) (includes relevant generic kernels)
MER2 Rover (Spirit)
MESSENGER
- manual selection of individual
Mars Express kernels from operations collections
.
.
Manual

WebGeocalc 19
 N IF “Tooltip” Feature
Navigation and Ancillary Information Facility

Solar System Kernels

Latest Leapseconds Kernel
Latest Planetary Constants Kernel
Ground Stations Kernels
Cassini Huygens
Clementine
Dawn
Deep Impact (Primary mission) If you hover your cursor over a kernel set name,
Deep Impact (EPOXI mission)
Deep Space 1
some information about the kernel set will
GRAIL appear–for example, dates covered by the data.
Hayabusa
Lunar Reconnaissance Orbiter
MER1 Rover (Opportunity)
MER2 Rover (Spirit)
MESSENGER Archived MESSENGER kernels covering from 2004-08-03 to 2015-04-30
Mars Express
Mars Global Surveyor
Mars Odyssey

You can hover over the kernel set name

in the “Kernel selection” menu, or in the
“Kernels Selected” panel.

This feature is not available for

“Manual” kernel selection.
WebGeocalc 20
 N IF Pre-load Feature
Navigation and Ancillary Information Facility

WGC automatically loads at

startup (“pre-loads”) generic
kernel sets that are often
needed in WGC calculations.

Pre-loaded kernel sets appear in

the “Kernels Selected” area at
the bottom-right of any WGC
page.

Any of these pre-loaded kernel

sets can be unloaded if desired
using the (x) symbol appearing
next to it

WebGeocalc 21
 N IF Auto-complete Feature
Navigation and Ancillary Information Facility

• If you select any kernel set(s) other than “Manual”, many of

the input widgets will be supplied with the names of all
available selections
– Just start typing the name you want and all items matching what you
typed will appear in a drop down menu
– Alternatively, simply type a “blank” and all items available within the
kernel set(s) you selected will appear
• In the example below, using the Cassini Huygens archive, the
user has typed “mi” in the “Target” selection box. The names
of the three objects containing those letters are displayed for
the user’s selection. (All three are satellites of Saturn.)

BERGELMIR
MIMAS
YMIR

WebGeocalc 22
 N IF Downloading Results
Navigation and Ancillary Information Facility

• You can download tabular results to your

computer by clicking the “Download Results”
button, then selecting the format desired:
– Excel
– Comma separated values
– Plain text

• You can download any plots you've created by

clicking on the “Download Plot” button
– Plots are saved in PNG format with a transparent background
» Easily pasted into a document or presentation

WebGeocalc 23
 N IF Saving Results for Use as New Inputs
Navigation and Ancillary Information Facility

• You can save a numeric output, or an event finder

interval start or stop time, by clicking on the value
– The saved value will appear in a “Saved Values” panel on the
right side of your browser window
– This value can then be dragged to an input widget in a
subsequent calculation

• You can save a complete set of event finder

output interval start and stop times by clicking the
“Save All Intervals” button
– These can then be used as part of the input for a subsequent
geometric event finder computation if you select “List of
intervals” for the “Input times” selection. Simply drag the list
of saved intervals to the "List of intervals" box.

WebGeocalc 24
 N IF WGC Programmatic Interface
Navigation and Ancillary Information Facility

• NAIF also offers a programmatic(API) interface to

the WGC SPICE geometry engine
– To use this interface, one writes a program that constructs
JSON payloads identifying the computation of interest, the
kernel set(s) to be used, and the computation inputs, and
submits them to the WGC server using RESTful URLs
– The WGC SPICE geometry engine executes the computation and
returns the results in JSON format
• The “API Docs” link found near the top-right of a
WGC installation having the API interface points to
a page with complete details
– For the NAIF instance, that link is also provided here:
https://wgc2.jpl.nasa.gov:8443/webgeocalc/documents/api-
info.html

WebGeocalc 25
 N IF Getting Help
Navigation and Ancillary Information Facility

• WGC users must read the “About the Data” web page to
understand the kinds of SPICE kernels (data) available to the
WGC tool

• Each calculation and most GUI controls have associated HELP

available by clicking the ? icon

• Most computation descriptions have an associated graphic

depicting one or more examples of what may be computed

• Some GUI controls have a second-level, more extensive help

description, available by clicking the “Read more…” text
displayed in the first level help

WebGeocalc 26
 N IF Usage Rules
Navigation and Ancillary Information Facility

• The WGC program has a link entitled “Rules of Use”

– WGC users must read and abide by these rules

• While easier than writing a SPICE-aware program,

using WGC nevertheless requires some knowledge
of space geometry and of NASA’s SPICE system
– The NAIF website provides much SPICE information:
» https://naif.jpl.nasa.gov

WebGeocalc 27
 N IF Limited Capability
Navigation and Ancillary Information Facility

• WGC does not provide all of the space geometry

computational capability offered by the SPICE
Toolkits
– But WGC nevertheless provides substantial capability–likely
more than is obvious at first glance

• More capability might be added if the user

community finds this tool useful

WebGeocalc 28
 N IF Feedback
Navigation and Ancillary Information Facility

• WGC includes a “Feedback” button, making it

rather easy to provide the NAIF team with any sort
of useful feedback…
– What you like or don’t like about WGC
– What seems incorrect, incomplete or unclear
– What features you would like to see added
» Caution: NAIF already has a long list of improvements
we’d like to make, so we make no promises to act on any
specific feedback

WebGeocalc 29
 N IF Problems Using WGC
Navigation and Ancillary Information Facility

• There are several limitations and errors you might

encounter in using WebGeocalc

– See the next several pages for examples

– Some of these conditions could be unique to the WGC

installation at NAIF, and not exist with some other installation

WebGeocalc 30
 N IF Missing Input
Navigation and Ancillary Information Facility

• WGC will alert you to missing inputs.

WebGeocalc 31
 N IF Request is Too Large
Navigation and Ancillary Information Facility

• WGC has limits set on computational resources.

– No more than 50,000 “Geometry Calculator” computations
– No more than 10 million “Geometric Event Finder” time steps
– No more than 3 minutes of wall clock time
• If any of these limits will be (or have been)
exceeded, you’ll see a message saying so and
your computation request will be terminated.
• Some examples:
50000

WebGeocalc 32
 N IF SPICE Error Messages
Navigation and Ancillary Information Facility

• WGC will display a SPICE Toolkit error message

when an underlying SPICE API is able to detect a
problem.
• These SPICE error messages all begin with:
“CSPICE_N00xx:” followed by some text

• Refer to the remaining charts for some examples.

WebGeocalc 33
 N IF Unusable Time Tag(s) - 1
Navigation and Ancillary Information Facility

• Time tag processing within WGC makes use of

SPICE Toolkit modules.
• These Toolkit modules offer a great deal of
capability. But not every conceivable style of time
tag, and not every time system, are acceptable.
• What to do?
– Use the help icons ? next to any Time system or Time format
input.
– See Appendix 2 of the CHRONOS User’s Guide for some
details and many examples.
» https://naif.jpl.nasa.gov/misc/chronos_ug.html

– See the Time Required Reading document for a full explanation

of time treatment within SPICE.
» https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/time.html

WebGeocalc 34
 N IF Unusable Time Tag(s) - 2
Navigation and Ancillary Information Facility

• A few examples of bad time tags and resultant error

messages.
– Using UTC and Calendar format, and inputting: 2010:10:03 05:44:12

» Would have worked using: 2010-10-03 05:44:12 or 2010/10/03 05:44:12

– Using UTC and Calendar format, and inputting: 2455160.098304

» Needed to specify “Julian date” format

– Using UTC and Calendar format, and inputting: 2010:10:03T05:44:12

» Instead, use an ISO-defined format such as: 2010-10-03T05:44:12

• (For separators, use dashes before the “T” and colons after the “T”)

WebGeocalc 35
 N IF Unusable Time Tag(s) - 3
Navigation and Ancillary Information Facility

• A few more examples of bad time tags and resultant error

messages.
– Using UTC and Calendar format, and inputting: 2010-10-03 05:44:12 JD

» 2010-10-03 05:44:12 is not a Julian date format: remove the trailing JD

– Using TDB and Julian date format, and inputting: 2.4404005000000000 D+06

» “E” and “D” exponent notations are not allowed

– Using Spacecraft clock and Spacecraft clock string format, and inputting:
81138762:563

» The Spacecraft clock ID value is 0, which is not a valid clock ID. Either you did
not load an archival kernel set (containing the mission SCLK kernel) or you did
not manually load a SCLK kernel.
WebGeocalc 36
 Incorrect Use of
N IF or Interpretation of Time Tags
Navigation and Ancillary Information Facility

• Be aware that a time tag of this general form:

2019 DEC 18 13:21:53.261
that you’ve taken from elsewhere, or that you have
produced using SPICE–what we call calendar
format–could represent a time in either the UTC or
the TDB (a.k.a. ET) time system. Be sure you know
which time system you are dealing with!
– Refer to the “Time” tutorial for further information
• Spacecraft clock times occur as either a SCLK
string or a double precision number of tics.
– SCLK strings often appear like this: 53321876.214
– The decimal character within this string is NOT a decimal
point; rather it is simply a separator between the two parts of
the clock string. See the “LSK and SCLK” tutorial for details.

WebGeocalc 37
 N IF Time out of Bounds - 1
Navigation and Ancillary Information Facility

• WGC will display a SPICE error message when

SPICE is able to detect a problem.

• In this example the user requested the position of Mercury

relative to the MESSENGER spacecraft at a time outside the
bounds of loaded SPK kernels. (In this case it was before
MESSENGER was launched.)
WebGeocalc 38
 N IF Time out of Bounds - 2
Navigation and Ancillary Information Facility

• Users involved with mission planning often ask to

make a computation for a future time that is not
within the bounds of loaded time-dependent
kernels (most usually SPKs and CKs).
– Kernels available in SPICE archives cover only up to a date in
the past. This can be seen using the Tool Tip displayed when
you hover your cursor over the name of the archived kernel set.
» Example for the Cassini archive as of October 2017:
Archived Cassini kernels covering from 1997-10-15 to 2016-12-31

– Some kernels available via MANUAL loading from NAIF’s

operations collections might contain “predict” data, but there is
no guarantee, and it can be difficult for a person not familiar
with the mission of interest to determine which kernel to load.

WebGeocalc 39
 N IF Missing Data - 1
Navigation and Ancillary Information Facility

• If you try to make a series of calculations (e.g. over a

time interval, or at each of a set of times) it could be
that some of the calculations can be made while others
cannot due to data gaps or otherwise missing data.
– A gap in a CK is the most likely culprit. This is usually caused by
sparse or missing downlinked spacecraft attitude telemetry.
– The graphic below represents a CK file.
» The orange bars are called “interpolation intervals” during which
orientation can be determined.
» The white spaces between the orange bars are gaps during
which orientation cannot be determined.

CK file:
CK START Time CK END Time

» See the next page for some options to deal with this.

WebGeocalc 40
 N IF Missing Data - 2
Navigation and Ancillary Information Facility

• When making “Geometry Calculator” computations

you can control the action taken by WGC using the
“Error handling” control found at the bottom of each
“Geometry Calculator” web page.
– The options are:
» Stop on error (the default setting)
» Report errors and continue (a more friendly but still safe option)
» Silently omit errors (dangerous; not recommended)
• However, when making “Geometric Event Finder”
calculations you haven’t any options: WGC will issue
an error message and discontinue the computation,
showing no interval results at all. L

WebGeocalc 41
 N IF Incomplete Data
Navigation and Ancillary Information Facility

• Computations involving ephemerides

(trajectories) or orientations often require the
chaining–the stringing together–of multiple
“chunks” of data to obtain needed positional
information.
• Kernels containing ALL the needed “chunks” of
data to complete the chain must be loaded into
WGC.
– This is rarely a problem when using a mission’s archive since
much care is taken to make the archive complete.
– But incomplete data is often a problem when MANUALY
loading individual kernels from a mission operations
collection. The user may not understand what are the needed
components of an ephemeris chain (SPK, FK) or an orientation
chain (some of CK, FK, PCK).

WebGeocalc 42
 N IF Mixed Up Target and Observer
Navigation and Ancillary Information Facility

• A user wants to find the sub-observer point on the

moon using the Lunar Reconnaissance Orbiter
(LRO) spacecraft as the observer.
• S/he selects the “Sub-Observer Point”
calculation, loads the LRO kernel set, and
specifies the Target as “LRO,” the reference
frame as “IAU_MOON” and the observer as the
“MOON.”

– S/he mixed up what should be the observer and the target.

Interchange these two items and the calculation will work.

WebGeocalc 43
 N IF Limitation – One at a Time
Navigation and Ancillary Information Facility

• WebGeocalc executes only one computation at a

time.
– Any computation requests received while one
computation is in progress will be queued in the order
received.
» A “queued” message will be displayed in your browser’s
window.
» Each request will automatically execute once having
reached the top of the queue.

WebGeocalc 44
N IF
Navigation and Ancillary Information Facility

Digital Shape Kernel Subsystem

(DSK)

April 2023
 N IF Topics
Navigation and Ancillary Information Facility

• DSK subsystem overview

• DSK shape representations
• N67 version of DSK subsystem
• DSK APIs and graphical depictions
• DSK API example
• DSK utility programs
• DSK concepts
• Writing and using DSK files

Digital Shape Kernel 2

 N IF DSK Subsystem Overview
Navigation and Ancillary Information Facility

• The DSK subsystem

– enables SPICE-based applications to
conveniently make use of high fidelity surface
shape (topographic) data in geometry
computations
– serves as a format for transmission and archival
of surface shape data
– consists of SPICE software, DSK file format
specifications, and documentation

Digital Shape Kernel 3

 N IF DSK Shape Representations
Navigation and Ancillary Information Facility

• The DSK subsystem handles two representations

of shape data
– Tessellated plate model (Type 2)

– Digital elevation model (development not yet finished) (Type 4)

Digital Shape Kernel 4

 N IF Tessellated Plate Model – Type 2
Navigation and Ancillary Information Facility
• The surface of the object is represented as a collection of
triangular plates
• More flexible than digital elevation model: any arbitrary 3-D
surface can be modeled
– Surface could be a complicated shape with multiple surface points
having the same latitude and longitude
» Examples: “dumbbell”-shaped asteroid, caves, arches
• Less efficient than digital elevation model (DSK Type 4) of
similar resolution in terms of storage and computational
speed

Phobos Itokowa Churyumov-Gerasimenko

Digital Shape Kernel 5
 N IF Digital Elevation Model – Type 4
Navigation and Ancillary Information Facility
• Maps longitude/latitude to “elevation”
– Elevation of a surface point can be defined as distance from the origin of
a body-fixed reference frame or height above a reference ellipsoid

• Example: rendering of a piece of DSK data created from MGS

laser altimeter (MOLA) Mars DEM

Digital Shape Kernel 6

 N IF N67 Toolkit with DSK
Navigation and Ancillary Information Facility

• Supports only the tessellated plate model data type

(Type 2 DSK)

• Support for Digital Elevation Model (DEM) (Type 4

DSK) will be added in a future Toolkit version

Digital Shape Kernel 7

 N IF Some DSK Features
Navigation and Ancillary Information Facility

• Supports multi-segment, multi-file DSK data sets

– Up to 5000 DSK files can be loaded simultaneously
– Up to 10,000 DSK segments can be loaded simultaneously

• Supports run-time data translation: big-endian DSK

files can be read on little-endian platforms, and vice
versa

• Pre-DSK era SPICE Toolkit geometry APIs will

support DSK shape data, where applicable

Digital Shape Kernel 8

 N IF APIs Available in N66 Toolkits -1
Navigation and Ancillary Information Facility

• Kernel load/unload/info:
– FURNSH, UNLOAD, KCLEAR, KTOTAL, KINFO, KDATA
• Geometry:
– Ray-surface intercept: SINCPT, DSKXV, DSKXSI
– Sub-observer point: SUBPNT
– Sub-solar point: SUBSLR
– Illumination angles at surface point: ILLUMF, ILLUMG, ILUMIN
– Longitude-latitude pairs to surface points: LATSRF
– Find occultation state at a given time: OCCULT
– Find occultation or transit of point target behind/across DSK
shape: GFOCLT
– Generate limb points: LIMBPT
– Generate terminator points: TERMPT
– Compute outward normal vector at surface point: SRFNRM

Digital Shape Kernel 9

 N IF APIs Available in N66 Toolkits -2
Navigation and Ancillary Information Facility

• Low-level access:
– DLA segment traversal: DLABFS, DLABBS, DLAFNA, DLAFPA
– Fetch type 2 counts/plates/vertices/normals: DSKZ02, DSKP02,
DSKV02, DSKN02
– Fetch all type 2 data structure contents: DSKI02, DSKD02
– Fetch DSK segment descriptor: DSKGD
• Plate utilities:
– PLTVOL, PLTAR, PLTEXP, PLTNP, PLTNRM
• Create DSK files:
– DSKOPN, DSKW02, DSKCLS, DSKMI2, DSKRB2
• Summary routines:
– DSKOBJ, DSKSRF
• Surface name-code translation:
– SRFS2C, SRFSCC, SRFC2S, SRFCSS

Digital Shape Kernel 10

 N IF Graphic Depictions
Navigation and Ancillary Information Facility

• In the next several charts we provide graphic

depictions of the high-level APIs that should be of
interest to many users

Digital Shape Kernel 11

 N IF Plate Model Surface Intercept
Navigation and Ancillary Information Facility

API: SINCPT

Intercept nearest to
observer’s location

Additional intercepts ---not computed

Input ray

Observer’s location
Observer is external to object

Digital Shape Kernel 12

 N IF Plate Model Sub-observer Point
Navigation and Ancillary Information Facility

API: SUBPNT

Reference ellipsoid
Sub-observer point
(nadir definition)

Outward normal to
reference ellipsoid

Sub-observer point
(target center definition)
Observer to sub-
observer point vector
Observer to sub- (nadir definition)
observer point vector
(target center definition)
Observer location

Digital Shape Kernel 13

 N IF Plate Model Sub-solar Point
Navigation and Ancillary Information Facility

API: SUBSLR

Reference ellipsoid
Sub-solar point (target
center definition)

Observer to sub-
observer point vector Sub-solar point (nadir
(target center definition) definition)

Observer location
Outward normal to
reference ellipsoid
Observer to sub-
observer point vector
(target center definition)

Sun location

Digital Shape Kernel 14

 N IF Plate model Illumination Angles
Navigation and Ancillary Information Facility

Direction to illumination source

API: ILLUMF
Outward surface normal
Phase angle

Direction to observer Incidence

angle
Emission angle

Also returned:
- target epoch (corrected for light time),
- observer visibility flag,
- illumination source visibility flag

Digital Shape Kernel 15

 N IF Plate Model Surface Point Grid
Navigation and Ancillary Information Facility

API: LATSRF
Ray emanating from Exterior bounding
sphere point, pointing sphere for target object
toward center of body-
fixed, body-centered
reference frame
•
•
•

Surface intercept
Point on bounding point corresponding
to point on bounding
sphere, specified by
• sphere:
planetocentric • • planetocentric
longitude and longitude and
latitude, and by latitude of intercept
radius of exterior • match those of the
bounding sphere. • • sphere point. An
This grid contains 9 intercept is
such points. computed for each
input sphere point.

Digital Shape Kernel 16

 N IF Plate Model Limb-1
Navigation and Ancillary Information Facility

API: LIMBPT

Ray emanating from

observer and tangent to Specified half-plane
Limb point---lies on a
target body bounded by observer-
tangent ray in the
target center line
selected half-plane (for
some shapes, multiple (axis): contains ray
tangents will exist for a given
axis and half-plane)

Limb point angle relative to axis

Observer location
Axis: observer-target center vector

Digital Shape Kernel 17

 N IF Plate Model Limb-2
Navigation and Ancillary Information Facility

API: LIMBPT
Rays emanating from
observer, lying in half-
plane, and tangent to
target body
Limb points---each is
tangent point of a ray
in the selected half
plane

Specified half-plane
bounded by observer-
target center line
(axis): contains ray

Observer location
Angular search step
Axis: observer-target
must be less than
center vector
this angle
Digital Shape Kernel 18
 N IF Plate Model Terminator-Umbral
Navigation and Ancillary Information Facility

API: TERMPT
Ray tangent to sun
and target body Specified half-plane
bounded by sun center- Umbral terminator
target center line (axis): point: lies on a tangent
contains ray ray in the specified
half-plane (for some
shapes, multiple tangents will
exist for a given axis and half-
plane). Terminator point
and ray vertex are on
same side of axis.

•
Sun center

Axis: sun center-target center vector

Digital Shape Kernel 19

 N IF Plate Model Terminator-Penumbral
Navigation and Ancillary Information Facility

API: TERMPT
Axis: sun center-target
center vector

Ray tangent to sun

and target body

Penumbral terminator
point: lies on a tangent
• ray in the specified
Sun center half-plane (for some
shapes, multiple tangents will
exist for a given axis and half-
Specified half-plane bounded plane). Terminator point
by sun center-target center
line (axis): contains semi-
lies in half-space on
infinite portion of ray opposite side of axis
from ray’s vertex.
Terminator tangent ray angle
relative to axis

Digital Shape Kernel 20

 N IF Example of API Using DSK - 1
Navigation and Ancillary Information Facility

• Find ray intercept point on target surface: n cod

e
ra
– CALL SINCPT ( METHOD, TARGET, ET, FIXREF, ABCORR, Fort ple
m
exa
OBSRVR, DREF, DVEC, SPOINT, TRGEPC,
SRFVEC, FOUND)
– SINCPT is a high-level SPICE API.
– The input string argument METHOD indicates the surface model to
use.
» To model the target body shape using an ellipsoid, set
METHOD to ‘ellipsoid’
» To model the target body shape using DSK data, set METHOD
to one of the forms
• ‘DSK/UNPRIORITIZED’
– If all DSK segments for the body designated by TARGET are
applicable
• ‘DSK/UNPRIORITIZED/SURFACES = <surface name or ID 1>, …’
– If only DSK segments for the specified surfaces associated with the
body designated by TARGET are applicable
» For the DSK case, the keyword UNPRIORITIZED is currently required.
This keyword indicates that no applicable segment can mask another.

Digital Shape Kernel 21

 N IF Example of API Using DSK - 2
Navigation and Ancillary Information Facility

» Other inputs: target body name, epoch, body-fixed reference

frame, aberration correction, observer name, reference frame
for direction vector, direction vector.

» Outputs: ray-surface intercept in Cartesian coordinates,

expressed in the body-fixed frame associated with the target---
evaluated at the optionally light-time corrected epoch
TRGEPC, TRGEPC itself, observer-to-intercept vector
expressed in body-fixed frame, and found flag indicating
whether intercept exists.

Digital Shape Kernel 22

 N IF DSK Utility Programs
Navigation and Ancillary Information Facility

• Create DSK files: MKDSK

– Creates a DSK file containing a single type 2 segment
• Export DSK data to text format files: DSKEXP
– Writes data from Type 2 DSK segments to one or more text files
– Supports simple output formats such as “obj”
• Summarize DSK files: DSKBRIEF
• Modify DSK segment attributes: DSKMOD
• Merge DSK files: DLACAT
– Concatenates segments from multiple DSK files into a single DSK file
• Transform binary architecture of DSK file: TOXFR, TOBIN,
BINGO (BINGO not part of standard SPICE Toolkit)
• Read/write comment area: COMMNT

• DSKMOD, DLACAT, and BINGO are provided on the NAIF Web

site (https://naif.jpl.nasa.gov/naif/utilities.html)

Digital Shape Kernel 23

 N IF DSK Concepts-1
Navigation and Ancillary Information Facility
• Surface
– "Surface" is a second identifier, in addition to the central body
» A “surface” has a name and an integer ID code
• Surfaces occupy a name space distinct from that of bodies
• APIs are provided for surface name/ID conversion
– Used to distinguish different versions of data for a given body
» Allows use of different versions without loading and unloading kernels
• High-frequency kernel loading and unloading is too inefficient for DSK applications

• Data class
– Data class is a “hook” to differentiate kinds of data for different
applications
» Distinct from concept of “data type”
– Existing classes indicate geometric characteristics of surface data
» Class 1: shape is single-valued function of domain coordinates.
Example, for latitudinal coordinates:
• Every ray emanating from the origin of the body-fixed reference frame
associated with the body passes through the surface once
• Such surfaces cannot have features such as cliffs or caves
• DEMs can represent class 1 surfaces
» Class 2: arbitrary shape
• Not required to be convex, closed, or connected
• Plate models are the only DSK data type that can be used for class 2
Digital Shape Kernel surfaces 24
 N IF DSK Concepts-2
Navigation and Ancillary Information Facility

• Kernel priority
– Unlike SPK, CK, and binary PCK files, the concept of segment “priority” does not
apply to all DSK applications
» Not applicable to data sets including segments of class 2
• Concept simply doesn’t make sense when multiple heights can correspond to a single
longitude/latitude coordinate pair
» Can apply to data sets containing only class 1 segments
• Coordinate systems
– Associated with segments
» Segment coverage is described in terms of a coordinate system associated
with that segment
– Can be any of
» Planetocentric (latitudinal)
» Planetodetic
» Cartesian
• Segment coverage
– The spatial “coverage” of a segment is a region of space within which the segment
provides valid surface data
» Characterized by three coordinate ranges
• For example: min, max longitude; min, max latitude; min, max radius
» “Padding” data may be provided outside of a segment’s coverage region

Digital Shape Kernel 25

 N IF Writing Shape and Orientation Kernels
Navigation and Ancillary Information Facility

LAT/LON and height

DSK
above ellipsoid or Digital
distance from center MKDSK shape kernel
of frame (N66 or later) Program
Digital Terrain
or SPICE Shape Model
Routines
Lists of plate (SPICE Toolkit)
model vertices
and associated
plates
Tessellated Plates
Shape Model

Axes dimensions
for tri-axial Text editor
ellipsoid
(Usually done by
NAIF) Triaxial Ellipsoid
Shape Model
Z
Some source of
rotation state
information (pole Text editor X
Text PCK
RA/DEC and Planetary constants
prime meridian (Usually done by
NAIF) Y kernel containing
location) Orientation rotation data for the
body, and possibly
tri-axial shape
Digital Shape Kernel 26
 N IF Using Shape and Orientation Kernels
Navigation and Ancillary Information Facility

DSK
Digital
shape kernel

Digital Terrain
Shape Model
Your Application Program
Pick one
shape model
Shap
e
Tessellated Plates
Shape Model

SPICE
modules

n
tio
Triaxial Ellipsoid nta
ie
Shape Model Or
Z
Your other
X
PCK data, as
needed
Planetary constants SPICE modules for
obtaining rotation
Y kernel containing state and shape,
Orientation rotation data for the and then
body, and possibly computing derived
quantities
tri-axial shape
Digital Shape Kernel 27
N IF
Navigation and Ancillary Information Facility

Writing an Icy (IDL)

Based Program

April 2023
 N IF Viewing This Tutorial
Navigation and Ancillary Information Facility

Undefined variables are displayed in red

Results are displayed in blue

Please read the tutorial “Preparing for

Programming” prior to attempting the
exercise contained in this tutorial.

Writing an Icy-based program 2

 N IF Introduction
Navigation and Ancillary Information Facility

First, let's go over the important steps in the process of writing an Icy-based
program and putting it to work:

• Understand the geometry problem.

• Identify the set of SPICE kernels that contain the data needed to perform the
computation.
• Select the SPICE APIs needed to compute the quantities of interest.
• Write and compile the program.
• Get actual kernel files and verify that they contain the data needed to support
the computation for the time(s) of interest.
• Run the program.

To illustrate these steps, let's write a program that computes the apparent
intersection of the boresight ray of a given CASSINI science instrument with the
surface of a given Saturnian satellite. The program will compute:

• Planetocentric and planetodetic (geodetic) latitudes and longitudes of the

intercept point.
• Range from spacecraft to intercept point.
• Illumination angles (phase, solar incidence, and emission) at the intercept point.

Writing an Icy-based program 3

 N IF Observation geometry
Navigation and Ancillary Information Facility

We want the boresight on-bo ard clock ephemeris time UTC time

intercept on the surface, range

from s/c to intercept, and
illumination angles at instrument inertial frame

the intercept point. fram e

When? time (UTC, TDB or TT) instrument

surface normal

sp acecraft boresight
emission angle
frame
On what object? satnm spacecraft solar incidence angle
position
In what frame? fixref Phase angle
surface
intersection

body-fixed
For which instrument? instnm frame
planetocentric
latitude
planetocentric
For what spacecraft? scnm longitude

Using what model? setupf

Writing an Icy-based program 4
 N IF Needed Data
Navigation and Ancillary Information Facility

on-bo ard clock ephemeris time UTC time

instrument inertial frame

Time transformation kernels frame

instrument
Orientation models sp acecraft
frame
boresight emission angle surface normal

solar incidence angle

spacecraft
position

Instrument descriptions phase angle

surface
intersection

body-fixed
frame
planetocentric
Shapes of satellites, planets planetocentric
latitude
longitude

Ephemerides for spacecraft,

Saturn barycenter and satellites. sun

Writing an Icy-based program 5

 N IF Which Kernels are Needed?
Navigation and Ancillary Information Facility

Data required to compute vectors, rotations and other parameters shown in

the picture are stored in the SPICE kernels listed below.

Note: these kernels have been selected to support this presentation; they should not be assumed to be
appropriate for user applications.

Parameter Kernel Type File name

----------------------- -------------- ------------
time conversions generic LSK naif0009.tls
CASSINI SCLK cas00084.tsc
satellite orientation CASSINI PCK cpck05Mar2004.tpc
satellite shape CASSINI PCK cpck05Mar2004.tpc
satellite position planet/sat
ephemeris SPK 020514_SE_SAT105.bsp
planet barycenter position planet SPK 981005_PLTEPH-DE405S.bsp
spacecraft position spacecraft SPK 030201AP_SK_SM546_T45.bsp
spacecraft orientation spacecraft CK 04135_04171pc_psiv2.bc
instrument alignment CASSINI FK cas_v37.tf
instrument boresight Instrument IK cas_iss_v09.ti

Writing an Icy-based program 6

 N IF Load kernels
Navigation and Ancillary Information Facility

The easiest and most flexible way to make these kernels available to the program is
via cspice_furnsh. For this example we make a setup file (also called a “metakernel”
or “furnsh kernel”) containing a list of kernels to be loaded:

Note: these kernels have been selected to support this presentation; they
should not be assumed to be appropriate for user applications.
\begindata

KERNELS_TO_LOAD = ('naif0009.tls', 'cas00084.tsc', 'cpck05Mar2004.tpc',

'020514_SE_SAT105.bsp', '981005_PLTEPH-DE405S.bsp',
'030201AP_SK_SM546_T45.bsp', '04135_04171pc_psiv2.bc',
'cas_v37.tf', 'cas_iss_v09.ti')
\begintext

and we make the program prompt for the name of this setup file:

read, setupf, PROMPT='Enter setup file name > '

cspice_furnsh, setupf

Writing an Icy-based program 7

 N IF Programming Solution
Navigation and Ancillary Information Facility

• Prompt for setup file (“metakernel”) name; load kernels specified via setup
file. (Done on previous chart.)

• Prompt for user inputs required to completely specify problem. Obtain

further inputs required by geometry routines via Icy calls.

• Compute the intersection of the boresight direction ray with the surface of
the satellite, presented as a triaxial ellipsoid.

If there is an intersection,

•Convert Cartesian coordinates of the intersection point to planetocentric

latitudinal and planetodetic coordinates
•Compute spacecraft-to-intercept point range
•Find the illumination angles (phase, solar incidence, and emission) at
the intercept point

• Display the results.

We discuss the geometric portion of the problem first.

Writing an Icy-based program 8

 N IF Compute surface intercept
Navigation and Ancillary Information Facility

Compute the intercept point (point) of the boresight vector (insite) specified in
the instrument frame (iframe) of the instrument mounted on the spacecraft (scnm)
with the surface of the satellite (satnm) at the TDB time of interest (et) in the
satellite’s body-fixed frame (fixref). This call also returns the light-time
corrected epoch at the intercept point (trgepc), the spacecraft-to-intercept point
vector (srfvec), and a flag indicating whether the intercept was found (found).
We use "converged Newtonian" light time plus stellar aberration corrections to
produce the most accurate surface intercept solution possible. We model the
surface of the satellite as an ellipsoid.

cspice_sincpt, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, iframe, $

insite, point, trgepc, srfvec, found

The range we want is obtained from the outputs of cspice_sincpt. These

outputs are defined only if a surface intercept is found. If found is true, the
spacecraft-to-surface intercept range is the norm of the output argument srfvec.
Units are km. We use the Icy function cspice_vnorm to obtain the norm:

cspice_vnorm( srfvec )

We'll write out the range data along with the other program results.

Writing an Icy-based program 9

 N IF Compute Lat/Lon and Illumination Angles
Navigation and Ancillary Information Facility

Compute the planetocentric latitude (pclat) and longitude (pclon), as well as

the planetodetic latitude (pdlat) and longitude (pdlon) of the intersection
point.

if ( found ) then begin

cspice_reclat, point, r, pclon, pclat

;; Let re, rp, and f be the satellite's longer equatorial

;; radius, polar radius, and flattening factor.

re = radii[0]
rp = radii[2]
f = ( re – rp ) / re;

cspice_recgeo, point, re, f, pdlon, pdlat, alt

The illumination angles we want are the outputs of cspice_ilumin. Units are
radians.

cspice_ilumin, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $

point, trgepc, srfvec, phase, solar, emissn

Writing an Icy-based program 10

 N IF Geometry Calculations: Summary
Navigation and Ancillary Information Facility

;; Compute the boresight ray intersection with the surface of the

;; target body.
cspice_sincpt, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $
iframe, insite, point, trgepc, srfvec, found
;; If an intercept is found, compute planetocentric and planetodetic
;; latitude and longitude of the point.
if ( found ) then begin
cspice_reclat, point, r, pclon, pclat
;; Let re, rp, and f be the satellite's longer equatorial
;; radius, polar radius, and flattening factor.
re = radii[0]
rp = radii[2]
f = ( re – rp ) / re;
cspice_recgeo, point, re, f, pdlon, pdlat, alt

;; Compute illumination angles at the surface point.

cspice_ilumin, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $

point, trgepc, srfvec, phase, solar, emissn
...
endif else begin
...
Writing an Icy-based program 11
 N IF Get inputs - 1
Navigation and Ancillary Information Facility

The code above used quite a few inputs that we don't have yet:

• TDB epoch of interest ( et );

• satellite and s/c names (satnm, scnm);
• satellite body-fixed frame name (fixref);
• satellite ellipsoid radii (radii);
• instrument fixed frame name (iframe);
• instrument boresight vector in the instrument frame (insite);

Some of these values are user inputs; others can be obtained via Icy calls
once the required kernels have been loaded.

Let's prompt for the satellite name (satnm), satellite frame name (fixref),
spacecraft name (scnm), instrument name (instnm) and time of interest (time):

read, satnm , PROMPT='Enter satellite name > '

read, fixref, PROMPT='Enter satellite frame > '
read, scnm , PROMPT='Enter spacecraft name > '
read, instnm, PROMPT='Enter instrument name > '
read, time , PROMPT='Enter time > '

Writing an Icy-based program 12

 N IF Get Inputs - 2
Navigation and Ancillary Information Facility

Then we can get the rest of the inputs from Icy calls:

To get the TDB epoch (et) from the user-supplied time string (which may
refer to the UTC, TDB or TT time systems):

cspice_str2et, time, et

To get the satellite’s ellipsoid radii (radii):

cspice_bodvrd, satnm, "RADII", 3, radii

To get the instrument boresight direction (insite) and the name of the
instrument frame (iframe) in which it is defined:

cspice_getfvn, instnm, ROOM, shape, iframe, insite, bundry

Writing an Icy-based program 13

 N IF Getting inputs: summary
Navigation and Ancillary Information Facility

;; Prompt for the user-supplied inputs for our program

read, setupf, PROMPT='Enter setup file name > '
cspice_furnsh, setupf

read, satnm , PROMPT='Enter satellite name > '

read, fixref, PROMPT='Enter satellite frame > '
read, scnm , PROMPT='Enter spacecraft name > '
read, instnm, PROMPT='Enter instrument name > '
read, time , PROMPT='Enter time > '
;; Get the epoch corresponding to the input time:
cspice_str2et, time, et
;; Get the radii of the satellite.
cspice_bodvrd, satnm, "RADII", 3, radii

;; Get the instrument boresight and frame name.

cspice_getfvn, instnm, ROOM, shape, iframe, insite, bundry

Writing an Icy-based program 14

 N IF Display results
Navigation and Ancillary Information Facility
;; Display results. Convert angles from radians to degrees for output.
print
print, 'Intercept planetocentric longitude (deg): ', $
cspice_dpr()*pclon
print, 'Intercept planetocentric latitude (deg): ', $
cspice_dpr()*pclat
print, 'Intercept planetodetic longitude (deg): ', $
cspice_dpr()*pdlon
print, 'Intercept planetodetic latitude (deg): ', $
cspice_dpr()*pdlat
print, 'Range from spacecraft to intercept point (km): ', $
cspice_vnorm(srfvec)
print, 'Intercept phase angle (deg): ', $
cspice_dpr()*phase
print, 'Intercept solar incidence angle (deg): ', $
cspice_dpr()*solar
print, 'Intercept emission angle (deg): ', $
cspice_dpr()*emissn
endif else begin
print, 'No intercept point found at ' + time
endelse
END

Writing an Icy-based program 15

 N IF Complete the program
Navigation and Ancillary Information Facility

To finish up the program we need to declare the variables we've used.

• We'll highlight techniques used by NAIF programmers

• Add remaining IDL code required to make a syntactically valid program

PRO PROG_GEOMETRY

ROOM = 10L
setupf = ''
satnm = ''
fixref = ''
scnm = ''
instnm = ''
time = ''
R2D = cspice_dpr()

Writing an Icy-based program 16

 N IF Complete source code - 1
Navigation and Ancillary Information Facility

;; Prompt for the user-supplied inputs for our program.

read, setupf, PROMPT='Enter setup file name > '
cspice_furnsh, setupf
read, satnm , PROMPT='Enter satellite name > '
read, fixref, PROMPT='Enter satellite frame > '
read, scnm , PROMPT='Enter spacecraft name > '
read, instnm, PROMPT='Enter instrument name > '
read, time , PROMPT='Enter time > '
;; Get the epoch corresponding to the input time:
cspice_str2et, time, et

;; Get the radii of the satellite.

cspice_bodvrd, satnm, 'RADII', 3, radii

;; Get the instrument boresight and frame name.

cspice_getfvn, instnm, ROOM, shape, iframe, insite, bundry

Writing an Icy-based program 17

 N IF Complete source code - 2
Navigation and Ancillary Information Facility
;; Compute the boresight ray intersection with the surface of the
;; target body.
cspice_sincpt, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $
iframe, insite, point, trgepc, srfvec, found
;; If an intercept is found, compute planetocentric and planetodetic
;; latitude and longitude of the point.
if ( found ) then begin
cspice_reclat, point, r, pclon, pclat
;; Let re, rp, and f be the satellite's longer equatorial
;; radius, polar radius, and flattening factor.
re = radii[0]
rp = radii[2]
f = ( re - rp ) / re
cspice_recgeo, point, re, f, pdlon, pdlat, alt

;; Compute illumination angles at the surface point.

cspice_ilumin, 'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, $
point, trgepc, srfvec, phase, solar, emissn
;; Display results. Convert angles from radians to degrees
;; for output.
print
print, 'Intercept planetocentric longitude (deg): ', $
R2D*pclon
Writing an Icy-based program 18
 N IF Complete source code - 3
Navigation and Ancillary Information Facility

print, 'Intercept planetocentric latitude (deg): ', $

R2D*pclat
print, 'Intercept planetodetic longitude (deg): ', $
R2D*pdlon
print, 'Intercept planetodetic latitude (deg): ', $
R2D*pdlat
print, 'Range from spacecraft to intercept point (km): ', $
cspice_vnorm(srfvec)
print, 'Intercept phase angle (deg): ', $
R2D*phase
print, 'Intercept solar incidence angle (deg): ', $
R2D*solar
print, 'Intercept emission angle (deg): ', $
R2D*emissn
endif else begin
print, 'No intercept point found at ' + time
endelse

;; Unload the kernels and clear the kernel pool

cspice_kclear
END

Writing an Icy-based program 19

 N IF Compile the program - 1
Navigation and Ancillary Information Facility

Though IDL functions in a manner similar to interpreted languages, it does

compile source files to a binary form.

Ensure that both the Icy Toolkit, and an IDL installation are properly installed.
IDL must load the Icy DLM, icy.dlm/icy.so(dll) to compile those scripts
containing Icy calls. IDL loads DLMs from default locations and from the
current directory when the user ran IDL. The user may also explicitly load a
DLM with the dlm_register command.

Now compile the code.

Writing an Icy-based program 20

 N IF Compile the program - 2
Navigation and Ancillary Information Facility

Terminal Window

IDL> .compile prog_geometry.pro

% Compiled module: PROG_GEOMETRY.

Writing an Icy-based program 21

 N IF Running the program
Navigation and Ancillary Information Facility

It looks like we have everything taken care of:

• We have all necessary kernels

• We made a setup file (metakernel) pointing to them

• We wrote the program

• We compiled the program

Let's run it.

Writing an Icy-based program 22

 N IF Running the program
Navigation and Ancillary Information Facility

Terminal Window

IDL> prog_geometry
Enter setup file name > setup.ker
Enter satellite name > PHOEBE
Enter satellite frame > IAU_PHOEBE
Enter spacecraft name > CASSINI
Enter instrument name > CASSINI_ISS_NAC
Enter time > 2004 jun 11 19:32:00

Intercept planetocentric longitude (deg): 39.843719

Intercept planetocentric latitude (deg): 4.1958778
Intercept planetodetic longitude (deg): 39.843719
Intercept planetodetic latitude (deg): 5.0480106
Range from spacecraft to intercept point (km): 2089.1697
Intercept phase angle (deg): 28.139479
Intercept solar incidence angle (deg): 18.247220
Intercept emission angle (deg): 17.858309

Writing an Icy-based program 23

 N IF Backup
Navigation and Ancillary Information Facility

• Latitude definitions:
– Planetocentric latitude of a point P: angle between segment from
origin to point and x-y plane (red arc in diagram).
– Planetodetic latitude of a point P: angle between x-y plane and
extension of ellipsoid normal vector N that connects x-y plane and
P (blue arc in diagram).

P
N
z-axis
Reference ellipsoid
Planetocentric
Planetodetic
latitude
latitude

O x-y plane
Writing an Icy-based program 24
N IF
Navigation and Ancillary Information Facility

Writing a Mice (MATLAB)

Based Program

April 2023
 N IF Viewing This Tutorial
Navigation and Ancillary Information Facility

Undefined variables are displayed in red

Results are displayed in blue

Please read the tutorial “Preparing for

Programming” prior to attempting the
exercise contained in this tutorial.

Writing a Mice-based program 2

 N IF Introduction
Navigation and Ancillary Information Facility

First, let's go over the important steps in the process of writing a Mice-based
program and putting it to work:

• Understand the geometry problem.

• Identify the set of SPICE kernels that contain the data needed to perform the
computation.
• Select the SPICE APIs needed to compute the quantities of interest.
• Write and execute the program.
• Get actual kernel files and verify that they contain the data needed to support
the computation for the time(s) of interest.
• Run the program.

To illustrate these steps, let's write a program that computes the apparent
intersection of the boresight ray of a given CASSINI science instrument with the
surface of a given Saturnian satellite. The program will compute:

• Planetocentric and planetodetic (geodetic) latitudes and longitudes of the

intercept point.
• Range from spacecraft to intercept point.
• Illumination angles (phase, solar incidence, and emission) at the intercept point.

Writing a Mice-based program 3

 N IF Observation geometry
Navigation and Ancillary Information Facility

We want the boresight on-bo ard clock ephemeris time UTC time

intercept on the surface, range

from s/c to intercept, and
illumination angles at instrument inertial frame

the intercept point. fram e

When? time (UTC, TDB or TT) instrument

surface normal

sp acecraft boresight
emission angle
frame
On what object? satnm spacecraft solar incidence angle
position
In what frame? fixref Phase angle
surface
intersection

body-fixed
For which instrument? instnm frame
planetocentric
latitude
planetocentric
For what spacecraft? scnm longitude

Using what model? setupf

Writing a Mice-based program 4
 N IF Needed Data
Navigation and Ancillary Information Facility

on-bo ard clock ephemeris time UTC time

instrument inertial frame

Time transformation kernels frame

instrument
Orientation models sp acecraft
frame
boresight emission angle surface normal

solar incidence angle

spacecraft
position

Instrument descriptions Phase angle

surface
intersection

body-fixed
frame
planetocentric
Shapes of satellites, planets planetocentric
latitude
longitude

Ephemerides for spacecraft,

Saturn barycenter and satellites.

Writing a Mice-based program 5

 N IF Which Kernels are Needed?
Navigation and Ancillary Information Facility

Data required to compute vectors, rotations and other parameters shown in

the picture are stored in the SPICE kernels listed below.

Note: these kernels have been selected to support this presentation; they should not be assumed to be
appropriate for user applications.

Parameter Kernel Type File name

----------------------- -------------- ------------
time conversions generic LSK naif0009.tls
CASSINI SCLK cas00084.tsc
satellite orientation CASSINI PCK cpck05Mar2004.tpc
satellite shape CASSINI PCK cpck05Mar2004.tpc
satellite position planet/sat
ephemeris SPK 020514_SE_SAT105.bsp
planet barycenter position planet SPK 981005_PLTEPH-DE405S.bsp
spacecraft position spacecraft SPK 030201AP_SK_SM546_T45.bsp
spacecraft orientation spacecraft CK 04135_04171pc_psiv2.bc
instrument alignment CASSINI FK cas_v37.tf
instrument boresight Instrument IK cas_iss_v09.ti

Writing a Mice-based program 6

 N IF Load kernels
Navigation and Ancillary Information Facility

The easiest and most flexible way to make these kernels available to the program is
via cspice_furnsh. For this example we make a setup file (also called a “metakernel”
or “furnsh kernel”) containing a list of kernels to be loaded:

Note: these kernels have been selected to support this presentation; they
should not be assumed to be appropriate for user applications.
\begindata

KERNELS_TO_LOAD = ('naif0009.tls', 'cas00084.tsc', 'cpck05Mar2004.tpc',

'020514_SE_SAT105.bsp', '981005_PLTEPH-DE405S.bsp',
'030201AP_SK_SM546_T45.bsp', '04135_04171pc_psiv2.bc',
'cas_v37.tf', 'cas_iss_v09.ti')
\begintext

and we make the program prompt for the name of this setup file:

setupf = input('Enter setup file name > ', 's');

cspice_furnsh( setupf )

Writing a Mice-based program 7

 N IF Programming Solution
Navigation and Ancillary Information Facility

• Prompt for setup file (“metakernel”) name; load kernels specified via setup
file. (Done on previous chart.)

• Prompt for user inputs required to completely specify problem. Obtain

further inputs required by geometry routines via Mice calls.

• Compute the intersection of the boresight direction ray with the surface of
the satellite, presented as a triaxial ellipsoid.

• If there is an intersection:
• Convert Cartesian coordinates of the intersection point to
planetocentric latitudinal and planetodetic coordinates
• Compute spacecraft-to-intercept point range
• Find the illumination angles (phase, solar incidence, and emission) at
the intercept point

• Display the results.

We discuss the geometric portion of the problem first.

Writing a Mice-based program 8

 N IF Compute surface intercept
Navigation and Ancillary Information Facility

Compute the intercept point (point) of the boresight vector (insite) specified in
the instrument frame (iframe) of the instrument mounted on the spacecraft (scnm)
with the surface of the satellite (satnm) at the TDB time of interest (et) in the
satellite’s body-fixed frame (fixref). This call also returns the light-time
corrected epoch at the intercept point (trgepc), the spacecraft-to-intercept point
vector (srfvec), and a flag indicating whether the intercept was found (found).
We use "converged Newtonian" light time plus stellar aberration corrections to
produce the most accurate surface intercept solution possible. We model the
surface of the satellite as an ellipsoid.

[point, trgepc, srfvec, found] = cspice_sincpt( ...

'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, iframe, insite );

The range we want is obtained from the outputs of cspice_sincpt. These

outputs are defined only if a surface intercept is found. If found is true, the
spacecraft-to-surface intercept range is the norm of the output argument srfvec.
Units are km. We use the MATLAB function norm to obtain the norm:

norm( srfvec )

We'll write out the range data along with the other program results.

Writing a Mice-based program 9

 N IF Compute Lat/Lon and Illumination Angles
Navigation and Ancillary Information Facility

Compute the planetocentric latitude (pclat) and longitude (pclon), as well as

the planetodetic latitude (pdlat) and longitude (pdlon) of the intersection
point.

if ( found )
[r, pclon, pclat] = cspice_reclat( point );

% Let re, rp, and f be the satellite's longer equatorial

% radius, polar radius, and flattening factor.
re = radii(1);
rp = radii(3);
f = ( re - rp ) / re;

[pdlat, pdlat, alt] = cspice_recgeo( point, re, f );

The illumination angles we want are the outputs of cspice_ilumin. Units are
radians.

[trgepc, srfvec, phase, solar, emissn] = cspice_ilumin( ...

'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, point );

Writing a Mice-based program 10

 N IF Geometry Calculations: Summary
Navigation and Ancillary Information Facility

% Compute the boresight ray intersection with the surface of the

% target body.
[point, trgepc, srfvec, found] = cspice_sincpt( ...
'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, iframe, insite );
% If an intercept is found, compute planetocentric and planetodetic
% latitude and longitude of the point.
if ( found )
[r, pclon, pclat] = cspice_reclat( point );
% Let re, rp, and f be the satellite's longer equatorial
% radius, polar radius, and flattening factor.
re = radii(1);
rp = radii(3);
f = ( re - rp ) / re;
[pdlon, pdlat, alt] = cspice_recgeo( point, re, f );
% Compute illumination angles at the surface point.
[trgepc, srfvec, phase, solar, emissn] = cspice_ilumin( ...
'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, point );
...
else
...

Writing a Mice-based program 11

 N IF Get inputs - 1
Navigation and Ancillary Information Facility

The code above used quite a few inputs that we don't have yet:

• TDB epoch of interest ( et );

• satellite and s/c names (satnm, scnm);
• satellite body-fixed frame name (fixref);
• satellite ellipsoid radii (radii);
• instrument fixed frame name (iframe);
• instrument boresight vector in the instrument frame (insite);

Some of these values are user inputs; others can be obtained via Mice calls
once the required kernels have been loaded.

Let's prompt for the satellite name (satnm), satellite frame name (fixref),
spacecraft name (scnm), instrument name (instnm) and time of interest (time):

satnm = input( 'Enter satellite name > ', 's');

fixref = input( 'Enter satellite frame > ', 's');
scnm = input( 'Enter spacecraft name > ', 's');
instnm = input( 'Enter instrument name > ', 's');
time = input( 'Enter time > ', 's');

Writing a Mice-based program 12

 N IF Get Inputs - 2
Navigation and Ancillary Information Facility

Then we can get the rest of the inputs from Mice calls:

To get the TDB epoch (et) from the user-supplied time string (which may
refer to the UTC, TDB or TT time systems):

et = cspice_str2et( time );

To get the satellite’s ellipsoid radii (radii):

radii = cspice_bodvrd( satnm, 'RADII', 3 );

To get the instrument boresight direction (insite) and the name of the
instrument frame (iframe) in which it is defined:

[shape, iframe, insite, bundry] = cspice_getfvn( instnm, ROOM );

Writing a Mice-based program 13

 N IF Getting inputs: summary
Navigation and Ancillary Information Facility

% Prompt for the user-supplied inputs for our program.

setupf = input( 'Enter setup file name > ', 's');
cspice_furnsh( setupf )
satnm = input( 'Enter satellite name > ', 's');
fixref = input( 'Enter satellite frame > ', 's');
scnm = input( 'Enter spacecraft name > ', 's');
instnm = input( 'Enter instrument name > ', 's');
time = input( 'Enter time > ', 's');

% Get the epoch corresponding to the input time:

et = cspice_str2et( time );

% Get the radii of the satellite.

radii = cspice_bodvrd( satnm, 'RADII', 3 );

% Get the instrument boresight and frame name.

[shape, iframe, insite, bundry] = cspice_getfvn( instnm, ROOM );

Writing a Mice-based program 14

 N IF Display results
Navigation and Ancillary Information Facility

...
% Display results. Convert angles from radians to degrees
% for output.
fprintf( 'Intercept planetocentric longitude (deg): %11.6f\n', ...
cspice_dpr()*pclon )
fprintf( 'Intercept planetocentric latitude (deg): %11.6f\n', ...
cspice_dpr()*pclat )
fprintf( 'Intercept planetodetic longitude (deg): %11.6f\n', ...
cspice_dpr()*pdlon )
fprintf( 'Intercept planetodetic latitude (deg): %11.6f\n', ...
cspice_dpr()*pdlat )
fprintf( 'Range from spacecraft to intercept point (km): %11.6f\n', ...
norm(srfvec) )
fprintf( 'Intercept phase angle (deg): %11.6f\n', ...
cspice_dpr()*phase )
fprintf( 'Intercept solar incidence angle (deg): %11.6f\n', ...
cspice_dpr()*solar )
fprintf( 'Intercept emission angle (deg): %11.6f\n', ...
cspice_dpr()*emissn )
else
disp( ['No intercept point found at ' time ] )
end

Writing a Mice-based program 15

 N IF Complete the program
Navigation and Ancillary Information Facility

To finish up the program we need to declare the variables we've used.

• We'll highlight techniques used by NAIF programmers

• Add remaining MATLAB code required to make a syntactically valid
program

ROOM = 10;
R2D = cspice_dpr;

% Prompt for the user-supplied inputs for our program.

setupf = input( 'Enter setup file name > ', 's');
cspice_furnsh( setupf )

satnm = input( 'Enter satellite name > ', 's');

fixref = input( 'Enter satellite frame > ', 's');
scnm = input( 'Enter spacecraft name > ', 's');
instnm = input( 'Enter instrument name > ', 's');
time = input( 'Enter time > ', 's');

Writing a Mice-based program 16

 N IF Complete source code - 1
Navigation and Ancillary Information Facility

% Get the epoch corresponding to the input time:

et = cspice_str2et( time );

% Get the radii of the satellite.

radii = cspice_bodvrd( satnm, 'RADII', 3 );

% Get the instrument boresight and frame name.

[shape, iframe, insite, bundry] = cspice_getfvn( instnm, ROOM );

Writing a Mice-based program 17

 N IF Complete source code - 2
Navigation and Ancillary Information Facility

% Compute the boresight ray intersection with the surface of the

% target body.
[point, trgepc, srfvec, found] = cspice_sincpt( ...
'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, iframe, insite );

% If an intercept is found, compute planetocentric and planetodetic

% latitude and longitude of the point.
if ( found )
[r, pclon, pclat] = cspice_reclat( point );

% Let re, rp, and f be the satellite's longer equatorial

% radius, polar radius, and flattening factor.
re = radii(1);
rp = radii(3);
f = ( re - rp ) / re;

[pdlon, pdlat, alt] = cspice_recgeo( point, re, f );

% Compute illumination angles at the surface point.

[trgepc, srfvec, phase, solar, emissn] = cspice_ilumin( ...
'Ellipsoid', satnm, et, fixref, 'CN+S', scnm, point );

Writing a Mice-based program 18

 N IF Complete source code - 3
Navigation and Ancillary Information Facility
% Display results. Convert angles from radians to degrees
% for output.
fprintf( 'Intercept planetocentric longitude (deg): %11.6f\n',...
R2D*pclon )
fprintf( 'Intercept planetocentric latitude (deg): %11.6f\n',...
R2D*pclat )
fprintf( 'Intercept planetodetic longitude (deg): %11.6f\n',...
R2D*pdlon )
fprintf( 'Intercept planetodetic latitude (deg): %11.6f\n',...
R2D*pdlat )
fprintf( 'Range from spacecraft to intercept point (km): %11.6f\n',...
norm(srfvec) )
fprintf( 'Intercept phase angle (deg): %11.6f\n',...
R2D*phase )
fprintf( 'Intercept solar incidence angle (deg): %11.6f\n',...
R2D*solar )
fprintf( 'Intercept emission angle (deg): %11.6f\n',...
R2D*emissn )
else
disp( ['No intercept point found at ' time ]
end

% Unload the kernels and clear the kernel pool

cspice_kclear

Writing a Mice-based program 19

 N IF Running the program
Navigation and Ancillary Information Facility

It looks like we have everything taken care of:

• We have all necessary kernels

• We made a setup file (metakernel) pointing to them

• We wrote the program

Let's run it.

Writing a Mice-based program 20

 N IF Running the program
Navigation and Ancillary Information Facility

Terminal Window

>> prog_geometry
Enter setup file name > setup.ker
Enter satellite name > PHOEBE
Enter satellite frame > IAU_PHOEBE
Enter spacecraft name > CASSINI
Enter instrument name > CASSINI_ISS_NAC
Enter time > 2004 jun 11 19:32:00

Intercept planetocentric longitude (deg): 39.843719

Intercept planetocentric latitude (deg): 4.195878
Intercept planetodetic longitude (deg): 39.843719
Intercept planetodetic latitude (deg): 5.048011
Range from spacecraft to intercept point (km): 2089.169724
Intercept phase angle (deg): 28.139479
Intercept solar incidence angle (deg): 18.247220
Intercept emission angle (deg): 17.858309

Writing a Mice-based program 21

 N IF Backup
Navigation and Ancillary Information Facility

• Latitude definitions:
– Planetocentric latitude of a point P: angle between segment from
origin to point and x-y plane (red arc in diagram).
– Planetodetic latitude of a point P: angle between x-y plane and
extension of ellipsoid normal vector N that connects x-y plane and
P (blue arc in diagram).

P
N
z-axis
Reference ellipsoid
Planetocentric
Planetodetic
latitude
latitude

O x-y plane
Writing a Mice-based program 22
N IF
Navigation and Ancillary Information Facility

Writing a CSPICE (C)

Based Program

April 2023
 N IF Viewing This Tutorial
Navigation and Ancillary Information Facility

Undefined variables are displayed in red

Results are displayed in blue

Writing a CSPICE-based program 2

 N IF Introduction
Navigation and Ancillary Information Facility

First, let's go over the important steps in the process of writing a CSPICE-based
program and putting it to work:

• Understand the geometry problem.

• Identify the set of SPICE kernels that contain the data needed to perform the
computation.
• Select the SPICE APIs needed to compute the quantities of interest.
• Write and compile the program.
• Get actual kernel files and verify that they contain the data needed to support
the computation for the time(s) of interest.
• Run the program.

To illustrate these steps, let's write a program that computes the apparent
intersection of the boresight ray of a given CASSINI science instrument with the
surface of a given Saturnian satellite. The program will compute

• Planetocentric and planetodetic (geodetic) latitudes and longitudes of the

intercept point.
• Range from spacecraft to intercept.
• Illumination angles (phase, solar incidence, and emission) at the intercept point.

Writing a CSPICE-based program 3

 N IF Observation geometry
Navigation and Ancillary Information Facility

We want the boresight on-bo ard clock ephemeris time UTC time

intercept on the surface, range

from s/c to intercept, and
illumination angles at instrument inertial frame

the intercept point. fram e

When? time (UTC, TDB or TT) instrument

surface normal

sp acecraft boresight
emission angle
frame
On what object? satnm spacecraft solar incidence angle
position
In what frame? fixref Phase angle
surface
intersection

body-fixed
For which instrument? instnm frame
planetocentric
latitude
planetocentric
For what spacecraft? scnm longitude

Using what model? setupf

Writing a CSPICE-based program 4
 N IF Needed Data
Navigation and Ancillary Information Facility

on-bo ard clock ephemeris time UTC time

instrument inertial frame

Time transformation kernels frame

instrument
Orientation models sp acecraft
frame
boresight emission angle surface normal

solar incidence angle

spacecraft
position

Instrument descriptions phase angle

surface
intersection

body-fixed
frame
planetocentric
Shapes of satellites, planets planetocentric
latitude
longitude

Ephemerides for spacecraft,

Saturn barycenter and satellites. sun

Writing a CSPICE-based program 5

 N IF Which Kernels are Needed?
Navigation and Ancillary Information Facility

Data required to compute vectors, rotations and other parameters shown in

the picture are stored in the SPICE kernels listed below.

Note: these kernels have been selected to support this presentation; they should not be assumed to be
appropriate for user applications.

Parameter Kernel Type File name

----------------------- -------------- ------------
time conversions generic LSK naif0009.tls
CASSINI SCLK cas00084.tsc
satellite orientation CASSINI PCK cpck05Mar2004.tpc
satellite shape CASSINI PCK cpck05Mar2004.tpc
satellite position planet/sat
ephemeris SPK 020514_SE_SAT105.bsp
planet barycenter position planet SPK 981005_PLTEPH-DE405S.bsp
spacecraft position spacecraft SPK 030201AP_SK_SM546_T45.bsp
spacecraft orientation spacecraft CK 04135_04171pc_psiv2.bc
instrument alignment CASSINI FK cas_v37.tf
instrument boresight Instrument IK cas_iss_v09.ti

Writing a CSPICE-based program 6

 N IF Load Kernels
Navigation and Ancillary Information Facility

The easiest and most flexible way to make required kernels available to the
program is via furnsh_c. For this example we make a setup file (also called a
“metakernel” or “furnsh kernel”) containing a list of kernels to be loaded:
Note: these kernels have been selected to support this presentation; they
should not be assumed to be appropriate for user applications.

\begindata

KERNELS_TO_LOAD = ('naif0009.tls', 'cas00084.tsc', 'cpck05Mar2004.tpc',

'020514_SE_SAT105.bsp', '981005_PLTEPH-DE405S.bsp',
'030201AP_SK_SM546_T45.bsp', '04135_04171pc_psiv2.bc',
'cas_v37.tf', 'cas_iss_v09.ti')
\begintext

and we make the program prompt for the name of this setup file:

prompt_c ( "Enter setup file name > ", FILESZ, setupf );

furnsh_c ( setupf );

Writing a CSPICE-based program 7

 N IF Programming Solution
Navigation and Ancillary Information Facility

• Prompt for setup file (“metakernel”) name; load kernels specified via setup
file. (Done on previous chart.)

• Prompt for user inputs required to completely specify problem. Obtain

further inputs required by geometry routines via CSPICE calls.

• Compute the intersection of the boresight direction ray with the surface of
the satellite, presented as a triaxial ellipsoid.

If there is an intersection,

•Convert Cartesian coordinates of the intercept point to planetocentric

latitudinal and planetodetic coordinates
•Compute spacecraft-to-intercept point range
•Find the illumination angles (phase, solar incidence, and emission) at
the intercept point

• Display the results.

We discuss the geometric portion of the problem next.

Writing a CSPICE-based program 8

 N IF Compute Surface Intercept and Ranges
Navigation and Ancillary Information Facility

Compute the intercept point (point) of the boresight vector (insite) specified
in the instrument frame (iframe) of the instrument mounted on the spacecraft (scnm)
with the surface of the satellite (satnm) at the TDB time of interest (et) in the
satellite’s body-fixed frame (fixref). This call also returns the light-time corrected
epoch at the intercept point (trgepc), the spacecraft-to-intercept point vector
(srfvec), and a flag indicating whether the intercept was found (found).
We use "converged Newtonian" light time plus stellar aberration corrections to
produce the most accurate surface intercept solution possible. We model the
surface of the satellite as an ellipsoid.

sincpt_c ( "Ellipsoid", satnm, et, fixref, "CN+S", scnm, iframe, insite,

point, &trgepc, srfvec, &found );

The range we want is obtained from the outputs of sincpt_c. These outputs
are defined only if a surface intercept is found. If found is true, the
spacecraft-to-surface intercept range is the norm of the output argument srfvec.
Units are km. We use the CSPICE function vnorm_c to obtain the norm:

vnorm_c ( srfvec )

We'll write out the range data along with the other program results.

Writing a CSPICE-based program 9

 N IF Compute Lat/Lon and Illumination Angles
Navigation and Ancillary Information Facility

Compute the planetocentric latitude (pclat) and longitude (pclon), as well as

the planetodetic latitude (pdlat) and longitude (pdlon) of the intersection
point.

if ( found )
{
reclat_c ( point, &r, &pclon, &pclat );

/* Let re, rp, and f be the satellite's longer equatorial

radius, polar radius, and flattening factor. */
re = radii[0];
rp = radii[2];
f = ( re – rp ) / re;

recgeo_c ( point, re, f, &pdlon, &pdlat, &alt);

The illumination angles we want are the outputs of ilumin_c. Units are radians.

ilumin_c ( "Ellipsoid", satnm, et, fixref, "CN+S", scnm, point,

&trgepc, srfvec, &phase, &solar, &emissn );

Writing a CSPICE-based program 10

 N IF Geometry Calculations: Summary
Navigation and Ancillary Information Facility
/* Compute the boresight ray intersection with the surface of the
target body. */

sincpt_c ( "Ellipsoid", satnm, et, fixref, "CN+S", scnm,

iframe, insite, point, &trgepc, srfvec, &found );
/* If an intercept is found, compute planetocentric and planetodetic
latitude and longitude of the point. */
if ( found )
{
reclat_c ( point, &r, &pclon, &pclat );
/* Let re, rp, and f be the satellite's longer equatorial
radius, polar radius, and flattening factor. */
re = radii[0];
rp = radii[2];
f = ( re – rp ) / re;
recgeo_c ( point, re, f, &pdlon, &pdlat, &alt );
/* Compute illumination angles at the surface point. */
ilumin_c ( "Ellipsoid", satnm, et, fixref, "CN+S", scnm, point,
&trgepc, srfvec, &phase, &solar, &emissn );
...
}
else
{ ... }

Writing a CSPICE-based program 11

 N IF Get Inputs - 1
Navigation and Ancillary Information Facility

The code above used quite a few inputs that we don't have yet:

• TDB epoch of interest ( et );

• satellite and s/c names (satnm, scnm);
• satellite body-fixed frame name (fixref);
• satellite ellipsoid radii (radii);
• instrument fixed frame name (iframe);
• instrument boresight vector in the instrument frame (insite);

Some of these values are user inputs; others can be obtained via CSPICE calls
once the required kernels have been loaded.

Let's prompt for the satellite name (satnm), satellite frame name (fixref),
spacecraft name (scnm), instrument name (instnm) and time of interest (time):

prompt_c ( "Enter satellite name > ", WORDSZ, satnm );

prompt_c ( "Enter satellite frame > ", WORDSZ, fixref );
prompt_c ( "Enter spacecraft name > ", WORDSZ, scnm );
prompt_c ( "Enter instrument name > ", WORDSZ, instnm );
prompt_c ( "Enter time > ", WORDSZ, time );

Writing a CSPICE-based program 12

 N IF Get Inputs - 2
Navigation and Ancillary Information Facility

Then we can get the rest of the inputs from CSPICE calls:

To get the TDB epoch (et) from the user-supplied time string (which may
refer to the UTC, TDB or TT time systems):

str2et_c ( time, &et );

To get the satellite’s ellipsoid radii (radii):

bodvrd_c ( satnm, "RADII", 3, &i, radii );

To get the instrument boresight direction (insite) and the name of the
instrument frame (iframe) in which it is defined:

getfvn_c ( instnm, ROOM, WORDSZ, WORDSZ,

shape, iframe, insite, &n, bundry );

Writing a CSPICE-based program 13

 N IF Getting Inputs: Summary
Navigation and Ancillary Information Facility
/* Prompt for the user-supplied inputs for our program */
prompt_c ( "Enter setup file name > ", FILESZ, setupf );
furnsh_c ( setupf );
prompt_c ( "Enter satellite name > ", WORDSZ, satnm );
prompt_c ( "Enter satellite frame > ", WORDSZ, fixref );
prompt_c ( "Enter spacecraft name > ", WORDSZ, scnm );
prompt_c ( "Enter instrument name > ", WORDSZ, instnm );
prompt_c ( "Enter time > ", WORDSZ, time );
/* Get the epoch corresponding to the input time: */
str2et_c ( time, &et );
/* Get the radii of the satellite. */
bodvrd_c ( satnm, "RADII", 3, &i, radii );
/* Get the instrument boresight and frame name. */
getfvn_c ( instnm, ROOM, WORDSZ, WORDSZ,
shape, iframe, insite, &n, bundry );

Writing a CSPICE-based program 14

 N IF Display Results
Navigation and Ancillary Information Facility
/* Display results. Convert angles from radians to degrees for output. */
printf ( "\n"
"Intercept planetocentric longitude (deg): %11.6f\n"
"Intercept planetocentric latitude (deg): %11.6f\n"
"Intercept planetodetic longitude (deg): %11.6f\n"
"Intercept planetodetic latitude (deg): %11.6f\n"
"Range from spacecraft to intercept point (km): %11.6f\n"
"Intercept phase angle (deg): %11.6f\n"
"Intercept solar incidence angle (deg): %11.6f\n"
"Intercept emission angle (deg): %11.6f\n",
dpr_c() * pclon,
dpr_c() * pclat,
dpr_c() * pdlon,
dpr_c() * pdlat,
vnorm_c( srfvec ),
dpr_c() * phase,
dpr_c() * solar,
dpr_c() * emissn );

}
else
{
printf ( "No intercept point found at %s\n", time );
}

Writing a CSPICE-based program 15

 N IF Complete the Program
Navigation and Ancillary Information Facility

To finish up the program we need to declare the variables we've used.

• We'll highlight techniques used by NAIF programmers

• Add remaining C code required to make a syntactically valid program

Writing a CSPICE-based program 16

 N IF Complete Source Code - 1
Navigation and Ancillary Information Facility
SpiceDouble alt;
SpiceDouble bundry[ROOM][3];
SpiceDouble emissn;
#include <stdio.h>
SpiceDouble et;
#include "SpiceUsr.h"
SpiceDouble f;
SpiceDouble insite[3];
int main ()
SpiceDouble srfvec[3];
{ SpiceDouble pclat;
#define FILESZ 256 SpiceDouble pclon;
#define WORDSZ 41 SpiceDouble pdlat;
#define ROOM 10 SpiceDouble pdlon;
SpiceDouble phase;
SpiceDouble point [3];
SpiceBoolean found; SpiceDouble r;
SpiceDouble radii [3];
SpiceChar iframe[WORDSZ]; SpiceDouble re;
SpiceChar instnm[WORDSZ]; SpiceDouble rp;
SpiceChar satnm [WORDSZ]; SpiceDouble solar;
SpiceChar fixref[WORDSZ]; SpiceDouble trgepc;
SpiceChar scnm [WORDSZ];
SpiceChar setupf[FILESZ]; SpiceInt i;
SpiceChar shape [WORDSZ]; SpiceInt n;
SpiceChar time [WORDSZ];

Writing a CSPICE-based program 17

 N IF Complete Source Code - 2
Navigation and Ancillary Information Facility

/* Prompt for the user-supplied inputs for our program */

prompt_c ( "Enter setup file name > ", FILESZ, setupf );
furnsh_c ( setupf );
prompt_c ( "Enter satellite name > ", WORDSZ, satnm );
prompt_c ( "Enter satellite frame > ", WORDSZ, fixref );
prompt_c ( "Enter spacecraft name > ", WORDSZ, scnm );
prompt_c ( "Enter instrument name > ", WORDSZ, instnm );
prompt_c ( "Enter time > ", WORDSZ, time );
/* Get the epoch corresponding to the input time: */
str2et_c ( time, &et );
/* Get the radii of the satellite. */
bodvrd_c ( satnm, "RADII", 3, &i, radii );
/* Get the instrument boresight and frame name. */
getfvn_c ( instnm, ROOM, WORDSZ, WORDSZ,
shape, iframe, insite, &n, bundry );

Writing a CSPICE-based program 18

 N IF Complete Source Code - 3
Navigation and Ancillary Information Facility
/* Compute the boresight ray intersection with the surface of the
target body. */
sincpt_c ( "Ellipsoid", satnm, et, fixref, "CN+S", scnm,
iframe, insite, point, &trgepc, srfvec, &found );
/* If an intercept is found, compute planetocentric and planetodetic
latitude and longitude of the point. */
if ( found )
{
reclat_c ( point, &r, &pclon, &pclat );
/* Let re, rp, and f be the satellite's longer equatorial
radius, polar radius, and flattening factor. */
re = radii[0];
rp = radii[2];
f = ( re – rp ) / re;
recgeo_c ( point, re, f, &pdlon, &pdlat, &alt );
/* Compute illumination angles at the surface point. */
ilumin_c ( "Ellipsoid", satnm, et, fixref, "CN+S", scnm, point,
&trgepc, srfvec, &phase, &solar, &emissn );
/* Display results. Convert angles to degrees for output. */
printf ( "\n"
"Intercept planetocentric longitude (deg): %11.6f\n"
"Intercept planetocentric latitude (deg): %11.6f\n"

Writing a CSPICE-based program 19

 N IF Complete Source Code - 4
Navigation and Ancillary Information Facility

"Intercept planetodetic longitude (deg): %11.6f\n"

"Intercept planetodetic latitude (deg): %11.6f\n"
"Range from spacecraft to intercept point (km): %11.6f\n"
"Intercept phase angle (deg): %11.6f\n"
"Intercept solar incidence angle (deg): %11.6f\n"
"Intercept emission angle (deg): %11.6f\n",
dpr_c() * pclon,
dpr_c() * pclat,
dpr_c() * pdlon,
dpr_c() * pdlat,
vnorm_c( srfvec ),
dpr_c() * phase,
dpr_c() * solar,
dpr_c() * emissn
);
}
else {
printf ( "No intercept point found at %s\n", time );
}
return(0);
}

Writing a CSPICE-based program 20

 N IF Compile and Link the Program - 1
Navigation and Ancillary Information Facility

• First be sure that both the CSPICE Toolkit and a C compiler

are properly installed.
– A "hello world" C program must be able to compile, link, and run
successfully in your environment.
– Any of the mkprodct.* scripts in the cspice/src/* paths of the CSPICE
installation should execute properly.
• Ways to compile and link the program:
– If you're familiar with the "make" utility, create a makefile. Use compiler
and linker options from the mkprodct.* script found in the
cspice/src/cook_c path of your CSPICE installation.
– Or, modify the cookbook mkprodct.* build script.
» Your program name must be *.pgm, for example demo.pgm, to be
recognized by the script.
» Change the library references in the script to use absolute
pathnames.
» Change the path for the executable to the current working directory.
» If your compiler supports it, add a –I option to reference the
cspice/include path to make CSPICE *.h files available. Otherwise,
copy those files from the include path to your current working
directory.
» On some platforms, you must modify the script to refer to your
program by name.
Writing a CSPICE-based program 21
 N IF Compile and Link the Program - 2
Navigation and Ancillary Information Facility

– Or, compile the program on the command line. The program

must be linked against the CSPICE object library cspice.a
(cspice.lib under MS Visual C++/C) and the C math library. On a
PC running Linux and gcc, if
» The gcc compiler is in your path
• As indicated by the response to the command "which gcc"
» the Toolkit is installed in the path (for the purpose of this
example) /myhome/cspice
» You've named the program demo.c
then you can compile and link your program using the
command
» gcc –I/myhome/cspice/include \
-o demo \
demo.c /myhome/cspice/lib/cspice.a –lm

• Note: the preprocessor flag

-DNON_UNIX_STDIO
used in the mkprodct.csh script is needed for code generated by f2c, but
is usually unnecessary for compiling user code.

Writing a CSPICE-based program 22

 N IF Compile and Link the Program - 3
Navigation and Ancillary Information Facility

Terminal Window

Prompt> mkprodct.csh
Setting default compiler:
gcc

Setting default compile options:

-c -ansi -O2 -DNON_UNIX_STDIO

Setting default link options:

-lm

Compiling and linking: demo.pgm

Compiling and linking: demo.pgm

Prompt>

Writing a CSPICE-based program 23

 N IF Running the Program - 1
Navigation and Ancillary Information Facility

It looks like we have everything taken care of:

• We have all necessary kernels

• We made a setup file (metakernel) pointing to them

• We wrote the program

• We compiled and linked it

Let's run it.

Writing a CSPICE-based program 24

 N IF Running the Program - 2
Navigation and Ancillary Information Facility

Terminal Window
Prompt> demo
Enter setup file name > setup.ker
Enter satellite name > PHOEBE
Enter satellite frame > IAU_PHOEBE
Enter spacecraft name > CASSINI
Enter instrument name > CASSINI_ISS_NAC
Enter time > 2004 jun 11 19:32:00

Intercept planetocentric longitude (deg): 39.843719

Intercept planetocentric latitude (deg): 4.195878
Intercept planetodetic longitude (deg): 39.843719
Intercept planetodetic latitude (deg): 5.048011
Range from spacecraft to intercept point (km): 2089.169724
Intercept phase angle (deg): 28.139479
Intercept solar incidence angle (deg): 18.247220
Intercept emission angle (deg): 17.858309
Prompt>

Writing a CSPICE-based program 25

 N IF Backup
Navigation and Ancillary Information Facility

• Latitude definitions:
– Planetocentric latitude of a point P: angle between segment from
origin to point and x-y plane (red arc in diagram).
– Planetodetic latitude of a point P: angle between x-y plane and
extension of ellipsoid normal vector N that connects x-y plane and
P (blue arc in diagram).

P
N
z-axis
Reference ellipsoid
Planetocentric
Planetodetic
latitude
latitude

O x-y plane
Writing a CSPICE-based program 26
N IF
Navigation and Ancillary Information Facility

Writing a SPICE (FORTRAN)

Based Program

April 2023
 N IF Viewing This Tutorial
Navigation and Ancillary Information Facility

Undefined variables are displayed in red

Results are displayed in blue

Writing a FORTRAN-based program 2

 N IF Introduction
Navigation and Ancillary Information Facility

First, let's go over the important steps in the process of writing a SPICE-based
Fortran program and putting it to work:

• Understand the geometry problem.

• Identify the set of SPICE kernels that contain the data needed to perform the
computation.
• Select the SPICE APIs needed to compute the quantities of interest.
• Write and compile the program.
• Get actual kernel files and verify that they contain the data needed to support
the computation for the time(s) of interest.
• Run the program.

To illustrate these steps, let's write a program that computes the apparent
intersection of the boresight ray of a given CASSINI science instrument with the
surface of a given Saturnian satellite. The program will compute

• Planetocentric and planetodetic (geodetic) latitudes and longitudes of the

intercept point.
• Range from spacecraft to intercept point.
• Illumination angles (phase, solar incidence, and emission) at the intercept point.

Writing a FORTRAN-based program 3

 N IF Observation geometry
Navigation and Ancillary Information Facility

We want the boresight on-bo ard clock ephemeris time UTC time

intercept on the surface, range

from s/c to intercept, and
illumination angles at instrument inertial frame

the intercept point. fram e

When? TIME (UTC, TDB or TT) instrument

surface normal

sp acecraft boresight
emission angle
frame
On what object? SATNM spacecraft solar incidence angle
position
In what frame? FIXREF Phase angle
surface
intersection

body-fixed
For which instrument? INSTNM frame
planetocentric
latitude
planetocentric
For what spacecraft? SCNM longitude

Using what model? SETUPF

Writing a FORTRAN-based program 4
 N IF Needed Data
Navigation and Ancillary Information Facility

on-bo ard clock ephemeris time UTC time

instrument inertial frame

Time transformation kernels frame

instrument
Orientation models sp acecraft
frame
boresight emission angle surface normal

solar incidence angle

spacecraft
position

Instrument descriptions Phase angle

surface
intersection

body-fixed
frame
planetocentric
Shapes of satellites, planets planetocentric
latitude
longitude

Ephemerides for spacecraft, sun

Saturn barycenter and satellites.

Writing a FORTRAN-based program 5

 N IF Which Kernels are Needed?
Navigation and Ancillary Information Facility

Data required to compute vectors, rotations and other parameters shown in

the picture are stored in the SPICE kernels listed below.

Note: these kernels have been selected to support this presentation; they should not be assumed to be
appropriate for user applications.

Parameter Kernel Type File name

----------------------- -------------- ------------
time conversions generic LSK naif0009.tls
CASSINI SCLK cas00084.tsc
satellite orientation CASSINI PCK cpck05Mar2004.tpc
satellite shape CASSINI PCK cpck05Mar2004.tpc
satellite position planet/sat
ephemeris SPK 020514_SE_SAT105.bsp
planet barycenter position planet SPK 981005_PLTEPH-DE405S.bsp
spacecraft position spacecraft SPK 030201AP_SK_SM546_T45.bsp
spacecraft orientation spacecraft CK 04135_04171pc_psiv2.bc
instrument alignment CASSINI FK cas_v37.tf
instrument boresight Instrument IK cas_iss_v09.ti

Writing a FORTRAN-based program 6

 N IF Load Kernels
Navigation and Ancillary Information Facility

The easiest and most flexible way to make required kernels available to the
program is via FURNSH. For this example we make a setup file (also called a
“metakernel” or “furnsh kernel”) containing a list of kernels to be loaded:
Note: these kernels have been selected to support this presentation they
should not be assumed to be appropriate for user applications.

\begindata

KERNELS_TO_LOAD = ('naif0009.tls', 'cas00084.tsc', 'cpck05Mar2004.tpc',

'020514_SE_SAT105.bsp', '981005_PLTEPH-DE405S.bsp',
'030201AP_SK_SM546_T45.bsp', '04135_04171pc_psiv2.bc',
'cas_v37.tf', 'cas_iss_v09.ti')
\begintext

and we make the program prompt for the name of this setup file:

CALL PROMPT ( 'Enter setup file name > ', SETUPF )

CALL FURNSH ( SETUPF )

Writing a FORTRAN-based program 7

 N IF Programming Solution
Navigation and Ancillary Information Facility

• Prompt for setup file (“metakernel”) name load kernels specified via setup
file. (Done on previous chart.)

• Prompt for user inputs required to completely specify problem. Obtain

further inputs required by geometry routines via SPICELIB calls.

• Compute the intersection of the boresight direction ray with the surface of
the satellite, presented as a triaxial ellipsoid.

If there is an intersection,

•Convert Cartesian coordinates of the intercept point to planetocentric

latitudinal and planetodetic coordinates
•Compute spacecraft-to-intercept point range
•Find the illumination angles (phase, solar incidence, and emission) at
the intercept point

• Display the results.

We discuss the geometric portion of the problem next.

Writing a FORTRAN-based program 8

 N IF Compute Surface Intercept and Ranges
Navigation and Ancillary Information Facility

Compute the intercept point (POINT) of the boresight vector (INSITE) specified in
the instrument frame (IFRAME) of the instrument mounted on the spacecraft (SCNM)
with the surface of the satellite (SATNM) at the TDB time of interest (ET) in the
satellite’s body-fixed frame (FIXREF). This call also returns the light-time
corrected epoch at the intercept point (TRGEPC), the spacecraft-to-intercept point
vector (SRFVEC), and a flag indicating whether the intercept was found (FOUND).
We use "converged Newtonian" light time plus stellar aberration corrections to
produce the most accurate surface intercept solution possible. We model the
surface of the satellite as an ellipsoid.

CALL SINCPT ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM, IFRAME,

. INSITE, POINT, TRGEPC, SRFVEC, FOUND )

The range we want is obtained from the outputs of SINCPT. These

outputs are defined only if a surface intercept is found. If FOUND is true, the
spacecraft-to-surface intercept range is the norm of the output argument SRFVEC.
Units are km. We use the SPICELIB function VNORM to obtain the norm:

VNORM ( SRFVEC )

We'll write out the range data along with the other program results.

Writing a FORTRAN-based program 9

 N IF Compute Lat/Lon and Illumination Angles
Navigation and Ancillary Information Facility

Compute the planetocentric latitude (PCLAT) and longitude (PCLON), as well as

the planetodetic latitude (PDLAT) and longitude (PDLON) of the intersection
point.

IF ( FOUND ) THEN
CALL RECLAT ( POINT, R, PCLON, PCLAT )
C Let RE, RP, and F be the satellite's longer equatorial
C radius, polar radius, and flattening factor.
RE = RADII(1)
RP = RADII(3)
F = ( RE - RP ) / RE

CALL RECGEO ( POINT, RE, F, PDLON, PDLAT, ALT )

The illumination angles we want are the outputs of ILUMIN. Units are radians.

CALL ILUMIN ( 'Ellipsoid', SATNM, ET, FIXREF,

. 'CN+S', SCNM, POINT, TRGEPC, SRFVEC,
. PHASE, SOLAR, EMISSN )

Writing a FORTRAN-based program 10

 N IF Geometry Calculations: Summary
Navigation and Ancillary Information Facility
C Compute the boresight ray intersection with the surface of the
C target body.

CALL SINCPT ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM, IFRAME,

. INSITE, POINT, TRGEPC, SRFVEC, FOUND )
C If an intercept is found, compute planetocentric and planetodetic
C latitude and longitude of the point.
IF( FOUND ) THEN

CALL RECLAT ( POINT, R, PCLON, PCLAT )

C Let RE, RP, and F be the satellite's longer equatorial
C radius, polar radius, and flattening factor.
RE = RADII(1)
RP = RADII(3)
F = ( RE - RP ) / RE
CALL RECGEO ( POINT, RE, F, PDLON, PDLAT, ALT )
C Compute illumination angles at the surface point.
CALL ILUMIN ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM,
. POINT, TRGEPC, SRFVEC, PHASE, SOLAR, EMISSN )
...
ELSE
...

Writing a FORTRAN-based program 11

 N IF Get Inputs - 1
Navigation and Ancillary Information Facility

The code above used quite a few inputs that we don't have yet:

• TDB epoch of interest ( ET )

• satellite and s/c names (SATNM, SCNM)
• satellite body-fixed frame name (FIXREF)
• satellite ellipsoid radii (RADII)
• instrument fixed frame name (IFRAME)
• instrument boresight vector in the instrument frame (INSITE)

Some of these values are user inputs others can be obtained via SPICELIB calls
once the required kernels have been loaded.

Let's prompt for the satellite name (SATNM), satellite frame name (FIXREF),
spacecraft name (SCNM), instrument name (INSTNM) and time of interest (TIME):

CALL PROMPT ( 'Enter satellite name > ', SATNM )

CALL PROMPT ( 'Enter satellite frame > ', FIXREF )
CALL PROMPT ( 'Enter spacecraft name > ', SCNM )
CALL PROMPT ( 'Enter instrument name > ', INSTNM )
CALL PROMPT ( 'Enter time > ', TIME )

Writing a FORTRAN-based program 12

 N IF Get Inputs - 2
Navigation and Ancillary Information Facility

Then we can get the rest of the inputs from SPICELIB calls:

To get the TDB epoch (ET) from the user-supplied time string (which may
refer to the UTC, TDB or TT time systems):

CALL STR2ET ( TIME, ET )

To get the satellite’s ellipsoid radii (RADII):

CALL BODVRD ( SATNM, 'RADII', 3, I, RADII )

To get the instrument boresight direction (INSITE) and the name of the
instrument frame (IFRAME) in which it is defined:

CALL GETFVN ( INSTNM, ROOM, SHAPE, IFRAME,

. INSITE, N, BUNDRY )

Writing a FORTRAN-based program 13

 N IF Getting Inputs: Summary
Navigation and Ancillary Information Facility
C Prompt for the user-supplied inputs for our program.
CALL PROMPT ( 'Enter setup file name > ', SETUPF )
CALL FURNSH ( SETUPF )
CALL PROMPT( 'Enter satellite name > ', SATNM )
CALL PROMPT( 'Enter satellite frame > ', FIXREF )
CALL PROMPT( 'Enter spacecraft name > ', SCNM )
CALL PROMPT( 'Enter instrument name > ', INSTNM )
CALL PROMPT( 'Enter time > ', TIME )
C Get the epoch corresponding to the input time:
CALL STR2ET ( TIME, ET )
C Get the radii of the satellite.
CALL BODVRD ( SATNM, 'RADII', 3, I, RADII )
C Get the instrument boresight and frame name.
CALL GETFVN ( INSTNM, ROOM, SHAPE, IFRAME,
. INSITE, N, BUNDRY )

Writing a FORTRAN-based program 14

 N IF Display Results
Navigation and Ancillary Information Facility
C Display results. Convert angles from radians to degrees
C for output.
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetocentric longitude (deg): ', DPR()*PCLON
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetocentric latitude (deg): ', DPR()*PCLAT
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetodetic longitude (deg): ', DPR()*PDLON
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetodetic latitude (deg): ', DPR()*PDLAT
WRITE ( *, '(1X,A,F12.6)' )
. 'Range from spacecraft to intercept point (km): ',
. VNORM(SRFVEC)
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept phase angle (deg): ', DPR()*PHASE
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept solar incidence angle (deg): ', DPR()*SOLAR
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept emission angle (deg): ',
. DPR()*EMISSN
ELSE
WRITE (*,*) 'No intercept point found at '// TIME
END IF

Writing a FORTRAN-based program 15

 N IF Complete the Program
Navigation and Ancillary Information Facility

To finish up the program we need to declare the variables we've used.

• We'll highlight techniques used by NAIF programmers

• Add remaining Fortran code required to make a syntactically valid program

Writing a FORTRAN-based program 16

 N IF Complete Source Code - 1
Navigation and Ancillary Information Facility
PROGRAM PROG26
DOUBLE PRECISION EMISSN
IMPLICIT NONE
DOUBLE PRECISION ET
DOUBLE PRECISION DPR DOUBLE PRECISION F
DOUBLE PRECISION VNORM DOUBLE PRECISION INSITE(3)
DOUBLE PRECISION SRFVEC(3)
DOUBLE PRECISION PCLAT
INTEGER FILESZ DOUBLE PRECISION PCLON
PARAMETER ( FILESZ = 255 ) DOUBLE PRECISION PDLAT
INTEGER WORDSZ DOUBLE PRECISION PDLON
PARAMETER ( WORDSZ = 40 ) DOUBLE PRECISION PHASE
INTEGER ROOM DOUBLE PRECISION POINT (3)
PARAMETER ( ROOM = 10 ) DOUBLE PRECISION R
DOUBLE PRECISION RADII (3)
CHARACTER*(WORDSZ) IFRAME
DOUBLE PRECISION RE
CHARACTER*(WORDSZ) INSTNM
DOUBLE PRECISION RP
CHARACTER*(WORDSZ) SATNM DOUBLE PRECISION SOLAR
CHARACTER*(WORDSZ) FIXREF DOUBLE PRECISION TRGEPC
CHARACTER*(WORDSZ) SCNM
CHARACTER*(FILESZ) SETUPF
CHARACTER*(WORDSZ) SHAPE INTEGER I
CHARACTER*(WORDSZ) TIME INTEGER N
DOUBLE PRECISION ALT
DOUBLE PRECISION BUNDRY(3, ROOM) LOGICAL FOUND

Writing a FORTRAN-based program 17

 N IF Complete Source Code - 2
Navigation and Ancillary Information Facility
C Prompt for the user-supplied inputs for our program.
CALL PROMPT ( 'Enter setup file name > ', SETUPF )
CALL FURNSH ( SETUPF )
CALL PROMPT ( 'Enter satellite name > ', SATNM )
CALL PROMPT ( 'Enter satellite frame > ', FIXREF )
CALL PROMPT ( 'Enter spacecraft name > ', SCNM )
CALL PROMPT ( 'Enter instrument name > ', INSTNM )
CALL PROMPT ( 'Enter time > ', TIME )
C Get the epoch corresponding to the input time:
CALL STR2ET ( TIME, ET )
C Get the radii of the satellite.
CALL BODVRD ( SATNM, 'RADII', 3, I, RADII )
C Get the instrument boresight and frame name.
CALL GETFVN ( INSTNM, ROOM, SHAPE, IFRAME,
. INSITE, N, BUNDRY )

Writing a FORTRAN-based program 18

 N IF Complete Source Code - 3
Navigation and Ancillary Information Facility

C Compute the boresight ray intersection with the surface of the

C target body.
CALL SINCPT ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM, IFRAME,
. INSITE, POINT, TRGEPC, SRFVEC, FOUND )
C If an intercept is found, compute planetocentric and planetodetic
C latitude and longitude of the point.
IF( FOUND ) THEN
CALL RECLAT ( POINT, R, PCLON, PCLAT )
C Let RE, RP, and F be the satellite's longer equatorial
C radius, polar radius, and flattening factor.
RE = RADII(1)
RP = RADII(3)
F = ( RE - RP ) / RE
CALL RECGEO ( POINT, RE, F, PDLON, PDLAT, ALT )
C Compute illumination angles at the surface point.
CALL ILUMIN ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM,
. POINT, TRGEPC, SRFVEC, PHASE, SOLAR, EMISSN )
C Display results. Convert angles from radians to degrees
C for output.
WRITE ( *, * )
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetocentric longitude (deg): ', DPR()*PCLON

Writing a FORTRAN-based program 19

 N IF Complete Source Code - 4
Navigation and Ancillary Information Facility

WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetocentric latitude (deg): ', DPR()*PCLAT
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetodetic longitude (deg): ', DPR()*PDLON
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept planetodetic latitude (deg): ', DPR()*PDLAT
WRITE ( *, '(1X,A,F12.6)' )
. 'Range from spacecraft to intercept point (km): ',
. VNORM(SRFVEC)
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept phase angle (deg): ', DPR()*PHASE
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept solar incidence angle (deg): ', DPR()*SOLAR
WRITE ( *, '(1X,A,F12.6)' )
. 'Intercept emission angle (deg): ',
. DPR()*EMISSN
ELSE
WRITE (*,*) 'No intercept point found at '// TIME
END IF
END

Writing a FORTRAN-based program 20

 N IF Compile and Link the Program - 1
Navigation and Ancillary Information Facility

• First be sure that both the SPICE Toolkit and a

Fortran compiler are properly installed.
– A "hello world" Fortran program must be able to compile, link,
and run successfully in your environment.
– Any of the mkprodct.* scripts in the toolkit/src/* paths of the
SPICE Toolkit installation should execute properly.
• Ways to compile and link the program:
– If you're familiar with the "make" utility, create a makefile. Use
compiler and linker options from the mkprodct.* script found in
the toolkit/src/cookbook path of your SPICE Toolkit installation.
– Or, modify the cookbook mkprodct.* build script.
» Your program name must be *.pgm, for example demo.pgm,
to be recognized by the script.
» Change the library references in the script to use absolute
pathnames.
» Change the path for the executable to the current working
directory.
» On some platforms, you must modify the script to refer to
your program by name.
Writing a FORTRAN-based program 21
 N IF Compile and Link the Program - 2
Navigation and Ancillary Information Facility

– Or, compile the program on the command line. The program

must be linked against the SPICELIB object library spicelib.a
(spicelib.lib under MS Windows systems). On a PC running
Linux and g77, if
» The g77 compiler is in your path
• As indicated by the response to the command "which g77"
» the Toolkit is installed in the path (for the purpose of this
example) /myhome/toolkit
» You've named the program demo.f
then you can compile and link your program using the
command
» g77 -o demo demo.f \
/myhome/toolkit/lib/spicelib.a

Writing a FORTRAN-based program 22

 N IF Compile and Link the Program - 3
Navigation and Ancillary Information Facility

Terminal Window

Prompt> mkprodct.csh
Using the g77 compiler.

Setting default Fortran compile options:

-c -C

Setting default C compile options:

-c

Setting default link options:

Compiling and linking: demo.pgm

Compiling and linking: demo.pgm

Prompt>

Writing a FORTRAN-based program 23

 N IF Running the Program - 1
Navigation and Ancillary Information Facility

It looks like we have everything taken care of:

• We have all necessary kernels

• We made a setup file (metakernel) pointing to them

• We wrote the program

• We compiled and linked it

Let's run it.

Writing a FORTRAN-based program 24

 N IF Running the Program - 2
Navigation and Ancillary Information Facility

Terminal Window
Prompt> demo
Enter setup file name > setup.ker
Enter satellite name > PHOEBE
Enter satellite frame > IAU_PHOEBE
Enter spacecraft name > CASSINI
Enter instrument name > CASSINI_ISS_NAC
Enter time > 2004 jun 11 19:32:00

Intercept planetocentric longitude (deg): 39.843719

Intercept planetocentric latitude (deg): 4.195878
Intercept planetodetic longitude (deg): 39.843719
Intercept planetodetic latitude (deg): 5.048011
Range from spacecraft to intercept point (km): 2089.169724
Intercept phase angle (deg): 28.139479
Intercept solar incidence angle (deg): 18.247220
Intercept emission angle (deg): 17.858309
Prompt>

Writing a FORTRAN-based program 25

 N IF Backup
Navigation and Ancillary Information Facility

• Latitude definitions:
– Planetocentric latitude of a point P: angle between segment from
origin to point and x-y plane (red arc in diagram).
– Planetodetic latitude of a point P: angle between x-y plane and
extension of ellipsoid normal vector N that connects x-y plane and
P (blue arc in diagram).

P
N
z-axis
Reference ellipsoid
Planetocentric
Planetodetic
latitude
latitude

O x-y plane
Writing a FORTRAN-based program 26
N IF
Navigation and Ancillary Information Facility

Making an SPK File

April 2023
 N IF Table of Contents
Navigation and Ancillary Information Facility

• Purpose
• Scope
• Assumptions about user’s knowledge
• SPK overview
• Summary of SPK architecture
• Discussion applicable to all production methods
– Recommended SPK types
• Selecting the polynomial degree (for polynomial SPK types)
• SPK production methods
– Using the “Make SPK” (MKSPK) program
– Using SPICELIB, CSPICE or IDL writer modules (APIs)
• Finishing up, applicable to all methods
– Adding comments
– Validation
– Merging
• Special requirements for making SPKs to be used in DSN/SPS
software for view period generation, scheduling, metric predicts
generation, and related functions.
• Issues affecting performance (reading efficiency) and usability
Making an SPK File 2
 N IF Purpose
Navigation and Ancillary Information Facility

• This tutorial provides guidance for writing an

SPK file using software provided by NAIF:
– the MKSPK application program
or
– SPK writer modules from SPICELIB (FORTRAN), CSPICE (C-
language), Icy (IDL) or Mice (MATLAB) toolkit
» Only partial implementation in Icy and Mice

Making an SPK File 3

 N IF Scope
Navigation and Ancillary Information Facility

• This tutorial addresses production of SPKs:

– for general purposes
– for use with NASA’s Deep Space Network (DSN)

• This tutorial does not address production of SPKs:

– by JPL navigation teams using MONTE and the NIOSPK utility
– by ESA/ESAC for its missions that use SPICE
» Those use custom “MEX2KER” software that was provided by NAIF
– having TCB time tags, in support of certain IAU needs
» These are SPK Types 101, 102, etc.
– use of the OEM2SPK utility, used to process CCSDS* Orbit
Ephemeris Message files
» See the OEM2SPK User’s Guide for this information

*CCSDS = Consultative Committee for Space Data Systems

Making an SPK File 4
 N IF Background Assumptions
Navigation and Ancillary Information Facility

• It is assumed the reader has some familiarity with the SPICE

system, and with basic ideas of orbital mechanics.
– The SPICE Overview tutorial (“spice_overview”) is available at:
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/pdf/individual_docs/
• It is assumed the reader has read the “SPK Tutorial” that
characterizes much of the SPK subsystem, with emphasis on
reading SPK files.
– The SPK “reading” tutorial (“spk”) is available at:
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/pdf/individual_docs/
• It is assumed the reader has available the SPK reference
document entitled “SPK Required Reading,” supplied with
each copy of the SPICE Toolkit (.../doc/spk.req)
– SPK Required Reading is also available at:
https://naif.jpl.nasa.gov/naif/documentation.html

Making an SPK File 5

 N IF SPK References
Navigation and Ancillary Information Facility

• References for SPK production

– “Making an SPK” tutorial (this document)
– “SPK (Ephemeris System)” tutorial (focused on reading an SPK)
– “SPK Required Reading” technical reference (spk.req)
– “MKSPK Users Guide” (mkspk.ug)
– The source code “headers” provided as part of the SPK writer
modules (subroutines)
– “SPKMERGE User’s Guide” (spkmerge.ug)
– “SPY User’s Guide” (spy.ug)

Making an SPK File 6

 N IF Brief Overview - 1
Navigation and Ancillary Information Facility

• You should understand the physics of your data

and how that relates to SPK type. For instance:
– Type 5 works best for an orbit well approximated by a sequence
of one or more conic orbits.
– Types 9 and 13 fit data regardless of the expected physics.
• Caution: a good fit in the mathematical realm may not respect
the physics of the trajectory. For example, fitting polynomials
to an excessively sparse set of states for a planetary orbiter
could result in an interpolated path that intersects the planet.

Making an SPK File 7

 N IF Brief Overview - 2
Navigation and Ancillary Information Facility

• Ordinarily, use the NAIF MKSPK application to

create SPKs from Cartesian state data or conic
elements.
– Depending on your source data, SPK types 5, 9, 10, and 13 will
satisfy the requirements for most users.
» Type 5, yields compact SPK files when the trajectory is well
approximated by piecewise two-body motion. Type 5 may
be the best choice for planetary or solar orbiters when
available state data are sparse.
» Type 9, a good, general choice
» Type 13, when you have very accurate velocity data
» Type 10 applies ONLY to Two Line Element Sets (TLEs).
• Alternatively, use the Toolkit’s SPK writing
subroutines in your own production program.
• Caution: an SPK made for use by the NASA DSN
has additional requirements, discussed later on.
Making an SPK File 8
 N IF
Navigation and Ancillary Information Facility

Summary of SPK Architecture

Making an SPK File 9

 N IF SPK File Structure: The User's View
Navigation and Ancillary Information Facility

Logical Organization of an SPK File

Comment area
Always present

… Segment 1

Possibly present
- sometimes by your choice
- sometimes required
Segment n

Making an SPK File 10

 N IF SPK File Structure - 1
Navigation and Ancillary Information Facility

A minimal SPK file, containing only one segment

Records are fixed-length: 1024 bytes
ID WORD ND NI IFNAME FWD BWD FREE BFF 0 PAD FTP 0 PAD File record: One record.

Comment area: Present only if used. If

Comment area text U* used, one or more records.

N/P/C D1 U Descriptor record: Contains 1 to 25

segment descriptors. One record.

I1 U Segment ID record: Contains 1 to 25

segment IDs. One record.

Segment 1 Data segment: One or more records.

ID WORD: Indicates file architecture and type N/P/C: Next, previous record pointers and descriptor count
ND, NI: Number of d.p. and integer descriptor components Dn: Descriptor for segment n
IFNAME: Internal file name In: Segment ID for segment n
FWD, BWD: Forward and backward linked list pointers
FREE: First free DAF address U: Unused space
BFF: Binary file format ID U*: Possibly unused space
FTP: FTP corruption test string

Making an SPK File 11

 N IF SPK File Structure - 2
Navigation and Ancillary Information Facility
An SPK file containing multiple segments–in this example, 27
Records are fixed-length: 1024 bytes
ID WORD ND NI IFNAME FWD BWD FREE BFF 0 PAD FTP 0 PAD File record: One record

Comment area: Present only if used.

Comment area text U*
Descriptor record: Contains 1 to 25
N/P/C D1 D2 … … D25
segment descriptors. One record.

I1 I2 … … I25 U Segment ID record: Contains 1 to 25

segment IDs. One or more records.

Segment 1
Segment 2 Data segments: One or more records per
segment. (Up to 25 segments.)
...

...
Segment 25 U*
N/P/C D26 D27 U Descriptor record: Contains 1 to 25
segment descriptors. One record.

I26 I27 U Segment ID record: Contains 1 to 25

segment IDs. One or more records.

Segment 26
Data segments: One or more records per
segment. (Up to 25 segments.)
Segment 27
U*
Making an SPK File Diagram not to scale 12
 N IF SPK File Structure - Description
Navigation and Ancillary Information Facility
• File record
– Contents
» Internal file name (set by file creator)
» Architecture and binary file format identifiers
» File structure parameters
» FTP transmission corruption detection string
– Used by SPK reader and writer subroutines
• Comment Area
– A place where “metadata” (data about data) may be placed to help a
user of the SPK file understand the circumstances of its production and
any recommendations about for what uses it was intended
• Descriptor record and Segment ID record
– One of each of these is needed for every collection of 1-to-25 segments
• Segment[s]
– Collection[s] of ephemeris data
» Minimum of one segment
» Maximum:
• The practical maximum is a few thousand segments
• Serious performance degradation occurs above 100000 segments for a single body
• Absolute limits are imposed by the range of the INTEGER data type for your computer
– Numerous SPK types may be used within an SPK file, but only one SPK
type may appear within a given segment
Making an SPK File
– Segments of different types may be intermixed within a given SPK file
13
 N IF What is an SPK Segment?
Navigation and Ancillary Information Facility

• A segment is a collection of information:

» providing ephemeris (position and velocity) of a single object …
» given relative to a single center of motion …
» specified in a single reference frame known to SPICE …
• Either built-in (“hard coded”) or defined in a loaded frames kernel (FK)
» covering a specified, continuous period of time, and
» using a single SPK data type
– Example: ephemeris for the Voyager 2 spacecraft, relative to the center
of the Neptunian system (Neptune’s barycenter), given in the J2000
inertial reference frame, covering a specific period of time, and using
Hermite interpolation with variable length intervals, produced using
SPK Type 13

• An SPK segment must contain enough data to yield an

object’s state at any epoch within the time bounds
associated with the segment
– This has implications that depend on the SPK type being produced

Making an SPK File 14

 N IF
Navigation and Ancillary Information Facility

Discussion applicable to all

SPK production methods

Making an SPK File 15

 N IF The SPK Family
Navigation and Ancillary Information Facility
Type Description Notes
1 Modified divided difference arrays Unique form produced at JPL; not likely to be useful to others.
2 Chebyshev polynomials for position; fixed length time Velocity is obtained by differentiation. Used at JPL for planets.
intervals. Evaluates quickly.
3 Chebyshev polynomials for position and velocity; fixed Separate polynomial sets for position and velocity. Used at JPL for
length time intervals natural satellites.
4 Special form used only by Hubble Space Telescope Not available for general use.
5 Discrete states using weighted two-body propagation Ok if motion very closely approximates two-body motion.
6 Special form of trigonometric expansion of elements for Not available for general use.
Phobos and Deimos
7 Precessing elements Not available for general use.
8 Lagrange interpolation of position and velocity; fixed Use Type 9 unless state spacing is truly uniform when measured
length intervals between states in the TDB system.
9 Lagrange interpolation of position and velocity; variable Versatile type; easy to use with MKSPK.
length intervals between states
10 Weighted two-line element sets (Space Command) Handles both “near-earth” and “deep space” versions.
11 Not used
12 Hermite interpolation of position and velocity; fixed Use Type 13 unless state spacing is truly uniform when measured
length intervals between states in the TDB system.
13 Hermite interpolation of position and velocity; variable Versatile type; easy to use with MKSPK. Use for DSN support.
length intervals between states
14 Chebyshev polynomials for position and velocity, The most flexible of the Chebyshev types.
variable length time intervals
15 Precessing conic elements propagator ---
16 Special form used by ESA’s Infrared Space Observatory Not available for general use.
17 Equinoctial elements Used for some satellites.
18 Emulation of ESOC’s “DDID” format Used for SMART-1, MEX, VEX, and Rosetta
19 Revised emulation of ESOC’s “DDID” format Similar to Type 18, but uses “mini-segments” to reduce the
number of true segments needed. (New in N65 toolkits.)
20 Chebyshev polynomials for velocity; fixed length time Provided to handle ephemerides produced by the Institute of
intervals. Applied Astronomy in St. Petersburg, Russia. (New in N65
toolkits.)

Making an SPK File 21 Modified divided difference arrays Same as Type 1 except allows greater number of coefficients.
16
 N IF Recommended SPK Data Types - 1
Navigation and Ancillary Information Facility

• SPK type 2 (Chebyshev polynomials for position, velocity given by

differentiation) Used at JPL for planetary ephemerides.
• SPK type 3 (Separate Chebyshev polynomials for position and velocity)
Used at JPL for satellite ephemerides.
• SPK type 5 (Weighted two-body extrapolation) Often used for comets
and asteroids, as well as for sparse data sets where a two-body
approximation is acceptable.
• SPK types 9 and 13 (Sliding-window Lagrange and Hermite interpolation
of unequally-spaced states) Often used by users of NAIF’s “Make SPK”
(MKSPK) application.
• SPK type 10 (weighted Space Command two-line element extrapolation)
Often used for earth orbiters.
• SPK type 14 (Separate Chebyshev polynomials for position and velocity,
with variable time steps) This is the most flexible Chebyshev data type.
• SPK type 15 (Precessing conic elements) Provides a very compact
ephemeris representation; limited to orbits where this type of
approximation is valid.
• SPK type 17 (Equinoctial elements) Most suited for representation of
ephemerides of natural satellites in equatorial or near-equatorial orbits.

Making an SPK File 17

 N IF Recommended SPK Data Types - 2
Navigation and Ancillary Information Facility

• Each type has certain properties that may

promote or limit its usefulness in a particular
application. These properties include but are not
limited to the following.
» Ability to model the actual ephemeris to be represented with
the accuracy required for your application.
» Consistency between velocity and derivative of position.
» Evaluation speed (performance).
» Compactness (file size).
» Availability of SPICE software needed to write files of that
type.
• Users are encouraged to consult with NAIF about
the suitability of an SPK type for a particular
purpose.

Making an SPK File 18

 N IF Creating Multiple SPK Segments
Navigation and Ancillary Information Facility
• Each SPK segment must have a single object, center of motion,
reference frame and SPK data type.
• Limiting segment size to 10,000 states or “packets of ephemeris data”
can improve performance when searching within a segment.
– Absolute limits on segment size depend on the size of the INTEGER data type.
• The total number of segments for any one body in a single SPK file must
be kept under the dimension of the SPKBSR segment buffer, currently
set to 100,000.
– The total number of segments for any one body, contributed by all loaded SPK files, must
be kept under the 100K limit.
– For best efficiency, the total number of concurrently loaded segments for all bodies
should be less than this 100K limit. Adherence to this criterion ensures that loaded SPK
files need not be searched repeatedly for segment descriptors (which contain summary
data).
– More details about reading efficiency are provided at the end of this tutorial.
• One may elect to initiate a new segment (or more) as the means for
modeling a propulsive maneuver.
– This is because the SPK reader modules will NOT allow interpolation over a segment
boundary.
• When starting a new segment you may use a new segment identifier, for
instance to indicate a new trajectory leg after a maneuver.
– Can only be done if using SPK writer modules–not if using the MKSPK application.

Making an SPK File 19

 N IF Choosing Polynomial Degree
Navigation and Ancillary Information Facility

• If you make a Type 8 or 9 (Lagrange interpolation) or

a Type 12 or 13 (Hermite interpolation) SPK file you
must specify the degree of the interpolating
polynomial that the SPK reader subroutine will use.
– This choice needs some consideration about desired accuracy, file
size and evaluation speed (performance).
– This choice is also affected by the “smoothness” of the orbit data
you wish to represent with an SPK file.
– The allowed range of degree is 1-to-27. In addition, to ensure
position and velocity continuity over the time span covered by the
orbit data:
» for Types 8 and 9, the polynomial degree must be odd.
» for Types 12 and 13, the polynomial degree must be equivalent
to 3-mod-4, meaning degree 3, 7, 11, 15, 19, 23 or 27.

Making an SPK File 20

 N IF Reference Frame
Navigation and Ancillary Information Facility

• Any reference frame known to the SPICE system,

whether built-in (hard coded) or defined at run time
through a Frames Kernel (FK), may be used for
ephemeris data placed in an SPK file.
– If the frame is provided via an FK, that same FK must be used when
reading the SPK
• Some examples of typical reference frames used:
– Inertial (non-rotating):
» J2000: Earth Mean Equator and Equinox of J2000, a.k.a.
EME2000; J2000 is generally used in SPICE as a label for the
ICRF frame
» ECLIPJ2000: Mean ecliptic and equinox of J2000
– Body-fixed (non-inertial)
» ITRF93: International Terrestrial Reference Frame, for earth
» MOON_PA: Moon Principal Axes

Making an SPK File 21

N IF
Navigation and Ancillary Information Facility

SPK Production Methods

 N IF Choices for Making an SPK File
Navigation and Ancillary Information Facility

• There are two* methods available for making an SPK

file.
1. Take an ephemeris data file produced by your own trajectory
propagator program and input this into the conversion utility
(MKSPK) provided by NAIF that outputs an SPK file.
2. Incorporate the appropriate SPK writer modules (subroutines) into
your own code:
» Add these routines to your trajectory estimator/propagator.
or...
» Write your own “post-processor” conversion utility, similar to
MKSPK mentioned above.
• Both methods are described in the next few pages.

*The OEM2SPK and NIOSPK specialized utilities are

also methods, but are not discussed in this tutorial.
Making an SPK File 23
 N IF Making Your Choice - 1
Navigation and Ancillary Information Facility

• Using the MKSPK program provided in the Toolkit

could be the easiest and safest for many situations.
– Provides considerable flexibility for accepting a wide assortment of
input data formats.
– Allows one to make multi-segment SPK files when the target, center
of motion, reference frame, or SPK type changes.
» But not as straight forward as it could/should be.
• Best done through multiple program executions (although one could
be tricky and accomplish this in a single execution).
• A future version of MKSPK may better accommodate this.
• Note: production of multiple segments in type 5, 8, 9, 12 and 13 SPK
files, when the amount of input data requires this, is automatically
handled.

Making an SPK File 24

 N IF Making Your Choice - 2
Navigation and Ancillary Information Facility

• Using the SPK “writer” modules found in

SPICELIB, CSPICE, Icy and Mice offers the
greatest flexibility and user control.
– Using these requires that you write your own program.
– You’ll likely need to use some additional SPICE modules as
well.

Making an SPK File 25

 N IF
Navigation and Ancillary Information Facility

Using NAIF’s
MKSPK
Application Program

Making an SPK File 26

 N IF Using the MKSPK Utility - 1
Navigation and Ancillary Information Facility

Setup file

ASCII file of NAIF’s

ephemeris MKSPK SPK File
data Program
Optional
comment
file
Possible SPK
data types
Suitable kinds of input ephemeris data are: produced are:

- Table of Cartesian state vectors - Type 05

- Table of conic elements - Type 08
- One or more sets of equinoctial elements - Type 09
- One or more sets of Space Command two- - Type 10
line elements - Type 12
- Type 13
- Type 15
- Type 17

Making an SPK File 27

 N IF Using the MKSPK Utility - 2
Navigation and Ancillary Information Facility

This table indicates which SPK types

can be made from the four kinds
of input data accepted by MKSPK

SPK Type Produced by MKSPK --> 5 8 9 10 12 13 15 17

Input Data Type
Cartesian state vectors Y Y Y N Y Y Y Y
Conic elements Y Y Y N Y Y Y Y
Equinoctial elements N N N N N N N Y
Space Command Two-line elements N N N Y N N N N

Y = Yes N = No

Making an SPK File 28

 N IF Using the MKSPK Utility - 3
Navigation and Ancillary Information Facility

• MKSPK will produce a file consisting of one or more

segments as needed.
– It can write up to 10,000 data points in one segment.
– For multi-segment files based on types 5, 8, 9, 12 and 13, the
program will repeat sufficient data points at both sides of each
interior segment boundary to ensure the SPK file will provide a
continuous ephemeris through the segment boundary epoch.
• You can use MKSPK to add a new segment to an
existing SPK file.
• You can use SPKMERGE to merge two or more SPK
files made from separate executions of MKSPK.
– It’s important to fully understand how SPKMERGE works if you do
this; see the User’s Guide.

Making an SPK File 29

 N IF Using the MKSPK Utility - 4
Navigation and Ancillary Information Facility

• MKSPK does not provide direct/specific means for

including propulsive maneuvers within an SPK file.
– Instead, use either of these two methods.
» Append a new SPK segment to an existing SPK file, using
MKSPK.
» Merge a collection of SPK files, using SPKMERGE.

Making an SPK File 30

 N IF
Navigation and Ancillary Information Facility

Using SPK “Writer” Modules

Making an SPK File 31

 N IF Using SPK Writer Routines
Navigation and Ancillary Information Facility

• The next several charts outline how to use the “SPK writer”
modules available in the Toolkit libraries. The types
available in the supported Toolkits are summarized below.*
SPK Types 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Supported

✔✔ ✔ ✔ ✔✔✔ ✔✔✔✔ ✔✔✔✔✔

SPICELIB
(Fortran 77)

✔✔ ✔ ✔✔✔ ✔✔ ✔ ✔✔ ✔
CSPICE
(C)

✔✔ ✔ ✔✔✔ ✔✔ ✔
ICY
(IDL)

✔✔✔ ✔
MICE
(MATLAB)

= 4, 6, 7, 16: made for special circumstances; not available for general use
= 11: ID was not used

* As of Toolkit version N67

Making an SPK File 32
 N IF What Routines To Use - 1
Navigation and Ancillary Information Facility
For all except SPK type 14
SPKOPN Open a new SPK file. (Use
SPKOPA to append to existing file.)
SPKWxx Write a segment of SPK type xx
.
.
[SPKWxx] [ Write more segments ]
. [ Repeat as needed ]
.
SPKCLS Close the file
[ … ] indicates possible multiple occurrences

These routine names are for the FORTRAN (SPICELIB) Toolkit. For CSPICE
the names are the same but are in lower case and have an “_c” appended. For Icy
and Mice, module names are case-insensitive and have "cspice_" prepended.

Making an SPK File 33

 N IF What Routines To Use - 2
Navigation and Ancillary Information Facility

For SPK type 14

SPKOPN, SPKOPA Open file to add data
SPK14B Begin a new segment
SPK14A Add data to segment
[SPK14A] Add more data
SPK14E End the segment
SPK14B Begin a new segment
SPK14A Add data to segment
Repeat
[SPK14A] Add more data as needed

SPK14E End the segment

etc.
SPKCLS Close the file

Making an SPK File [SPK14A] indicates possible multiple occurrences 34

 N IF Close the SPK File
Navigation and Ancillary Information Facility

• Once you have completed the addition of all

data to your SPK file, be sure to call the
SPKCLS routine to close the file.
– Failure to properly close an SPK file will result in a problem
file having been produced.
• This point is emphasized here because it has
been a frequent problem.

Making an SPK File 35

 N IF
Navigation and Ancillary Information Facility

Finishing Up

Making an SPK File 36

 N IF Not Quite Done Yet
Navigation and Ancillary Information Facility

• You’ve now used either MKSPK or the appropriate

SPK writer routines to produce an SPK file. To
complete the job you should do the following.
– Add comments (metadata) to the comment area of the SPK file.
» This could have been done during execution of MKSPK.
» It can be done after the SPK has been created by using the
Toolkit’s “commnt” utility program.
– Validate the file before sending it off to your customer.
– Consider if there is a need to merge this newly made SPK file with
others.

• See the next several charts for more information on

these subjects.

Making an SPK File 37

 N IF Add Comments (metadata)
Navigation and Ancillary Information Facility

• It is strongly recommended that the producer of an SPK file add

to the file, in the “comment area,” appropriate descriptive
information. Topics should include at least:
– when, how and by whom the file was created,
– intended use for the file,
– cautions or restrictions on how the file is to be used.
• The comments might also include some of these topics.
– Time coverage
– Ephemeris objects included
– Type(s) of data used (in the sense of reconstructed versus predicted)
– Any available estimates of accuracy
– Sources of the data used to produce this SPK file
– Name(s) of previously generated SPK file(s) being replaced by this file
– Any knowledge of plans for future updates to (replacements for) this file
– Name and version number of your SPK production program
– Type of platform (hardware/OS/compiler) on which the SPK file was generated
• If you are modifying an existing SPK file, be sure to check the
existing comments to see if updates are needed in addition to
adding appropriate new ones.
Making an SPK File 38
 N IF How to Add Comments to an SPK
Navigation and Ancillary Information Facility

• Several means are available for adding

comments (metadata) to an SPK file.
– An option in the MKSPK program allows comments
supplied in a separate text file to be added to the
comment area during MKSPK execution.
– Use the “COMMNT” utility program from the SPICE
Toolkit.
» This may be run as an interactive program or in
command line mode within a script.
– If using FORTRAN, C or IDL you can use APIs.
» Not currently supported in MATLAB.

Making an SPK File 39

 N IF Validate the SPK File
Navigation and Ancillary Information Facility

• Validation of SPK files is critical

– Caution is needed more for one-of-a-kind files than for those
generated in a previously tested, unchanging process.
– Some SPICE utility programs might help with your validation.
» SPY: can do a variety of structure and semantic checks.
• SPY is available from the Utilities link of the NAIF website.
» SPKDIFF: used to statistically compare two supposedly similar
SPK files.
• SPKDIFF is available in each Toolkit package and also from the Utilities link of
the NAIF website.
– Consider writing your own validation program.
– Caution: successfully running an SPK summary program (e.g.
BRIEF or SPACIT) or successfully running the format conversion
program (TOXFR or SPACIT) is a positive sign, but is not a
sufficient test.

Making an SPK File 40

 N IF Validate the Overall Process
Navigation and Ancillary Information Facility

• When you first start producing SPK files, or when

changing the SPK “type” used or the kind of
mission (trajectory) to be represented, validation
(or revalidation) of the overall process is advised.
– Validation of not only SPKs, but of end products derived from
SPKs, is advised.

• Consider writing a program that compares states

from your source data with states extracted from
your new SPK file.
– Do this using interpolated states from your source data–not
just the states placed in the SPK file.
– Verify a uniformly good fit over the whole time interval covered
by the file.
Making an SPK File 41
 N IF Common SPK Production Errors
Navigation and Ancillary Information Facility

• Some of the most common SPK production errors

are these
– Picking an SPK type that can not well represent the ephemeris
data you wish to represent
– For Types 8, 9, 12 and 13, picking an invalid polynomial degree
– For Types 8, 9, 12 and 13, picking a polynomial degree that
does not allow high fidelity representation of your source
ephemeris
– For Types 8, 9, 12 and 13, having a HUGE change in time step
size in two time-adjacent SPK segments
– For Types 8, 9, 12 and 13, allowing position and/or velocity data
to have unduly large discontinuities at segment boundaries
– Leaving time gaps between segments (even very small, sub-
second gaps can cause problems for users)
• It takes careful design to avoid, and careful
validation to detect some of these!
Making an SPK File 42
 N IF Make a Merged SPK File ?
Navigation and Ancillary Information Facility

• Sometimes it is helpful to customers if portions of two

or more SPK files are merged into just one.
– (Sometimes the opposite is true, so be careful!)
• If making a merged product is appropriate, use the
SPICE utility SPKMERGE.
– Read the SPKMERGE User’s Guide.
» Be especially aware of how SPKMERGE directives affect the
precedence order of the data being merged. (This is different from
the precedence order that applies when one reads an SPK file or
files.)
– Carefully examine your results (probably using either BRIEF or
SPACIT) to help verify you got what you expected.
• If you’ve made a merged SPK file, check to see that the
included comments are appropriate.

Making an SPK File 43

 N IF Get Help
Navigation and Ancillary Information Facility

• Considering consulting with JPL’s NAIF team for

assistance with:
– picking the SPK type to be used
– picking the method for producing SPK files
– designing tests to validate the process

• Examine SPK files from other missions that could

help you check your process.
– Such files can be found under the "Data" link on the NAIF
website.

Making an SPK File 44

 N IF
Navigation and Ancillary Information Facility

Backup

• Making SPKs for use by the DSN

• SPK reading efficiency

Making an SPK File 45

 N IF DSN Interface Overview
Navigation and Ancillary Information Facility

• SPKs prepared for use in the DSN/SPS may be used in one

or more of four DSN software sets:
– Metric Predicts Generator (MPG)
» Used for view period generation, DSN scheduling and DSN metric
predicts (antenna pointing and tuning of the transmitters and
receivers)
– Telecomm Predicts (UTP/TFP)
» Subsystem for prediction and analysis of telecommunications
signal levels
– Radiometric Modeling and Calibration Subsystem (RMC)
» Used to calibrate atmospheric effects on radio waves
– Delta Differenced One-way Range (Delta-DOR) subsystem
» A special tracking data type providing additional precision to
spacecraft navigation

• All SPKs delivered to the SPS must pass through a front-

end gateway that has some restrictions that go beyond
SPICE requirements; see the next page.

Making an SPK File 46

 N IF SPS Validation Gateway
Navigation and Ancillary Information Facility

• The SPS’ front-end gateway requires:

– an SPK contain data for only one spacecraft
» The presence of non-spacecraft ephemeris data is ok
– an SPK have no data gaps for the spacecraft

• Additionally, for historical reasons, the spacecraft

SPK must be of Type 1 or Type 13
– This restriction could be diminished or removed sometime in
the future if DSN personnel find time to test the Metric Predicts
Generator code using additional SPK data types.

Making an SPK File 47

 N IF SPK Reading: Efficiency Issues - 1
Navigation and Ancillary Information Facility

• SPK file creators should design files to support

efficient read access by those who will use the SPKs.
– This requires knowledge of how SPK file attributes impact efficiency.

• When you store "large" amounts (>10^7 states or data

packets) of ephemeris data in one or more SPK files,
SPK reading efficiency may be affected by:
– SPK segment size
– the number of segments for a body in one SPK file
– the number of segments for a body contributed by multiple SPK files
– the number of loaded segments for all bodies
– the number of loaded files

Making an SPK File 48

 N IF SPK Reading: Efficiency Issues - 2
Navigation and Ancillary Information Facility

• Segment size
– When a segment contains more than 10,000 states or data packets,
the SPK readers will generally take longer to search the segment for
requested data.
» When the segment is larger than this size, more records are read
to look up segment directory information. If these records are not
buffered, more physical records are read from the SPK file.
– There is a trade-off between segment size and numbers of segments
and files.
» It can be preferable to have large segments rather than have "too
many" segments or files. (Read on)

Making an SPK File 49

 N IF SPK Reading: Efficiency Issues - 3
Navigation and Ancillary Information Facility

• Number of segments for a body in one SPK file

– An SPK file MUST not contain more segments for one body
than can be "buffered" at one time.
» The SPK reading system buffers coverage descriptions ("segment
descriptors") for segments it has examined to satisfy previous
requests for state data.
• Don't confuse descriptor buffering with data buffering.
– The SPK reading system also buffers segment DATA, as opposed to
segment descriptors, but this is not relevant to this discussion.
» One fixed-size buffer is used for all SPK segment descriptors.
• The size of this buffer is given by the parameter "STSIZE," declared in
the SPKBSR suite of routines.
• STSIZE is currently set by NAIF to 100,000.
– NAIF recommends that users NOT change this parameter since
maintenance problems may result.
» Unsurprisingly, the system works best when all needed segment
descriptors are buffered simultaneously.

Making an SPK File continued on next page 50

 N IF SPK Reading: Efficiency Issues - 4
Navigation and Ancillary Information Facility

• Number of segments for a body in one SPK file,

continued.
» The buffering scheme is "lazy": no descriptors are buffered for
segments that haven't been examined.
• But when an SPK file is searched for data for a specified body, descriptor data for
ALL segments in the file for that body are buffered.
» The buffering algorithm can "make room" in the buffer by
discarding unneeded, buffered descriptor data.
• A "least cost" algorithm decides which buffered data to discard.
» When more buffer room is needed than can be found:
• The SPK reading system reads data directly from SPK files without
buffering descriptor information.
• This is NOT an error case: the SPK system will continue to provide
correct answers. But the system will run VERY SLOWLY.
– This situation is analogous to "thrashing" in a virtual-memory
operating system.
– If buffer overflow occurs frequently, the SPK reading system may be
too slow to be of practical use.

Making an SPK File 51

 N IF SPK Reading: Efficiency Issues - 5
Navigation and Ancillary Information Facility

• Number of segments for a body contributed by

multiple SPK files:
– Buffer overflow can occur if too many segments for one body are
contributed by multiple loaded SPK files.
» Overflow can take longer to occur than in the single-SPK case,
due to lazy buffering: files that haven't been searched don't
consume buffer space.
• Thus an impending overflow problem may not be detected early in a
program run.
– User applications can avoid buffer overflow if data are appropriately
spread across multiple SPK files.
» Applications can avoid buffer overflow by:
• loading only those files of immediate interest
• unloading files once they're no longer needed

Making an SPK File 52

 N IF SPK Reading: Efficiency Issues - 6
Navigation and Ancillary Information Facility

• Number of segments for all bodies, contributed by all

loaded SPK files:
– Buffer overflow does not result from loading SPK files contributing
more than STSIZE segments for different bodies.
– However, if the total number of loaded segments for bodies of
interest exceeds STSIZE, thrashing can occur as descriptor data are
repeatedly discarded from the buffer and then re-read.
» Loaded segments for bodies for which data are not requested do
not contribute to the problem.
– For best efficiency, load only files contributing fewer than a total of
STSIZE segments for all bodies of interest.
» When more than STSIZE segments are needed, applications
should process data in batches: unload files containing
unneeded data in order to make room for new files.

Making an SPK File 53

 N IF SPK Reading: Efficiency Issues - 7
Navigation and Ancillary Information Facility

• Number of loaded SPK files:

– Up to 5000 SPK files may be loaded at one time by an application.
» The 5000 limit applies to DAF-based files, so loaded C-kernels and
binary PCK kernels count against this limit.
– But loading large numbers of SPK files hurts efficiency:
» Since operating systems usually allow a process to open much
fewer than 5000 files, the SPK system must open and close files
via the host system's file I/O API in order to provide a "virtual"
view of 5000 open files.
• The more such file I/O, the slower an application runs.
» Loading a large number of SPK files could result in a buffering
problem if too many segments are loaded for the bodies of
interest.

Making an SPK File 54

 N IF SPK Reading: Efficiency Issues - 8
Navigation and Ancillary Information Facility

• Recommendations
– Limit segment counts to avoid buffer overflow and thrashing
» Never have more than STSIZE segments for one body in an SPK
file and never have more than STSIZE segments for one body
loaded simultaneously.
» Don't require users to have more than STSIZE segments loaded at
one time.
» If necessary, use larger segments to enable smaller segment
counts.
– Consider distributing SPK data across multiple files …
» so as to make selective SPK loading convenient
• facilitate processing data in batches
» so that loading very large numbers of SPK files at once is
unnecessary

Making an SPK File 55

N IF
Navigation and Ancillary Information Facility

Making a CK file

April 2023
 N IF Summary
Navigation and Ancillary Information Facility

• SPICE provides means to create CK files, either by packaging

orientation computed by others, or by first computing orientation
within SPICE and then packaging it in a CK file
– Packaging of already existing orientation data can be done in two ways:
» Use SPICE CK writer routines by calling them from within your own SPICE-
based application
» Convert a text file containing orientation data to a CK using the Toolkit’s
msopck program
– Computing as well as packaging orientation can be done in two ways:
» Use SPICE geometry routines and CK writer routines by calling them from
within your own SPICE-based application
• Constructing orientation using SPICE routines is not discussed here
» Convert orientation rules and schedules to a CK using the prediCkt
program available from the NAIF website

Making a CK File 2
 N IF CK Writer Routines
Navigation and Ancillary Information Facility

• The SPICE toolkit provides the following CK writer routines for

the FORTRAN, C, IDL and MATLAB toolkits, respectively:
– For Type 1 CK
» CKW01 / ckw01_c / cspice_ckw01
– For Type 2 CK
» CKW02 / ckw02_c / cspice_ckw02
– For Type 3 CK
» CKW03 / ckw03_c / cspice_ckw03
– For Type 4 CK
» CKW04B, CKW04A, CKW04E (no CSPICE, Icy, or Mice wrappers)
– For Type 5 CK
» CKW05 / ckw05_c (no Icy or Mice wrapper)
– For Type 6 CK
» CKW06 (no CSPICE, Icy or Mice wrappers)
• Only the Type 3 writer is discussed in this tutorial
– Writers for Types 1 and 2 have very similar interfaces
– Types 4, 5 and 6 are are not commonly used

Making a CK File 3
 N IF Type 3 Writer Example - 1
Navigation and Ancillary Information Facility

• The following C-language code fragment

illustrates the creation of a Type 3 C-kernel
having a single segment.

ckopn_c ( filename, "my-ckernel", 0, &handle );

/*
Insert code that properly constructs the
sclkdp, quats, avvs, and starts arrays.
*/
ckw03_c ( handle, begtim, endtim, inst,
"ref", avflag, "segid", nrec,
sclkdp, quats, avvs, nints, starts );

ckcls_c ( handle );

Making a CK File 4
 N IF Type 3 Writer Example - 2
Navigation and Ancillary Information Facility

• handle - file handle for the newly created C-kernel.

• begtim, endtim - start and stop times in SCLK
ticks for the segment.
• inst - ID code for the instrument for which the C-
kernel is being made.
• ref - name of the base reference frame. Must be
one known to SPICE during your program execution.
• avflag - a SpiceBoolean indicating whether or not
to include angular velocity in the segment.
• segid - a string identifying the segment. It must be
no more than 40 characters in length.

Making a CK File 5
 N IF Type 3 Writer Example - 3
Navigation and Ancillary Information Facility

• nrec - number of records in sclkdp, quats, and avvs.

• sclkdp - monotonically increasing list of times, given
in SCLK ticks, that identify when quats and avvs were
sampled or calculated.
• quats - a list of SPICE quaternions that rotate vectors
from the base frame specified by the ref argument to
the inst frame.
• avvs - angular rate vectors given in the base frame
specified by the ref argument.
• nints - number of entries in starts.
• starts - a list of SCLK ticks indicating the start of
interpolation intervals. They must correspond to
entries in sclkdp.

Making a CK File 6
 N IF Type 3 writer - Making Up Rates
Navigation and Ancillary Information Facility

• One of the easiest ways to make up angular rates

is to assume a constant rotation rate between
subsequent quaternions:
for(k=0; k<(nrec-1); k++ ) {
q2m_c ( quats[k][0], init_rot );
q2m_c ( quats[k+1][0], final_rot );
mtxm_c ( final_rot, init_rot, rotmat );
raxisa_c ( rotmat, axis, &angle );
sct2e_c ( scid, sclkdp[k], &init_et );
sct2e_c ( scid, sclkdp[k+1], &final_et );
vscl_c ( angle/(final_et-init_et), axis,
&avvs[k][0] ); }
• Then copy the (nrec-1) value of avvs into the last
element of avvs.

Making a CK File
continued on next page 7
 N IF Type 3 Writer - Making Up Rates (2)
Navigation and Ancillary Information Facility

• Constructing angular rates in this fashion

assumes that no more than one 180-degree
rotation has occurred between adjacent
quaternions.
– raxisa_c chooses the smallest angle that performs the
rotation encapsulated in the input matrix.

• Other techniques exist, including differentiating

quaternions. Care must be exercised when taking
that approach.

Making a CK File 8
 N IF MSOPCK
Navigation and Ancillary Information Facility

• msopck makes CK files from orientation data provided in a

time- tagged, space-delimited table in text format
• msopck can process quaternions (SPICE and non-SPICE
styles), Euler angles, or rotation matrices, tagged with UTC,
SCLK, or ET time tags
• msopck requires all program directives to be provided in a
setup file that follows the SPICE text kernel syntax
• msopck has a simple command line interface with the following
usage
msopck setup_file input_data_file output_ck_file
• If the specified output CK already exists, new segment(s) are
appended to it

Making a CK File 9
 MSOPCK
N IF List of Setup File Keywords
Navigation and Ancillary Information Facility
Supporting LSK_FILE_NAME = 'LSK file'
SCLK_FILE_NAME = 'SCLK file' (or MAKE_FAKE_SCLK='new SCLK file')
Kernels/Files FRAMES_FILE_NAME = 'FRAMES file'
COMMENTS_FILE_NAME = 'file containing comments'
PRODUCER_ID = 'producer group/person name'
INTERNAL_FILE_NAME = 'internal file name string'
CK_SEGMENT_ID = 'segment ID string'
Output CK CK_TYPE = 1, 2, or 3
INSTRUMENT_ID = CK ID
Specifications REFERENCE_FRAME_NAME = 'reference frame name'
MAXIMUM_VALID_INTERVAL = interval length, seconds
INPUT_TIME_TYPE = 'SCLK', 'UTC', 'TICKS', 'DPSCLK', or 'ET'
TIME_CORRECTION = bias to be applied to input times, seconds
INPUT_DATA_TYPE = 'MSOP QUATERNIONS', 'SPICE QUATERNIONS',
'EULER ANGLES', or 'MATRICES'
QUATERNION_NORM_ERROR = maximum normalization error
EULER_ANGLE_UNITS = 'DEGREES' or 'RADIANS'
EULER_ROTATIONS_ORDER = ( 'axis3', 'axis2', 'axis1' )
EULER_ROTATIONS_TYPE = 'BODY' or 'SPACE'
Input data ANGULAR_RATE_PRESENT = 'YES', 'NO', 'MAKE UP', 'MAKE UP/NO AVERAGING'
Specifications ANGULAR_RATE_FRAME = 'REFERENCE' or 'INSTRUMENT'
ANGULAR_RATE_THRESHOLD = ( max X rate, max Y rate, max Z rate )
OFFSET_ROTATION_ANGLES = ( angle3, angle2, angle1 )
Optional and OFFSET_ROTATION_AXES = ( 'axis3', 'axis2', 'axis1' )
conditional OFFSET_ROTATION_UNITS = 'DEGREES' or 'RADIANS'
keywords are DOWN_SAMPLE_TOLERANCE = down sampling tolerance, radians
shown in green INCLUDE_INTERVAL_TABLE = 'YES' or 'NO' (default 'YES')
CHECK_TIME_ORDER = 'YES' or 'NO' (default 'NO')
Making a CK File 10
 N IF MSOPCK - Input Details (1)
Navigation and Ancillary Information Facility

Four Examples
INPUT_DATA_TYPE = 'SPICE QUATERNIONS'

Input file: TIME1 [TIME2] QCOS QSIN1 QSIN2 QSIN3 [ARX ARY ARZ ]
..... ....... .... ..... ..... ..... ... ... ...
TIME1 [TIME2] QCOS QSIN1 QSIN2 QSIN3 [ARX ARY ARZ ]

INPUT_DATA_TYPE = 'MSOP QUATERNIONS'

Input file: TIME1 [TIME2] -QSIN1 -QSIN2 -QSIN3 QCOS [ARX ARY ARZ ]
..... ....... ..... ..... ..... .... ... ... ...
TIME1 [TIME2] -QSIN1 -QSIN2 -QSIN3 QCOS [ARX ARY ARZ ]

INPUT_DATA_TYPE = 'EULER ANGLES'

Input file: TIME1 [TIME2] ANG3 ANG2 ANG1 [ARX ARY ARZ ]
..... ...... .... .... .... ... ... ...
TIME1 [TIME2] ANG3 ANG2 ANG1 [ARX ARY ARZ ]

INPUT_DATA_TYPE = 'ROTATION MATRICES'

Input file: TIME1 [TIME2] M11 M12 M13 M21 ... M33 [ARX ARY ARZ ]
..... ...... ... ... ... ... ... ... ... ... ...
TIME1 [TIME2] M11 M12 M13 M21 ... M33 [ARX ARY ARZ ]

Making a CK File 11
 N IF MSOPCK - Input Details (2)
Navigation and Ancillary Information Facility
• Quaternions
– INPUT_DATA_TYPE = 'SPICE QUATERNIONS' indicates the quaternions being
used follow the SPICE formation rules(*)
– INPUT_DATA_TYPE = 'MSOP QUATERNIONS' indicates the quaternions being
used follow the traditional AACS formation rules(*)
» Normally quaternions that come in telemetry are of this type
– QUATERNION_NORM_ERROR keyword may be used to identify and filter out
input records with quaternions that are not unit vectors
» It is set to a tolerance for comparing the norm of the input quaternion
with 1
• Euler angles
– All three angles must be provided
– For the angles provided on the input as
TIME1 [TIME2] ANG3 ANG2 ANG1 [ ARX ARY ARZ ]
and rotation axes specified in the setup as
EULER_ROTATIONS_ORDER = ( 'axis3', 'axis2', 'axis1' )
the matrix rotating vectors from base to the structure frame is computed as
Vinst = [ANG3]axis3 * [ANG2]axis2 * [ANG1]axis1 * Vref
– Angles can be provided in degrees or radians
(*) NAIF prepared a “white paper” explaining differences between various quaternion styles:
Making a CK File https://naif.jpl.nasa.gov/pub/naif/misc/Quaternion_White_Paper/Quaternions_White_Paper.pdf 12
 N IF MSOPCK - Input Details (3)
Navigation and Ancillary Information Facility

• Angular rates are an optional input. Their presence or absence

must be indicated using the ANGULAR_RATE_PRESENT
keyword
– If angular rates are provided (ANGULAR_RATE_PRESENT = 'YES'), they
must be in the form of a 3D vector expressed either in the base frame (less
common) or instrument frame (more common)
» The ANGULAR_RATE_FRAME keyword must be set to indicate which of
the two is used
– If angular rates are not provided, the program can either make a CK without
rates (ANGULAR_RATE_PRESENT = 'NO'), or try to compute rates from the
orientation data by using a uniform rotation algorithm implemented in Type
3 CKs, either with averaging (ANGULAR_RATE_PRESENT = 'MAKE UP') or
without averaging (ANGULAR_RATE_PRESENT = 'MAKE UP/NO
AVERAGING') of the rates computed for adjacent orientation data points
– ANGULAR_RATE_THRESHOLD may be used to identify and filter out input
records with angular rate components that are too large to be real
• Input data can be tagged with UTC, SCLK string, SCLK ticks or
ET, as specified using the INPUT_TIME_TYPE keyword
– Time tags must not have embedded spaces
Making a CK File 13
 N IF MSOPCK - Output Details (1)
Navigation and Ancillary Information Facility
• msopck can generate Type 1, 2, or 3 CKs
– Type 1 is rarely used - only in cases when the input contains very few data
points that are far apart so that interpolation between them makes no sense
– Type 2 is also rarely used, primarily to package orientation for spinning
spacecraft
» Normally the input for making Type 2 CKs should contain two times and
the angular rate in each record
– Type 3 is the most commonly used type because it provides interpolation
between the orientation data points stored in the CK
• Interpolation intervals are determined based on the threshold
value specified in the MAXIMUM_VALID_INTERVAL keyword
– The threshold interval is specified in units of seconds
– A Type 3 CK will allow interpolation between all input points for which the
duration between points is less than or equal to the threshold
• An additional transformation to be combined with the input
attitude may be specified using OFFSET_ROTATION_* keywords
– The convention for specification of the offset rotation angles is the same as
for the input Euler angles
– A vector defined in the base frame is first multiplied by the offset rotation
Vinst = [ROTinput] * [ROToffset] * Vref
Making a CK File 14
 N IF MSOPCK - Output Details (2)
Navigation and Ancillary Information Facility

• The time tags may be adjusted by a constant value, specified

in seconds, using the TIME_CORRECTION keyword
• The order of input time tags can be checked using the
CHECK_TIME_ORDER keyword.
• The output CK file contains one or more CK segments
– Multiple segments are generated if the input data volume is large and
does not fit into the program’s internal buffer (100,000 pointing records)
– When the output file has many segments, each segment’s start time is
equal to the stop time of the previous segment, i.e. there are no gaps at
the segment boundaries
• The Comment area of the output CK contains the following
information:
– Contents of a comment file, if it was specified using the
COMMENT_FILE_NAME keyword
– Contents of the setup file
– Summary of coverage for each segment written to the file, including a
table listing interpolation intervals for segments of Type 2 or 3

Making a CK File 15
 N IF MSOPCK - Example (1)
Navigation and Ancillary Information Facility
Terminal Window
$ more msopck_setup.example
MSOPCK setup for predict M'01 CK generation.
==============================================================================
\begindata
PRODUCER_ID = 'NAIF/JPL'
LSK_FILE_NAME = 'naif0007.tls'
SCLK_FILE_NAME = 'ORB1_SCLKSCET.00001.tsc'
COMMENTS_FILE_NAME = 'msopck_comments.example'
INTERNAL_FILE_NAME = 'sample M01 SC Orientation CK File'
CK_SEGMENT_ID = 'SAMPLE M01 SC BUS ATTITUDE'
INSTRUMENT_ID = -53000
REFERENCE_FRAME_NAME = 'MARSIAU'
CK_TYPE = 3
MAXIMUM_VALID_INTERVAL = 60
INPUT_TIME_TYPE = 'SCLK'
INPUT_DATA_TYPE = 'MSOP QUATERNIONS'
QUATERNION_NORM_ERROR = 1.0E-3
ANGULAR_RATE_PRESENT = 'MAKE UP'
\begintext
$

Making a CK File 16
 N IF MSOPCK - Example (2)
Navigation and Ancillary Information Facility
Terminal Window
$ more msopck_comments.example

Sample Mars Surveyor '01 Orbiter Spacecraft Orientation CK File

===========================================================================

Orientation Data in the File

--------------------------------------------------------

This file contains sample orientation for the Mars Surveyor ‘01
Orbiter (M01) spacecraft frame, 'M01_SPACECRAFT', relative
to the Mars Mean Equator and IAU vector of J2000, 'MARSIAU', inertial
frame. The NAIF ID code for the 'M01_SPACECRAFT' frame is -53000.

Status
--------------------------------------------------------

This file is a special sample C-Kernel file created by NAIF to illustrate

MSOPCK program. This file should not be used for any other purposes.

...

Making a CK File 17
 N IF MSOPCK - Example (3)
Navigation and Ancillary Information Facility
Terminal Window
$ more msopck_input.example
0767491368.064 -0.24376335 0.68291384 0.28475901 0.62699316
0767491372.114 -0.24249471 0.68338563 0.28591829 0.62644323
0767491373.242 -0.24204185 0.68355329 0.28633291 0.62624605
0767491374.064 -0.24194814 0.68358228 0.28641744 0.62621196
0767491380.064 -0.24012676 0.68424169 0.28807922 0.62543010
0767491386.064 -0.23830473 0.68489895 0.28973563 0.62464193
0767491392.064 -0.23648008 0.68555126 0.29139303 0.62384833
0767491398.064 -0.23465389 0.68620253 0.29304524 0.62304745
0767491404.064 -0.23282999 0.68684150 0.29470173 0.62224580
0767491404.114 -0.23277293 0.68686688 0.29475362 0.62221455
0767491405.242 -0.23231585 0.68702790 0.29516507 0.62201253
0767491410.064 -0.23100059 0.68748174 0.29634561 0.62143935
0767491416.064 -0.22917353 0.68811325 0.29799308 0.62062853
0767491422.064 -0.22734161 0.68874177 0.29963482 0.61981412
0767491428.064 -0.22551078 0.68936246 0.30128030 0.61899473
0767491434.064 -0.22367453 0.68998299 0.30291779 0.61816987
0767491436.114 -0.22300583 0.69021050 0.30351804 0.61786298
0767491438.011 -0.22251770 0.69037871 0.30395477 0.61763631
...

Making a CK File 18
 N IF MSOPCK - Example (4)
Navigation and Ancillary Information Facility
Terminal Window
$ msopck msopck_setup.example msopck_input.example msopck_example_ck.bc

MSOPCK Utility Program, Version 3.0.0, 2003-05-05; SPICE Toolkit Ver. N0057
...
<comment file contents>
...
<setup file contents>
...
********************************************************************************
RUN-TIME OBTAINED META INFORMATION:
********************************************************************************
PRODUCT_CREATION_TIME = 2004-04-29T12:17:55
START_TIME = 2004-04-27T00:00:05.516
STOP_TIME = 2004-04-27T23:59:56.275
********************************************************************************
INTERPOLATION INTERVALS IN THE FILE SEGMENTS:
********************************************************************************
SEG.SUMMARY: ID -53000, COVERG: 2004-04-27T00:00:05.516 2004-04-27T23:59:56.275
--------------------------------------------------------------------------------
2004-04-27T00:00:05.516 2004-04-27T20:05:26.282
2004-04-27T20:11:20.278 2004-04-27T23:59:56.273

Making a CK File 19
 N IF PREDICKT
Navigation and Ancillary Information Facility

• prediCkt makes CK files from a set of orientation

specification rules, and schedules defining when these
rules are to be followed
• prediCkt has a simple command line interface
• prediCkt requires orientation and schedule specifications to
be provided in a setup file that follows the SPICE text kernel
syntax
• prediCkt requires the names of all supporting kernels --
SPK, PCK, etc -- be provided in a meta-kernel (a “furnsh
kernel”)
• prediCkt and its User Guide are available only from the
Utilities link of the NAIF webpages

Making a CK File 20
 N IF PREDICKT - Usage
Navigation and Ancillary Information Facility

• prediCkt has the following command line arguments

-furnish support_data
-spec ck_specs
-ck outfile
-tol fit_tolerance [units]
-<sclk|newsclk> sclk_kernel
• ‘-furnish’, ‘-spec’ and ‘-ck’ are used to specify the input meta-
kernel, input attitude specification file and output CK file
• ‘-tol’ is used to specify the tolerance to which the orientation
stored in the CK should match the specified attitude profile
• ‘-sclk’ or ‘-newsclk’ specify the name of an existing SCLK or
the new “fake” SCLK to be created for use with the output CK

Making a CK File 21
 N IF PREDICKT - Furnsh and Spec Files
Navigation and Ancillary Information Facility

• A “FURNSH” kernel lists SPICE kernels that are

to be used by prediCkt to determine geometry
needed to compute orientations
• A prediCkt attitude specification (spec) file,
using the text kernel syntax, is used to provide
three types of information:
– specification of dynamic directions
– specification of orientations based on these directions
– specification of the schedules defining when those
orientations should be followed
• The contents of the FURNSH kernel and the spec
file are included in the comment area of the
output CK file

Making a CK File 22
 N IF PREDICKT - Directions
Navigation and Ancillary Information Facility

• Dynamic directions can be of the following types

– Based on ephemeris (position vectors, velocity vectors)
– Fixed with respect to a reference frame (expressed as a Cartesian vector
or specified by RA and DEC)
– Towards sub-observer point
– Based on the surface normal and lines of constant latitude or longitude
– Based on other, already defined directions (rotated from them,
computed as cross products using them, etc)
• Example: these two sets of keyword assignments specify
nadir and spacecraft velocity directions for the M01
spacecraft
DIRECTION_SPECS += ( 'ToMars = POSITION OF MARS -' )
DIRECTION_SPECS += ( 'FROM M01 -' )
DIRECTION_SPECS += ( 'CORRECTION NONE' )
DIRECTION_SPECS += ( 'scVelocity = VELOCITY OF M01 -' )
DIRECTION_SPECS += ( 'FROM MARS -' )
DIRECTION_SPECS += ( 'CORRECTION NONE' )

Making a CK File 23
 N IF PREDICKT - Orientations
Navigation and Ancillary Information Facility

• An orientation is specified by:

– defining that one of the frame’s axes (+X,+Y,+Z,-X,-Y,-Z) points
exactly along one of the defined directions
– defining that another of the frame’s axes points as closely as
possible to another defined direction
» The third axis is the cross product of the first two
– specifying the base frame with respect to which the orientation of
this “constructed” frame is to be computed

• Example: these keyword assignments specify the

nominal nadir orientation for the THEMIS
instrument, flown on the M01 spacecraft
ORIENTATION_NAME += 'CameratoMars'
PRIMARY += '+Z = ToMars'
SECONDARY += '+Y = scVelocity'
BASE_FRAME += 'J2000'

Making a CK File 24
 N IF PREDICKT - Schedules (1)
Navigation and Ancillary Information Facility

• A schedule is defined by specifying a series of time

intervals during which a given orientation is to be
followed
– For each interval for a given CK ID, the spec file defines the
orientation name, start time, and stop time (as Ephemeris Times)

• Example: these spec file keyword assignments

specify a schedule with a single window during which
M01 (Mars Odyssey) will yield nadir-pointed
orientation for the THEMIS instrument
CK-SCLK = 53
CK-SPK = -53
CK-FRAMES += -53000
CK-53000ORIENTATION += 'SOLUTION TO M01_THEMIS_IR = CameratoMars'
CK-53000START += @2004-FEB-10-00:00
CK-53000STOP += @2004-FEB-15-00:00

Making a CK File 25
 N IF PREDICKT - Schedules (2)
Navigation and Ancillary Information Facility

• In the example on the previous slide:

– the CK-FRAMES keyword specifies the CK ID to be used in the output CK

» This ID is incorporated into the keywords defining the schedule
intervals

– the CK-SCLK keyword specifies the ID of the SCLK kernel to be used in

creating the CK

– the CK-SPK keyword specifies the ID of the object, the position of which
is used in applying light time correction when orientation is computed

– the “SOLUTION TO” construct specifies that although the orientation is

sought for the M01 spacecraft frame (ID -53000), it is computed for the
camera frame (M01_THEMIS_IR) and then transformed to the spacecraft
frame

Making a CK File 26
 N IF PREDICKT - Example (1)
Navigation and Ancillary Information Facility
Terminal Window
$ cat m01_map_nadir.prediCkt
\begindata
DIRECTION_SPECS += ( 'ToMars = POSITION OF MARS -' )
DIRECTION_SPECS += ( 'FROM M01 -' )
DIRECTION_SPECS += ( 'CORRECTION NONE' )

DIRECTION_SPECS += ( 'scVelocity = VELOCITY OF M01 -' )

DIRECTION_SPECS += ( 'FROM MARS -' )
DIRECTION_SPECS += ( 'CORRECTION NONE' )

ORIENTATION_NAME += 'CameratoMars'
PRIMARY += '+Z = ToMars'
SECONDARY += '+Y = scVelocity'
BASE_FRAME += 'J2000'

CK-SCLK = 53
CK-SPK = -53
CK-FRAMES += -53000
CK-53000ORIENTATION += 'SOLUTION TO M01_THEMIS_IR = CameratoMars'
CK-53000START += @2004-FEB-10-00:00
CK-53000STOP += @2004-FEB-15-00:00
\begintext

Making a CK File 27
 N IF PREDICKT - Example (2)
Navigation and Ancillary Information Facility
Terminal Window
$ cat m01_map_nadir.furnsh
\begindata
KERNELS_TO_LOAD = ( 'naif0007.tls'
'm01_v26.tf'
'mar033-5.bsp'
'm01_map_rec.bsp'
'm01.tsc' )
\begintext
$ prediCkt -furnish m01_map_nadir.furnsh -spec m01_map_nadir.prediCkt -ck m01_map_nadir.bc -tol
0.01 degrees -sclk m01.tsc

Begin Segment: 1 --- SOLUTION TO M01_THEMIS_IR = CameratoMars

Constructing Segment
From: 2004 FEB 10 00:00:00.000
To : 2004 FEB 15 00:00:00.000
Percentage finished: 0.0%
Percentage finished: 5.0 % (50 quaternions)
...
Percentage finished: 95.0 % (925 quaternions)
$

Making a CK File 28
N IF
Navigation and Ancillary Information Facility

Overview of the Events Kernel

EK

April 2023

Note: the EK is infrequently used by NASA flight projects.

Only a brief overview of the EK subsystem is provided.
 N IF Scope
Navigation and Ancillary Information Facility

• This tutorial provides an overview of the entire

Events Kernel subsystem, comprised of three
logical components:
– Science Plan ESP
– Sequence ESQ
– Notebook ENB

• Depending on specific circumstances:

– the three logical components might exist as three distinct and
different mechanisms
– two or all three logical components might be implemented with
a single mechanism
– one or more logical components may not be used

Intro to EK Subsystem 2
 N IF E-Kernel Subsystem Objectives
Navigation and Ancillary Information Facility

• Assemble, archive and provide convenient and

useful access to plans, commands and notes
about the acquisition of space science
observations

– For use by on-going project science and engineering team

members
– For use by post-mission researchers

• Accomplish the above with minimal impact on

science and mission operations team members

Intro to EK Subsystem 3
 N IF Nominal E-kernel Composition*
Navigation and Ancillary Information Facility

Objectives Mission
for Commands Scientist’s Logical
Operations Component
Science and Activities Notebook
Logs View
Observations

Science Plan Sequence Notebook Physical

Component Component Component Component
View

* As originally envisioned by NAIF

Intro to EK Subsystem 4
 N IF Nominal E-kernel Implementation*
Navigation and Ancillary Information Facility

Sequence Science Plan Notebook Physical

Component Component Component Component
(ESQ) (ESP) (ENB) View*

DBK Web + Implementation*

Database Kernel
DBK

* As originally implemented by NAIF

Intro to EK Subsystem 5
 N IF Science Plan - ESP
Navigation and Ancillary Information Facility

• Each entry is a statement of science objectives

for a series of coordinated observations to be
made over a stated period of time
– Might include some information about the planned mechanics
(observation design) for obtaining the data

• The Science Plan (ESP) could be implemented as

a part of the SEQUENCE component (ESQ), or as
a part of the NOTEBOOK component (ENB), or as
a separate product using some other mechanism

Intro to EK Subsystem 6
 N IF Sequence - ESQ
Navigation and Ancillary Information Facility

• Principal entries are instrument and spacecraft

“commands” or “macro calls” that carry out the
objectives of the Science Plan. These contain the
lowest level of detail that could be helpful while also
being practical for inclusion in the E-kernel product
– Could include ground system events, such as tracking station status
– Could include “announcements” of the occurrence of geometric
conditions of wide interest, such as equator crossing, occultation
entry, etc.
– Could include “state records” that summarize the status of an
instrument or subsystem or spacecraft at a given epoch. (If to be
included, state records might be derived rather than actually stored
as physical objects.)
• CAUTION: within NASA this kind of information might
be restricted under ITAR
Intro to EK Subsystem 7
 N IF Notebook - ENB
Navigation and Ancillary Information Facility

• Entries are notes provided by scientists and flight

team engineers about what happened as mission
operations are conducted, including unplanned,
unanticipated or unexplained occurrences
• Entries could also be general notes thought to be of
interest to scientists
• Two methods for providing entries are available
– Entries submitted using e-mail can include MIME attachments, such
as GIF, JPEG, EXCEL, WORD, etc., in addition to plain ASCII text
– Entries submitted using WWW are limited to plain ASCII text

Intro to EK Subsystem 8
 N IF E-Kernel Status
Navigation and Ancillary Information Facility

• The E-kernel is the least well developed and least

used component of the SPICE system
– It’s of less interest to flight project instrument and engineering
teams as compared to the other SPICE components
» Their perception is that EK information could be useful to
future users of a mission’s data, but not so much to an active
flight team, and since they are already very busy they have
not enough time to contribute inputs to an EK

• Unfortunately NAIF and other kernel producers

seem unlikely to produce EK components in the
future

Intro to EK Subsystem 9
N IF
Navigation and Ancillary Information Facility

SPICE Development Plans

and Possibilities

April 2023
 N IF SPICE 2.0
Navigation and Ancillary Information Facility

• Develop SPICE 2.0: a re-implementation of the

SPICE Toolkit from the ground, up, providing
thread-safe and object oriented features
– This is the major NAIF undertaking, started in May 2017
– It is being implemented in C++11
– It is expected to take several years

• More details in “SPICE 2.0 Preview” Tutorial

(available upon request)

• No worries: none of the current Toolkits will be

dropped.

Plans and Possibilities for Further Development 2

 N IF DSK Shape Models
Navigation and Ancillary Information Facility

• Extension of the DSK shape model subsystem

– Complete the Type 4 DSK code for working with digital elevation
models developed for SMAP

– Add more functionality to the tessellated plate model (Type 2 DSK)

» The first official version of the Type 2 subsystem, for small,
irregularly shaped bodies, was released in the N66 Toolkits

– Unfortunately NAIF has no real target date in mind for this work

Plans and Possibilities for Further Development 3

 N IF Tool Development
Navigation and Ancillary Information Facility

• Continue adding capabilities to the WebGeocalc

tool
– More kinds of calculations
– More ease-of-use features
– This work is on-going

• Continue adding capabilities to the Cosmographia

3D mission visualization program
– This work is on-going

Plans and Possibilities for Further Development 4

 N IF Support for More Languages- 1
Navigation and Ancillary Information Facility

• Complete the Java Native Interface (JNISpice)

Toolkit family
– Capability is parallel to CSPICE, and reliability is very good
» NAIF used JNISpice to implement the WebGeocalc tool
– Additional documentation needs to be written

• Python interface
– 3rd party SpiceyPy enjoys wide adoption and use,
fulfilling the needs of the community
– Because of that, NAIF does not plan to do its own
Python work in the foreseeable future

Plans and Possibilities for Further Development 5

 N IF Support for More Languages- 2
Navigation and Ancillary Information Facility

• 3rd parties have also implemented Ruby, Swift,

Julia, Rust, Unreal Engine interfaces to CSPICE
– NAIF server provides links to some of them
» https://naif.jpl.nasa.gov/naif/links.html
– NAIF hasn’t tried testing any of these packages
– NAIF does not know how complete they are
– Give them a try, but use due caution as you do so
» You might be able to do some one-off tests using the
WebGeocalc tool as a “gold bar”
» You could try using the “spice_discussion” bulletin board
to see what other people have to say about these
interfaces

Plans and Possibilities for Further Development 6

 N IF Some Other Possibilities?
Navigation and Ancillary Information Facility

• More high-level SPICE 1.0 (current SPICE)

computations, such as specular point
• More “geometry finder” computations
• Develop a more flexible and extensible instrument
modeling mechanism

Plans and Possibilities for Further Development 7

 N IF Programmatic Expansion
Navigation and Ancillary Information Facility

• NAIF is helping the Republic of South Korea

implement SPICE on their Korean Pathfinder
Lunar Orbiter (KPLO) mission

• Colleagues at LASP are helping the United Arab

Emirates deploy SPICE in support of their
upcoming Hope mission to Mars

• We hope to find the means to support upcoming

planetary science-focused SmallSat/CubeSat
missions and Commercial Lunar Payload Systems
(CLPS) program

Plans and Possibilities for Further Development 8

 N IF What do You Suggest?
Navigation and Ancillary Information Facility

• NAIF solicits suggestions from you!

– How might we improve SPICE?
– How might we improve SPICE training?
– How might we improve NAIF’s operations?
– How might we improve SPICE operability across the large and still
growing space exploration community?

• We’re interested in programmatic ideas as well as

technical ones.

Plans and Possibilities for Further Development 9

N IF
Navigation and Ancillary Information Facility

Porting Kernels

April 2023
 N IF Porting Issues - 1
Navigation and Ancillary Information Facility

• Data formats vary across platforms, so data files

created on platform “X” may not be usable on
platform “Y.”
– Binary formats: different platforms use different bit
patterns to represent numbers (and possibly characters).
– Text formats: different platforms use different mechanisms
to represent “lines” in text files.
– Usually a “line terminator character sequence”
indicates end-of-line.
• We say two platforms have “compatible” binary or
text formats if they use the same binary or text data
representations.
• We say that a file is “native” if its format is the same
as that of the computer you are using.
Porting Kernels 2
 N IF Porting Issues - 2
Navigation and Ancillary Information Facility

• Toolkit software can usually read kernels obtained

from an incompatible platform
– Binary SPK, CK, PCK and DSK kernels from one system can
always be read on an incompatible system
– Text kernels from one system can be read on an
incompatible system only when using a C, IDL, MATLAB or
JNI: not when using Fortran

• See later charts for compatibility matrix

Porting Kernels 3
 N IF Porting Issues - 3
Navigation and Ancillary Information Facility

• When conversion to native format is required to make

the kernel usable (see a later chart), several options
are available.
– Use bingo for both binary and text kernels
– Available only from the NAIF website; not provided in Toolkit
packages
– For text kernels, doing your file download using ftp in ASCII mode
will perform the required format conversion on the fly
– Web browsers often do text format conversion
– However ASCII mode may not be available – sftp clients usually
don’t provide it. In such cases other tools such as freeware
dos2unix and unix2dos, or bingo from the SPICE utilities page,
must be used.
– For binary kernels, the SPICE toxfr and tobin tools may be used to
convert files to and from SPICE transfer format
– This is an ASCII-based format that may be transferred in the
same way as other ASCII files.
Porting Kernels 4
 Compatible Environments
N IF for Text Kernels
Navigation and Ancillary Information Facility

Since text kernels are only text files…

Groupings of Text Compatible End of line indicator

Environments
1 PC using Windows or NT <CR><LF>
2 Unix <LF>
PC with LINUX
Macintosh OSX (Motorola,
Intel, or M1 chip)

On a Unix/Linux/OSX box you can easily see what kind of line terminator
is being used in a text file using the Unix “cat –et” command on your
text file.

<CR> tokens will appear as ”^M”

<LF> tokens will appear as “$”

Porting Kernels 5
 Compatible Environments
N IF for Binary Kernels
Navigation and Ancillary Information Facility

Groupings of Binary Compatible Binary Representation

Environments
1 PC/ Windows IEEE - Little endian
PC/Linux
Mac (Intel and M1 chip)
2 Sun IEEE - Big endian
Old Mac Power PC (Motorola chip,
discontinued after 2005)

Porting Kernels 6
 N IF Caution Using Email
Navigation and Ancillary Information Facility

• NAIF recommends against the use of email to

transfer kernels unless previous tests have
already proven successful using the same
conditions/computers intended for current use.
Possible causes of problems are:
– incompatible binary or text representations (as already
discussed).
– an attachment size limit somewhere in the e-mail chain.
– the sender’s or recipient’s mail client modifies the kernel based
on file name or presumed content.

• When you must email kernels, compress them

either with zip or gzip, then send the compressed
file as an email attachment.

Porting Kernels 7
 N IF Binary Kernels - Caveats
Navigation and Ancillary Information Facility

• If the kernel you are using is a non-native binary kernel

you can read this file but you may not write data to this
file.
– You can read most non-native binary kernels using the automatic run-
time conversion capability found in the APIs of modern Toolkits.
» Exception: non-native DAS-based files (ESQ) created before 2001
cannot be read. They must first be converted to native format.
– You cannot write information into the comment area, or delete
information from the comment area.
– You cannot append additional data to the kernel.

Porting Kernels 8
 Binary Kernels
N IF Allowed Operations
Navigation and Ancillary Information Facility

• You may “load” and read both non-native and native

binary kernels in the same runtime instance

• You may merge similar native and non-native files–

the resultant, merged file will be in native format.
– SPKs: using SPKMERGE or DAFCAT
– CKs: using DAFCAT
– DSKs: using DLACAT

Porting Kernels 9
 N IF Text Kernels - Caveats
Navigation and Ancillary Information Facility

• Cutting/pasting complete, or pieces of, data

assignments or \begindata or \begintext
markers into a text kernel can cause a problem
– It may result in insertion of non-printing characters or incorrect
end-of-line terminations
– This is not a problem for comments, but it is probably best to
treat all portions of a text kernel the same
• If creating a text kernel by editing an existing one:
– first save a backup copy
– be sure you are starting with a file in native format for the
computer you are using: either Unix/Linux/Mac or Windows
– be sure to insert a final end-of-line marker at the end of your
last line of data or text
» Press “return”

Porting Kernels 10
N IF
Navigation and Ancillary Information Facility

SPICE-Enhanced
Cosmographia

April 2023
 N IF Cosmographia Overview - 1
Navigation and Ancillary Information Facility

• SPICE-Enhanced Cosmographia is an interactive

3D Solar System visualization tool

It can be used to And has visual guides

render… such as …
– natural bodies – stars
– spacecraft – longitude-latitude grids
– sensor FOVs – shadows
– observation footprints – reflections
– trajectories – atmospheres
– directions
– reference frames

Cosmographia 2
 N IF Cosmographia Overview - 2
Navigation and Ancillary Information Facility

• It is a standalone application that needs to be

installed and run on a user computer
– SPICE data used by the program must be available locally on
that computer

• The program installers for Mac, Linux and

Windows are available on the NAIF server
https://naif.jpl.nasa.gov/naif/cosmographia.html

Cosmographia 3
 N IF Cosmographia History
Navigation and Ancillary Information Facility

• It was originally designed as a general interest solar system

simulator by Chris Laurel in 2011-2012
• In 2013-2014, with permission from the original author, JPL
developers started augmenting it to use SPICE kernels to
accurately visualize space mission geometry
• NAIF took over in 2014 and since then, with the help from
Chris Laurel, continued its development, releasing 5 new
versions to date
– Version 2.0, March 2015
» Initial release by NAIF
– Version 3.0, December 2015
» Added Python-based scripting, on-line User’s Guide, frame and vector visualization, and
more
– Version 4.0, February 2019
» Upgrade to SPICE N0066, Qt5, and PyQt5; new GUI and catalog features; new scripting
functions
– Version 4.1, February 2022
» Upgrade to SPICE N0067; DSK support; font size controls; new scripting functions; and
more
– Version 4.2, December 2022
» Upgrade to Python3; addition of Python scripting support on Windows

Cosmographia 4
 N IF Cosmographia Capabilities
Navigation and Ancillary Information Facility

• Uses SPICE data to ensure accurate geometry rendering

– Trajectories, velocities, direction vectors based on SPK
– Orientations, reference frames based on SPICE frames
– 3D shapes based on DSK
– Distances, altitudes, angles based on SPICE calculations
• Allows easy introduction of new missions by defining their
SPICE data and objects in JSON-formatted catalog files
• Provides controls to easily manipulate time and camera
position in the Solar System
• Includes built-in Python3 scripting interface for creating
visualization sequences
• Has built-in screenshot and video recording (OSX only)
capabilities
• Can be launched from a terminal/command window with a
variety of options, facilitating use in automated applications
• And many more …
Cosmographia 5
 N IF Cosmographia GUI Controls
Navigation and Ancillary Information Facility

• Cosmographia GUI provides a wide variety of controls including

Top Menu, Left Toolbar, Object Context Menu, Mouse gestures,
and Keyboard Shortcuts.
– For convenience, most Cosmographia functions can be accessed through
more than one type of control

Top Menu
Object Context
Menu (invoked
with right click)

Left Toolbar

Cosmographia 6
 N IF Setting up for a New Mission
Navigation and Ancillary Information Facility

• Setting up Cosmographia to visualize a mission

based on SPICE data usually requires
– Downloading needed kernels to user’s computer
– Creating a JSON catalog file loading these kernels, directly or via
a meta-kernel
– Creating a JSON catalog file defining attributes of natural bodies
that are the mission’s targets, including attributes defining how
to compute target’s trajectory and orientation using SPICE
– Creating a similar JSON catalog file for the spacecraft(s)
– Creating JSON catalog files defining sensor parameters, if
applicable
– Creating JSON files defining sensor observation sequences, if
applicable
• With the help from Cosmographia documentation,
JSON catalog templates, and example JSON
catalogs this can be done with a fairly modest effort
Cosmographia 7
 N IF Cosmographia Built-in Scripting
Navigation and Ancillary Information Facility

• Cosmographia includes a Python3-based scripting interface

– provides access to many of the program’s elementary visualization
functions
– allows users to create visualization sequences using these functions
• This example script loads VCO SPICE data, spacecraft and
LIR instrument catalog files, sets a specific UTC time, aligns
program rendering view with the instrument FOV, takes a
screenshot simulating an image, and exits the program
import cosmoscripting
cosmo = cosmoscripting.Cosmo()
cosmo.loadCatalogFile("/Users/naif/VCO/spice_VCO.json")
cosmo.loadCatalogFile("/Users/naif/VCO/spacecraft_VCO.json")
cosmo.loadCatalogFile("/Users/naif/VCO/sensor_VCO_LIR_PIC-VENUS.json")
cosmo.setTime("2015-12-07 05:26:01 UTC")
cosmo.setFov(12.5,2.0)
cosmo.moveToPov("VCO_LIR_PIC",[0,0,0.01],[0,0,1],[1,0,0],1).wait(2)
cosmo.saveScreenShotToFile("Users/naif/VCO/cosmo_screenshot.png").wait(1)
cosmo.quit()

• Cosmoscripting-based scripts can be run from GUI via menu

or from command line using the “-p” option.
Cosmographia 8
 N IF Cosmographia Documentation
Navigation and Ancillary Information Facility

• Detailed information about all Cosmographia

features is available in its on-line User’s Guide
https://cosmoguide.org

Cosmographia 9