0% found this document useful (0 votes)

1K views

SPICE Tutorials Merged

Uploaded by

Edmond Abdou

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views

SPICE Tutorials Merged

Uploaded by

Edmond Abdou

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 1026

N IF

Navigation and Ancillary Information Facility

Welcome SPICE Tutorials

to the

July 2013

N IF
For you

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 use of primary SPICE components Provide examples of how to use SPICE software and data files Provide some insight into conventions and common problems Provide a variety of hands-on programming exercises Provide a peek at new capabilities being worked on or considered Familiarize you with available SPICE resources

For NAIF (if these tutorials are being seen in a class setting)
Get students feedback on todays SPICE system Especially whats hard to understand, hard to use, missing Get students suggestions for further development of SPICE Get students suggestions for improvements to NAIF support of the space science community

Welcome to tutorials

N IF
Broad coverage

Navigation and Ancillary Information Facility

Ancillary Data

Science Instrument Data

SPICE deals with these data to support the planning for and analysis of these data

Introduction

N IF

History
Navigation and Ancillary Information Facility

Implementation of a precursor to SPICE 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 Todays SPICE system dates from about 1991

Tutorials Introduction

N IF

Breadth of Use
Navigation and Ancillary Information Facility

The original focus of SPICE was on ancillary data and associated software needed by scientists for:
initial science data analysis science archive preparation

The scope of SPICE usage has grown to cover the full mission lifecycle, as well as post-mission archive uses.

Mission concept development

Mission design validation

Detailed science observation planning

Mission Lifecycle

Science archive preparation

Mission operations support

Initial science data analysis

Science archive user support

Tutorials Introduction

N IF

Major SPICE Users*

Navigation and Ancillary Information Facility

SPICE is used on all NASA planetary exploration projects

Examples: All Mars missions, Cassini, Deep Impact, Messenger, Juno

Limited SPICE data have been (or are being) created for some past missions
Examples: Voyager, Viking Orbiter

SPICE is used to some degree in support of some space physics and astrophysics missions
Examples: Hubble Telescope, Spitzer Telescope, IBEX, Wise, Kepler, Solar Probe

SPICE was or is used on many non-NASA missions

Russias Mars 96 and Phobos-Grunt; ESAs Huygens Probe, Smart-1, Mars Express, Rosetta and Venus Express; Japans Hayabusa and SELENE; Indias Chandrayaan-1 and Resourcesat-2

SPICE will be used on at least one NASA earth science mission (SMAP) SPICE ephemerides are used at some terrestrial observatories SPICE is used by NASAs Deep Space Network for both scheduling and operating the DSN antennas.
* Not all are supported by NAIF; some are using SPICE on their own.
Tutorials Introduction

N IF

Ancillary Data Archives

Navigation and Ancillary Information Facility

SPICE is the U.S. Planetary Data Systems de facto standard for archiving ancillary data
But its use is not a formal requirement

SPICE data for European planetary missions are archived in ESAs Planetary Science Archive
Some of these data will be mirrored on the NAIF server

SPICE data for some Japanese, Indian and Russian missions may be available in the future from their local archives
Already the case for Hayabusa

Use of SPICE is recommended by the International Planetary Data Alliance

But its use is not a requirement

Tutorials Introduction

N IF

Distribution and Use of SPICE

Navigation and Ancillary Information Facility

SPICE system components are freely distributed

Projects pay for local deployment and operation, done either by their own personnel, or by NAIF, or a combination There are no U.S. ITAR restrictions on distribution There are no licensing requirements

Users get complete source code and much documentation SPICE users are encouraged to reference SPICE when it has provided a significant contribution to ones work See the Rules link on the NAIF Home Page for a complete list of rules and recommendations
Tutorials Introduction

N IF

Training Materials
Navigation and Ancillary Information Facility

This set of tutorials has been presented and revised numerous times
No matter how hard we try, it seems impossible to:

get all the facts absolutely right and up-to-date get the level of detail right for every student get all of the language clear, complete and concise present everything in the correct order

These training materials are meant to supplementnot replacethe subroutine headers and the required reading reference documents that are the primary sources for user information about SPICE

Tutorials Introduction

N IF
Navigation and Ancillary Information Facility

Motivation for Developing SPICE

July 2013

N IF

Why Did NAIF Build SPICE?

Navigation and Ancillary Information Facility

Scientists said they would like to:

- use common tools and methods throughout a projects lifecycle, and for all projects (national and international) - understand the calculations and transformations used to produce observation geometry data - be able to produce custom geometry calculations themselves, whenever and however they want - have the ability to revise the fundamental data and software tools used to produce their own observation geometry data

Motivation for SPICE

N IF
Trajectory Data

What Existed Prior to SPICE ?

Navigation and Ancillary Information Facility

SEDR - Supplemental Experiment Data Record JPL Scientists Institution

Scientists Data Analysis Program

S/C Orientation Data

SEDR Generation

SEDR

SEDR Parameters Database SEDR Commands Science Telemetry

Motivation for SPICE

Scientists Software Modules

Science Results

EDR* Generation

EDR

Science Instrument Data

* EDR = Experiment Data Record = "raw" science instrument data

N IF

SEDR System Characteristics

Navigation and Ancillary Information Facility

The SEDR Generation program was built and operated at JPL

Scientists 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

SPICE Detriments vs. SEDR

Navigation and Ancillary Information Facility

End users ("consumers") 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 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

Motivation for SPICE

N IF
Navigation and Ancillary Information Facility

An Overview of SPICE

July 2013

N IF

Space Science Data: Two Kinds

Navigation and Ancillary Information Facility

Ancillary Data

Science Instrument Data

SPICE deals with these data to support the planning for and analysis of these data

Overview of SPICE

N IF
Reference frames Positions Orientations Sizes/shapes Pointing Other
Orientation of spacecraft

What are Ancillary Data?

Navigation and Ancillary Information Facility
Orientation

Antenna reference frame

and size/ shape

of Earth

Spacecraft Earth

Sun

EME 2000 reference frame (J2000)

Solar System Barycenter

Instrument reference frame

Relative positions of spacecraft and solar system bodies

Orientation and size/ shape of planet

Pointing of Instrument field-of-view

Planet

Time Conversion Calculations

Overview of SPICE

Logs of Commands and Events 3

N IF

How Use Ancillary Data?

Navigation and Ancillary Information Facility

Ancillary data are those that help scientists and engineers determine:
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 what events were occurring on the spacecraft or ground that might affect interpretation of science observations

In the above weve used past tense, but doing the same functions for future times to support mission planning is equally applicable

Overview of SPICE

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 typescalled "kernels used by scientists and engineers
Overview of SPICE

N IF

Why SPICE?
Navigation and Ancillary Information Facility

Knowing observation geometry and 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

Having 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

N IF

SPICE System Components

Navigation and Ancillary Information Facility

Data files (kernels)... Software (SPICE Toolkit) .. Documentation .. Tutorials . Programming lessons .. Training classes User consultation ...
Overview of SPICE

N IF

Genesis of the SPICE Acronym*

Navigation and Ancillary Information Facility

S P I C E

Spacecraft Planet Instrument C-matrix Events

* Coined by Dr. Hugh Kieffer, USGS Astrogeology Branch, Flagstaff AZ, circa 1985
Overview of SPICE

N IF
Logical Components
Spacecraft

SPICE Data Overview

Navigation and Ancillary Information Facility

Physical Files

Contents
Space vehicle or target body trajectory (ephemeris)

SPK PcK IK CK EK
ESP ESQ ENB

P Planet I Instrument
Camera-matrix

Target body size, shape and orientation

Instrument field-of-view size, shape and orientation

C E

Orientation of space vehicle or any articulating structure on it Events information: - Science Plan (ESP) - Sequence of events (ESQ) - Experimenters Notebook (ENB)

Events

Others
Overview of SPICE

FK LSK SCLK DSK

Reference frame specifications Leapseconds tabulation Spacecraft clock coefficients Digital shape models 9

N IF
SPK

SPICE Data Details- 1

Navigation and Ancillary Information Facility

Space vehicle ephemeris (trajectory) Planet, satellite, comet and asteroid ephemerides More generally, position of something relative to something else Planet, satellite, comet and asteroid orientations, sizes, shapes Possibly other similar constants such as parameters for gravitational model, atmospheric model or rings model Instrument field-of-view size, shape, orientation Possibly additional information, such as internal timing
10

PcK

Overview of SPICE

N IF
CK

SPICE Data Details- 2

Navigation and Ancillary Information Facility

Instrument platform (e.g. spacecraft) attitude More generally, orientation of something relative to a specified reference frame

Events, broken into three components:

EK
3 components

ESP: Science observation plans ESQ: Spacecraft & instrument commands ENB: Experiment notebooks and ground data system logs

EK is not much used

Overview of SPICE

N IF
FK

SPICE System Data - 3

Navigation and Ancillary Information Facility

Frames
- 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

DSK

Shape models (digital elevation model and tessellated plate model) (DSK)
Under development now

Overview of SPICE

UTC = Coordinated Universal Time

ET = Ephemeris Time

SCLK = Spacecraft Clock Time

N IF
Contents

SPICE Toolkit Software

Navigation and Ancillary Information Facility

Versions
Four languages
Fortran C Interactive Data Language (IDL) MATLAB Underdevelopment: Java Native Interface (JNI) Perhaps also Python PC/Linux PC/Windows Sun/Solaris Mac/OSX (even iPhone) Hewlett Packard/HP-UX

Library of subroutines (~1500)

Just a few used within a customers program to compute quantities derived from SPICE data files

Programs (~30)
SPICE data production SPICE data management

Five platforms

Documentation
Highly annotated source code Technical Reference Manuals (23) User Guides

Several compilers
For the Fortran and C Toolkits

Overview of SPICE

N IF
SPK PcK

Example: Using SPICE in Mission Planning

Navigation and Ancillary Information Facility

Users Planning Program

Evaluation of a planned orbit Instrument pointing plan Observation geometry visualization Analysis of expected communications link performance

Users Own Modules

SCLK LSK
Other needed data

Selected SPICE Toolkit Library Modules

Select kernel types and specific kernels as needed

Overview of SPICE

N IF
SPK PcK

Example: Using SPICE in Science Data Analysis

Navigation and Ancillary Information Facility

Users Geometry Program

Users Own Modules
Instrument Data

Derived Observation Geometry

SCLK LSK

Selected SPICE Toolkit Library Modules

Users Science Data Analysis Program

Instrument Calibration Data

EK
Select kernel types and specific kernels as needed
Overview of SPICE

Spectacular Science Results

N IF

SPICE System Characteristics - 1

Navigation and Ancillary Information Facility

SPICE Toolkit software is portable between computers New Toolkits are released about every 10-15 months Code is 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

N IF

SPICE System Characteristics - 2

Navigation and Ancillary Information Facility

All numeric computations use double precision numbers Kernel files are portable between computers Kernel files are separable
Use only those you need for a particular application

Kernel files are extensible

New data types can be added within a kernel family

SPICE kernels and software are free of licensing and U.S. ITAR restrictions
Everyone is free to use SPICE

And best of all, no cost to individual end users

Overview of SPICE

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) Sometimes even selected compilation options

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

Over 40 environments are supported

Overview of SPICE

N IF

How is SPICE Used ?

Navigation and Ancillary Information Facility
Payload Dumps over Interference and pointing
227 225 223 Alice Consert Cosima Giada Midas Miro Osiris Rosina Virtis-M Virtis-H RPC IES RPC ICA RPC LAP RPC MIP RPC MAG

Evaluation of a planned trajectory

Spacecraft Visibility
Station #1 Station #2 Station #3

Pointing

219 217 215 213 211 209 207 205 203

Interference1

207

219

209

221

211

223

213

225

Interference2 215
NNO Pass

221

203

Mission engineering analyses

Time

Planning an instrument pointing profile

Observation geometry visualization

205

217

Elevation

Science data archiving and analysis

Latitude

Longitude Overview of SPICE

227

N IF

What Can One Do With SPICE?

Navigation and Ancillary Information Facility

Compute many kinds of observation geometry parameters at selected times

A Few Examples
Positions

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

Size,

shape and orientation of planets, satellites, comets and asteroids

Orientation

of a spacecraft and its various moving structures

Instrument

field-of-view location on a planets surface or atmosphere

N IF

What Can One Do With SPICE?

Navigation and Ancillary Information Facility

Find times when a selected geometric event occurs, or when a selected geometric condition exists
A Few Examples

50 100 150

When is an object in shadow?

When is the spacecrafts altitude within a given range? (say 50 to 100 km)

When is an object in front of another, as seen from a spacecraft?

How close will two spacecraft get?

N IF

What Vehicle Types Can Be Supported?

Navigation and Ancillary Information Facility

Cruise/Flyby
Remote sensing In-situ measurement Instrument calibration

Landers
Remote sensing In-situ measurements Rover or balloon relay

Orbiters
Remote sensing In-situ measurement Communications relay

Rovers
Remote sensing In-situ sensing Local terrain characterization

Balloons and aircraft*

Remote sensing In-situ measurements

Terrestrial applications
Ephemerides for telescopes Radiometric tracking & comm Optical tracking & comm

Overview of SPICE

* Not yet demonstrated

N IF
Time conversions UTC to ET mapping (generic LSK file)

Global SPICE Geometry

Navigation and Ancillary Information Facility
Time conversions Universal Time Coordinated (UTC) Orbiter on-board clock (SCLK) ET to orbiter on-board clock mapping (orbiter SCLK file)

Position Vectors Earth position relative to Solar System barycenter (planet ephemeris SPK file)

Ephemeris Time (ET) XE

ZE Frame Orientations YE XO ZO ZR XR YJ2000 ZL YR YL XL Rover frame orientation relative to local level frame (rover CK file) YO Orbiter frame orientation relative to J2000 frame (orbiter CK file)

ZJ2000 Rover position relative to the landing site (lander) (rover SPK file)

XJ2000

Landing site (lander) position relative to the Mars center (landing site SPK file)

Mars position relative to the Solar System barycenter (planet ephemeris SPK file) XM Orbiter position relative to the center of Mars (orbiter SPK file) Overview of SPICE

Local level frame orientation relative to planet body-fixed frame (mission FK file)

Planet body-fixed frame orientation relative to J2000 frame (generic PCK file)

N IF
Position Vectors Spacecraft position relative to planet center (spacecraft SPK file)

Orbiter Geometry
Navigation and Ancillary Information Facility
Frame Orientations Spacecraft frame orientation relative to inertial frame (spacecraft CK file) Camera frame orientation relative to spacecraft frame (mission FK file) XSC XA YSC ZSC ZA YA XAG ZAG YC ZC XC YSG YAG XSG ZSG Solar array gimbal frame orientation relative to spacecraft frame (solar array CK file) High gain antenna gimbal frame orientation relative to spacecraft frame (antenna CK file) Magnetometer frame orientation relative to solar array gimbal frame (mission FK file) High gain antenna frame orientation relative to high gain antenna gimbal frame (mission FK file)

High gain antenna gimbal position relative to spacecraft (structures SPK file)

High gain antenna phase center location relative to high gain antenna gimbal (structures SPK file)

Solar array gimbal position relative to spacecraft center (structures SPK file) XM YM Magnetometer position relative to solar array gimbal (structures SPK file) Overview of SPICE ZM

N IF
Position Vectors Left and right mast camera positions relative to camera head (structures SPK file) Robotic arm gimbal and camera relative positions (structures SPK file) Mast camera head position relative to lander (structures SPK file) Meteo sensor positions relative to lander (structures SPK file) Lander position relative to landing site (lander SPK file)

Lander Geometry
Navigation and Ancillary Information Facility
Frame Orientations Left and right mast camera frame orientations relative to camera head frame (mission FK file) Mast camera head frame orientation relative to lander frame (mast camera CK file) Robotic arm gimbal frames orientations relative to each other (arm CK file) Robotic arm camera frame orientation relative to last gimbal frame (mission FK file) Lander frame orientation relative to local level frame (lander CK file) Local level frame orientation relative to planet body-fixed frame (mission FK file) Descent camera frame orientation relative to lander frame (mission FK file)

YLC YRC ZRC XLC XCH YCH YRC ZCH XRC ZRC XL

XDC XLL YDC

Descent camera position relative to lander (structures SPK file) Landing site position relative to planet center (landing site SPK file) Overview of SPICE

ZDC

YLL ZLL

N IF
Position Vectors Left and right mast camera center positions relative to end of mast (structures SPK file) End of mast position relative to elbow gimbal (structures SPK file) YRC ZRC

Rover Geometry
Navigation and Ancillary Information Facility
YLC XLC Frame Orientations Left and right mast camera frames orientation relative to mast elbow frame (mission FK file) Mast elbow frame orientation relative to mast shoulder frame (mast CK file) YE Mast shoulder frame orientation relative to mast torso frame (mast CK file) Mast torso frame orientation relative to rover frame (mast CK file) ZS YT ZR XR Rover frame orientation relative to local level frame (rover CK file) Local level frame orientation relative to planet body-fixed rotating frame (mission FK file)

XRC ZLC

XE Mast elbow gimbal position relative to shoulder gimbal (structures SPK file) Mast shoulder gimbal position relative to torso gimbal (structures SPK file) Mast torso gimbal position relative to rover (structures SPK file) Rover position relative to landing site (rover SPK file) Landing site position relative to planet center (landing site SPK file)

XS ZT

YS XT

YR YL XL(NORTH) ZL(GRAVITY)

Overview of SPICE

N IF
Data Restorations Apollo 15, 16 [L] Mariner 2 [L] Mariner 9 [L] Mariner 10 [L] Viking Orbiters [L] Viking Landers [L] Pioner 10/11/12 [L] Haley armada [L] Phobos 2 [L] (RSA) Ulysses [L] Voyagers [L] Lunar Orbiter [L] Helios 1,2 [L]

SPICE Users

Past Users Current/Pending Users Anticipated Navigation and Ancillary Information Facility Magellan [L] Cassini Orbiter Mars Rover 2020 Clementine (NRL) Mars Odyssey NASA Discovery Program Mars Observer [F] Mars Exploration Rover NASA New Frontiers Program Mars 96 (RSA) [F] Mars Reconnaissance Orbiter Mars Pathfinder DAWN Examples of Possible Future Use ? Mars Climate Orbiter [F] Mars Science Lab Solar Probe + Mars Polar Lander [F] Juno BepiColombo (ESA, JAXA) NEAR MAVEN Solar Orbiter (ESA) Deep Space 1 SMAP (Earth Science) JUICE (ESA) Galileo OSIRIS REx ExoMars (ESA, RSA) Genesis LADEE Akatsuki (JAXA) Deep Impact InSight Luna-Resurs (ISRO/RSA) Huygens Probe (ESA) [L] Luna-Glob (RSA) Stardust/NExT Europa Clipper Mars Global Surveyor Lunar Reconnaissance Orbiter Examples of Unsupported Users Phoenix New Horizons EPOXI Messenger STEREO GRAIL Spitzer Space Telescope [L] ISO [S] (ESA) Mars Express (ESA) Kepler [L] CONTOUR [F] Venus Express (ESA) Hubble Space Telescope [S] [L] = limited use Space VLBI [L] (multinational) Rosetta (ESA) Radioastron (RSA) [L] [S] = special services Smart-1 (ESA) IBEX [F] = mission failed Chandrayaan-1 (ISRO) James Webb Space Telescope [S] Hayabusa (JAXA) International Planetary Data Alliance Last updated 6/20/2013 Kaguya (JAXA) Planetary Data System NASA AMMOS Phobos Sample Return (RSA) [F] Planetary Science Archive (ESA) NASA Deep Space Network [S] NAIF has/had project-supplied funding to support mission operations, consultation for flight team members, and SPICE data archive preparation. NAIF also has PDS funding to help scientists and students with using SPICE data that have been officially archived at the NAIF Node of the PDS. NAIF has/had NASA funding to support a foreign partner in SPICE deployment and archive review, and to consult with flight team SPICE users. NAIF has token funding to consult with kernel producers at APL. APL provides support to science teams. NAIF has/had modest PDS-supplied funding to consult on assembly of a SPICE archive. NAIF has PDS funding to help scientists and students with using SPICE data that have been officially archived at the NAIF Node of the PDS. User consultation is provided by ESA's Science Operations Department. Note: SPICE is an option available to, but not a standard of, NASA, JPL, the PDS, ESA, ESA's PSA, and the IPDA. Overview of SPICE

N IF

Building Blocks for Your Applications

Navigation and Ancillary Information Facility

The SPICE ancillary information system can serve as a set of blocks for building tools for implementing tools supporting multi-mission, international space exploration programs

S
Overview of SPICE

I C

E
28

SPICE: the ancillary information system that NAIF builds and often operates. NAIF: the JPL entity responsible for development and deployment of SPICE. NAIF Node of the PDS: one responsibility of the NAIF Group--archiving and providing long-term access to SPICE data for the worldwide science community.

N IF
Navigation and Ancillary Information Facility

Fundamental Concepts

April 2013

N IF

Topics
Navigation and Ancillary Information Facility

Preface Time Reference Frames Coordinate Systems Positions and States Aberration Corrections

Fundamental Concepts

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

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

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

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

N IF

Tying UTC to Earths Rotation (UT1)

Navigation and Ancillary Information Facility

Ideally, UTC noon and astronomical noon at Greenwich (UT1) should occur simultaneously. However, the earths 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 daynormally either June 30 or December 31. The variations in the earths rotation that cause leap seconds to be needed are not predictable.
Fundamental Concepts

N IF
1998 1998 1999 1999 Dec Dec Jan Jan 31 31 01 01

Leapseconds (+ and -)
Navigation and Ancillary Information Facility

Normal sequence of UTC time tags

23:59:58.0 23:59:59.0 00:00:00.0 00:00:01.0

Sequence with a Positive Leapsecond

1998 1998 1998 1999 1999 Dec Dec Dec Jan Jan 31 31 31 01 01 23:59:58.0 23:59:59.0 23:59:60.0 00:00:00.0 00:00:01.0

Leap seconds complicate the task of finding the duration between two UTC epochs: You need to know when past leap seconds occurred to compute durations defined by pairs of past UTC epochs. Durations defined by pairs of future UTC epochs are indeterminate if leap seconds could occur in the interim.

Sequence with a Negative Leapsecond

1998 Dec 31 23:59:57.0 1998 Dec 31 23:59:58.0 1999 Jan 01 00:00:00.0 1999 Jan 01 00:00:01.0

Fundamental Concepts

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 ideal time at the Solar System Barycenter (TCB) by a scale factor, so that TDB advances on average at the same rate as TAI.

Navigation and Ancillary Information Facility

A reference frame is an ordered set of three mutually orthogonal (possibly time dependent) unitlength direction vectors, coupled with a location called the frames 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 Fundamental Concepts

Spherical coordinates

N IF

Reference Frame Center

Elevation (angle between vector and x-y plane)

One example of a topocentric frame. There are other types of topocentric frames: for example, the z-axis could point down, the xaxis North, and the y-axis East.
Fundamental Concepts

Orthogonal projection of vector onto x-y plane

N IF

Spacecraft and Instrument Frames

Navigation and Ancillary Information Facility

Defined relative to structures

There are multiple, inconsistent standards! (USNO, IAU, PDS) NAIF strongly suggests you use only planetocentric or planetodetic coordinates
Toolkit planetocentric routines are RECLAT, LATREC, DRDLAT, DLATDR Toolkit planetodetic routines are RECGEO, GEOREC, DRDGEO, DGEODR
Fundamental Concepts X

Observer

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

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

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

Fundamental Concepts

* Assuming both frames are right-handed

N IF
where Si(t) = and

Transforming States
Navigation and Ancillary Information Facility

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

( )
Pi(t) dPi(t)/dt

i = A or B

TA to B(t) =

RA to B(t)

dRA to B(t)/dt RA to B(t)

)
27

The SPICELIB routines SXFORM and PXFORM return state transformation and position transformation matrices respectively.
Fundamental Concepts

N IF

Aberration Corrections: Introduction

Targets (geometric) position and orientation at time ET

Note: The angular separation of the geometric and light time corrected positions as seen by the observer has been exaggerated for readability.

Targets velocity vector

Targets angular velocity vector Targets position and orientation at time ET-LT (light time corrected position and orientation)

Light travels this path in LT seconds Observers position at time ET At time ET, the observers 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

N IF

Prediction Using Light Time Corrections

Navigation and Ancillary Information Facility

Predicted target body, surface feature, and star image locations (in red)

Actual 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

N IF

Stellar Aberration Correction

Navigation and Ancillary Information Facility

Targets (geometric) position and orientation at time ET

Note: The angular separation of the geometric, light time corrected, and apparent positions as seen by the observer has been exaggerated for readability.

Targets apparent position and orientation Targets position and orientation at time ET-LT (light time corrected position and orientation)

Observers velocity relative to SSB

To the observer, light appears to travel this path

Observers position at time ET At time ET, the observers 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

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

N IF
Navigation and Ancillary Information Facility

SPICE Conventions
A summary of standards, lingo and common usage within SPICE July 2013

N IF
SPICE

SPICE Lexicon - 1
Navigation and Ancillary Information Facility

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 NASAs Planetary Data System (PDS).

SPICE Conventions

N IF
SPICE Toolkit The Toolkit Toolkit SPICELIB CSPICE

SPICE Lexicon - 2
Navigation and Ancillary Information Facility

Names that refer to the principal collection of software produced by JPLs NAIF Team as part of the SPICE information system. The Fortran 77 version of the Toolkit. The principal user library found within Fortran versions of the Toolkit. Used to refer to the entire C Toolkit, and also to the principal user library found within C versions of the Toolkit. An IDL interface to CSPICE A MATLAB interface to CSPICE

Icy Mice

Sorry for this rather confusing terminology!

SPICE Conventions

N IF
Text kernel

SPICE Lexicon - 3
Navigation and Ancillary Information Facility

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 (Furnsh) Any set of text kernels 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

N IF
Command file

SPICE Lexicon - 4
Navigation and Ancillary Information Facility

Many SPICE application and utility programs either require, or optionally accept, an input file containing program directives, and sometimes input data. Unfortunately NAIF has not used a consistent approach for referring to such files. The following names have been used: setup file preferences file command file specifications file definitions file

Found flag
A Boolean output from a SPICE API that informs your program whether or not a result was obtained

Database Kernel (DBK)

A SPICE kernel that, in conjunction with Toolkit DBK software, provides a self-contained SQL-like database capability.
SPICE Conventions

N IF

SPICE Lexicon - 5
Navigation and Ancillary Information Facility

Deprecated software
Code that, while still useable, has been superseded with a newer and presumably better version We encourage you to not use deprecated SPICE software

Toolkit version naming

"Nxxxx" e.g. N0064 is Version 64 Often shortened to just Nxx (e.g. N64) Used for all instances of a given toolkit release

Satellite is used to refer only to a natural satellite, never to a spacecraft. Run-time occurs when you execute a program

SPICE Conventions

N IF

SPICE Lexicon - 6
Navigation and Ancillary Information Facility

Names used synonymously

Kernel, SPICE file, SPICE kernel, SPICE kernel file Meta-kernel and Furnsh Kernel Module, routine, subroutine, procedure, function and API Application, program, utility, executable Metadata, comments Time, Epoch Encoded SCLK, ticks* Frame, Reference Frame** Ephemeris, trajectory Rectangular coordinates, Cartesian coordinates** Geodetic, Planetodetic (coordinate system) Ephemeris time (ET), Barycentric Dynamical Time (TDB) Attitude and orientation International Celestial Reference Frame (ICRF) and Earth Mean Equator and Equinox of 2000 reference frame (J2000) Body, solar system object and 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), and to use frame in the sense of a set of three orthogonal vectors.
SPICE Conventions

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 PDS 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* b* x* text format (e.g. pck00008.tpc) binary format (e.g. de421.bsp) transfer format (e.g. de421.xsp)

SPICE Conventions

N IF
SPK: .bsp .xsp PcK: .tpc .bpc .xpc IK: .ti FK: .tf LSK: .tls CK: .bc .xc binary CK file transfer format CK file text LSK file text FK file text IK file binary SPK file transfer format SPK file text PcK file
(The most common type PcK)

Common SPICE Kernel File Name Extensions

Navigation and Ancillary Information Facility SCLK: .tsc MK: .tm DSK: .bds ESP: .bep .xep ESQ: .bes .xes ENB: .ten DBK: .bdb .xdb
9

text SCLK file text meta-kernel file (FURNSH kernel) binary DSK file

binary PcK file

(Very few instances of this)

transfer format PcK file

EK Family (ESP, ESQ, ENB) binary Science Plan EK file transfer format Science Plan EK file binary Sequence Component EK file transfer format Sequence Component EK file text Experimenters Notebook EK file

SPICE Conventions

These are strong suggestions but not requirements

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 .req .txt .idx Users Guide Required Reading technical reference document Used for a few miscellaneous documents Used only for the permuted index document

All HTML documents included in the Toolkit have extension .html Alternate formats of some Toolkit documents are available from the NAIF anonymous ftp server
.pdf PDF documents

SPICE Conventions

N IF

Coordinate System Conventions - 2

Navigation and Ancillary Information Facility

Planetodetic coordinate systems

Planetodetic longitude is planetocentric longitude
increases positively eastward
Z

Y X

SPICE Conventions

N IF

Coordinate System Conventions - 3

Navigation and Ancillary Information Facility

Planetographic coordinate systems

Z
Spin direction

For dwarf planets, asteroids and comets:

Y X

Observer
15

N IF

Quaternions
Navigation and Ancillary Information Facility

The SPICE system uses quaternions 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 JPL ACS/AACS and other aerospace applications

The relationship between SPICE and MSOP quaternions:

Let M be a rotation matrix such that for any vector v, M*v is the result of rotating v by radians in the counterclockwise direction about unit vector A. Then the quaternions representing M are: SPICE: (+/-) ( cos(/2), sin(/2)A(1), sin(/2)A(2), sin(/2)A(3) ) MSOP: (+/-) ( -sin(/2)A(1), -sin(/2)A(2), -sin(/2)A(3), cos(/2) )

Details about SPICE quaternions are found in:

Rotations Required Reading document NAIF white paper on quaternions:
SPICE Conventions ftp://naif.jpl.nasa.gov/pub/naif/misc/Quaternion_White_Paper/

SPICE quaternion conversion routines: M2Q, Q2M

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

N IF
Navigation and Ancillary Information Facility

for Physical Objects and Reference Frames

IDs and Names

July 2013

N IF

Topics
Navigation and Ancillary Information Facility

Summary of naming/numbering schemes used in SPICE Naming/numbering of physical objects Naming/numbering of reference frames Connection between the schemes
Caution: users sometimes confuse the ID assigned to an object and the ID(s) assigned to reference frame(s) associated with that object. Read on for details.
NAIF IDs and Names

N IF
physical objects reference frames

Overview - 1
Navigation and Ancillary Information Facility

SPICE uses IDs and names to identify: An ID is an integer number A name is a text string IDs are used primarily as data identifiers inside SPICE kernels Names are used primarily as input and output arguments in SPICE software interfaces (APIs)

NAIF IDs and Names

N IF

Overview - 2
Navigation and Ancillary Information Facility

Navigation and Ancillary Information Facility

Physical 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 and more

NAIF IDs and Names

N IF

Object Names Where Used?

Navigation and Ancillary Information Facility

Physical 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, in newer PCK routines -- BODVRD,

Physical object names are not used as data identifiers within kernels

NAIF IDs and Names

N IF

Object IDs and Names Where Defined?

Navigation and Ancillary Information Facility

Name-to-ID mappings used by SPICE may be defined in two places

In Toolkit software Hard-coded in the source code Defined here for both physical objects and reference frames 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 can be placed in any text kernel Mappings defined in text kernels take precedence over those defined in Toolkit source code

NAIF IDs and Names

N IF

Spacecraft and Ground Stations

Navigation and Ancillary Information Facility

Examples of Object IDs and Names

Spacecraft (negative numbers)

Within NASA, this number is generally the negative of the numeric ID assigned by the NASA control authority at GSFC
-6 -7 -82 -94 PIONEER-6, P6 PIONEER-7, P7, CASSINI, CAS MARS GLOBAL SURVEYOR, MGS

Unfortunately sometimes NASA re-uses a number This will happen with increasing frequency in the future Probably a new scheme is needed

DSN ground stations (399000 + station number)

399005 399066 398990
NAIF IDs and Names

DSS-05 DSS-66 NEW_NORCIA

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

N IF

0 10

Examples of Object IDs and Names

Planets

Navigation and Ancillary Information Facility

Sun and Solar System Barycenter (10 and 0)

SOLAR SYSTEM BARYCENTER, SSB SUN

Planetary system barycenters (numbers from 1 to 9)

1 2 3 4 9 MERCURY BARYCENTER VENUS BARYCENTER EARTH MOON BARYCENTER, EMB, MARS BARYCENTER PLUTO BARYCENTER

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

199 299 399 499 999 MERCURY VENUS EARTH MARS PLUTO
12

NAIF IDs and Names

N IF
301 401 402 501 901

Examples of Object IDs and Names

Satellites

Navigation and Ancillary Information Facility

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

MOON PHOBOS DEIMOS IO CHARON, 1978P1

See the BACKUP section for details about how to handle more than 98 satellites.

NAIF IDs and Names

N IF
1000001 1000002 1000032

Examples of Object IDs and Names

Comets & Asteroids

Navigation and Ancillary Information Facility

Periodic Comets (1000000 + sequence number*)

AREND AREND-REGAUX HALE-BOPP

Numbered Asteroids (2000000 + IAU asteroid number)

2000001 2000004 2009969 CERES VESTA BRAILLE, 1992KD

There are three exceptions, for Gaspra, Ida and Dactyl See NAIF_IDS.REQ

One can search on SPK ID or name and find the other item using this website: http://ssd.jpl.nasa.gov/sbdb.cgi
*Sequence number is assigned by JPLs Solar System Dynamics Group
NAIF IDs and Names

N IF

Examples of Object IDs and Names

Instruments

Navigation and Ancillary Information Facility

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 0999. The only requirement is that they must be unique within each mission
-82760 -82761 -82762 -82763 -82001 -82002 -82008 -82009 CASSINI_MIMI_CHEMS CASSINI_MIMI_INCA CASSINI_MIMI_LEMMS1 CASSINI_MIMI_LEMMS2 CASSINI_SRU-A CASSINI_SRU-B CASSINI_SRU-A_RAD CASSINI_SRU-B_RAD

NAIF IDs and Names

N IF

Object IDs/Names -- Mapping APIs

Navigation and Ancillary Information Facility

SPICE provides two routines to map physical object IDs to names, and vice versa
To get the ID for a given physical 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 physical 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

N IF

Adding New or Additional 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 NAIF_BODY_CODE += ( my_spacecraft_name += ( my_spacecraft_ID ) )

See NAIF_IDs Required Reading for details

NAIF IDs and Names

N IF
Navigation and Ancillary Information Facility

N IF

1 17

Examples of Frame IDs and Names

Inertial and Body-fixed

Navigation and Ancillary Information Facility

Inertial frames (positive integers starting at 1)

J2000 ECLIPJ2000

Body-fixed frames (positive integers starting at 10001)

10012 10013 10013 10020 13000 IAU_VENUS IAU_EARTH IAU_MARS IAU_MOON ITRF93

NOTE: SPICE users would rarely if ever need to know or use the frame IDs; you use only the frame name
NAIF IDs and Names

N IF

Spacecraft and Instrument

Navigation and Ancillary Information Facility

Examples of Frame IDs and Names

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 -82001 -82760 -82761 -82762 -82763 -82764 -83765 CASSINI_SC_COORD CASSINI_SRU-A CASSINI_MIMI_CHEMS CASSINI_MIMI_LEMMS_INCA CASSINI_MIMI_LEMMS1 CASSINI_MIMI_LEMMS2 CASSINI_MIMI_LEMMS_BASE CASSINI_MIMI_LEMMS_ART

Spacecraft structure frame (ID and name) Instrument frames (ID and name)

NOTE: SPICE users would rarely if ever need to know or use the frame IDs; you use only the frame name

NAIF IDs and Names

N IF

Frame IDs/Names -- Mapping APIs

Navigation and Ancillary Information Facility

SPICE provides two routines 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.

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

NAIF IDs and Names

N IF

Connections between Objects and Frames

Navigation and Ancillary Information Facility

Although physical 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

N IF
CK IDs

Odd Ball Cases

Navigation and Ancillary Information Facility

Historically IDs used in CKs are called structure IDs but in reality they are much more closely related to frames than to physical 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 the same as the spacecraft ID 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

N IF
Ephemeris objects

Name/IDs Example -- CASSINI (1)

Navigation and Ancillary Information Facility

Objects IDs/Names
10 399 699 601 602
Spacecraft and its structures

Frames IDs/Names
1 10013 10016 10039 10040 -82000 -82001 -82790 -82791 -82792 J2000 IAU_EARTH IAU_SATURN IAU_MIMAS IAU_ENCELADUS CASSINI_SC_COORD CASSINI_SRU-A CASSINI_CDA CASSINI_CDA_ART CASSINI_CDA_BASE CASSINI_CAPS CASSINI_CAPS_ART CASSINI_CAPS_BASE

SUN EARTH SATURN MIMAS ENCELADUS CASSINI CASSINI_SRU-A CASSINI_CDA

-82 -82001 -82790

CDA instrument

-82820
CAPS instrument

CASSINI_CAPS_IMS CASSINI_CAPS_ELS CASSINI_CAPS_IBS_DT1 CASSINI_CAPS_IBS_DT2 CASSINI_CAPS_IBS_DT3

-82820 -82821 -82822

-82821 -82822 -82823 -82824

NAIF IDs and Names

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 missions 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

N IF
Navigation and Ancillary Information Facility

Introduction to Kernels
July 2013

N IF
Overview Kernel architecture Producing kernels Using kernels

Agenda
Navigation and Ancillary Information Facility

Introduction to Kernels

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

N IF
SPK PcK

SPICE Kernels Family

Navigation and Ancillary Information Facility

FK
Reference frame specifications

Spacecraft and Planet Ephemeris Planetary Constants, for natural bodies Orientation Size and shape

SCLK
Spacecraft clock correlation data

LSK
Leapseconds

IK
Instrument

MK
Meta-Kernel (a.k.a. FURNSH kernel) Mechanism for aggregating and easily loading a collection of kernel files

CK
Pointing (C-matrix)

EK
Events, up to three distinct components ESP: science plan ESQ: sequence ENB: experimenters notebook

DSK (under development)

Digital shape kernel Tesselated plate model Digital elevation model

DBK
Database mechanism
Primarily used to support the ESQ

Introduction to Kernels

N IF

Text and Binary Kernels

Navigation and Ancillary Information Facility

SPICE text kernels are:

text PCK (the most common type of PCK) IK FK LSK SCLK MK

SPICE binary kernels are:

SPK binary PCK (exists only for Earth and moon) CK DSK (digital shape kernel)*

ESQ (part of the E-kernel) Rarely used DBK (database kernel)

* New kind, under development

Introduction to Kernels

N IF

SPICE Kernel Forms

Navigation and Ancillary Information Facility

Binary form: SPK, binary PCK, CK, EK/ESQ1, DSK

A file mostly containing data encoded in binary form Binary kernels are not human-readable; they require the use of Toolkit software to examine the data contents

Text form: text PcK, IK, FK, LSK, SCLK, MK

Plain text files containing only printing characters (ASCII values 32-126), i.e. human-readable text.

Transfer form of a binary kernel

This is an ASCII representation of a binary kernel Was used for porting the file between computers with incompatible binary representations (e.g. PC and UNIX) Use of the transfer format is no longer needed for porting due to the runtime translation capability added to SPICE long ago But it is one way to convert a non-native binary kernel into native format, needed for modifying the kernel or improving read efficiency
The ESP and ENB components of the EK might be binary, or text, or html, depending on specific implementation.
[1]

Introduction to Kernels

N IF
Navigation and Ancillary Information Facility

Kernel Architecture
- Text kernels - Binary kernels - Comments in kernels

Introduction to Kernels

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 can and should also contain descriptive meta-data (comments) that describe the assignments

Introduction to Kernels

N IF
KPL/<kernel type> \begindata NAME NaMe NUMBERS NUMBERS NUMBERS START \begintext

Example Text Kernel

Navigation and Ancillary Information Facility

= 'Sample text value' = 'Keywords are case sensitive' = ( 10.123, +151.241, -1D14 ) += ( 1.0, 1, -10 ) += ( 1.542E-12, 1.123125412 ) = @2011-JAN-1

A data block

< some comments about the data > \begindata < more data in keyword = value syntax > \begintext < etc., etc. >

A meta-data block
(also called comments)

Another data block Another meta-data block

The next several pages describe what you see above See the Kernel Required Reading document for details
Introduction to Kernels

N IF

Text Kernel Formatting

Navigation and Ancillary Information Facility

KPL/<kernel type>
- Appears on the first line - Tells SPICE software what kind of kernel it is - Examples of kernel type are FK, IK, PCK, SCLK

\begindata and \begintext

- Markers, on lines by themselves, which set off the beginning of data and the beginning of meta-data blocks respectively

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

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

Max line length, including any white space

132 characters
Introduction to Kernels

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 J2000 There is no time system implied This conversion does not need a leap seconds kernel

Introduction to Kernels

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, period, parenthesis, equals sign or tab Recommendation: dont use the + sign as the last character

Values
Numeric: integer, floating point and scientific notation are allowed String: maximum length of 80 characters and enclosed in single quotes SPICE has a means to concatenate multiple string values Time: identified by the @ character and converted to barycentric dynamical time (TDB) Any of these three types can be provided as a vector of values Components are separated by commas Parenthesis enclose the vector

See Kernel Required Reading for more information

Introduction to Kernels

N IF

Example Binary Kernel

Navigation and Ancillary Information Facility

A binary kernel contains lots of non-printing (unintelligible) data, usually interspersed with occasional occurrences of ASCII characters. Includes a comment area where descriptive meta-data should be placed.

Introduction to Kernels

N IF

Comments In SPICE Kernels

Navigation and Ancillary Information Facility

All SPICE kernels can and should contain commentsdescriptive 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

N IF
Navigation and Ancillary Information Facility

Producing Kernels

Introduction to Kernels

N IF

Making a Text Kernel

Navigation and Ancillary Information Facility

Text kernels may be produced using any available text editor

Remember, text kernels must contain only printing characters (ASCII values 32-126), i.e. human-readable text. TAB characters are allowed but HIGHLY DISCOURAGED Text kernels must have each line terminated with the end-ofline indicator appropriate for the operating system you are using For Unix, PC/Linux, Mac OSX: <LF> For PC/Windows: <CR><LF> Dont forget to insert the end-of-line indicator on the very last line of the kernel! See the BACKUP for information on converting text kernels between these two styles

Introduction to Kernels

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

N IF
Navigation and Ancillary Information Facility

Using Kernels

Introduction to Kernels

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, and binary PCK 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

N IF

Loading Kernels - 2
Navigation and Ancillary Information Facility

Use the FURNSH routine to load all kernelstext and binary

CALL FURNSH ( name.ext ) furnsh_c ( name.ext ); cspice_furnsh, name.ext cspice_furnsh ( name.ext ) (Fortran) (C) (IDL) (MATLAB)

Best practice: dont hard code filenameslist these in a meta-kernel and load the meta-kernel using FURNSH
CALL FURNSH (meta-kernel_name) (Fortran example) See the next page for more information on meta-kernels

Caution: Transfer format" versions of binary kernels can not be loaded; they must first be converted to binary with the Toolkit utility program tobin or spacit

Introduction to Kernels

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
You can simply load the meta-kernel, causing 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 A meta-kernel is implemented using the SPICE text kernel standards
Refer to the Kernels Required Reading technical reference for details

The terms meta-kernel and FURNSH kernel are used synonymously

Introduction to Kernels

N IF

Sample Meta-Kernel (1)

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', '/home/mydir/kernels/c-kernel.bc', '/home/mydir/kernels+, '/custom/kernel_data/p_constants.tpc, )

The commas are optional

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 sizes by the text kernel standards.
Introduction to Kernels

N IF

Sample Meta-Kernel (2)

SBP*

Text editor
3

LSK SCLK
3

SBP*

Text editor
2

FK DSK

SBP*

Text editor

Meta-kernel
(FURNSH)

SBP*

Who usually makes the kernels at JPL?

1 2 3

NAV and NAIF NAIF

This represents current practice for most JPL missions, but is by no means a requirement. Anyone can make SPICE files.

*SBP = SPICE-based program that uses modules from the

SPICE Toolkit. In some cases the Toolkit contains such a program already built. In some cases NAIF may have such a ready-built program that is not in the SPICE Toolkit.

NAIF or other Introduction to Kernels

N IF
File Type

Why & How Kernels are Modified - 1

Navigation and Ancillary Information Facility Why Modified How Modified - COMMNT, SPACIT or SPICELIB module - SPKMERGE - BSPIDMOD - Text editor - Text editor - Text editor - Text editor - COMMNT, SPACIT, or SPICELIB module - DAFCAT, CKSMRG - CKSPANIT, CKSMRG - CKSLICER - Text editor - Text editor - COMMNT, SPACIT or SPICELIB module - DSKMERGE
29

SPK PcK
Text version

-To add metadata (comments) -To merge files or subset a file -To correct/revise an object ID -To revise data values -To add additional data items and values -To revise data values -To add additional data items and values -To add metadata (comments) -To merge files -To revise the interpolation interval -To subset a file -To revise data values -To add additional data items and values -To add metadata (comments) -To merge files or subset a file

FK DSK
Introduction to Kernels

N IF
File Type
The EK family

Why & How Kernels are Modified - 2

Navigation and Ancillary Information Facility Why Modified -To add, revise or delete data -To add metadata (comments) -To add additional data -To revise data -To delete data -To add metadata (comments) -To merge files -To change entry status (public <--> private) -To delete an entry - To add a new leapsecond How Modified - (Depends on implementation) - (Depends on implementation) - Toolkit modules - Toolkit modules - Toolkit modules - COMMNT, SPACIT or SPICELIB module - (under development) - WWW - WWW - Text editor

ESP ESQ ENB LSK SCLK

Meta-kernel
(FURNSH)

- To add metadata

- Text editor

- To revise contents in any way

- Text editor

Introduction to Kernels

N IF
SPK
High Level

SPICE Data Structures Hierarchy

Navigation and Ancillary Information Facility

EK Family

PCK
OR

FK SCLK

LSK

Meta-kernel
(FURNSH)

DSK

ENB
AND

ESP
OR

ESQ

Mid Level

DLA

DBK

MIME
Low Level

DAF
Binary DAF = Double Precision Array File DBK = Data Base Kernel DAS = Direct Access, Segregated

TEXT

including plain text

Text

DAS

Binary

DSK = Digital Shape Kernel (under development) DLA = DAS Linked Array (under development)

Introduction to Kernels

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.

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 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

Introduction to Kernels

N IF

Some Useful Tools - 1

Navigation and Ancillary Information Facility

For a Unix or Linux (including Mac) environment

To display all non-printing characters, 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)

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

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> For converting either style text kernel to the other style, use the SPICE bingo executable 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

N IF
Navigation and Ancillary Information Facility

Porting Kernels
July 2013

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 endof-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 used on the computer you are using.

Porting Kernels

N IF

Porting Issues - 2
Navigation and Ancillary Information Facility

Toolkit software can usually read kernels obtained from an incompatible platform
Binary SPK, CK, or PCK 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 or MATLAB toolkit (not Fortran toolkits)

The Toolkit cannot read certain kernels from incompatible platforms

Text kernels, if using a FORTAN toolkit DAS-based files, such as E-kernels (ESQ) or shape model kernels (DSK)

See later charts for compatibility matrix

Porting Kernels

N IF

Porting Issues - 3
Navigation and Ancillary Information Facility

When conversion to native format is required to make the kernel usable, 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 dont provide it. In such cases other tools such as dos2unix and unix2dos, or bingo, 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

N IF

Compatible Environments for Text Kernels

Navigation and Ancillary Information Facility

Since text kernels are only text files

Groupings of Text Compatible Environments 1 2 PC using Windows or N T Unix PC with LINUX Macintosh OSX (Motorola or Intel ch i p )

End of line indicator <CR><LF> <LF>

Porting Kernels

N IF

Compatible Environments for Binary Kernels

Navigation and Ancillary Information Facility

Groupings of Binary Compatible Environments PC/ Windows PC/Linux Mac Pro (Intel chip)

Binary Representation IEEE - Little endian

Sun Mac Power PC (Motorola chip, discontinued after 2005)

IEEE - Big endian

Porting Kernels

N IF

Caution Using Email

Navigation and Ancillary Information Facility

Also known as meta-data

July 2013

N IF

What are Comments?

Navigation and Ancillary Information Facility

Comments 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 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 Data pedigree How and by whom the kernel was created
The program(s) and/or steps used in creation Contact information for users questions email address phone numbers

Data sources used as inputs when creating the kernel Intended kernel usage Companion files

In SPICE, we sometimes refer to comments as meta-data

Comments in SPICE Kernels

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 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

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)
This capability is not yet available in Mice

Text Kernels
Use a text editor
Begin comment sections with the \begintext marker alone on a line
(The marker is not needed for comments placed at the beginning of a text kernel)

End comment sections with a \begindata marker 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

Comments in SPICE Kernels

N IF
Navigation and Ancillary Information Facility

Getting and Installing the SPICE Toolkit

July 2013

N IF

Getting Toolkit
Navigation and Ancillary Information Facility

All instances of the SPICE Toolkit are available 24x7 from the NAIF server:
http://naif.jpl.nasa.gov/naif/toolkit.html

No password or identification is needed To download a Toolkit package

Select language FORTRAN, C, IDL, or MATLAB Select computer platform/OS/compiler combination Be careful about picking the right architecture: 64 or 32 bit Download all toolkit package components package file toolkit.tar.Z (or toolkit.exe), cspice.tar.Z (or cspice.exe), icy.tar.Z (or icy.exe), or mice.tar.Z (or mice.exe) Installation script (if present) import*.csh Accompanying documents - README, dscriptn.txt, whats,new
Installing the SPICE Toolkit

N IF

Dont Port it Yourself

Navigation and Ancillary Information Facility

The packages provided on the NAIF server have been built and tested by NAIF on the indicated environments. We highly recommend you NOT try to port any instance of the Toolkit to some other environment, especially without consulting with NAIF first.
There are portability issues and compiler optimization issues that must be carefully dealt with.

Installing the SPICE Toolkit

N IF

Installing Toolkit
Navigation and Ancillary Information Facility Terminal Window

To install the Toolkit, follow the directions given in the README. Normally this consists of the following for Unix, Linux and OSX boxes:
prompt> chmod u+x importSpice.csh prompt> ./importSpice.csh prompt> rm toolkit.tar

For PCs running Windows, execute the toolkit.exe application (or cspice or icy or mice) to expand the archive.
> toolkit

You now have the expanded toolkit (or cspice or icy or mice) package.

Installing the SPICE Toolkit

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

N IF

Checking It Out
Navigation and Ancillary Information Facility

Try some executables

Use tobin to convert the SPICE transfer format SPK and CK files supplied with the Toolkit to local binary format cook_01.tsp, cook_02.tsp, cook_01.tc, and cook_02.tc are found in the ../data directory Use brief, ckbrief or spacit to summarize the converted kernels

Problems might occur if your operating system or compiler versions are (way) out of sync with what NAIF used in making its builds
Rebuild the Toolkit using the script makeall.csh (or makeall.bat) located in the top level directory (toolkit or cspice or icy or mice)

In the rare circumstance that things still dont work, contact your System Administrator or NAIF

Installing the SPICE Toolkit

N IF

Backup
Navigation and Ancillary Information Facility

Getting the Toolkit using command line FTP

Installing the SPICE Toolkit

N IF

Command line FTP - 1

Navigation and Ancillary Information Facility Terminal Window

prompt> ftp naif.jpl.nasa.gov Connected to naif.jpl.nasa.gov 220 Welcome to the NAIF FTP service. Name (your.sight:your_name): anonymous 331 Please specify the password Password: [email protected] 230230- ====================================================================== 230- | Jet Propulsion Laboratory | 230- | * * * W A R N I N G * * * | 230- | Property of the | 230- | UNITED STATES GOVERNMENT | 230- ====================================================================== 230230 Login successful. Have fun. Remote system type is UNIX. Using binary mode to transfer files. ftp> cd pub/naif/toolkit/<FORTRAN or C or IDL or MATLAB> 250 CWD command successful. ftp> dir

Installing the SPICE Toolkit

N IF
ftp> dir Mac_OSX_Absoft Mac_OSX_IFORT Mac_OSX_g77 PC_Cygwin PC_Linux PC_Windows_Digital PC_Windows_IFORT PC_Windows_Lahey Sun_Solaris

Command line FTP - 2

Navigation and Ancillary Information Facility Terminal Window
ftp> dir Mac_OSX_Apple_C Mac_OSX_Intel_C PC_Cygwin_C PC_Linux_C PC_Linux_C_64bit PC_Windows_Visual_C Sun_Solaris_C Sun_Solaris_GCC Sun_Solaris_GCC_64bit ftp> dir Mac_OSX_Apple_C Mac_OSX_Intel_C PC_Linux_C PC_Windows_Visual_C Sun_Solaris_C Sun_Solaris_GCC ftp> dir Mac_OSX_Apple_C Mac_OSX_Intel_C PC_Linux_C PC_Windows_Visual_C

The environments available at the time you download the Toolkit will likely differ from those shown here.

FORTRAN

IDL

MATLAB

Installing the SPICE Toolkit

N IF

Command line FTP - 3

Navigation and Ancillary Information Facility Terminal Window

ftp> cd <environment>/packages ftp> binary 200 Type set to I ftp> get toolkit.tar.Z ( or toolkit.exe or cspice.tar.Z or cspice.exe or icy.tar.Z or icy.exe or mice.tar.Z or mice.exe ) . . . ftp> ascii 200 Type set to A ftp> get importSpice.csh ( or importCSpice.csh or importIcy.csh or importMice.csh ) ( not availabe for Windows environment ) ftp> get README ftp> get dscriptn.txt ftp> get whats.new ftp> quit

Installing the SPICE Toolkit

N IF
Navigation and Ancillary Information Facility

Preparing for Programming Using the SPICE Toolkits

July 2013

N IF
Unix
set set set set

Setting Path to Toolkit Executables

Navigation and Ancillary Information Facility

Recommended for all languages

csh, tcsh: Use the set command to add the location of toolkit executables to your path.
path path path path = = = = ($path ($path ($path ($path /my_directory/toolkit/exe) /my_directory/cspice/exe) /my_directory/icy/exe) /my_directory/mice/exe)

bash
PATH=$PATH:/my_directory/toolkit/exe PATH=$PATH:/my_directory/cspice/exe PATH=$PATH:/my_directory/icy/exe PATH=$PATH:/my_directory/mice/exe

Windows
Add location of toolkit executables to the environment variable PATH from the Advanced pane on the System Control Panel (Control Panel->System->Advanced).
drive:\my_directory\toolkit\exe drive:\my_directory\cspice\exe drive:\my_directory\icy\exe drive:\my_directory\mice\exe

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

Preparing for Programming

N IF
/naif/cspice/ /naif/toolkit/

Unix/Linux: Builds
Navigation and Ancillary Information Facility

Assume your Toolkit distribution is installed at:

for CSPICE (C toolkits) for SPICE (Fortran toolkits)

Compile and link an applicationlets pretend its named programagainst the CSPICE or SPICELIB library.
For C: $ gcc program.c -I/naif/cspice/include /naif/cspice/lib/cspice.a -lm For FORTRAN:
$ g77 program.f /naif/toolkit/spicelib.a

Note: some FORTRAN compilers (e.g. Absoft) require an additional flag "-lU77" to pull in the standard Unix symbols when linking against SPICELIB.

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

N IF

Windows: 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. This depends on your version of the Microsoft development environment.
If programming for a 32-bit environment, you can set the environment variables by executing from a DOS shell one of the vars32 batch scripts supplied with Microsoft compilers:
vars32.bat vcvars32.bat vsvars32.bat

If available on your system, you can execute the Visual Studio version Command Prompt utility from the Programs -> Microsoft Visual Studio version -> Visual Studio Tools menu. The utility spawns a DOS shell set with the appropriate environment variables.

Preparing for Programming

N IF

Windows: Builds for C and Fortran

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:

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

Preparing for Programming

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.
Unix, X86 architecture
cp icy.dlm icy.so /usr/local/itt/idl64/bin/bin.linux.x86/

Windows, X86 architecture

cp icy.dlm icy.dll C:\ITT\IDL64\bin\bin.x86\

continued on next page

Preparing for Programming

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_"

Caveat: 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 to IDL_DLM_PATH the directory. This directory contains an icy.dlm but not icy.so.

continued on next page

Preparing for Programming

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 (by whatever means) 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

N IF

Icy: Using the IDL IDE

Navigation and Ancillary Information Facility

Recommended for Icy Use the IDL IDEs preferences panel to set the current working directory to the location where you will be developing your lessons code. Optional: Place your dlm_register command in a start up script. Specify the script using the IDL IDEs preferences panel.

Preparing for Programming

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

N IF
Navigation and Ancillary Information Facility

Backup
Icy programming example Mice programming example References

Preparing for Programming

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

N IF

Graphic Output
Navigation and Ancillary Information Facility

z y

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

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' ); % x y z Plot the resulting trajectory. = pos(1,:); = pos(2,:); = pos(3,:);

plot3(x,y,z) cspice_kclear

Preparing for Programming

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

N IF

References
Navigation and Ancillary Information Facility

icy.req, Icy Required Reading mice.req, Mice Required Reading Introduction to the Family of SPICE Toolkits, tutorial

Preparing for Programming

N IF
Navigation and Ancillary Information Facility

Introduction to the Family of SPICE Toolkits

July 2013

N IF

Topics
Navigation and Ancillary Information Facility

Architecture Contents Characteristics Versions Capabilities Directory Structure Application Programs Utility Programs Documentation Backup: Currently Supported Environments

Introduction to the SPICE Toolkit

N IF

Toolkit Architecture
Navigation and Ancillary Information Facility

The SPICE Toolkit is available in Fortran, C, IDL (Interactive Data Language), and Matlab. The Fortran, C, IDL, and Matlab Toolkits are packaged and delivered as standalone products.
The IDL and Matlab Toolkits, by necessity, also include the complete C Toolkit.

Introduction to the SPICE Toolkit

N IF
Users Application Program

Toolkit Architecture Pictorial

Navigation and Ancillary Information Facility
Users Application Program Users Application Program Users Application Program

IDL Wrappers ANSI C Wrappers ANSI C Wrappers

Matlab Wrappers ANSI C Wrappers

ANSI Fortran 77

f2c

Translated C

Application and Utility Programs

f2c

Application and Utility Programs

Language Product name

FORTRAN Toolkit

C CSPICE

CSPICE runs under a wide variety of ANSI C compilers. 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.
Includes all the most commonly used modules. More will be added as time permits.

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

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.
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

N IF
Toolkit Version

Toolkit Versions
Navigation and Ancillary Information Facility

SPICE Toolkits have an associated Version number

Example: N0064 (also written as N64)

The version number applies to the Fortran, C, IDL and Matlab 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, Icy or Mice or the geometry finder subsystem

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

N IF

Toolkit Library Overview

Navigation and Ancillary Information Facility

Toolkit libraries contain a broad set of capabilities related to the computations needed for observation geometry and time conversions. 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) Toolkit duplicates most functionality available in the C Toolkit wrapper routines. The Matlab (Mice) Toolkit provides interfaces to those routines NAIF considers the most often needed by users.

Introduction to the SPICE Toolkit

N IF

Toolkit Library Capabilities

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) Query binary EK files (EK-ESQ)

Kernel write access

Sorting, finding order vector, reordering Searching: linear, binary Insertion and deletion

Name/code conversion
Bodies Frames

I/O support
Logical unit management (Fortran toolkits) Open, read, write text files Kernel pool API

Exception handling
Control exception handling behavior: mode, set message, assign output device.

Introduction to the SPICE Toolkit

N IF

Toolkit Library Capabilities

Navigation and Ancillary Information Facility

Advanced data types

Cells, Sets Windows (sometimes called schedules) Symbol Tables Planes, Ellipses

Introduction to the SPICE Toolkit

N IF

Toolkit Directory Structure

Navigation and Ancillary Information Facility

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.

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

Introduction to the SPICE Toolkit

N IF
data doc

Toolkit Directory Structure

Navigation and Ancillary Information Facility

The next level is comprised of:

Cookbook example kernels (use ONLY for training with cookbook programs). 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, Users Guide pages, etc.).

etc
In generic Toolkits this directory is empty.

exe
Executables for brief, chronos, ckbrief, commnt, inspekt, mkspk, msopck, spacit, spkdiff, frmdiff, spkmerge, tobin, toxfr, version. Executables for the several cookbook example programs.

Introduction to the SPICE Toolkit

N IF
lib

Toolkit Directory Structure

Navigation and Ancillary Information Facility
File to include in callers of CSPICE is SpiceUsr.h

include (applies to CSPICE, Icy, and Mice)

API header files.

Toolkit libraries:
For Fortran SPICE Toolkits
spicelib.a or spicelib.lib (public modules; use these) support.a or support.lib (private modules; dont use these)

For CSPICE Toolkits

cspice.a or cspice.lib (public modules; use these) csupport.a or csupport.lib (private modules; dont use these)

For Icy Toolkits:

icy.so (shared object library) icy.dlm (dynamically loadable module) cspice.a or cspice.lib csupport.a or csupport.lib

For Mice Toolkits:

mice.mex* (shared object library) cspice.a or cspice.lib 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 *.h files appearing here are not part of the user API

Introduction to the SPICE Toolkit

N IF

Toolkit Application Programs

Navigation and Ancillary Information Facility

SPICE Toolkit application programs perform various tasks. Some examples are:
create a new SPK file from a text file of state vectors or elements
mkspk

compare (diff) two SPKs

spkdiff

compare (diff) two reference frames

frmdiff

create a new CK from a text file of attitude data

msopck

carry out a wide assortment of time conversions

chronos

query an Event Kernel (EK)

inspekt

Introduction to the SPICE Toolkit

N IF
commnt

Toolkit Utility Programs

Navigation and Ancillary Information Facility

SPICE Toolkit utility programs are available to:

add comments to binary kernels read comments from binary kernels
commnt, spacit inspekt (only for EK/ESQ files)

summarize coverage of binary kernels

brief, ckbrief, 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)

Introduction to the SPICE Toolkit

N IF

Toolkit Documentation
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 Act as primary functional specification: I/O, exceptions, particulars defining behavior of module 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

continues on next page

Introduction to the SPICE Toolkit

N IF

Toolkit Documentation
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 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 of Required Readings were adapted for all languages
Some of the Required Reading documents provided with CSPICE are still based upon Fortran SPICE Some of the Required Readings for Icy or Mice toolkits are still based upon CSPICE

Users Guides Interface specifications for the Toolkit utility programs and applications. HTML versions are accessible using the Users Guide Documents link from the top level index. Plain text versions are located under doc and have extension .ug.

Introduction to the SPICE Toolkit

N IF

Toolkit Documentation
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: C: IDL: Matlab: spicelib.idx cspice.idx icy.idx and cspice .idx 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

N IF

Toolkit Documentation
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. Whats New in SPICE Describes new features and bug fixes in each Toolkit release. Plain text version is doc/whats.new. HTML version is accessible using the Whats 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

Introduction to the SPICE Toolkit

N IF
Navigation and Ancillary Information Facility

Backup Supported Environments

Introduction to the SPICE Toolkit

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.
Please dont try to use or port a Toolkit built for another environment.

For the version N0064 Toolkit, NAIF supports a few more environments than those shown on the next four charts, but these will be gone as of N0065.

Introduction to the SPICE Toolkit

N IF

Supported Environments - Fortran

Navigation and Ancillary Information Facility

Product Name
Mac/Intel, OS-X, Intel FORTRAN, 32bit Mac/Intel, OS-X, Intel FORTRAN, 64bit Mac/Intel, OS-X, gfortran, 32bit Mac/Intel, OS-X, gfortran, 64bit PC, CYGWIN, g77, 32bit PC, Linux, Intel FORTRAN, 32bit PC, Linux, g77, 32bit PC, Linux, gfortran, 32bit PC, Linux, gfortran, 64bit PC, Windows, Intel FORTRAN, 32bit PC, Windows, Intel FORTRAN, 64bit Sun/Intel, Solaris, SUN FORTRAN, 32bit Sun/SPARC, Solaris, SUN FORTRAN, 32bit

Operating System
OS X 10.6.8 OS X 10.6.8 OS X 10.6.8 OS X 10.6.8 Windows/Cygwin Red Hat Linux (RHE4) Red Hat Linux (RHE4) Red Hat Linux (RHE4) Red Hat Linux (RHE4) Windows XP Windows XP Solaris 9 Solaris 9

Compiler
Intel Fortran 10.1 Intel Fortran 10.1 gfortran, GNU Fortran 4.3 gfortran, GNU Fortran 4.3 g77, GNU Fortran 3.2 Intel Fortran 10.0 g77, GNU Fortran 3.4 gfortran, GNU Fortran 4.3 gfortran, GNU Fortran 4.3 Intel Fortran 9.1 Intel Fortran 9.1 Sun FORTRAN 95 8.2 Sun FORTRAN 95 8.2

Introduction to the SPICE Toolkit

N IF
Product Name
Mac/Intel, OS-X, Apple C. 32bit Mac/Intel, OS-X, Apple C, 64bit PC, CYGWIN, gCC, 32bit PC, Linux, gCC, 32bit PC, Linux, gCC, 64bit PC, Windows, Microsoft Visual C, 32bit PC, Windows, Microsoft Visual C, 64bit Sun/Intel, Solaris, SunC, 32bit Sun/Intel, Solaris, SunC, 64bit Sun/SPARC, Solaris, gCC, 32bit Sun/SPARC, Solaris, gCC, 64bit Sun/SPARC, Solaris, SUN C, 32bit Sun/SPARC, Solaris, SUN C, 64bit

Supported Environments - C
Navigation and Ancillary Information Facility

Operating System
OS X 10.4.x OS X 10.4.x Windows/Cygwin Red Hat Linux (RHE4) Red Hat Linux (RHE4) Windows NT/2K/XP Windows NT/2K/XP Solaris 9 Solaris 9 Solaris 9 Solaris 9 Solaris 9 Solaris 9

Compiler
gcc, GNU C 4.2.1 gcc, GNU C 4.2.1 gcc, GNU C 3.2 gcc, GNU C 3.4.6 gcc, GNU C 3.4.6 Microsoft Visual Studio 2008 C Microsoft Visual Studio 2008 C SunC, GNU C 3.3.2 SunC, GNU C 3.3.2 gcc, GNU C 3.3.2 gcc, GNU C 3.3.2 Sun C 5.8 Sun C 5.8

Introduction to the SPICE Toolkit

N IF
Product Name
Mac/Intel, OS-X, Apple C/IDL, 32bit Mac/Intel, OS-X, Apple C/IDL, 64bit PC, Linux, gcc/IDL, 32bit PC, Linux, gcc/IDL, 64bit

Supported Environments - IDL*

Navigation and Ancillary Information Facility

Operating System
OS X 10.6.8 OS X 10.6.8 Red Hat Linux (RHE4) Red Hat Linux (RHE4) Windows XP Windows XP Solaris 9 Solaris 9 Solaris 9

Compiler
gcc, GNU C 4.2.1 gcc, GNU C 4.2.1 gcc, GNU C 3.4.6 gcc, GNU C 3.4.6 Microsoft Visual Studio 2008 C Microsoft Visual Studio 2008 C gcc, GNU C 3.3.2 gcc, GNU C 3.3.2 Sun C 5.8

PC, Windows, Microsoft Visual C/IDL, 32bit PC, Windows, Microsoft Visual C/IDL, 64bit Sun, Solaris, gcc/IDL, 32bit Sun, Solaris, gcc/IDL, 64bit Sun, Solaris, SUN C/IDL, 32bit

*NAIF built and tested Icy using IDL version 8.1.

Introduction to the SPICE Toolkit

N IF
Product Name
Mac/Intel, OS-X, Apple C, 32bit Mac/Intel, OS-X, Apple C, 64bit PC, Linux, gCC, 32bit PC, Linux, gCC, 64bit PC, Windows, Microsoft Visual C/ Matlab, 32bit PC, Windows, Microsoft Visual C/ Matlab, 64bit Sun, Solaris, SUN C/Matlab, 32bit

Supported Environments - Matlab*

Navigation and Ancillary Information Facility

Operating System
OS X 10.6.8 OS X 10.6.8 Red Hat Linux (RHE4) Red Hat Linux (RHE4) Windows XP Windows XP Solaris 9

Compiler
gcc, GNU C 4.2.1 gcc, GNU C 4.2.1 gcc, GNU C 3.4.6 gcc, GNU C 3.4.6 Microsoft Visual Studio .NET 7.0 C Microsoft Visual Studio 2008 C Sun C 5.8

*Mice requires use of Matlab version 7.2 (R2006a) or higher

Introduction to the SPICE Toolkit

N IF

Unsupported Environments
Navigation and Ancillary Information Facility

NAIF is unable to support environments other than those listed on the previous set of charts. The SPICE and CSPICE packages should function as expected on platforms running:
OpenBSD FreeBSD minGW

using a current gfortran or gcc compiler.

The Mice package has been successfully built against the octave environment (version < 3.4) on Linux and OS X.

Introduction to the SPICE Toolkit

N IF

Unsupported Environments
Navigation and Ancillary Information Facility

NAIF does not support these environments. However

The SPICE and CSPICE packages should function as expected on any platform using a current gcc tool-chain (gcc version < 4.0 does not constitute current, neither does pre OS X Mac OS). Examples of such platforms are:

OpenBSD FreeBSD minGW

The Mice package has been successfully built against the GNU Octave environment (version < 3.4) on Linux and OS X.

Introduction to the SPICE Toolkit

N IF
Navigation and Ancillary Information Facility

Matlab Interface to CSPICE Mice

How to Access the CSPICE library Using Matlab July 2013

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

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

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.

MATLAB Interface to CSPICE

N IF

How Does It Work? (2)

Navigation and Ancillary Information Facility

continued on next page

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

Exelis

N IF

Topics
Navigation and Ancillary Information Facility

Icy Benefits How does it work? Distribution Icy Operation Vectorization Simple Use of Icy Functionality

IDL Interface to CSPICE

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 three-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

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 routines call parameters.

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

continued on next page

IDL Interface to CSPICE

N IF

How Does It Work? (2)

Navigation and Ancillary Information Facility

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:

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 IDLs 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.

IDL Interface to CSPICE

continued on next page

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

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

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

N IF

Simple Use of Icy Functionality

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: "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 IDL Interface to CSPICE

N IF

Graphic Output using IDL iTool

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

N IF
Navigation and Ancillary Information Facility

Using Module (API) Headers

July 2013

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

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

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

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
SPKEZR STR2ET

C
spkezr_c str2et_c

IDL (Icy)
cspice_spkezr cspice_str2et

MATLAB (Mice)
cspice_spkezr cspice_str2et

spkezr is the principal ephemeris access module str2et is a key time conversion module

Using Module Headers

N IF
Navigation and Ancillary Information Facility

Time Conversion and Time Formats

July 2013

N IF

Time Systems and Kernels

Navigation and Ancillary Information Facility

Time inputs to and outputs from users 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) 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 Encoded Spacecraft Clock, expressed as clock ticks since the clock start

SPICE provides routines to convert between these string and numeric representations

Time Conversion and Formats

N IF

Converting Time Strings

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. For example:
1996-12-18T12:28:28 1978/03/12 23:28:59.29 Mar 2, 1993 11:18:17.287 p.m. PDT 1995-008T18:28:12 1993-321//12:28:28.287 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

Spacecraft Clock String to numeric Ephemeris Time

SCS2E ( scid, string, ET ) Converts SCLK strings consistent with SCLK parameters. For example:
5/65439:18:513 (VGR1) 946814430.172 (MRO) 1/0344476949-27365 (MSL)

Requires a SCLK kernel and the LSK kernel

Time Conversion and Formats

N IF

Converting Numeric Times

Navigation and Ancillary Information Facility

Numeric Ephemeris Time to Calendar, DOY or Julian Date UTC, TDB, or TDT String
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 a backup 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

Numeric Ephemeris Time to Spacecraft Clock String

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

Time Conversion and Formats

N IF

Quoting Time Strings

Navigation and Ancillary Information Facility

Any kind of time string used as an argument in a SPICE API must be provided in quotes
Fortran, Matlab and IDL: use single quotes C: use double quotes

Time Conversion and Formats

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 (to compute body position relative to the Sun) and PCK (to compute body rotation) kernels

Numeric Ephemeris Time to planetocentric longitude of the Sun (Ls)

Return value = LSPCN (body, et, abcorr ) While Ls is not a time system, it is frequently used to determine body season for a given epoch
Spring 0 Ls; Summer 90 Ls; Autumn 180 Ls; Winter 270 Ls

Requires SPK and PCK kernels

Time Conversion and Formats

N IF
Uniform time systems (TDT,TAI, JED, JDTDT)

Principal Time System Interfaces

Navigation and Ancillary Information Facility
L-sub-S Local Solar Time Kernels needed needs lsk UTC seconds past J2000 needs sclk needs lsk and sclk LSPCN ET2LST DELTET needs pck and spk needs no kernels
(planetocentric longitude of the sun)

Time string in UTC, TDB or TDT

UNITIM Barycentric Dynamical Time (TDB or ET) SCS2E SCE2S

(Includes lots of formatting flexibility)

TIMOUT ET2UTC ETCAL

SCE2C

SCT2E SCDECD

STR2ET TDB string

Time Conversion and Formats

Encoded Spacecraft Clock (Ticks) SCENCD = APIs mentioned in this tutorial

Spacecraft Clock (SCLK)

N IF
Navigation and Ancillary Information Facility

Backup

Time Conversion and Formats

N IF

Use of Time Format Picture

Navigation and Ancillary Information Facility

Example Time Strings and the Corresponding Format Pictures

Common Time Strings
1999-03-21T12:28:29.702 1999-283T12:29:33 1999-01-12, 12:00:01.342 TDB 2450297.19942145 JD TDB

Format Picture Used (fmtpic)

YYYY-MM-DDTHR:MN:SC.### YYYY-DOYTHR:MN:SC ::RND YYYY-MM-DD, HR:MN:SC.### ::TDB TDB JULIAND.######## ::TDB JD TDB

Less Common Time Strings

465 B.C. Jan 12 03:15:23 p.m. 04:28:55 A.M. June 12, 1982 Thursday November 04, 1999 DEC 31, 15:59:60.12 1998 (PST)

Format Picture Used (fmtpic)

YYYY ERA Mon DD AP:MN:SC ampm AP:MN:SC AMPM Month DD, YYYY Weekday Month DD, YYYY MON DD, HR:MN:SC YYYY (PST)::UTC-8

Time Conversion and Formats

N IF
Navigation and Ancillary Information Facility

Leapseconds and Spacecraft Clock Kernels LSK and SCLK

July 2013

N IF

Topics
Navigation and Ancillary Information Facility

Kernels Supporting Time Conversions

LSK SCLK

Forms of SCLK Time Within SPICE Backup

LSK & SCLK

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).
(Its possible there could be two or more clocks associated with a given spacecraft.)

LSK & SCLK

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.
Utility programs using LSK: spkmerge, chronos, spacit, etc. Subroutines using LSK: STR2ET, TIMOUT, ET2UTC, etc.

As with all SPICE kernels, load it using FURNSH. 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 always the best one to use. Announcement of each new LSK is made using the spice_announce system. http://naif.jpl.nasa.gov/mailman/listinfo/spice_announce Updates can occur ONLY on January 1st and July 1st
LSK & SCLK

N IF
KPL/LSK . . . <comments> . . . \begindata DELTET/DELTA_T_A DELTET/K DELTET/EB DELTET/M DELTET/DELTA_AT

LSK File Example

Navigation and Ancillary Information Facility

= 32.184 = 1.657D-3 = 1.671D-2 = ( 6.239996D0

1.99096871D-7 )

= ( 10, @1972-JAN-1 11, @1972-JUL-1 12, @1973-JAN-1 13, @1974-JAN-1 14, @1975-JAN-1 . . . <more leapsecond records> . . . 32, @1999-JAN-1 33, @2006-JAN-1 34, @2009-JAN-1 )

\begintext

LSK & SCLK

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

N IF

The Spacecraft Clock Kernel (SCLK)

Navigation and Ancillary Information Facility

The spacecraft clock kernel contains data used in conversions from SCLK to other time systems. It is required by Toolkit utilities and routines that utilize SCLK time.
For example, the SPICE CK subsystem makes heavy use of spacecraft clock time.

As with all SPICE kernels, 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 projects database. 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

N IF
KPL/SCLK . . . <comments> . . . \begindata SCLK_KERNEL_ID SCLK_DATA_TYPE_74 SCLK01_TIME_SYSTEM_74 SCLK01_N_FIELDS_74 SCLK01_MODULI_74 SCLK01_OFFSETS_74 SCLK01_OUTPUT_DELIM_74 = = = = = = = ( ( ( ( ( ( (

SCLK File Example

Navigation and Ancillary Information Facility

@2009-12-07/18:03:04.00 ) 1 ) 2 ) 2 ) 4294967296 256 ) 0 0 ) 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

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, whether for science or engineering/housekeeping data.

A SCLK value encoded as a double precision number (called ticks) is used within SPICE because its easy to convert this to other time systems, such as ephemeris time (ET, also called TDB).
LSK & SCLK

N IF

Sample SCLK String

Navigation and Ancillary Information Facility

The Cassini orbiter SCLK time string consists of three fields separated by delimiters.
Partition Delimiter

1/1609504792.123

Clock Field Delimiter* (not a decimal point)

Partition: Accounts for clock resets or counter roll-over.

Least Significant Clock Field: Ranges from 0 to 255. Nominally 1/256th of a second increment.

Most Significant Clock Field: Ranges from 0 to 4294967295 (232-1). Nominally 1 second increment.
LSK & SCLK

* Several SCLK delimiter characters are available in SPICE. See SCLK Required Reading for details.
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. When referring to epochs in the first partition, the leading 1/ may be omitted. Many modern spacecraft dont use a partition other than 1.

LSK & SCLK

N IF

Constructing an SCLK String

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 First four bytes are an unsigned integer representing seconds Last byte is an unsigned byte representing fractional seconds (as a count of 1/256 second ticks) Convert integer and fractional seconds to two strings Concatenate strings together using a recognized delimiter (., :, etc) Add the partition number and delimiter Optional, for most modern missions it may be omitted (not so for Chandrayaan-1 )
LSK & SCLK

5F EF 18 18 7B

1609504792 '123 1609504792.123 1/1609504792.123

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

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 Most Useful SPICELIB Routines headers for the routines mentioned in this tutorial CHRONOS Users Guide Porting_kernels tutorial

Related documents
Kernel Required Reading CK Required Reading

LSK & SCLK

N IF

Backup
Navigation and Ancillary Information Facility

Examples of SCLK strings SCLK Interface Routines

LSK & SCLK

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. Intermediate Clock Field: Ranges from 0 to 9. Nominally 1/15th of a second. Intermediate Clock Field: Ranges from 0 to 90. Nominally 2/3rd of a second.

Partition: Accounts for clock resets or counter rollover. Most Significant Clock Field: Ranges from 0 to 16777214. Nominally 60 2/3rd second increment.

LSK & SCLK

N IF

More Sample SCLK Strings

Navigation and Ancillary Information Facility

The following are examples of SCLK strings* from missions using SPICE.
Cassini
1/1334314108.134

MPF
1/559627908.058

Viking 1&2
1/32233616

DS1
1/67532406.010

Mariner 9
1/11542909

Voyager 1&2
1/05812:00:001

Galileo
1/16777214:90:9:7

Mars Odyssey
1/687231994.091

Mars Express
1/0090979196.29713

Genesis
1/666230496.204

NEAR
1/40409721942

Venus Express
1/0033264000.50826

MGS
1/655931592.103

Stardust
1/697451990.042

Rosetta
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

N IF

SCLK Interface Routines

Navigation and Ancillary Information Facility

Convert SCLK times using the following routines

SCS2E (SC, SCLKCH, ET) SCE2S (SC, ET, SCLKCH) SCT2E (SC, SCLKDP, ET) SCE2C1 (SC, ET, SCLKDP) SCE2T (SC, ET, SCLKDP) SCENCD(SC, SCLKCH, SCLKDP) SCDECD(SC, SCLKDP, SCLKCH) (SCLK String ET) (ET SCLK String) (Encoded SCLK ET) (ET Continuous Encoded SCLK) (ET Discrete Encoded SCLK) (Encode SCLK) (Decode SCLK)

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

LSK & SCLK

N IF
Navigation and Ancillary Information Facility

Introduction to the SPICE Ephemeris Subsystem SPK

Focused on reading SPK files

July 2013

N IF

First clear your mind!

Navigation and Ancillary Information Facility

SPK is probably unlike any previous ephemeris or trajectory representation youve used or heard about. We think youll find it to be much more capable than other ephemeris system architectures. As such, its also a bit more complicated to grasp. Dont panic! Shortly youll be reading SPK files like a pro.

SPK Subsystem

N IF
Navigation and Ancillary Information Facility

Overview of SPICE Ephemeris Data

SPK Subsystem

N IF

A Picture is worth
Navigation and Ancillary Information Facility

Well start with a mostly pictorial view of ephemeris data and SPK files, just to ease you into this topic.

SPK Subsystem

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, often referred to as the 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

A single SPK file can contain data for multiple ephemeris objects, and often does See the next page for a pictorial representation of some of these objects.
SPK Subsystem

N IF

Examples of Ephemeris Objects

Navigation and Ancillary Information Facility
Asteroid Comet

The head and the tail of every blue arrow are located at ephemeris objects.
Sun

Antenna feed cone

Solar system barycenter* Spacecraft

Earth

....
*A barycenter is the center
of mass of a system of bodies, such as Saturn plus all of Saturn's satellites, or, the sun and all the planets and satellites in the solar system. SPK Subsystem

Communications Station Satellite Planetary system barycenter*

Lander or rover

Planet's mass center 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 epoch_4, x4, y4, z4, vx4, vy4, vz4 .................. etc. ................... .................. etc. ................... epoch_n, xn, yn, zn, vxn, vyn, vzn epoch = time

Perhaps this is an ASCII table or an Excel spreadsheet containing rows of time-tagged Cartesian state vectors

It may not be written inside the table or spreadsheet, but perhaps an interface agreement and/or a table name somehow tells you:
what objectthe targetthis ephemeris is for what is the name of the reference frame (coordinate frame) in which the data are given what is the center of motion of the target maybe also what are the start and stop times of the file meaning, what are epoch_1 and epoch_n
SPK Subsystem

We insert this meta-data into the segment

what objectthe targetthis ephemeris is for what is the name of the reference frame (coordinate frame) in which the data are given what is the center of motion of the target maybe also what are the start and stop times of the file meaning, what are epoch_1 and epoch_n
SPK Subsystem

N IF
Some other stuff

A Simple SPK File

Navigation and Ancillary Information Facility

Target, Ref Frame ID, Center of Motion, Tstart, Tstop

This most simple of SPK files is made up of a single segment containing ephemeris data:

SPK Subsystem

for a single object (perhaps a spacecraft, an asteroid, or whatever) given in a single reference frame (coordinate frame) having a single center of motion with data spanning from Tstart to Tstop
11

N IF
Some other stuff

A More Substantial SPK File

Navigation and Ancillary Information Facility

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, x1, y1, vx1, vy1, epoch-4, x4, Ref y4,Frame z4, z1, vx4, vy4, vz4 vz1 Target, ID, Center of Motion T5, T6 epoch-2, x2, y2, z2, vx2, vy2, vz2 .................. etc. ................... epoch-3, x3, y3, z3, vx3, vy3, vz3 .................. etc. ................... epoch_1, x1, z4, y1, vx4, z1, vx1, vy1, epoch-4, x4, y4, vy4, vz4 vz1 epoch-n, xn, yn, zn, vxn, vyn, vzn epoch_2, x2, y2, z2, vx2, vy2, vz2 .................. etc. ................... epoch_3, x3, y3, z3, vx3, vy3, vz3 .................. etc. ................... epoch_4, x4, zn, y4, vxn, z4, vx4, epoch-n, xn, yn, 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 with data spanning from T1 to T6

SPK Subsystem

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

epoch-1, x1, y1, z1, vx1, vy1, vz1 Target, Ref Frame Center of Motion, epoch-2, x2, y2, z2,ID, vx2, vy2, vz2 T5, T6 epoch-1, x1, y1, z1, vx1, vy1, vz1 epoch-3, x3,x2, y3, z3,z2, vx3, vy3, vz3 Target, Ref Frame ID, Center of Motion, epoch-2, y2, vx2, vy2, vz2 T7, T8 epoch-1, x1, y1, z1, vx1, vy1, vz1 epoch-4, x4, y4, z4, vx4, vy4, vz4 epoch-3, x3, y3, z3, vx3, vy3, vz3 Target, Ref Frame Center of Motion, epoch-2, x2, y2, z2,ID, vx2, vy2, vz2 T9, T10 .................. etc. ................... epoch-1, x1, z4, y1, vx4, z1, vx1, vy1, vz1 epoch-4, x4, y4, vy4, vz4 epoch-3, x3, y3, z3, vx3, vy3, vz3 .................. etc. ................... Target, Ref Frame Center of Motion, epoch-2, x2, y2, z2,ID, vx2, vy2, vz2 T11, T12 .................. etc. ................... epoch-1, x1, y1, z1, vx1, vy1, vz1 epoch-4, x4, y4, z4, vx4, vy4, vz4 epoch-n, xn, yn, x3, zn, y3, vxn, vyn, vzn epoch-3, z3, vx3, vy3, vz3 .................. etc. ................... epoch-2, x2, y2, z2, vx2, vy2, vz2 .................. etc. ................... epoch_1, x1, y1,vx4, z1, vy4, vx1, vy1, vz1 epoch-4, x4, y4, z4, vz4 epoch-n, xn, yn, x3, zn, y3, vxn, vyn, vzn epoch-3, z3, vx3, vy3, vz3vz2 .................. etc. ................... epoch_2, x2, y2, z2, vx2, vy2, .................. etc. ................... epoch-4, x4, x3, y4, y3, z4, z3, vx4, vy4, vz4vz3 epoch-n, xn, yn, zn, vxn, vyn, vzn epoch_3, vx3, vy3, .................. etc. ................... .................. etc. ................... epoch_4, x4,zn, y4,vxn, z4, vx4, epoch-n, xn, yn, vyn, vy4, vzn vz4 .................. etc. ................... .................. etc. ................... epoch-n, xn, yn, zn, vxn, vyn, vzn .................. etc. ................... epoch_n, xn, yn, zn, vxn, vyn, vzn

Target, Ref Frame ID, Center of Motion, T3, T4

This even more substantial SPK contains multiple segments having:

different objects different reference frames different centers of motion
SPK Subsystem

different pairs of start and stop times

N IF
Some other stuff

SPK Type Info in each Segment

Navigation and Ancillary Information Facility

Target, Ref Frame ID, Center of Motion, T1, T2, Type 13

epoch_1, epoch_2, epoch_3, epoch_4,

x1, x2, x3, x4,

y1, y2, y3, y4,

z1, z2, z3, z4,

vx1, vx2, vx3, vx4,

vy1, vy2, vy3, vy4,

vz1 vz2 vz3 vz4

Each segment can contain a different type of ephemeris data (as long as its been built into the SPK subsystem). Examples:
Discrete state vectors Chebyshev polynomials Conic elements Etc., etc.

Target, Ref Frame ID, Center of Motion, T3, T4, Type 3

MID, RADIUS, X coefs, Y coefs, Z coefs MID, RADIUS, X coefs, Y coefs, Z coefs MID, RADIUS, X coefs, Y coefs, Z coefs (some time tag info)
Target, Ref Frame ID, Center of Motion, T5, T6, Type 1

Each segment has the SPK Type stored in its meta-data record. Toolkit software knows how to 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

N IF
epoch_1, epoch_2, epoch_3, epoch_4, x1, x2, x3, x4, y1, y2, y3, y4, z1, z2, z3, z4, vx1, vx2, vx3, vx4,

SPK Data are Continuous

Navigation and Ancillary Information Facility

Cassini S/C, Ref Frame ID, Saturn, T1, T2, Type 13

vy1, vy2, vy3, vy4,

vz1 vz2 vz3 vz4

Within the time bounds (T1, T2) of a segment, SPICE software will return a resulta state vectorat any epoch not just at the epochs of the ephemeris records (epoch_1, epoch_2, etc.). In the example above, SPICE will return the position and velocity (the state) of the Cassini spacecraft relative to Saturn at any time t where: T1 t T2

SPK Subsystem

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 as seen from Deep Space Station 14. This is obtained by SPICE by chaining the gold, blue and violet chunks.
Huygens Probe
Titan-centered position Probe Ephemeris File DSN Stations Ephemeris File Satellite Ephemeris File Planet Ephemeris File

DSS-63

DSS-62

DSS-61

DSS-15

DSS-14

DSS-13

DSS-12

Earth-centered positions

Titan

Tethys

Enceladus

Mimas

Saturn barycenter-centered positions

Saturn
Technically, these are planet barycenter locations. More on this later on.

Jupiter

Mars

Earth

Venus

Mercury

Solar system barycenter-centered positions Solar System Barycenter

N IF

Automated Frame Transformation

Navigation and Ancillary Information Facility

As part of the chaining process just mentioned

position vectors are automatically rotated into a common frame the final vector is rotated into the output reference frame requested by the user
Reference Frames Used International Celestial Reference Frame (J2000)! Titan body-fixed frame (IAU_TITAN)! International Terrestrial Reference Frame (ITRF93)! DSS-14 topocentric reference frame (DSS-14_TOPO)!
Solar System Barycenter

Ephemeris Segments Used

Titan

Huygens Probe (after landing)

Saturn Barycenter

Deep Space Station 14

The position of the Huygens Probe relative to DSS-14, at time t, given in the DSS-14 topocentric reference frame, can be determined using a SINGLE Toolkit subroutine call.

Earth

A single subroutine call does it all!

CALL SPKPOS (HUYGENS_PROBE, t, DSS-14_TOPO, LT+S, DSS-14, POSITION, LT)
17

N IF

SPK Segment Order and Priority

Navigation and Ancillary Information Facility

Within a single SPK file

END

No results will be returned by the SPK reader API for any request time falling within these two data gaps
SPK Subsystem

N IF

Reference Frames Used in Writing and Reading SPKs

Navigation and Ancillary Information Facility

All ephemeris data have an associated reference frame

The frame specification is provided by the SPK producer

A program reading an SPK file must specify relative to what reference frame the output state or position vectors are to be given
This frame must be known to the program Known means either a built-in frame (hard coded) or one fully specified at run-time The users program may need to have access to additional SPICE data in order to construct some of these frames

SPK Subsystem

N IF

SPK Data Type Concept

Navigation and Ancillary Information Facility

SPK files contain various mathematical representations of ephemeris data ("data types"), but the high-level user interfaces (SPK "readers") are type-independent:
X, Y, Z, dX, dY, dZ at requested time

SPK Reader Modules

SPKEZR (to get position and velocity) SPKPOS (to get position only)

SPK SPK Type 3Type 4

Chebyshev Polynomials (separate ones for position and velocity)
SPK Subsystem

SPK Type 5
Weighted Two-body Motion

SPK SPK Type 8 Type 10

Space Command Two-line Elements

SPKSPK Type 12 13 Type

Hermite Interpolation of unequally spaced discrete state vectors
23

N IF

Why Have Multiple Data Types?

Navigation and Ancillary Information Facility

To allow SPK producers to choose an ephemeris representation well-suited for their applications. 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 other formats.

Types 1, 2, 3, 8, 10, 14, 15, 17 and 18 were developed to enable accurate duplication of data obtained from ephemeris developers.

SPK Subsystem

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 non-JPL ephemeris producers and by MKSPK users

Type 18 (Sliding window Hermite or Lagrange interpolation)

SPK Subsystem

Used in SPKs made by ESA missions

N IF
For planets

Barycenters
Navigation and Ancillary Information Facility

A planet and its satellites orbit the planet systems barycenter

For example, the planet Jupiter (599) and each of Jupiters 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)
SPICE objects 199 and 299 as well as 1 and 2 are found in a planet ephemeris file

Note: 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) But starting about 2013 this is no longer the case

For the solar system

Planet system barycenters (i.e. 1 through 9) and the sun (10) orbit the solar system barycenter (0)

SPK Subsystem

N IF
Body Mass Center ID Sun (10) Mercury (199) Venus (299) Earth (399) Mars (499) Jupiter (599) Saturn (699) Uranus (799) Neptune (899) Pluto (999)

Barycenter Offset Magnitude

Navigation and Ancillary Information Facility

System Barycenter ID SSB (0) M. BC (1) V. BC (2) E. BC (3) M. BC (4) J. BC (5) S. BC (6) U. BC (7) N. BC (8) P. BC (9)

Barycenter offset from Offset as % of body mass center (km)* body radius* 1,378,196 0 0 4942 0.002 220 312 43 74 2080 198% 0 0 77% ~0 0.3% 0.5% 0.17% 0.3% 174%

* Estimated maximum values over the time range 2000-2050

SPK Subsystem

N IF

SPK File Ephemeris Contents

Navigation and Ancillary Information Facility

A single SPK file can hold data for one ephemeris object, or for many ephemeris objects
This is illustrated in the next three charts

The 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

SPK Subsystem

N IF
Planet Ephemeris

Examples of Generic SPK File Contents

Navigation and Ancillary Information Facility jup230.bsp my_asteroids.bsp
Asteroid Ephemeris Merged Planet and Satellite Ephemeris

de421.bsp

0 1 199 2 299 3 301 399 4 499 5 6 7 8 9 10

S.S. BC Merc. BC Mercury Venus BC Venus Earth BC Moon Earth Mars BC Mars Jupiter BC Saturn BC Uranus BC Neptune BC Pluto BC Sun

2000253 Mathilde 2000433 Eros

3 399 5 501 502 503 504 505 514 599 10

Earth BC Earth Jupiter BC Io Europa Ganymede Callisto Amalthea Thebe Jupiter Sun

Generic SPK files may be obtained from the NAIF server

SPK Subsystem

N IF
Probe
-150 = Huygens probe

Examples of Flight Project SPK Files

Navigation and Ancillary Information Facility

This made-up example shows five collections of SPK files for the Cassini-Huygens mission

Orbiter
-82 = Cassini S/C

Planets
0 = solar system bc 3 = Earth barycenter 6 = Saturn barycenter 399 = Earth mass center 301 = Moon
Multiple objects

Satellites - 1
601 = Mimas 602 = Enceladus 603 = Tethys 604 = Dione 605 = Rhea 606 = Titan 607 = Hyperion 608 = Iapetus 609 = Phoebe 699 = Saturn mass center
Multiple objects

One object

610 = Janus 611 = Epimetheus : 617 = Pandora 699 = Saturn mass center

The users program must load as many of these SPK files as needed to satisfy her/his requirements. Sometimes a project NAV team combines (merges) several of these collections before releasing them, making the users job easier.
SPK Subsystem See the next page for a graphical representation of this collection of SPKs

Multiple objects

Satellites - 2
30

N IF
Planet: Satellite - 1:
(Major satellites)

Possible* SPK File Time Coverages for the Previous Example

Navigation and Ancillary Information Facility

Each bar represents a separate file

Satellite - 2:
(Minor satellites)

Orbiter :

Probe :
Time line:

Launch

cruise phase

Orbit Insertion

orbit phase

Probe Release

End of Mission 31

SPK Subsystem

* Note: This was not the real Cassini scenarioit is simply an illustration of some of the possibilities for ephemeris delivery on a planetary mission.

N IF

SPKs for Objects Located on 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 Needed to rotate body-fixed vectors to the J2000 frame

SPK Subsystem

N IF
Navigation and Ancillary Information Facility

Using SPK Files

SPK Subsystem

N IF

Retrieving Position or State Vectors

Navigation and Ancillary Information Facility

To retrieve position or state vectors of ephemeris objects one normally needs two kinds of SPICE kernels
Ephemeris kernel(s) (SPK) Leapseconds kernel (LSK) Used to convert between Coordinated Universal Time (UTC) and Ephemeris Time (ET)

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 and/or perform aberration corrections

State and position vectors retrieved from an SPK file by the SPK reader routines are 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

N IF

Retrieving a State Vector

Navigation and Ancillary Information Facility
tax n syn Fortra re he used

Initializationtypically done once per program execution

Tell your program which SPICE files to use (loading files) CALL FURNSH ('spk_file_name') Its better to replace these two calls with a single call to CALL FURNSH ('leapseconds_file_name')
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

N IF
INPUTS

Arguments of SPKEZR - 1
Navigation and Ancillary Information Facility

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 observer to target.

TDB: The time at the observer 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 your output state vector is to be given. SPK software will automatically convert ephemeris data to the frame you specify (if needed). SPICE must know the named frame. If it is not a built-in frame SPICE must have sufficient data at run-time to construct it.

* 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.
SPK Subsystem

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. 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.

SPK Subsystem

N IF

A Simple Example of Retrieving a State Vector

Navigation and Ancillary Information Facility

Initialization - typically do this just once per program execution

CALL FURNSH ( 'NAIF0010.TLS' ) CALL FURNSH ( 'HUYGENS_3_MERGE.BSP' )

Repeat in a loop if/as needed to solve your particular problem

Its better to replace these two calls with a single call to a furnsh kernel containing the names of all kernel files to load.

CALL STR2ET ('2004 NOV 21 02:40:21.3', TDB ) CALL SPKEZR ('TITAN', TDB, 'J2000', 'LT+S', 'HUYGENS PROBE', 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 Huygens probe 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) and has been corrected for both light time and stellar aberration (LT+S). The oneway light time (LT) is also returned. A SPICE leapseconds file (NAIF0010.TLS) is used, as is a SPICE ephemeris file (HUYGENS_3_MERGE.BSP) containing ephemeris data for the Huygens probe (-150), Saturn barycenter (6), Saturn mass center (699), Saturn's satellites (6xx) and the sun (10), relative to the solar system barycenter.
SPK Subsystem

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

N IF

A Slightly More Complex Example - 1 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 bodys IAU body-fixed reference frame youll 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 youll need: FK, CK and SCLK for the spacecraft SPK(s) for the spacecraft and object LSK

SPK Subsystem

N IF

A Slightly More Complex Example - 2 Retrieving a State Vector

Navigation and Ancillary Information Facility

Obtain the state of Titan relative to Huygens Probe in the Titan body-fixed reference frame
Initialization...typically once per program execution

Tell your program which SPICE files to use (loading files) CALL FURNSH ('HUYGENS_MERGED_SPK.BSP') Its better to replace these two calls with a single call to a CALL FURNSH ('NAIF0010.TLS') furnsh kernel containing the CALL FURNSH (NAIF0010.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 planets IAU body-fixed frame CALL SPKEZR (TITAN', TDB, 'IAU_TITAN, 'LT+S', HUYGENS PROBE', 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

N IF

Manipulating and Using SPK Files

Navigation and Ancillary Information Facility

You can subset an SPK, or merge two or more SPKs

The merge may be keyed off of objects, or time, or both

You can read data from just one, or many* SPK files in your application program
Dont forget the precedence rule: data in a later loaded file take precedence over data from an earlier loaded file
( * The allowed number of simultaneously loaded DAF-based files is currently set to 1000.)

You can convert an SPK that is in non-native binary format to native binary format if you need to add data or comments

SPK Subsystem

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

These comments may be extracted or viewed using an API (subroutine) or a SPICE utility program.

SPK Subsystem

N IF
BRIEF SPACIT COMMNT MKSPK SPKDIFF SPKMERGE

SPK Utility Programs

Navigation and Ancillary Information Facility

The following SPK utility programs are included in the Toolkit:

summarizes coverage for one or more SPK files generates segment-by-segment summary of an SPK file reads, appends, or deletes comments in an SPK file converts ephemeris data provided in a text file into an SPK file compares two SPK files subsets or merges one or more SPK files

These additional SPK utility programs are provided on the NAIF Web site (http://naif.jpl.nasa.gov/naif/utilities.html)
SPY PINPOINT BSPIDMOD DAFMOD DAFCAT BFF BINGO
SPK Subsystem

validates, inspects, and analyses SPK files creates an SPK file for fixed locations (ground stations, etc) alters body IDs in an SPK file alters body or frame IDs in an SPK file concatenates together SPK files displays binary file format of an SPK file converts SPK files between big- and little-endian formats
44

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 Users Guide for details
% brief 070413BP_SCPSE_07097_07121.bsp

Summary for: 070413BP_SCPSE_07097_07121.bsp Bodies: CASSINI (-82) MERCURY BARYCENTER (1) VENUS BARYCENTER (2) EARTH BARYCENTER (3) MARS BARYCENTER (4) JUPITER BARYCENTER (5) SATURN BARYCENTER (6) URANUS BARYCENTER (7) NEPTUNE BARYCENTER (8) PLUTO BARYCENTER (9) SUN (10) MERCURY (199) VENUS (299) MOON (301) EARTH (399) MARS (499) MIMAS (601) ENCELADUS (602) TETHYS (603) DIONE (604) RHEA (605) TITAN (606) HYPERION (607) IAPETUS (608) PHOEBE (609) SATURN (699)

Note, the default is ET, not UTC!

Start of Interval (ET) -------------------------------2007 APR 07 16:22:23.000

End of Interval (ET) -------------------------------2007 MAY 01 09:34:03.000

SPK Subsystem

N IF

Summarizing an SPK File - 2

Navigation and Ancillary Information Facility

A detailed summary can be made using the Toolkit utility SPACIT

See the SPACIT Users 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 --------------------------------------------------------------------------------

SPK Subsystem

: : (This is a partial output; not all data could be displayed on this chart)

N IF

Summarizing an SPK File - 3

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

N IF

Additional Information on SPK

Navigation and Ancillary Information Facility

For more information about SPK, look at the following:

The on-line (full) SPK tutorial Most Useful Routines document SPK Required Reading document Headers of the subroutines mentioned Using Frames tutorial BRIEF and SPKDIFF Users Guides NAIF_IDS Required Reading Frames Required Reading Time Required Reading Kernel Required Reading

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 doesnt 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

In the above situations youll 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

This could occur if youve been given a file coverage summary in calendar ET form and you mistook this for UTC ( ET = UTC + DELTAET, where DELTAET is about 65 seconds as of 9/11) 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 lighttime away* from your ET epoch of interest * Earlier, for the receive case; later, for the transmission case

N IF

Problems Using SPK Files - 2

Navigation and Ancillary Information Facility

You have requested aberration-corrected states but the 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 doesnt

In the above situations youll 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

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 relative to the solar system barycenter. 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.

SPK Subsystem

N IF
Saturn These vectors obtained from a satellite ephemeris SPK

Problems Using SPK Files - 3b (drawing)

Navigation and Ancillary Information Facility

Cassini spacecraft during interplanetary cruise

Titan

This vector obtained from a cruise phase spacecraft SPK

In this example the absence of a planet ephemeris SPK means the Cassini-Titan and CassiniSaturn vectors shown here cannot be determined because the Saturn Barycenter-to-Solar System Barycenter vector is not available. Given

This vector cannot be obtained from either the spacecraft or satellite SPKs; a planet ephemeris SPK is needed.

Solar System Barycenter

Sun

available in SPK files not available in SPK files cant be computed

Therefore SPK Subsystem

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

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

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 a state (or position) vector in your requested output frame.

Mistaking ET for UTC, or vice-versa. You must have loaded sufficient SPKs to be able to chain states to the solar system barycenter if doing aberration corrections. Using light time corrections requires target ephemeris data at the light time-corrected epoch.
If youre working near the beginning of an SPK, the light timecorrected epoch may occur earlier than available data.

SPK Subsystem

N IF

Problems Using SPK Files - 7

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

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.
CALL SPKEZR ( 'MGS', ET, 'J2000', 'NONE', 'MARS', STATE, LT ) The SPK subsystem locates an SPK segment containing the ephemeris 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

Overview Text PCKs PCK reference frames Binary PCKs Using PCKs Interface Routines PCK Precedence Rules PCK Utility Programs

PcK Subsystem

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 Binary PCKs are used only for high-accuracy orientation data
Available only for the earth and the moon

PcK Subsystem

N IF

Text PCKs - 1
Navigation and Ancillary Information Facility

Text PCK files contain orientation, shape and other data associated with natural solar system bodies. 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 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 MAKSPK application to make a Type 5 SPK file.

Text PCKs are sometimes produced by flight projects and othersnot only by NAIF.
PcK Subsystem

* Report of the IAU/IAG Working Group on cartographic coordinates and rotational elements: <year issued>; published in Celestial Mechanics and Dynamical Astronomy

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_RADII = ( 60268 BODY699_POLE_RA = ( 40.589 BODY699_POLE_DEC = ( 83.537 60268 54364 ) -0.036 0. ) -0.004 0. )

Users may easily visually inspect data. 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

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.

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

N IF

Text PCK Orientation Models - 2

Navigation and Ancillary Information Facility

The 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 SPICE uses the names J2000 and EME2000 as synonyms for the ICRF inertial reference frame, even though J2000 and ICRF are, in fact, not identical. (The difference is well under 0.1 arc seconds.)

PcK Subsystem

N IF

Text PCK Orientation Models - 3

Navigation and Ancillary Information Facility

Body-fixed frames provided in text PCKs are planetocentric. 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

PcK Subsystem

*The dwarf planets are: Ceres, Eris, Haumea, Makemake, Pluto

N IF

Location of PCK Reference Frame Specifications

Navigation and Ancillary Information Facility

Many PCK reference frame specifications are built-in to SPICE.

Load a text PCK file to use IAU frames. Examples:
IAU_SATURN, IAU_TITAN, IAU_MARS, etc.
Be very cautious in using IAU_EARTH and IAU_MOON; the binary PCKs for these two bodies offer more accuracy

Load the appropriate binary PCK for either the earth or the moon For the earth IERS frame: ITRF93 For a lunar frame based on JPL ephemeris: DExxx See the special tutorial lunar-earth_pck-fk for details on these

Other PCK frames are not built in and must be specified at run time by loading frame kernels, for example:
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

N IF

PCK Shape Models

Navigation and Ancillary Information Facility

PCK shape models are nominally triaxial ellipsoids

For many bodies, two of the axes (equatorial axes) have the same value (spheroidal) For some bodies, one or more radii have not been determined.

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 and DRDGEO are the modules performing these transformations.

Exception: SPICE supports planetographic coordinate transformations only for bodies modeled as spheres or spheroids.
PGRREC, RECPGR, DPGRDR and DRDPGR are the modules supporting these transformations.

PcK Subsystem

N IF

Special Case: Binary PCKs

Navigation and Ancillary Information Facility

The SPICE system stores high-accuracy orientation models in binary PCKs.

Binary PCKs are implemented using the DAF file architecture (as are SPK files) SPICE Toolkit utilities enable reading and writing comments, summarizing, and porting binary PCKs. Like SPK files, binary PCKs support multiple data representations (data types).
Type 2: Chebyshev polynomials for Euler angles, angular velocity obtained by differentiation, constant interval length. Type 3: Separate Chebyshev polynomials for Euler angles and their derivatives, variable interval length.

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 are available for the Earth and Moon.

The orientation data provided by these kernels are much more accurate than those provided by generic text PCKs based on the IAU/IAG reports. These kernels are the topic of a tutorial on high-accuracy orientation data and associated frames for the Earth and Moon. PcK Subsystem

N IF

Using PCK Data

Navigation and Ancillary Information Facility

PCK orientation data are usually accessed using Frame system or SPK calls
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 ) CALL SXFORM ( 'IAU_SATURN', 'J2000', ET, XFORM )

Example: 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 )

PCK shape data are usually accessed using APIs needing size and shape data such as SUBPT, SUBSLR, ILUMIN, etc.

PcK Subsystem

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.

Returns 3x3 matrix (attitude only) 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 specified reference frame is inertial This call, in the course of its work, converts the position of the DSN station relative to the Earths center from an Earth-fixed, earth-centered frame to the J2000 frame.

PcK Subsystem

N IF

Interface Routines - 2
Navigation and Ancillary Information Facility

Call BODVRD or BODVCD to retrieve constants associated with a body. For example:
CALL BODVRD ( 'SATURN', CALL BODVCD ( 699, 'RADII', 3, 'RADII', 3, N, N, RADII 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

N IF

PCK Precedence Rules

Navigation and Ancillary Information Facility

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 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 didnt already exist

PcK Subsystem

N IF
BRIEF SPACIT COMMNT FRMDIFF

PCK Utility Programs

Navigation and Ancillary Information Facility

These utilities are included in the Toolkit

summarizes coverage for one or more binary PCK files generates segment-by-segment summary of a binary PCK file reads, appends, or deletes comments in a binary PCK file samples a PCK-based frame or compares orientation of two PCK-based frames

These additional utilities are provided on the NAIF Web site

BFF BINGO displays binary file format of an binary PCK file converts binary PCK files between big-endian and little-endian formats

PcK Subsystem

N IF

Additional Information on PCK

Navigation and Ancillary Information Facility

For more information about PCKs, look at the following:

Most Useful Routines document PCK Required Reading document Headers of the routines mentioned Lunar/Earth High-Precision PCK/FK tutorial BRIEF and FRMDIFF Users Guides

Related documents:
Frames Required Reading Kernel Required Reading NAIF_IDS Required Reading Time Required Reading

PcK Subsystem

N IF
Navigation and Ancillary Information Facility

Camera-matrix Kernel CK
(Orientation or Attitude Kernel) Emphasis on reading CK files
July 2013

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 commentssometimes called metadatathat 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

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 their 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 practice CKs usually contain data for just one structure

C-Kernel

N IF

CK File Varieties - 1
Navigation and Ancillary Information Facility

Reconstruction CK (also called definitive CK)

A CK file can be made from 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") These kinds of files are generally 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 This kind of file is generally used for engineering assessment, science observation planning, software testing and quick-look science data analysis If it has good fidelity, such a file might be used to fill in the data gaps of a reconstruction CK file In some cases (ESA in particular) the predict meets the reconstruction accuracy requirements; a true reconstruction CK is not produced
C-Kernel

N IF

CK File Varieties - 2
Navigation and Ancillary Information Facility

Knowledge of CK varietyreconstruction or predictmight 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 rare, and inadvisable, that both varieties be combined in a single file

C-Kernel

N IF

CK Data Types Concept

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 Type 1

CK Type 2

CK Type 3

CK Type 4
Chebychev Polynomials

CK Type 5
ESOC DDID

Discrete Piecewise Constant Linear Points Angular Velocity Interpolation

Discrete data type
C-Kernel

Continuous data types 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 ephemeris time (ET) and spacecraft clock time (SCLK) Sometimes an LSK is not needed in this conversion, but 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.
FK associates reference frames with CK data via CK IDs

C-Kernel

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: 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

N IF

An Example of Project CK Files

Navigation and Ancillary Information Facility

CASSINI SPACECRAFT

HUYGENS PROBE

CASSINI CDA MIRROR

-82000

-150000

-82791

A users 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

N IF
Cassini Orbiter:

Sample* CK File Coverage - 1

Navigation and Ancillary Information Facility

Huygens Probe:

Cassini CDA Mirror:

Launch cruise phase

Time line:

End of Mission 10

Orbit Probe Insertion Release

C-Kernel

* 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.

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 almost always contain gaps in coverage! Below is an example of this.
Time

Coverage of
as appears in file name/comments

Tstart

Tstop

a CK file:

as appears in ckbrief/spacit summary

CK file segments:

CK segments showing data gaps:

(CK Types 2 - 5)

Summary of pointing available to the CK reader for this CK file: Blue line segments represent interpolation intervalstimes when pointing will be returned and the FOUND flag set to TRUE.
C-Kernel

N IF

What is an Interpolation interval?

Navigation and Ancillary Information Facility

An interpolation interval is a time period for which the CK reader routines can compute and return pointing.
For CK Types 3 and 5 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 the CK readers 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

N IF

Coverage - Contrast CK with SPK

Summarizing a CK file - 2
Navigation and Ancillary Information Facility

A summary of interpolation intervals in a CK can be made using 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 -----------------------2007-APR-12 00:01:06.462 2007-APR-12 05:58:22.576 . . .

Interval End ET -----------------------2007-APR-12 05:58:02.576 2007-APR-12 21:34:26.221

AV --Y Y
18

C-Kernel

continued on next page

N IF

Summarizing a CK file - 3
Navigation and Ancillary Information Facility
continued from previous page

A summary of interpolation intervals in a CK can also be made using FRMDIFF with its -t dumpc option A summary of gaps within interpolation intervals in a CK can be made using FRMDIFF with its -t dumpg option
% frmdiff -t dumpg \ k cas_v40.tf naif0008.tls cas00106.tsc \ -f 'YYYY-MM-DDTHR: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

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

N IF
CKBRIEF SPACIT COMMNT MSOPCK FRMDIFF

CK Utility Programs
Navigation and Ancillary Information Facility

The following CK utility programs are included in the Toolkit:

summarizes coverage for one or more CK files generates segment-by-segment summary of a CK file reads, appends, or deletes comments in an CK file converts attitude data provided in a text file into a CK file samples or compares orientation of CK-based frames

These additional CK utility programs are provided on the NAIF Web site
CKSLICER CKSMRG DAFCAT CKSPANIT DAFMOD prediCkt BFF BINGO subsets a CK file merges segments in a type 3 CK file (*) concatenates together CK files (*) modifies interpolation interval information in a Type 3 CK file alters structure or frame IDs in a CK file creates a CK file representing an orientation profile described by a set of orientation rules and a schedule displays binary file format of a CK file 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

N IF

Additional Information on CK
Navigation and Ancillary Information Facility

For more information about CK, look at the following documents

CK Required Reading headers for the CKGP and CKGPAV routines Most Useful SPICELIB Routines CKBRIEF and FRMDIFF Users Guides Frames tutorials: FK and Using Frames Porting_kernels tutorial SCLK Required Reading Time Required Reading Frames Required Reading NAIF_IDS Required Reading Rotations Required Reading

dont miss these

The Meaning of Tolerance - 1

Navigation and Ancillary Information Facility

The 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 - 5), if pointing information is not found within +/- tol of your pointing request time, no pointing will be returned and the found flag will be set to 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 later instance will be selected. For Types 2 - 5 (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.
*Ignoring segment priority
C-Kernel

N IF

The Meaning of Tolerance - 2

Navigation and Ancillary Information Facility

When reading a Type 1 CK containing discrete pointing instances

SCLKDP \ TOL /

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

N IF

The Meaning of Tolerance - 3

Navigation and Ancillary Information Facility

When reading a Type 2, 3, 4 or 5 CK (continuous pointing), with a pointing request that falls within a span of continuous pointing (an interpolation interval)
TOL | / |/\ [--+--] . . . (==----=============---======------===--) SCLKDP \

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

N IF

The Meaning of Tolerance - 4

Navigation and Ancillary Information Facility

When reading a Type 2, 3, 4 or 5 CK (continuous pointing), with a pointing request that is NOT within a span of continuous pointing (an interpolation interval)
SCLKDP \ TOL | / |/\ [--+--] . . . (--==============----======------===--)

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

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.

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

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 (outside of interpolation intervals)

One of the frames routines (SPKEZR, SPKPOS, SXFORM, PXFORM, SINCPT) signals an error
All frames 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 CKbased 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

N IF

Problems using CK - 3
Navigation and Ancillary Information Facility

Youve confirmed not having any of the previously described problems, but the FOUND flag comes back FALSE when using CKGPAV, or SXFORM or SPKEZR signals a frame related error.

You are using a SPICE routine that expects angular velocity as well as orientation, but the CK segments available at your requested epoch dont contain angular velocity. Routines expecting AV are: CKGPAV, SXFORM, SPKEZR Routines not expecting AV are: CKGP, PXFORM, SPKPOS

C-Kernel

N IF

Problems using CK - 4
Navigation and Ancillary Information Facility

The FOUND flag comes back 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 comes back 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 also prepared and can provide a white paper explaining differences between various quaternion styles commonly used in space applications.

C-Kernel

N IF

Problems using CK - 5
Navigation and Ancillary Information Facility

Youre 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 cant 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) Sun, HP, SGI and MAC (Motorola cpu) use the unix binary standard PC (Windows or Linux) uses its own 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

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' ) CALL FURNSH( 'sclk_file_name' ) CALL FURNSH( 'ck_file_name' )
Loop ... do as often as you need Better yet, use a furnsh kernel to load all the needed files.

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

N IF
Inputs instid

Arguments of CKGPAV
Navigation and Ancillary Information Facility

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 in backup slides
C-Kernel

N IF
Navigation and Ancillary Information Facility

Frames Kernel FK

July 2013

N IF

Background
Navigation and Ancillary Information Facility

First, reminders of what SPICE means by:

reference frame coordinate system

Frames Subsystem

N IF

What is a Reference Frame?

Navigation and Ancillary Information Facility

Within SPICE, a reference frame is specified by three orthogonal axes

Y X

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 assigned to it

Youll use these names as arguments in calling Toolkit APIs

Frames Subsystem

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

Frames Subsystem

N IF

Introduction
Navigation and Ancillary Information Facility

What does the FRAMES subsystem do?

1. It establishes relationships between reference frames used in geometry computations it "chains frames together in a frame tree.
and

2. It connects frames with the sources of their orientation specifications. In some cases those data are included in the Frames kernel. Based on these relationships and the orientation source information, it 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

N IF
Saturn Body-fixed frame

Sample Frame Tree

Navigation and Ancillary Information Facility
Inertial J2000 frame

PCK-based transformation

PCK-based transformation
Earth Body-fixed frame Titan body-fixed frame Topocentric Frame at the landing site

PCK-based transformation CK based transformation

ISS NAC instrument frame

Cassini spacecraft frame

Fixed offset transformation

Frames Subsystem

N IF
Frame class Inertial

Examples of Frames for Each Frame Class

Navigation and Ancillary Information Facility

Examples Earth Equator/Equinox of Epoch (J2000, ) Planet Equator/Equinox of Epoch (MARSIAU, ...) Ecliptic of Epoch (ECLIPJ2000, ...) Solar system body IAU frames (IAU_MARS, IAU_SATURN, ) High accuracy Earth frames (ITRF93, ) High accuracy Moon frames (MOON_PA, MOON_ME) Spacecraft (CASSINI_SC_BUS, ) Moving parts of an instrument (MPL_RA_JOINT1, ...) Instrument mounting alignment (CASSINI_ISS_NAC, ) Topocentric (DSS-14_TOPO, ) Geomagnetic Geocentric Solar Equatorial Planet true equator and equinox of date

Body-fixed

CK-based Fixed Offset Dynamic

Frames Subsystem

N IF
Frame class Inertial Bodyfixed CK based Fixed offset Dynamic

Frame Class Specifications

Navigation and Ancillary Information Facility

Frame Defined in Toolkit Toolkit or FK FK FK FK

Orientation data provided in Toolkit PCK CK FK Toolkit, or computed using FK, SPK, CK, and/or PCK

Frames Subsystem

N IF

Frames Subsystem Interfaces

Navigation and Ancillary Information Facility

SXFORM/PXFORM

returns state or position transformation matrix

CALL SXFORM ( FROM_FRAME_NAME, TO_FRAME_NAME, ET, MAT6x6 ) CALL PXFORM ( FROM_FRAME_NAME, TO_FRAME_NAME, ET, MAT3X3 )

SPKEZR/SPKPOS

returns 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 )
The above are FORTRAN examples, using SPICELIB modules. The same interfaces exist for C, using CSPICE modules, and for Icy and Mice.
Frames Subsystem

N IF

Frame Names
Navigation and Ancillary Information Facility

Frame names are character strings used to identify frames to Toolkit APIs Some examples of frame names:
J2000 IAU_MARS DAWN_SPACECRAFT MEX_OMEGA DSS-14_TOPO

Frames Subsystem

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 projects 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

N IF

Frames Kernel File

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
FRAME_DAWN_SPACECRAFT FRAME_-203000_NAME FRAME_-203000_CLASS FRAME_-203000_CLASS_ID FRAME_-203000_CENTER CK_-203000_SCLK CK_-203000_SPK = = = = = = = -203000 'DAWN_SPACECRAFT 3 -203000 -203 -203 -203

Fixed-offset Frame Example

for PCK-based frames for CK-based frames for fixed-offset frames for dynamic frames
15

N IF

Frame Definition Details - 4

The FRAMECLASS_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

N IF

Frame Definition Details - 5

The FRAMECENTER 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

N IF

Frame Definition Details - 6

Additional frame definition keywords may be required depending on the frame class
For CK frames, CKSCLK and CKSPK 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

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 5) 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.

July 2013

N IF

What is the Power of Frames?

Navigation and Ancillary Information Facility

The power of the Frames capability stems from the SPICE systems ability to construct complex reference frame transformations with no programming effort required of you - the end user
But its 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) and the Frames subsystem interfaces (SXFORM and PXFORM) The remaining pages illustrate typical use of frames Several VERY IMPORTANT usage issues are mentioned in the core Frames tutorial; be sure to also read that.
Using Frames

In SPICE terminology: reference frame = coordinate system

N IF
CASSINI

Offset Between Instruments

Navigation and Ancillary Information Facility Required Kernels: Generic LSK Mission FK Camera IK(s)

ISS NAC Frame

Misalignment angle between ISS camera boresights NAC Boresight

S/C Frame

ISS WAC Frame

WAC Boresight
ISS = Imaging Science System

Compute the angular separation between the ISS Narrow Angle Camera and Wide Angle Camera boresights:
C C Retrieve the matrix that transforms vectors from NAC to WAC frame CALL PXFORM( CASSINI_ISS_NAC, CASSINI_ISS_WAC, ET, MAT ) Transform NAC boresight to WAC frame and find separation angle CALL MXV ( MAT, NAC_BORESIGHT_nac, NAC_BORESIGHT_wac ) ANGLE = VSEP( NAC_BORESIGHT_wac , WAC_BORESIGHT_wac )
3

Using Frames

N IF
CASSINI ISS NAC Frame S/C Frame

Angular Constraints
Navigation and Ancillary Information Facility
J2000 Frame SSB Sun Sun direction in the NAC frame

Angle between NAC Boresight and Sun direction Saturn J2000 Frame

Required Kernels: Generic LSK Mission FK Spacecraft SCLK Camera IK Planetary Ephemeris SPK Spacecraft SPK Spacecraft CK

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 ) IF ( ANGLE .LE. CONSTRAINT ) WRITE(*,*) WE ARE IN TROUBLE!
Using Frames

N IF
J2000 Frame Sun Sun Direction In Local Level Frame Solar EL SSB

Angles at the Surface

Navigation and Ancillary Information Facility Required Kernels: Generic LSK Generic PCK Mission FK Planetary Ephemeris SPK Satellite Ephemeris SPK Landing Site SPK

Solar AZ

J2000 Frame Titan Titans IAU Body-fixed frame

Local Level Frame at the probe Landing Site

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 RECLAT(SUNVEC, R, AZIMUTH, ELEVATION) ELEVATION = -ELEVATION IF (AZIMUTH .LT. 0.D0) THEN AZIMUTH = AZIMUTH + TWOPI() ENDIF
Using Frames

N IF

Relative Position of Sensors

Navigation and Ancillary Information Facility Required Kernels: Generic LSK Mission FK Structure Locations SPK Spacecraft SCLK Solar Array CK

MAG+Y frame MAG-Y position relative MAG+Y

MAG-Y frame -Y Hinge -Y Gimbal frame frame

+Y Gimbal frame S/C 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 SPKEZR(MGS_MAG-Y, ET, MGS_SPACECRAFT, NONE, MGS_MAG+Y, STATE, LT) CALL PXFORM(MGS_MAG_+Y_SENSOR, MGS_MAG_-Y_SENSOR, ET, MAT)
Using Frames

N IF
MG S

Manipulators - 1
Navigation and Ancillary Information Facility Required Kernels: Generic LSK Mission FK Spacecraft SCLK HGA IK Structure Locations SPK Planetary Ephemeris SPK Spacecraft SPK Spacecraft CK HGA CK
SSB J2000 Frame Earth
HGA = High Gain Antenna

S/C Frame HGA Hinge frame HGA Gimbal frame J2000 Frame Sun HGA frame

Mars

MGS HGA off-pointing angle

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 )
Using Frames

N IF
RA J2 Frame RA Scoop Frame Dig Location in Surface fixed frame RA J1 Frame Dig Loc. in SSI frame

Manipulators - 2
Navigation and Ancillary Information Facility SSI Frame SSI Camera head Frame Required Kernels: Generic LSK Mission FK Lander SCLK Structure Locations SPK Lander SPK Lander CK SSI CK RA CK

MVACS Frame

Surface-fixed Frame

Compute the soil digging location in the MPL surface-fixed and camera left eye frames:
Using Frames

CALL SPKEZR( MPL_RA_SCOOP,ET,MPL_SURFACE_FIXED,NONE,MPL_SURF,ST1,LT ) CALL SPKEZR( MPL_RA_SCOOP,ET,MPL_SSI_LEFT, NONE,MPL_SSI, ST2,LT )

N IF
Navigation and Ancillary Information Facility

Dynamic Reference Frames

July 2013

N IF

Topics
Navigation and Ancillary Information Facility

Introduction to Dynamic Reference Frames Terminology Parameterized Dynamic Reference Frames Defining Dynamic Reference Frames
Two-Vector Frame Concepts Two-Vector Frame Examples "Of-Date" Frames Euler Frames Frozen Dynamic Frames Inertial Dynamic Frames

Generic Dynamic Reference Frame Kernel Backup

Dynamic Frames

N IF

What are Dynamic Frames

Navigation and Ancillary Information Facility

What are dynamic reference frames?

Dynamic reference frames ("dynamic frames" for short) have time-dependent orientation. Dynamic frames are specified using a frames kernel (FK). CK- and PCK-based frames are not considered to be dynamic frames although they are time-varying.

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

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 RTN ("radial, tangential, normal)
4

Dynamic Frames

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. Load any kernels on which the dynamic frame depends.
Some dynamic frames are constructed using data using SPK, FK, PCK, CK, SCLK or other SPICE kernels.

Then, refer to the dynamic frame by name in calls to SPICE routines, just as you would do with built-in frames such as "J2000."

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 always defined relative to another specified frame: the "base frame."
Dynamic Frames

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.
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

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 frame kernel. The term "API" stands for "Application Programming Interface." This term refers to the set of SPICE routines that are intended to be called directly by SPICE-based programs. The notation

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.
Freeze epoch

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

N IF

Two-Vector Frame Concepts - 1

Navigation and Ancillary Information Facility

Two-vector frames are defined using two timedependent vectors: the "primary" and "secondary" vectors.
Each 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

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:

Primary Vector Z

-X

X
Dynamic Frames

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.

Primary Vector Z

-X

Y Secondary Vector X
Component of secondary vector orthogonal to primary vector
17

Dynamic Frames

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. 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

N IF

Two-Vector Frame Concepts - 5

Navigation and Ancillary Information Facility

Position Vector
Is 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 routine: 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

N IF

Two-Vector Frame Concepts - 6

Navigation and Ancillary Information Facility

Target Near Point Vector

Is 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, as for position vectors. 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

N IF

Two-Vector Frame Concepts - 7

Navigation and Ancillary Information Facility

Velocity Vector

Is 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, as for position vectors.
Dynamic Frames

N IF

Two-Vector Frame Concepts - 8

Navigation and Ancillary Information Facility

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 noninertial, it is evaluated at a light time corrected epoch.
Dynamic Frames

continued on next page

N IF

Two-Vector Frame Concepts - 9

Navigation and Ancillary Information Facility

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.

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. ("Out of plane" direction)

Z Y
Normalized component of secondary vector orthogonal to primary vector. This vector is aligned with the view frame's +Y axis. ("In plane" direction)

Primary vector: spacecraft velocity relative to center of motion in J2000 frame. Associated with view frame's +Z axis in frame kernel. ("Down track" direction)

Dynamic Frames

N IF

Two-Vector Frame Examples - 4

Navigation and Ancillary Information Facility
Frame kernel specification.

Spacecraft "View Frame":

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 +X axis. \begindata FRAME_<frame_name> FRAME_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_PRI_AXIS FRAME_<frame_ID>_PRI_VECTOR_DEF FRAME_<frame_ID>_PRI_OBSERVER FRAME_<frame_ID>_PRI_TARGET FRAME_<frame_ID>_PRI_ABCORR FRAME_<frame_ID>_PRI_FRAME FRAME_<frame_ID>_SEC_AXIS FRAME_<frame_ID>_SEC_VECTOR_DEF FRAME_<frame_ID>_SEC_OBSERVER FRAME_<frame_ID>_SEC_TARGET FRAME_<frame_ID>_SEC_ABCORR
Dynamic Frames

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

<frame_ID> <frame_name> 5 <frame_ID> <orbiter_ID> 'J2000' 'PARAMETERIZED' 'TWO-VECTOR' 'Z' 'OBSERVER_TARGET_VELOCITY' 'MARS' <orbiter_ID/name> 'NONE' 'J2000' 'Y' 'OBSERVER_TARGET_POSITION' 'MARS' <orbiter_ID/name> 'NONE'

Definitions <frame_ID> = integer frame ID code <frame_name> = user-specified frame name <orbiter_ID> = NAIF ID code of spacecraft <orbiter_ID/name> = NAIF ID code or name of spacecraft

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 Associated with GSE frame's +X axis in frame kernel.

Z = X x Y, X

completing the right-handed frame

Y
Secondary vector: velocity of sun relative to earth in J2000 frame. Associated with GSE frame's +Y axis in frame kernel.
Dynamic Frames

Y = normalized component of secondary vector orthogonal to primary vector

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_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_PRI_AXIS FRAME_<frame_ID>_PRI_VECTOR_DEF FRAME_<frame_ID>_PRI_OBSERVER FRAME_<frame_ID>_PRI_TARGET FRAME_<frame_ID>_PRI_ABCORR FRAME_<frame_ID>_SEC_AXIS FRAME_<frame_ID>_SEC_VECTOR_DEF FRAME_<frame_ID>_SEC_OBSERVER FRAME_<frame_ID>_SEC_TARGET FRAME_<frame_ID>_SEC_ABCORR FRAME_<frame_ID>_SEC_FRAME
Dynamic Frames

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

Definition <frame_ID> 'GSE' <frame_ID> = integer frame 5 ID code <frame_ID> 399 'J2000' 'PARAMETERIZED' 'TWO-VECTOR' 'X' 'OBSERVER_TARGET_POSITION' 'EARTH' 'SUN' 'NONE' 'Y' 'OBSERVER_TARGET_VELOCITY' 'EARTH' 'SUN' 'NONE' 'J2000' 29

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.

Z = normalized component of secondary vector orthogonal to primary vector Primary vector: position of sun relative to earth Associated with GSM frame's +X axis in frame kernel. Y = Z x X, completing the right-handed frame

Dynamic Frames

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_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_PRI_AXIS FRAME_<frame_ID>_PRI_VECTOR_DEF FRAME_<frame_ID>_PRI_OBSERVER FRAME_<frame_ID>_PRI_TARGET FRAME_<frame_ID>_PRI_ABCORR FRAME_<frame_ID>_SEC_AXIS FRAME_<frame_ID>_SEC_VECTOR_DEF FRAME_<frame_ID>_SEC_FRAME FRAME_<frame_ID>_SEC_SPEC FRAME_<frame_ID>_SEC_UNITS FRAME_<frame_ID>_SEC_LONGITUDE FRAME_<frame_ID>_SEC_LATITUDE
Dynamic Frames

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

<frame_ID> Definition 'GSM' 5 <frame_ID> = integer frame <frame_ID> ID code 399 'J2000' 'PARAMETERIZED' 'TWO-VECTOR' 'X' 'OBSERVER_TARGET_POSITION' 'EARTH' 'SUN' 'NONE' 'Z' 'CONSTANT' 'IAU_EARTH' 'LATITUDINAL' 'DEGREES' 288.43 79.54 31

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.

X = normalized component of secondary vector orthogonal to primary vector Primary vector: position of earth relative to spacecraft. Associated with Roll-Celestial frame's +Z axis in frame kernel.

Y = Z x X, completing the right-handed frame

Dynamic Frames

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. \begindata FRAME_<frame_name> FRAME_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_PRI_AXIS FRAME_<frame_ID>_PRI_VECTOR_DEF FRAME_<frame_ID>_PRI_OBSERVER FRAME_<frame_ID>_PRI_TARGET FRAME_<frame_ID>_PRI_ABCORR FRAME_<frame_ID>_SEC_AXIS FRAME_<frame_ID>_SEC_VECTOR_DEF FRAME_<frame_ID>_SEC_FRAME FRAME_<frame_ID>_SEC_SPEC FRAME_<frame_ID>_SEC_UNITS FRAME_<frame_ID>_SEC_RA FRAME_<frame_ID>_SEC_DEC FRAME_<frame_ID>_SEC_OBSERVER FRAME_<frame_ID>_SEC_ABCORR
Dynamic Frames

Definitions <frame_ID> = integer frame ID code <frame_name> = user-specified frame name <spacecraft_ID> = NAIF ID code of spacecraft <spacecraft_ID/name> = NAIF ID code or name of spacecraft

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

<frame_ID> <frame_name> 5 <frame_ID> <spacecraft_ID> 'J2000' 'PARAMETERIZED' 'TWO-VECTOR' 'Z' 'OBSERVER_TARGET_POSITION' <spacecraft_ID/name> 'EARTH' 'NONE' 'X' 'CONSTANT' 'J2000' 'RA/DEC' 'DEGREES' <star right ascension in degrees> <star declination in degrees> <spacecraft_ID/name> 'S'

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

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 1976 IAU precession model (Lieske model) 1980 IAU nutation model

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

N IF

"Of-Date" Frames - 6
Navigation and Ancillary Information Facility

Earth true equator and equinox of date frame: +Z axis is perpendicular to 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 mean ecliptic of date. +Y axis completes the right-handed frame. \begindata FRAME_<frame_name> FRAME_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_PREC_MODEL FRAME_<frame_ID>_NUT_MODEL FRAME_<frame_ID>_ROTATION_STATE = = = = = = = = = = = Definitions <frame_ID> = integer frame ID code <frame_name> = user-specified frame name

<frame_ID> <frame_name> 5 <frame_ID> 399 'J2000' 'PARAMETERIZED' 'TRUE_EQUATOR_AND_EQUINOX_OF_DATE' 'EARTH_IAU_1976' 'EARTH_IAU_1980' 'ROTATING'

Dynamic Frames

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
1976 IAU precession model (Lieske model) 1980 IAU mean obliquity model

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

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. \begindata FRAME_<frame_name> FRAME_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_PREC_MODEL FRAME_<frame_ID>_OBLIQ_MODEL FRAME_<frame_ID>_ROTATION_STATE = = = = = = = = = = = Definitions <frame_ID> = integer frame ID code = user-specified frame name

<frame_name> <frame_ID> <frame_name> 5 <frame_ID> 399 'J2000' 'PARAMETERIZED' 'MEAN_ECLIPTIC_AND_EQUINOX_OF_DATE' 'EARTH_IAU_1976' 'EARTH_IAU_1980' 'ROTATING'

Dynamic Frames

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. Angles are converted to radians internally by SPICE. 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 (units are radians)
Dynamic Frames

N IF
Examples

Euler Frames - 2
Navigation and Ancillary Information Facility

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.
Dynamic Frames

continued on next page

N IF

Euler Frames - 3
Navigation and Ancillary Information Facility

Mean or true body equator and earth 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

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. PCK: angle_3 is angle_2 is angle_1 is 90 + RA 90 - Dec PM = = = = = = = = = = = = = = Euler Frame: angle_1 is -90 - RA angle_2 is -90 + Dec angle_3 is - PM

\begindata FRAME_IAU_MARS_EULER FRAME_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_EPOCH FRAME_<frame_ID>_AXES FRAME_<frame_ID>_UNITS FRAME_<frame_ID>_ANGLE_1_COEFFS FRAME_<frame_ID>_ANGLE_2_COEFFS FRAME_<frame_ID>_ANGLE_3_COEFFS
Dynamic Frames

<frame_ID> Definition 'IAU_MARS_EULER' 5 <frame_ID> = integer frame ID <frame_ID> code 499 'J2000' 'PARAMETERIZED' 'EULER' @2000-JAN-1/12:00:00 ( 3 1 3 ) 'DEGREES' ( -47.68143 0.33621061170684714E-10 ) ( -37.1135 -0.19298045478743630E-10 ) ( -176.630 -0.40612497946759260E-02 ) 45

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 given in SPICE text kernel format.

Dynamic Frames

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 mean equator of date. +X axis is parallel to cross product of +Z axis and vector normal to mean ecliptic of date. +Y axis completes the right-handed frame. \begindata FRAME_<frame_name> FRAME_<frame_ID>_NAME FRAME_<frame_ID>_CLASS FRAME_<frame_ID>_CLASS_ID FRAME_<frame_ID>_CENTER FRAME_<frame_ID>_RELATIVE FRAME_<frame_ID>_DEF_STYLE FRAME_<frame_ID>_FAMILY FRAME_<frame_ID>_PREC_MODEL FRAME_<frame_ID>_FREEZE_EPOCH = = = = = = = = = = Definitions <frame_ID> = integer frame ID <frame_ID> code <frame_name> <frame_name> = user-specified 5 frame name <frame_ID> 399 'J2000' 'PARAMETERIZED' 'MEAN_EQUATOR_AND_EQUINOX_OF_DATE' 'EARTH_IAU_1976' @1949-DEC-31/22:09:46.861901

Dynamic Frames

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 zero derivative block: the state transformation matrix has the form

Derivative block

R(t) | 0 -------|-----0 | R(t)

where R(t) is a time-dependent rotation.

Dynamic Frames

N IF

Inertial Dynamic Frames - 2

Navigation and Ancillary Information Facility

Dynamic Frames

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

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

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. Basically, 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

N IF
Run-time efficiency:

Limitations - 2
Navigation and Ancillary Information Facility

Dynamic frame evaluation typically requires more computation than is needed for CK or PCK 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

N IF
Navigation and Ancillary Information Facility

High Accuracy Orientation and Body-fixed Frames for the Moon and Earth
July 2013

N IF
Introduction Earth binary PCKs Lunar binary PCKs Lunar Frames Kernel
Frame specifications Frame alias names

Topics
Navigation and Ancillary Information Facility

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

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 Moon or the Earth.

Special PCK and FK for Earth and Moon

N IF

Introduction-2
Navigation and Ancillary Information Facility

NAIF provides High accuracy orientation data for the Earth and 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 each time an official new JPL Developmental Ephemeris (DE) is released. 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

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 ~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

N IF

IAU_EARTH vs ITRF93 Comparison Plot

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 this 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 newAPIs that require you to specify which frame to use.
The new APIs are: ILUMIN, SINCPT, SUBPNT, SUBSLR

If youre using SPICE to access Earth size and shape information, youll also need to load a text PCK file containing these data.
Typically use the latest generic text PCK: pck000xx.tpc

Navigation and Ancillary Information Facility

The high accuracy lunar orientation model obtained from the DE421 lunar ephemeris represents the result of a simultaneous numerical integration of lunar rotation and orbit, and of orbits of the planets.
The DE421 integration model includes*: A solid Moon Torques on the Moon from the static gravity field of degree 2-4. Torque is due to Earth, Sun, Venus, and Jupiter. Torques on the Moon and moments of inertia due to (degree 2) tides raised by Earth. Dissipation effects on torques and moments due to tides on the Moon. Torques due to Earth J2 interacting with Moon degree 2 (J2 and C22). Lunar quantities fit for DE421 include: Initial conditions for lunar orbit and rotation of body Moment of inertia difference (C-A)/B and (B-A)/C Third-degree gravity field coefficients Tidal Love numbers and dissipation Locations of four laser retroreflector arrays

It is anticipated that further improvements in the orientation of the moon will become available in new DExxx-based kernels in the future.
*Description provided by James G. Williams (JPL)
Special PCK and FK for Earth and Moon

N IF

Data Sources for High Accuracy Models

Navigation and Ancillary Information Facility

Data for lunar orientation come from JPLs DE/ LExxx planet/lunar ephemeris files.
Binary lunar PCKs represent the orientation of the Moons 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

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 maintained and available from NAIF. It has four functions.
1. Make two lunar framesPrincipal Axes (PA) and Mean Earth/Polar 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). 2. Connect the MOON_PA_DExxx frame name to the high accuracy lunar orientation PCK data that implement the PA orientation (relative to the ICRF). 3. Provide specifications, in the SPICE context, 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.

To access the PA or ME frame you must load the lunar FK into your program in addition to the lunar binary PCK that implements the lunar PA frame orientation.
19

Special PCK and FK for Earth and Moon

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 ILUMIN, SINCPT, SUBPNT, SUBSLR

If youre using SPICE to access Moon size and shape information, youll also need to load a text PCK file containing these data.
Typically use the latest generic text PCK, such as pck00009.tpc

Special PCK and FK for Earth and Moon

N IF
Example of file name
Kernel(s) needed

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?
moon_pa_de421_1900-2 050.bpc moon_080317.tf pck00009.tf

Lunar binary PCK

Lunar FK

Generic text PCK

Your objective

Orientation of DEnnn_PA frame

Orientation of DEnnn_ME frame

Orientation of IAU_MOON frame

Frame name to be used in SPICE software

MOON_PA

MOON_ME

IAU_MOON

Special PCK and FK for Earth and Moon

Non-native binary PCKs can be read without first being converted to the native binary form
If you need to write to a non-native binary PCK you must first convert it to native binary form using bingo or the pair of toxfr and tobin toxfr and tobin are avaiable in each Toolkit; bingo is available only from the NAIF website Converting a non-native binary PCK to native form will also speed up data access somewhat

Special PCK and FK for Earth and Moon

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 Moon and Earth The default body-fixed frames for the Moon and the Earth, for which the defining data are provided in a generic text PCK (taken from an IAU report) are very inaccurate representations of the actual orientations of these bodies

Special PCK and FK for Earth and Moon

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 Earth Moon

SPICE Default Body-fixed Frame IAU_Earth IAU_Moon

Better choice ITRF93 ITRFxx (in the future) Moon_PA or Moon_ME

Special PCK and FK for Earth and Moon

N IF

The Problem
Navigation and Ancillary Information Facility

The SPICE modules that make use of the default body-fixed Old: still available, but better to use those noted below reference frame are these
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, SINCPT, SUBPNT, SUBSLR

Special PCK and FK for Earth and Moon

N IF

Changing the Default Body-Fixed Frame Name

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

N IF

Using Association FKs to Change the Default

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 othernot both) moon_assoc_me.tf moon_assoc_pa.tf

These kernels are available on the NAIF server

For the Earth: ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/fk/planets/ For the Moon: ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/fk/satellites/

Special PCK and FK for Earth and Moon

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 choice for the moon!

File name

moon_assoc_pa.tf

moon_assoc_me.tf

PA Association FK**

ME Association FK**

no additional kernels
But best to use the replacements for these four, which dont use a default body-fixed frame: ILUMIN SINCPT SUBPNT SUBSLR

* LSPCN, ET2LST, ILLUM, SRFXPT, SUBPT, SUBSOL (and their C, Icy and Mice equivalents)
**Any version of one or the other of these kernels is good indefinitely; you do not need to use the latest instance offered on the NAIF server.
Special PCK and FK for Earth and Moon

N IF
Navigation and Ancillary Information Facility

Instrument Kernel IK

July 2013

N IF

Purpose
Navigation and Ancillary Information Facility

The Instrument Kernel serves as a repository for instrument specific information that may be useful within the SPICE context.
Always included: Specifications for an instruments field-of-view (FOV) size, shape, and orientation Other possibilities: Internal instrument timing parameters and other data relating to SPICE computations might also be placed in an I-kernel Instrument geometric calibration data

Note: instrument mounting alignment data are specified in a missions Frames Kernel (FK)
(Wasnt true for some of the earliest missions that used SPICE)
Instrument Kernel

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. etc

Instrument Kernel

N IF

I-Kernel Contents (1)

Navigation and Ancillary Information Facility

Examples of IK keywords, with descriptions:

INS-94031_FOCAL_LENGTH INS-41220_IFOV INS-41130_NUMBER_OF_SECTORS MGS MOC NA focal length MEX HRSC SRC pixel angular size 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 instruments FOV, if the SPICE Toolkits GETFOV routine is planned to be used to retrieve the FOV attributes Keywords required by GETFOV will be covered later in this tutorial

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)
Instrument Kernel

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

This documentation exists 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

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 string values

When an instruments 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 GETFOV routine
CALL GETFOV ( INSTID, ROOM, SHAPE, FRAME, BSIGHT, N, BOUNDS)

FORTRAN examples are shown

Instrument Kernel

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 Toolkits GETFOV module will be used
Keyword defining shape of the FOV INS#_FOV_SHAPE = 'CIRCLE' or 'ELLIPSE' or 'RECTANGLE' or 'POLYGON'

Keyword defining 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

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

N IF
Y
14.03 O

Circular Field of View

Navigation and Ancillary Information Facility

Consider an instrument with a circular field of view.

Y Boundary Corner Vector X (0,0,0) Instrument focal point Boresight Vector (0,1,4)
Angular Size

Subtended field of view angle

14.03 = arc tan (1/4)

Instrument Kernel

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 INS-11111_FOV_FRAME INS-11111_BORESIGHT INS-11111_FOV_BOUNDARY_CORNERS = = = = 'CIRCLE' 'FRAME_FOR_INS-11111' ( 0.0 0.0 1.0 ) ( 0.0 1.0 4.0 )

Specifying half angular extents of the FOV:

INS-11111_FOV_SHAPE INS-11111_FOV_FRAME INS-11111_BORESIGHT INS-11111_FOV_CLASS_SPEC INS-11111_FOV_REF_VECTOR INS-11111_FOV_REF_ANGLE INS-11111_FOV_ANGLE_UNITS = = = = = = = 'CIRCLE' 'FRAME_FOR_INS-11111' ( 0.0 0.0 1.0 ) 'ANGLES' ( 0.0 1.0 0.0 ) 14.03624347 'DEGREES'

Instrument Kernel

N IF

Elliptical Field of View

Navigation and Ancillary Information Facility

Consider an instrument with an elliptical field of view.

Y
14.03 O

26.57 O

Y Boundary Corner Vectors (0,1,4) Z X (2,0,4)

Subtended field of view angle

14.03 = arc tan (1/4) 26.57 = arc tan (2/4)

(0,0,0) Instrument focal point

Instrument Kernel

Boresight Vector

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 INS-22222_FOV_FRAME INS-22222_BORESIGHT INS-22222_FOV_BOUNDARY_CORNERS = = = = 'ELLIPSE' 'FRAME_FOR_INS-22222' ( 0.0 0.0 1.0 ) ( 0.0 1.0 4.0 2.0 0.0 4.0 )

Specifying half angular extents of the FOV:

INS-22222_FOV_SHAPE INS-22222_FOV_FRAME INS-22222_BORESIGHT INS-22222_FOV_CLASS_SPEC INS-22222_FOV_REF_VECTOR INS-22222_FOV_REF_ANGLE INS-22222_FOV_CROSS_ANGLE INS-22222_FOV_ANGLE_UNITS
Instrument Kernel

= = = = = = = =

'ELLIPSE' 'FRAME_FOR_INS-22222' ( 0.0 0.0 1.0 ) 'ANGLES' ( 0.0 1.0 0.0 ) 14.03624347 26.56505118 'DEGREES'
14

N IF

Rectangular Field of View

Navigation and Ancillary Information Facility

Consider an instrument with a rectangular field of view.

Y
14.03 O

26.57 O

Y Boundary Corner Vectors X Boresight Vector (2,1,4) (-2,1,4) Z

Subtended field of view angle

14.03 = arc tan (1/4) 26.57 = arc tan (2/4)

(0,0,0) Instrument focal point

Instrument Kernel

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 INS-44444_FOV_FRAME INS-44444_BORESIGHT INS-44444_FOV_BOUNDARY_CORNERS = = = = 'POLYGON' 'FRAME_FOR_INS-44444' ( 0.0 0.0 1.0 ) ( 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

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 Web site (http://naif.jpl.nasa.gov/naif/utilities.html)
OPTIKS BINGO displays field-of-view summary for all FOVs defined in a collection of IK files. converts IK files between UNIX and DOS text formats

C-Kernel

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: http://naif.jpl.nasa.gov/naif/data_archived.html

Unfortunately NAIF does not yet have an I-Kernel Required Reading document But information about IKs is available in other documents:
header of the GETFOV routine Kernel Required Reading OPTIKS Users Guide Porting_kernels tutorial NAIF IDs Tutorial Frames Required Reading

C-Kernel

N IF
IK file example

Backup
Navigation and Ancillary Information Facility

Computing angular extents from corner vectors returned by GETFOV

Instrument Kernel

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 --|
Instrument Kernel

continues

C C

Instrument Kernel

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

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) Instrument

Subtended field of view angles

Instrument Kernel

N IF
C

Rectangular FOV Angular Size - 2

Navigation and Ancillary Information Facility
FORTRAN EXAMPLE

Retrieve FOV parameters from the kernel pool. CALL GETFOV(-33333, 4, SHAPE, FRAME, BSGHT, N, BNDS) 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) 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)

Compute the angular separations ANG1 = VSEP( BSGHT, VEC1 ) ANG2 = VSEP( BSGHT, VEC2 ) Separate the larger and smaller angles. LRGANG = MAX( ANG1, ANG2) SMLANG = MIN( ANG1, ANG2)

Instrument Kernel

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; } 29

Instrument Kernel

N IF
Navigation and Ancillary Information Facility

Reading FKs and IKs

July 2013

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:
ftp://naif.jpl.nasa.gov/pub/naif/pds/data/di-c-spice-6-v1.0/disp_1000/data/fk/*.tf ftp://naif.jpl.nasa.gov/pub/naif/pds/data/di-c-spice-6-v1.0/disp_1000/data/ik/*.ti

CASSINI:
ftp://naif.jpl.nasa.gov/pub/naif/pds/data/co-s_j_e_v-spice-6-v1.0/cosp_1000/data/fk/*.tf ftp://naif.jpl.nasa.gov/pub/naif/pds/data/co-s_j_e_v-spice-6-v1.0/cosp_1000/data/ik/*.ti

MESSENGER:
ftp://naif.jpl.nasa.gov/pub/naif/pds/data/mess-e_v_h-spice-6-v1.0/messsp_1000/data/fk/*.tf ftp://naif.jpl.nasa.gov/pub/naif/pds/data/mess-e_v_h-spice-6-v1.0/messsp_1000/data/ik/*.ti

MARS EXPRESS:
ftp://naif.jpl.nasa.gov/pub/naif/MEX/kernels/fk/*.TF ftp://naif.jpl.nasa.gov/pub/naif/MEX/kernels/ik/*.TI
Reading FKs and IKs

N IF
Navigation and Ancillary Information Facility

Derived Quantities
July 2013

N IF

What are Derived Quantities?

Navigation and Ancillary Information Facility

Derived quantities are produced using data from kernels

These are the primary reason that SPICE exists!

Examples are:
Lighting conditions Surface intercept (LAT/LON) General geometry Coordinate system conversions Matrix and vector operations

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.

Derived Quantities

N IF
Geometric Objects
Planes Ellipses Ellipsoids Rays

A Quick Tour
Navigation and Ancillary Information Facility

Vector/Matrix Routines

Vector and vector derivative arithmetic Matrix arithmetic

Coordinate Systems
Spherical: latitude/longitude, co-latitude/longitude, right ascension/declination; Geodetic, Cylindrical, Rectangular, Planetographic

Others (the most interesting ones!)

Lighting angles, sub-points, intercept points, season, geometric event finder
Derived Quantities

The lists on the following pages are just a subset of whats available in the Toolkit.

N IF
Function

Vectors
Navigation and Ancillary Information Facility

Routine
VDOT, DVDOT VCROSS, DVCRSS VHAT, DVHAT UCROSS, DUCRSS VADD, VADDG VSUB, VSUBG VSCL, [VLCOM, [VLCOM3]] VSEP VNORM

<v,w> vxw v/|v| v x w / | v x w| v+w v-w av [+ bw [+ cu]] angle between v and w |v|

v v v
||

VPROJ,

VPERP

TWOVEC,

FRAME

w
Derived Quantities

N IF
Function
Mxv MxM Mt x v Mt x M M x Mt vt x M x v Mt M-1
M V X T
Derived Quantities

Matrices
Navigation and Ancillary Information Facility

Selected Matrix-Vector Linear Algebra Routines

Routine
MXV MXM MTXV MTXM MXMT VTMV XPOSE INVERSE, INVSTM
= = = = Matrix Vector Multiplication Transpose
5

N IF

Matrix Conversions
Navigation and Ancillary Information Facility

Function
Transform between Euler angles
ax ay az bx by bz cx cy cz

Routines
EUL2M, M2EUL
3x3 rotation matrix
ax ay az bx by bz cx cy cz x y z x y z x y z

0
ax ay az bx by bz cx cy cz

Transform between Euler angles and Euler angle rates or rotation matrix and angular velocity vector

EUL2XF, XF2EUL RAV2XF, XF2RAV

6x6 state transformation matrix

ax ay az bx by bz cx cy cz

Rotation axis and angle

Transform between

RAXISA, AXISAR ROTATE, ROTMAT

3x3 rotation matrix

ax ay az bx by bz cx cy cz

(Q0,Q1,Q2,Q3)
SPICE Style Quaternion
Derived Quantities

Transform between

3x3 rotation matrix

Q2M, M2Q
6

N IF
Function
Ellipsoids

Geometry
Navigation and Ancillary Information Facility

Routine
NEARPT, SUBPNT, DNEARP SURFPT, SINCPT SURFNM EDLIMB INELPL NPEDLN

nearest point surface ray intercept surface normal limb slice with a plane altitude of ray w.r.t. to ellipsoid

Planes
intersect ray and plane INRYPL PJELPL SAELGV

Ellipses
project onto a plane find semi-axes of an ellipse

Derived Quantities

N IF

Position Coordinate Transformations

Navigation and Ancillary Information Facility

Given the direction of an instrument boresight in a bodyfixed frame, return the illumination angles (incidence, phase, emission) at the surface intercept on a tri-axial ellipsoid

incidence phase instrument emission boresight direction

target-observer vector

Navigation and Ancillary Information Facility

This computation is for the reception case; radiation is received at the earth at a given epoch ET.

This simplified computation CALL SPKEZR to get light time corrected position of center of Saturn ignores the difference at time ET as seen from earth in J2000 frame SATCTR. between the light time from 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. The position and orientation of Saturn can be re-computed using the light time from earth to the intercept; the intercept can be re-computed until convergence is attained.
Derived Quantities

CALL SPKEZR to get light time corrected position of spacecraft as seen from earth at time ET in J2000 reference frame SCVEC.

CALL NVP2PL and use SATCTR and SATPOL to construct the ring plane RPLANE. CALL INRYPL to intersect the earth-spacecraft vector SCVEC with the Saturn ring plane RPLANE to produce the intercept point X. CALL VSUB to get the position of the intercept with respect to Saturn XSAT (subtract SATCTR from X) and use VNORM to get the distance of XSAT from the center of Saturn.
17

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 used to represent the ring plane. Use SINCPT to find the intercept of the earth-Cassini ray with the 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 Saturns 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

An alternate approach

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).

Direction to the observer

Spacecraft motion

A body such as a satellite

Derived Quantities

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 shorter than the minimum interval between occultation events that are to be distinguished, but large enough to solve problem with reasonable speed. Insert search interval into a SPICE window. This is the confinement window.

Direction to the observer A body such as a satellite

Spacecraft motion

CALL GFOCLT to find occultations, if any. The time intervals, within the confinement window, over which occultations occur will be returned in a SPICE window.
GFOCLT can treat targets as ellipsoids or points (but at least one must be an ellipsoid). GFOCLT can search for different occultation or transit geometries: full, partial, annular, or any.

Derived Quantities

N IF
Navigation and Ancillary Information Facility

Other Useful Functions

July 2013

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

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 routines 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.
Other Useful Functions

N IF
Text files provide a simple, human readable mechanism for sharing data. The Toolkit contains several utility routines to assist with the creation and parsing of text, and with the reading and writing of text files.

Text I/O (1)

Navigation and Ancillary Information Facility

[F,C] RDTEXT: read a line of text from a text file [F] TOSTDO: write a line of text to standard output [F,C] PROMPT: display a prompt, wait for and return users 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.
4

Other Useful Functions

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 CALL RDTEXT ( NAME, LINE, EOF ) DO WHILE ( .NOT. EOF ) process the line just read CALL RDTEXT ( NAME, LINE, EOF ) END DO

Terminal Window

Filename? mydata.file You specified the file: mydata.file

Other Useful Functions

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, TPARSE

Heavy duty parsing

[F] SCANIT
Other Useful Functions

N IF

String Manipulation - Parsing (3)

Navigation and Ancillary Information Facility
a dog

a dog, a cat, and a cow

lparsm
Split on a comma!

a cat and a cow

Remove

extra

spaces

cmprss

Remove extra spaces

Green eggs and ham the cat in the hat how the grinch stole Christmas

matchi( *g*)

green eggs and ham how the grinch stole Christmas

Match any string containing a g!

Other Useful Functions

N IF

String Manipulation - Creating (1)

Navigation and Ancillary Information Facility

Fill in the Blank

[F,C] 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] REPMI: Replace a marker with an integer.

CALL REPMI ( The value is: #, '#', 7, OUT )

OUT has the value The value is: 7

[F,C] REPMD: Replace a marker with a double precision number.

CALL REPMD ( The value is: #, '#, 3.141592654D0, 10, OUT )

OUT has the value The value is: 3.141592654E+00

[F,C] 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.

Other Useful Functions

N IF

String Manipulation - Creating (2)

Navigation and Ancillary Information Facility

Fill in the Blank (cont.)

[F,C] 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

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

Other Useful Functions

N IF
Sorting arrays

Searching, Sorting and Other Array Manipulations (1)

Navigation and Ancillary Information Facility

[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

N IF
Body A.U.1

Searching, Sorting and Other Array Manipulations (2)

Navigation and Ancillary Information Facility

Sorted Body

A.U.1

sun mercury venus earth mars jupiter saturn uranus neptune pluto

00.0 00.455 00.720 00.983 01.531 05.440 09.107 20.74 30.091 31.052

orderc

04 06 05 02 09 10 07 01 08 03

reordc,d

earth jupiter mars mercury neptune pluto saturn sun uranus venus

00.983 05.440 01.531 00.445 30.091 31.052 09.107 00.000 20.74 00.720

Vector of Body indices representing the list sorted in alphabetical order.

Distance in A.U. at Jan 01, 2006. 14

Other Useful Functions

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

N IF
Union

Windows Math
Navigation and Ancillary Information Facility

Intersection

Difference

Other Useful Functions

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 the list of values associated with a symbol Fetch/Sort values associated with a symbol

See symbols.req for more information.

Other Useful Functions

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. Sets and cells arent currently needed in the MATLAB Toolkits since MATLAB supports set math.

Other Useful Functions

N IF
NAIF Boris Chuck Ed Nat Lee Cassini Boris Chuck Ed Nat

Sets and Cells (2)

Navigation and Ancillary Information Facility

MGS Boris Ed

Other Lee

CALL UNIONC ( CASSINI, MGS, PROJECTS) CALL DIFFC ( NAIF, PROJECTS, OTHER )

Other Useful Functions

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 usernot 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

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] LGRESP, LGRINT, LGRIND, POLYDS, HRMESP, HRMINT Chebyshev Polynomial Evaluation: [F] CHBDER, CHBVAL, CHBINT

Other Useful Functions

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

N IF
Navigation and Ancillary Information Facility

SPICE Geometry Finder (GF) Subsystem

Searching for times when specified geometric events occur

July 2013

N IF

Navigation and Ancillary Information Facility

The current Fortran and C SPICE Toolkits provide some mid-level API routines 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 API routines are:

GFEVNT: All scalar numeric quantity searches GFFOVE: Target or ray in FOV searches GFOCCE: Occultation searches

Geometry Finder Subsystem

N IF

The SPICE Window

GF uses a SPICE window to:

confine the time bounds over which a search is to take place contain the time intervals that met the search criteria There may be none, one or multiple result intervals The result intervals can be of non-zero or zero length
A zero-length interval is simply an epochan instant in time

Search Confinement Window

Confinement Window Start Time

Geometry Finder Subsystem

Non-zero length result intervals

Zero length result intervals (epochs)

Confinement Window End Time

N IF

Cascading Search Using Multiple SPICE Windows

Navigation and Ancillary Information Facility

The result window from one search can be used as the confinement window for another.
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 a 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

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 figures of the Sun and Moon, as seen from DSS-14, 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 the occultation search (on the original confinement window), the total search time is greatly reduced.

Original confinement window

Result of angular separation search: second confinement window

Result of occultation search

Geometry Finder Subsystem

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

See the next page for an example

GF Search Examples

Geometry Finder Subsystem

Range Rate Extremum Search

Navigation and Ancillary Information Facility

Find the times when the range rate of a lunar reflector, as seen by an Earth station, attains an absolute extremum.

Reflector

Station Moon

Earth
Geometry Finder Subsystem

N IF

Angular Separation Inequality Search -1

Target in FOV Search

Navigation and Ancillary Information Facility

Find the time period when Titan appears in the FOV of the Cassini ISS Narrow Angle Camera (NAC). The target is an ephemeris object; the target shape is modeled as an ellipsoid. (Point targets are also supported.)

Titan Cassini ISS NAC FOV

The FOV shape may be any of:

Rectangle Circle Ellipse Polygon

Cassini orbiter

Geometry Finder Subsystem

N IF

Ray in FOV Search

Navigation and Ancillary Information Facility

Find the time period when the star having Hipparcos catalog number 6000 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 Circle Ellipse Polygon

Cassini orbiter

Geometry Finder Subsystem

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 Unit sphere Planetocentric Latitude 23.4 deg.

Path of sub-solar point on unit sphere (in red) J2000 Y

J2000 X

Geometry Finder Subsystem

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

J2000 X

Earth-Sun direction at epoch of J2000 equator crossing

Geometry Finder Subsystem

N IF

Position Coordinate Inequality Search -1

Navigation and Ancillary Information Facility

Find the time period 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

Geometry Finder Subsystem

N IF

Position Coordinate Inequality Search -2

Navigation and Ancillary Information Facility

Find the time period when the Lunar Reconnaissance Orbiters (LRO) off-nadir angle exceeds 5 degrees. Solution requires CKbased LRO spacecraft frame. 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

Geometry Finder Subsystem

N IF

Sub-Observer Point Coordinate Equality Search

Navigation and Ancillary Information Facility

Find the time at which the planetocentric latitude of the sub-spacecraft point, using the near point definition, is 25 degrees.
Body-fixed Z Outward surface normal direction at sub-spacecraft point

Path of sub-spacecraft point (in red)

Planetocentric Latitude 25 deg.

Spacecraft

Body-fixed Y

Body-fixed X
Geometry Finder Subsystem

N IF

Surface Intercept Coordinate Equality Search

Navigation and Ancillary Information Facility

Find the time at which the planetographic longitude of a given camera boresight surface intercept is -45 degrees.
Body-fixed Z

Path of boresight intercept (in red)

Spacecraft

Camera boresight direction at epoch of meridian crossing Body-fixed Y

Body-fixed X
Geometry Finder Subsystem

Planetographic Longitude -45 deg.

N IF

Surface Intercept Box Search

Navigation and Ancillary Information Facility

Find the time period when the planetographic longitude of a given 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

Planetographic Latitude 0 to 30 deg.

Path of boresight intercept (in red)

Spacecraft

Camera boresight direction Body-fixed Y

Body-fixed X
Geometry Finder Subsystem

Planetographic Longitude -45 to -70 deg.

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 IAU_SATURN X Cassini to DSS-13 radiation direction IAU_SATURN Y Path of radiation intercept (in red)
DSS-13
Geometry Finder Subsystem

Cassini orbiter

Earth

Ring plane ellipsoid: 1cm thick, radius 600000 km, centered at Saturns center

N IF

User-Defined Quantity Extremum Search

Navigation and Ancillary Information Facility

Find the time period 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 position of Titan

Angular separation of position vectors

Cassini orbiter

Geometry Finder Subsystem

N IF
Navigation and Ancillary Information Facility

Geometric Search Types and Constraints

Geometry Finder Subsystem

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

N IF

Find Local Maxima

Navigation and Ancillary Information Facility

Find time window during which Distance is a local maximum. GF API input arguments defining constraint:
RELATE = LOCMAX! ADJUST = 0.D0 ! REFVAL = 0.D0
(REFVAL is not used in this case but should be initialized for portability)

Confinement Window

Not Solutions

Distance

D = f(t)

Local extrema are always in the interior of the confinement window, never on the boundary

[t0,t0] Time
Geometry Finder Subsystem

Result Window
45

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 = 0.D0!
(REFVAL is not used in this case but should be initialized for portability)

Confinement Window

Distance

D = f(t)
DMIN

[t0,t0] Time
Geometry Finder Subsystem

Result Window
46

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 = 0.D0!
(REFVAL is not used in this case but should be initialized for portability)

Confinement Window DMAX

Distance

D = f(t)

[t0,t0] Time
Geometry Finder Subsystem

Result Window
47

N IF

Find Adjusted Absolute Minimum

Navigation and Ancillary Information Facility

Find time window during which Distance < DADJ = DMIN + ADJ0 GF API input arguments defining constraint:
RELATE = ABSMIN ADJUST = ADJ0 REFVAL = 0.D0 (ADJ0 > 0)
(REFVAL is not used in this case but should be initialized for portability)

Confinement Window

[ D = f(t)

Distance

DADJ DMIN ADJ0

Result Window
[ t0, t1 Time ] [ t 2 , t3 ]
48

Geometry Finder Subsystem

N IF

Find Adjusted Absolute Maximum

Navigation and Ancillary Information Facility

Find time window during which Distance > DADJ = DMAX - ADJ0 GF API input arguments defining constraint:
RELATE = ABSMAX ADJUST = ADJ0 REFVAL = 0.D0 (ADJ0 > 0)
(REFVAL is not used in this case but should be initialized for portability)

Confinement Window DMAX DADJ

[
ADJ0

Distance

D = f(t)

t0, t1 ] Time

[ t2, t3 ]

Result Window
49

Geometry Finder Subsystem

N IF
Navigation and Ancillary Information Facility

More Details
Root Finding, including step size selection Workspace API Example: GFDIST

Geometry Finder Subsystem

N IF
Navigation and Ancillary Information Facility

Root Finding

Geometry Finder Subsystem

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 windows 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

N IF

Step Size Selection

Navigation and Ancillary Information Facility

The GF subsystem asks the user to specify a time step (often called thestep 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

N IF
Note that:

Monotone Windows -1
Navigation and Ancillary Information Facility

Example: monotone windows for a distance function

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

Time
Geometry Finder Subsystem

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

[ t0, t1 ] Time
Geometry Finder Subsystem

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 step size delta window interval 2

t7
step = 3*delta

t6
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

N IF

Solving for Interval Endpoints

Navigation and Ancillary Information Facility

window interval 1 step size delta

window interval 2

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

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 dont 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 windows intervals.

Usually data errors are large enough so that the accuracy of the result is poorer than its precision.
Geometry Finder Subsystem

N IF
Navigation and Ancillary Information Facility

Workspace

Geometry Finder Subsystem

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; its 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

N IF
Navigation and Ancillary Information Facility

API Example: GFDIST Solve for Distance Constraints

Geometry Finder Subsystem

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

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.
Well show how to perform the set-up unique to each language. Note: theres no set-up to do in the MATLAB case; hence theres 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

N IF
Fortran constant and variable declarations

Fortran Set-up
Navigation and Ancillary Information Facility

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 here), if youre not sure what size is required. The actual INTEGER MAXWIN 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 )
Initializationtypically done once per program execution

Insert start and stop times into the confinement window:

CALL WNINSD ( tdb_0, tdb_1, CNFINE )

Geometry Finder Subsystem

N IF
Choose:

Execute the Search -1

Navigation and Ancillary Information Facility

Search executiondone as many times as necessary during program execution

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 Geometry Finder Subsystem Input/output output

N IF
Search execution, continued

Execute the Search -2

Navigation and Ancillary Information Facility

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: DONT 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

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, well 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 Reading an SPK tutorial backup charts for examples of aberration correction magnitudes.

N IF
INPUTS

Arguments of GFDIST - 2
Navigation and Ancillary Information Facility

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

N IF
Navigation and Ancillary Information Facility

Exception Handling

July 2013

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

N IF

Exceptions Are - 1
Navigation and Ancillary Information Facility

Run time error conditions

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

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, selecting TRACEBACK has no effect. errprt_c ( set, LEN, none, short, traceback );
Exception Handling

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

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, its 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

N IF

Get Error Status - 2

Navigation and Ancillary Information Facility

Use QCKTRC or TRCDEP and TRCNAM to retrieve traceback message

In CSPICE, only f2cd versions of these routines are available

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 handle error condition; a reset is automatically performed by Icy

Exception Handling

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

N IF
Signal error

Signal Errors - 2
Navigation and Ancillary Information Facility

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

N IF
Error action:

Icy Error Handling

Navigation and Ancillary Information Facility

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 librarys 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

N IF
Error action:

Mice Error Handling

Navigation and Ancillary Information Facility

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 librarys 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

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. Dont throw away error output. It may be the only useful clue as to whats 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

N IF
Navigation and Ancillary Information Facility

Toolkit Applications

July 2013

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 generic Toolkits. Time conversion tool: chronos SPK generation tool: mkspk SPK merge and subset tool: spkmerge SPK comparison tool: spkdiff CK generation tool: msopck Frame comparison tool: frmdiff Kernel summary tools: brief, ckbrief, spacit Comments manipulation tools: commnt, spacit File format converters: tobin, toxfr
Toolkit Applications

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 inside of IDL or MATLAB

Toolkit Applications

N IF

CHRONOS
Navigation and Ancillary Information Facility

chronos is an application that 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 -----------------------------Universal Coord. Time (UTC) Ephemeris Time (ET) S/C On-board Clock Time (SCLK) Local Solar Time (LST) --> Supported Time Types ----------------------------> SCET, ERT, ETT, LT --> SCET, ERT, ETT, SECONDS, LT --> SCLK, HEX, TICKS --> LST, LSUN

Toolkit Applications

N IF

CHRONOS - Input/Output Matrix

Navigation and Ancillary Information Facility

Input System/Type ----------------UTC / SCET (*) UTC / ERT UTC / ETT ET / SCET (*) ET / ERT ET / ETT ET / SECONDS SCLK / SCLK (*) SCLK / HEX SCLK / TICKS LST / LST

(*) default input/output types

Toolkit Applications

Output System/Type ----------------UTC / SCET (*) UTC / ERT UTC / ETT UTC / LT ET / SCET (*) ET / ERT ET / ETT ET / SECONDS ET / LT SCLK / SCLK (*) SCLK / HEX SCLK / TICKS LST / LST (*) LST / LSUN
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

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>] [-CENTER <cental body ID>] [-LANDINGTIME <UTC time of the landing>] [-SOL1INDEX <index of the first SOL>] [-NOLABEL] [-TRACE]

Items in square brackets are optional

Toolkit Applications

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

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 states, classic elements, and two-line elements Use of this program is discussed in a separate tutorial about making SPK files, and in the mkspk Users Guide.

Toolkit Applications

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
Extract an interval of time of interest from a single SPK file or a set of SPK files. 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

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 sources 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.

Toolkit Applications

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 spk_kernel bodies source_spk_kernel source_spk_kernel = = = = = naif0007.tls output.bsp -82, 10, 301, 399, 3 de403s.bsp 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

N IF

SPKDIFF
Navigation and Ancillary Information Facility

spkdiff is a command line program for comparing trajectories provided by two SPK files spkdiff compares SPKs 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 one SPK file, then computing another set of geometric states for the same or different body, center, and frame at the same times using the other SPK file, 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.

Toolkit Applications

N IF
$ spkdiff

SPKDIFF - Usage
Navigation and Ancillary Information Facility Terminal Window

spkdiff computes differences between geometric states obtained from two SPK files and either displays these differences or shows statistics about them (see the User's Guide for more details.) The program usage is: % spkdiff [options] <first SPK file> <second SPK file> Options are shown below. Order and case of keys are not significant. Values must be space-separated from keys, i.e. '-n 10', not '-n10'. -b1 -c1 -r1 -b2 -c2 -r2 -k -b -e -s -n -f -t
Toolkit Applications

<first body name or ID> <first center name or ID> <first reference frame name> <second body name or ID> <second center name or ID> <second reference frame name> <other kernel file name(s)> <interval start time> <interval stop time> <time step in seconds> <number of states: 2 to 1000000 (default: 1000)> <output time format (default: TDB seconds past J2000)> <report type: basic|stats|dump|dumpvf (default: basic)> 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 Position (km): 3.1341344106404E-01 Velocity (km/s): 2.8848827480682E-04

average 4.5090516995222E-02 4.2085874877127E-05

Toolkit Applications

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 -1.0394439243989E-07 -3.9614350816493E-05 2.2866028283812E+08 +4.2172435702119E-02 +2.3672255851626E-06 -1.1475679619731E-04 +1.4080506259574E-07 -3.9250157214024E-05 2.2866290049059E+08 +4.4830247467488E-02 +9.1590974014175E-05 -7.3802870365833E-04 -1.1724240528272E-07 -4.2099832045985E-05 2.2866551814305E+08 +4.5968515669515E-02 -1.3529652839857E-04 -7.5686845133612E-05 +3.4127364997784E-08 -4.2529268294482E-05 --More--

-8.0803561182349E-08 +1.3970238250217E-07 +5.7800410436763E-07 -4.7565892258325E-07

Toolkit Applications

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
has a simple command line interface requires all setups to be provided in a setup file that follows the SPICE text kernel syntax can process quaternions (SPICE and non-SPICE flavors), Euler angles, or matrixes, tagged with UTC, SCLK, or ET for more details see the Making a CK File Tutorial

Toolkit Applications

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 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 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, matrixes, or Euler angles), or a statistical analysis of rotations or differences.
Toolkit Applications

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)
Toolkit Applications

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 # to '2009 JAN 28 00:01:05.346' TDB (286372865.34683 TDB # # 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 2.8628543776953E+08 +6.9350851552324E-01 +3.7594215798843E-01

seco... seco...

-6.1... -6.1...

Toolkit Applications

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

N IF

Kernel Summary Applications

Navigation and Ancillary Information Facility

The contents of binary kernels can be summarized with the 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. 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.

Toolkit Applications

N IF

BRIEF
Navigation and Ancillary Information Facility

brief is a simple command line program for summarizing the contents of SPK or binary PCK files the files to be summarized can 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 motions along with the bodies treating all input files as if they were a single file displaying summary only for files covering a specified time or time range or containing data for a specified body displaying summary in tabular format or grouped by coverage and many others ...
Toolkit Applications

N IF
$ brief

BRIEF - Usage
Navigation and Ancillary Information Facility Terminal Window

BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0063 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 -t -a -utc -utcdoy -etsec display centers of motion/relative-to frames display summary in a tabular format treat all files as a single file display times in UTC calendar date format (needs LSK) display times in UTC day-of-year format (needs LSK) 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

N IF
$ brief de405s.bsp m01_cruise.bsp

BRIEF - Example
Navigation and Ancillary Information Facility Terminal Window

BRIEF -- Version 3.0.0, January 14, 2008 -- Toolkit Version N0063

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) ----------------------------2001 APR 07 16:25:00.000

End of Interval (ET) ----------------------------2001 OCT 24 05:00:00.000

Toolkit Applications

N IF

CKBRIEF
Navigation and Ancillary Information Facility

ckbrief is a simple command line program for summarizing the contents of CK files the files to be summarized can 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 as date UTC, DOY UTC, SCLK, or encoded SCLK (default time format is calendar ET) to display times as ET, UTC, or SCLK, an LSK file and 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 displaying summary only for files with data for a given CK ID and many others ...
Toolkit Applications

N IF

CKBRIEF Interval Summary

Navigation and Ancillary Information Facility

There often are coverage gaps within a CK segment Using the -dump option allows to get a complete list of continuous coverage intervals for each segment
Segment coverage reported by ckbrief with -dump Segment Coverage Reported by ckbrief without -dump

Time Sample CK Segment Type 3 Coverage Gaps Instances of Available Pointing Data

Toolkit Applications

N IF
$ ckbrief

CKBRIEF Usage
Navigation and Ancillary Information Facility Terminal Window

CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0063 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 -rel -n -t -utc -utcdoy -sclk display display display display display display display interpolation intervals relative-to frames (may need FK) frames associated with CK IDs (may need FK) summary in a tabular format times in UTC calendar date format (needs LSK&SCLK) times in UTC day-of-year format (needs LSK&SCLK) 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

N IF

CKBRIEF Example
Navigation and Ancillary Information Facility Terminal Window

$ ckbrief -sclk 981116_981228pa.bc sclk.ker CKBRIEF -- Version 5.0.0, February 11, 2009 -- Toolkit Version N0063 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 5.0.0, February 11, 2009 -- Toolkit Version N0063 Summary for: 990817_990818ra.bc Object: -82000 Interval Begin UTC -----------------------1999-AUG-17 17:30:01.418 1999-AUG-17 23:05:45.289 1999-AUG-18 06:06:09.124 1999-AUG-18 11:52:20.991 Interval End UTC -----------------------1999-AUG-17 23:05:42.039 1999-AUG-18 06:06:05.874 1999-AUG-18 11:52:17.741 1999-AUG-18 13:30:00.953 AV --N N N N

Toolkit Applications

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 5.0.0, February 11, 2009 -- Toolkit Version N0063 Summary for: mgs_spice_c_kernel_2004-099.bc Segment No.: 1 Object: -94000 Interval End UTC -----------------------2004-APR-08 06:53:47.805 2004-APR-08 06:54:07.805 2004-APR-08 06:54:35.805 2004-APR-08 06:54:55.805 2004-APR-08 06:55:07.805 2004-APR-08 06:55:23.805 2004-APR-08 11:59:55.802 2004-APR-08 23:59:55.795 AV --Y Y Y Y Y Y Y Y Relative to FRAME ----------------J2000 J2000 J2000 J2000 J2000 J2000 J2000 J2000

Interval Begin UTC -----------------------2004-APR-08 00:00:59.809 2004-APR-08 06:54:07.805 2004-APR-08 06:54:19.805 2004-APR-08 06:54:51.805 2004-APR-08 06:55:07.805 2004-APR-08 06:55:23.805 2004-APR-08 06:55:35.805 2004-APR-08 12:00:55.802

Toolkit Applications

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 It displays short menus where you choose the action desired

spacit may also be used to manage comments, and to convert between binary and transfer format

Toolkit Applications

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, 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 youre 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

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 to be replaced with better comments
Toolkit Applications

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 = = = = = = /kernels/gen/lsk/naif0007.tls de405.bsp /usr2/nio/gen/de405.nio 1 2 3 4 5 6 7 8 9 10 301 399 199 299 499 CAL-ET 1950 JAN 01 00:00:41.183 CAL-ET 2050 JAN 01 00:01:04.183

LEAPSECONDS_FILE SPK_FILE SOURCE_NIO_FILE BODIES BEGIN_TIME END_TIME

July 2013

N IF

Summary
Navigation and Ancillary Information Facility

NAIF makes available a set of applications not included in the generic Toolkits. This set includes programs for:
making, modifying, validating, inspecting, and analyzing SPK files: pinpoint, dafcat, bspidmod, dafmod, spy making and modifying CK files prediCkt, ckslicer, ckspanit, dafcat, cksmrg, dafmod making SCLK files makclk computing derived quantities orbnum, optics, spy determining SPICE kernel type and binary format archtype, bff converting between binary and text kernel formats bingo

Executables and Users Guides for selected computer environments are available from the NAIF server at:
http://naif.jpl.nasa.gov/naif/utilities.html
Non-Toolkit Applications

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 inside of IDL or MATLAB

Toolkit Applications

N IF
Ground stations

PINPOINT
Navigation and Ancillary Information Facility

pinpoint is a program for creating SPK files and topocentric frames FK files for objects whose position is a constant offset with respect to another object
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

N IF
$ more mer1_meridiani.def

PINPOINT Example
Navigation and Ancillary Information Facility Terminal Window

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) -------------------------------2001 JAN 01 00:00:00.000
Non-Toolkit Applications

End of Interval (ET) -------------------------------2100 JAN 01 00:00:00.000 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
Works on SPKs, CKs, and binary PCKs will not merge different types of kernels together, i.e. 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 programs 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

N IF
$ dafcat m01_merged.bsp

DAFCAT Example: SPK

Navigation and Ancillary Information Facility Terminal Window

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

N IF
$ dafcat m01.bc

DAFCAT Example: CK
Navigation and Ancillary Information Facility Terminal Window

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

N IF

BSPIDMOD
Navigation and Ancillary Information Facility

bspidmod is a program for altering the object IDs in a binary SPK file
can be used to modify IDs in an SPK file(s) produced with a bogus spacecraft ID (or a simulation spacecraft ID) can be used to replace good 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)

bspidmod is a command line program with 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 the in 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

N IF
$ brief mer2_crus_sim_id.bsp Brief. Version: 2.2.0

BSPIDMOD Example
Navigation and Ancillary Information Facility Terminal Window
(SPICE Toolkit N0057)

Summary for: mer2_crus_sim_id.bsp Body: -255 Start of Interval (ET) -------------------------------2003 JUL 09 00:15:00.000

End of Interval (ET) -------------------------------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) -------------------------------2003 JUL 09 00:15:00.000
Non-Toolkit Applications

End of Interval (ET) -------------------------------2004 JAN 04 04:25:42.557 10

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

N IF
$ brief mer2_crus_sim_id.bsp

DAFMOD Example: SPK

Navigation and Ancillary Information Facility Terminal Window

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

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 $ 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

-74900

MARSIAU

Non-Toolkit Applications

N IF

SPY
Navigation and Ancillary Information Facility

Spy is a command-line utility for validating, inspecting, and analyzing SPK files Spy can:
Dump SPK file contents Data Summary information Comment area Bookkeeping information Sample data from a set of loaded kernels Sample position, distance, velocity, derived velocity, speed, acceleration, acceleration magnitude, osculating elements Check SPK files Validate SPK structure Check sampled data for bounds violations Locate invalid double precision numbers 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

N IF
Operating modes Auxiliary files

SPY: Selected Features

Navigation and Ancillary Information Facility

Interactive, batch, shell command line 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
15

Online help: command language summary

Non-Toolkit Applications

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 Velocity Velocity Accel. X, X, X, X, Y, Y, Y, Y, Z Z Z Z (km) (km/s) (km/s) (km/s^2) 1.00103333E+03 1.00703333E+03 2.00103333E+03 2.00703333E+03 1.00203333E+03 1.00803333E+03 2.00203333E+03 2.00803333E+03 1.00303333E+03 1.00903333E+03 2.00303333E+03 2.00903333E+03 1.00403333E+03 1.01003333E+03 2.00403333E+03 2.01003333E+03 1.00503333E+03 1.01103333E+03 2.00503333E+03 2.01103333E+03 1.00603333E+03 1.01203333E+03 2.00603333E+03 2.01203333E+03

1 2

2000-JAN-01 12:00:10.000000 (TDB) 2000-JAN-01 12:00:20.000000 (TDB)

Non-Toolkit Applications

PREDICKT
Navigation and Ancillary Information Facility

prediCkt is a program for making CK files from a set of orientation specification rules and schedules defining when these rules are to be applied
has a simple command line interface requires orientation and schedule specification to be provided in a setup file that follows the SPICE text kernel syntax requires all supporting kernels -- SPK, PCK, etc -- to be loaded using a meta kernel for more details see Making CK Tutorial

Non-Toolkit Applications

N IF

CKSLICER
Navigation and Ancillary Information Facility

ckslicer is a program for subsetting a CK file ckslicer is a command line program with 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 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

N IF
$ dir mgs_sc_ab1_v2.bc -rw-rw-r-1 naifuser

CKSLICER Example
Navigation and Ancillary Information Facility Terminal Window
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-rw1 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

N IF

CKSPANIT
Navigation and Ancillary Information Facility

ckspanit is a 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 is a command line program with 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

CAUTION: before running ckspanit, make sure that interpolation over larger gaps is appropriate for the vehicle or structure you are dealing with. And dont forget to add appropriate comments to the newly created CK file.
Non-Toolkit Applications

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

N IF

CKSMRG
Navigation and Ancillary Information Facility

CAUTION: cksmrg should not be used to merge CKs from different sources, nor should it be used to merge overlapping predict CKs
Non-Toolkit Applications

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

N IF

MAKCLK
Navigation and Ancillary Information Facility

makclk is a program for converting a SCLKSCET file to an SCLK kernel

SCLKSCET 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 Users Guide provides detailed information about the setup file parameters and the SCLKSCET file format and contents.

Non-Toolkit Applications

N IF
$ more makclk.setup SCLKSCET_FILE OLD_SCLK_KERNEL FILE_NAME NAIF_SPACECRAFT_ID LEAPSECONDS_FILE PARTITION_TOLERANCE LOG_FILE = = = = = = =

MAKCLK Example
Navigation and Ancillary Information Facility Terminal Window
flc_sclkscet.00007 flc_template.tsc flc_sclkscet.00007.tsc -77 naif0009.tls 10 flc_sclkscet.00007.log

$ more flc_sclkscet.00007 (... SCLKSCET SFDU header ...) CCSD3RE00000$$scet$$NJPL3IS00613$$data$$ *____SCLK0_____ ________SCET0________ 0.000 2000-001T11:58:55.816 189345665.000 2006-001T00:00:00.816 189345666.000 2006-001T00:00:00.817 268620868.000 2008-188T12:53:23.211 276588129.000 2008-280T18:00:53.314 281552200.000 2008-338T04:55:23.270 284040077.000 2009-001T00:00:00.341 284040078.000 2009-001T00:00:00.342 287261113.000 2009-038T06:43:55.535 291848718.000 2009-091T09:04:01.136 CCSD3RE00000$$data$$CCSD3RE00000$$sclk$$
Non-Toolkit Applications

_DUT__ __SCLKRATE__ 64.184 1.000000000 64.184 0.000010000 65.184 1.000000000 65.184 0.999998631 65.184 0.999999788 65.184 1.000000029 65.184 0.000010000 66.184 1.000000029 66.184 1.000000131 66.184 1.000000166

N IF

MAKCLK Example (continued)

Navigation and Ancillary Information Facility Terminal Window

$ more flc_template.tsc KPL/SCLK \begindata SCLK_KERNEL_ID SCLK_DATA_TYPE_77 SCLK01_TIME_SYSTEM_77 SCLK01_N_FIELDS_77 SCLK01_MODULI_77 SCLK01_OFFSETS_77 SCLK01_OUTPUT_DELIM_77 SCLK_PARTITION_START_77 SCLK_PARTITION_END_77 SCLK01_COEFFICIENTS_77 \begintext

= = = = = = = = = =

( ( ( ( ( ( ( ( ( (

@2009-04-07/12:00 ) 1 ) 2 ) 2 ) 4294967296 256 ) 0 0 ) 1 ) 0.0000000000000E+00 ) 1.0995116277750E+12 ) 0.E+00 0.E+00 1.E+00 )

$ makclk ..... Enter the name of the command file > flc_sclkscet.00007.setup flc_sclkscet.00007.tsc created. $
Non-Toolkit Applications

N IF

ORBNUM
Navigation and Ancillary Information Facility

orbnum is a program for generating a SPICE orbit number file containing orbit start/stop times and orbit numbers 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 positions Z-coordinate, or min or max value of the s/c 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

If -pref, -num or -file have not been provided, the program will prompt for them If -d is not specified the program will prompt for the time span within which the search for orbit events is to be performed
Non-Toolkit Applications

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

N IF

OPTIKS
Navigation and Ancillary Information Facility

optiks is a utility 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 a command line program 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 two 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
Non-Toolkit Applications

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 ------------CASSINI_ISS_NAC CASSINI_ISS_NAC_RAD CASSINI_ISS_WAC CASSINI_ISS_WAC_RAD Shape ----RECTANGULAR CIRCULAR RECTANGULAR CIRCULAR Length -----+0.006108652382 +3.141592653590 +0.060737457969 +3.141592653590 Width ----+0.006108652382 +3.141592653590 +0.060737457969 +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, CASSINI_ISS_NAC_RAD ( +1.000000000000, -0.000000000000, CASSINI_ISS_WAC ( +0.001218344236, -0.999999225446, CASSINI_ISS_WAC_RAD ( +1.000000000000, -0.000000000000,
Non-Toolkit Applications

-0.000170972424 +0.000000000000 +0.000254451360 +0.000000000000

) ) ) ) 32

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, FK

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

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

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

N IF
$ bff mer2_surf_rover.bsp BIG-IEEE

BFF Examples
Navigation and Ancillary Information Facility Terminal Window

$ 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

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 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

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

N IF
Navigation and Ancillary Information Facility

SPICE Toolkit Common Problems

July 2013

N IF

Topics
Navigation and Ancillary Information Facility

Prevention The Common Problems Required Reading document Reporting a Problem to NAIF

Common Problems

N IF

Prevention - 1
Navigation and Ancillary Information Facility

Get well setup to use SPICE

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 relinking your application to the latest Toolkit

Read the pertinent documentation Tutorials, module headers, Required Reading technical reference documents, comments inside kernels Get the correct (usually latest) kernel files Verify that coverage and intended use are suitable 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, if needed, is one solution.
continued on next page Common Problems

N IF

Prevention - 2
Navigation and Ancillary Information Facility

Avoid common programming problems

Verify use of the correct time system for your need e.g., TDB, 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? e.g. which version of the IAU_Mars body-fixed frame? Check definitions of geometric quantities Geodetic versus latitudinal coordinates Oblate versus spherical body shapes Check aberration corrections Converged Newtonian light time + stellar aberration, light time + stellar aberration, light time only, or none? Target orientation corrected for light time? Dont confuse an instrument reference frame ID with the ID of the instrument itself (the object ID)
Common Problems

N IF

Useful Documentation
Navigation and Ancillary Information Facility

NAIF has compiled a list of common problems, probable causes, and solutions encountered by users of the various SPICE Toolkits:
Refer to /doc/html/req/problems.html or doc/req/PROBLEMS.REQ, both of which are provided in each Toolkit package.

Some tutorials (e.g. SPK and CK) contain a section near the end describing common problems. 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

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. At a minimum 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 youre using. The name and version of the compiler or programming environment (IDL, Matlab). The Toolkit version you are using, i.e. N0064 (also called N64). Names of the kernel files being used. You may need to provide the kernels themselves if these are not available to NAIF. Your inputs to SPICE modules that signaled the error. If possible, a code fragment from where the error seems to occur.

Send the email to anyone on the NAIF team.

Common Problems

N IF
Navigation and Ancillary Information Facility

Obtaining SPICE Components Offered by NAIF and Horizons

Emphasis on Kernels

July 2013

N IF

Overview
Navigation and Ancillary Information Facility

Many SPICE products are available from the NAIF server

These are mostly products produced at JPL by NAIF Access is available using the http or ftp 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 As a general rule, NAIF has no cognizance of these products

Navigation and Ancillary Information Facility

1 - Select the mission class of interest

2a - Select the project name to get access to the kernels folder for that project. (see next page)

- or -

Navigation and Ancillary Information Facility

Use GNUs wget or FileZilla or a similar utility to download the complete SPICE data set
Possible wget usage, and an example using Deep Impact wget -m -nH --cut-dirs=5 -nv (insert the URL of the "Volume FTP Link" for the SPICE data set here). For example:
wget -m -nH --cut-dirs=5 -nv ftp://naif.jpl.nasa.gov/pub/naif/pds/data/di-c-spice-6-v1.0/
disp_1000/

FileZilla info http://filezilla-project.org/client_features.php

N IF

Horizons
Navigation and Ancillary Information Facility

Horizons is an on-line ephemeris generator for natural bodies (and more)

Operated by JPLs Solar System Dynamics Group

Of primary interest to SPICE users is its ability to generate up-to-date SPK files for comets and asteroids
Horizons home: http://ssd.jpl.nasa.gov/?horizons Horizons web interface for manual generation of small bodies SPKs: http://ssd.jpl.nasa.gov/x/spk.html Horizons telnet interface for automated (programmatic) generation of small body SPKs: telnet ssd.jpl.nasa.gov 6775 For example script look at:
ftp://ssd.jpl.nasa.gov/pub/ssd/smb_spk
11

N IF
Navigation and Ancillary Information Facility

Summary of Key Points

July 2013

N IF

Which Pieces of SPICE Must I Use?

Navigation and Ancillary Information Facility

Theres not a simple answer

Depends on what mission you are working on Depends on what computation(s) you wish to make

Dont feel overwhelmed

Many 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

N IF
SPK: PCK:

Reminder of Key Subsystems

Navigation and Ancillary Information Facility

Position (and velocity) of things Size/shape/orientation of target bodies

For binary PCKs, only orientation is provided; use a text PCK to obtain size/shape

IK: Instrument field-of-view geometry (see also FK below) CK: Orientation of spacecraft or spacecraft structures that move FK: Definition and specification details for many reference frames, including instrument mounting alignments LSK: Time conversion: UTC (SCET) ET (TDB) SCLK and LSK: Time conversion: SCLK ET (TDB) DSK*: Tessellated plate shape model; digital elevation shape model
* DSK is under development; some test code is available

Summary of Key Points

N IF

Primary Kernel Interfaces - 1

Navigation and Ancillary Information Facility

Which SPICE modules are most commonly called to use data obtained from a given kernel type?
SPK
SPKEZR, SPKPOS, SPKCOV, SPKOBJ SXFORM, PXFORM, SPKEZR, SPKPOS, BODVRD

SXFORM, PXFORM, SPKEZR, SPKPOS STR2ET, TIMOUT, SCE2C, SCT2E, SCE2S, SCS2E SCS2E, SCE2S SXFORM, PXFORM, SPKEZR, SPKPOS

PCK

LSK

GETFOV, G*POOL

SCLK

SXFORM, PXFORM SPKEZR, SPKPOS, CKCOV, CKOBJ

(CKGPAV, CKGP)

DSK

Many: read the DSK documentation

* DSK is under development; some test code is available

Summary of Key Points

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)

N IF

Primary Kernel Interfaces - 2

Navigation and Ancillary Information Facility

For a given high-level module, which kind(s) of kernel(s) will or may be needed?
Module Name
SPKEZR, SPKPOS SXFORM, PXFORM CKGP, CKGPAV GETFOV G*POOL STR2ET, TIMOUT SCS2E, SCE2S CHRONOS (time conversion app.)

SPK Y M

Kernel Type(s) Needed PCK IK CK FK LSK M M M Y M M Y Y M M Y M L M L M L

SCLK M M L

Y M

Summary of Key Points

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

N IF

How Can I Understand How To Use Those Modules?

Navigation and Ancillary Information Facility

The primary user-oriented documentation about each module is found in the header located at the top of each source code file and in the modules HTML page in the API reference guide.
(More documentation is found at the additional entry points for those FORTRAN modules 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. See SPICE Documentation Taxonomy in the tutorials collection for additional reading suggestions.

Summary of Key Points

N IF

Does NAIF Provide Any Examples?

Navigation and Ancillary Information Facility

Nearly all module headers contain one or more working examples Most Useful SPICELIB Subroutines has code fragments /doc/html/info/mostused.html The required reading reference documents often contain examples /doc/html/req/index.html Some simple cookbook programs are found in the Toolkit /src/cookbook/ Make use of the SPICE Programming Lessons available from the NAIF server
ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/
Summary of Key Points

N IF
Navigation and Ancillary Information Facility

Writing an Icy (IDL) Based Program

July 2013

N IF

Viewing This Tutorial

Navigation and Ancillary Information Facility

Undefined variables are displayed in red Results are displayed in blue

Writing an Icy-based program

N IF

Introduction
Navigation and Ancillary Information Facility

First, let's go over the important steps in the process of writing a 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. Formulate an algorithm to compute the quantities of interest using SPICE. 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

N IF

Observation geometry
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

We want the boresight intercept on the surface, range from s/c to intercept, and illumination angles at the intercept point.

instrument fram e

inertial frame

When? TIME (UTC, TDB or TT) On what object? satnm In what frame? fixref
body-fixed frame sp acecraft frame spacecraft position

surface normal

instrument boresight

emission angle solar incidence angle

Phase angle

surface intersection

For which instrument? instnm For what spacecraft? scnm Using what model? setupf
Writing an Icy-based program

planetocentric longitude

planetocentric latitude

N IF

Needed Data
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

Time transformation kernels Orientation models Instrument descriptions Shapes of satellites, planets Ephemerides for spacecraft, Saturn barycenter and satellites.
Writing an Icy-based program
sp acecraft frame

instrument frame

inertial frame

instrument boresight emission angle surface normal spacecraft position

phase angle solar incidence angle

surface intersection

body-fixed frame planetocentric longitude

planetocentric latitude

sun

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 ----------------------time conversions satellite orientation satellite shape satellite position planet barycenter position spacecraft position spacecraft orientation instrument alignment instrument boresight

Kernel Type -------------generic LSK CASSINI SCLK CASSINI PCK CASSINI PCK planet/sat ephemeris SPK planet SPK spacecraft SPK spacecraft CK CASSINI FK Instrument IK

File name -----------naif0009.tls cas00084.tsc cpck05Mar2004.tpc 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

Writing an Icy-based program

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

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

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 satellites 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

N IF

Compute Lat/Lon and Illumination Angles

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, read, read, read, read, satnm , fixref, scnm , instnm, time , PROMPT='Enter PROMPT='Enter PROMPT='Enter PROMPT='Enter PROMPT='Enter satellite name satellite frame spacecraft name instrument name 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_bodn2c, instnm, instid, found cspice_getfov, instid, ROOM, shape, iframe, insite, bundry

Writing an Icy-based program

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

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 ABCORR ROOM setupf satnm fixref scnm instnm time R2D = = = = = = = = = CN+S' 10L '' '' '' '' '' '' cspice_dpr()

Writing an Icy-based program

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_bodn2c, instnm, instid, found if ( NOT found ) then begin print, "Unable to determine ID for instrument: ", instnm return endif cspice_getfov, instid, ROOM, shape, iframe, insite, bundry

Writing an Icy-based program

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

N IF
print, print, print, print, print, print,

Complete source code -4

Navigation and Ancillary Information Facility (deg): ', $ R2D*pclat 'Intercept planetodetic longitude (deg): ', $ R2D*pdlon 'Intercept planetodetic latitude (deg): ', $ R2D*pdlat 'Range from spacecraft to intercept point (km): ', $ cspice_vnorm(srfvec) 'Intercept phase angle (deg): ', $ R2D*phase 'Intercept solar incidence angle (deg): ', $ R2D*solar 'Intercept emission angle (deg): ', $ R2D*emissn

print, 'Intercept planetocentric latitude

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

N IF

Compile the program

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

N IF
IDL>

Compile and link the program - 2

Navigation and Ancillary Information Facility Terminal Window

.compile prog_geometry.pro

% Compiled module: PROG_GEOMETRY.

Writing an Icy-based program

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

N IF
IDL> Enter Enter Enter Enter Enter Enter

Running the program

Navigation and Ancillary Information Facility Terminal Window

prog_geometry setup file name satellite name satellite frame spacecraft name instrument name time

> > > > > >

setup.ker PHOEBE IAU_PHOEBE CASSINI CASSINI_ISS_NAC 2004 jun 11 19:32:00 39.843719 4.1958778 39.843719 5.0480106 2089.1697 28.139479 18.247220 17.858309

Intercept planetocentric longitude (deg): Intercept planetocentric latitude (deg): Intercept planetodetic longitude (deg): Intercept planetodetic latitude (deg): Range from spacecraft to intercept point (km): Intercept phase angle (deg): Intercept solar incidence angle (deg): Intercept emission angle (deg):

Writing an Icy-based program

N IF
Latitude definitions:

Backup
Navigation and Ancillary Information Facility

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 latitude Planetodetic latitude

O
Writing an Icy-based program

x-y plane
24

N IF
Navigation and Ancillary Information Facility

Writing an Mice (MATLAB) Based Program

July 2013

N IF

Viewing This Tutorial

Navigation and Ancillary Information Facility

Undefined variables are displayed in red Results are displayed in blue

Writing a Mice-based program

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. Formulate an algorithm to compute the quantities of interest using SPICE. 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 Mice-based program

N IF

Observation geometry
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

We want the boresight intercept on the surface, range from s/c to intercept, and illumination angles at the intercept point.

instrument fram e

inertial frame

When? TIME (UTC, TDB or TT) On what object? satnm In what frame? fixref
body-fixed frame sp acecraft frame spacecraft position

surface normal

instrument boresight

emission angle solar incidence angle

Phase angle

surface intersection

For which instrument? instnm For what spacecraft? scnm Using what model? setupf
Writing a Mice-based program

planetocentric longitude

planetocentric latitude

N IF

Needed Data
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

instrument frame

inertial frame

instrument boresight emission angle surface normal spacecraft position

Phase angle solar incidence angle

surface intersection

body-fixed frame planetocentric longitude

planetocentric latitude

N IF

Which Kernels are Needed?

Navigation and Ancillary Information Facility

Kernel Type -------------generic LSK CASSINI SCLK CASSINI PCK CASSINI PCK planet/sat ephemeris SPK planet SPK spacecraft SPK spacecraft CK CASSINI FK Instrument IK

Writing a Mice-based program

N IF

Load kernels
Navigation and Ancillary Information Facility

\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

= = = = =

input( input( input( input( input(

'Enter 'Enter 'Enter 'Enter 'Enter

satellite name satellite frame spacecraft name instrument name time

> > > > >

', ', ', ', ',

's'); 's'); 's'); 's'); 's');

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 satellites 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:
[instid, found] = cspice_bodn2c( instnm ); if ( ~found ) txt = sprintf( 'Unable to determine ID for instrument: %d', ... instnm ); error(txt) end [shape, iframe, insite, bundry] = cspice_getfov( instid, ROOM );
Writing a Mice-based program

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. [instid, found] = cspice_bodn2c( instnm ); if ( ~found ) txt = sprintf( 'Unable to determine ID for instrument: %d', ... instnm ); error(txt) end [shape, iframe, insite, bundry] = cspice_getfov( instid, ROOM );
Writing a Mice-based program

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', 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

... ... ... ... ... ... ... ...

Writing a Mice-based program

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

ABCORR = 'CN+S'; 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 fixref scnm instnm time
Writing a Mice-based program

= = = = =

input( input( input( input( input(

'Enter 'Enter 'Enter 'Enter 'Enter

satellite name satellite frame spacecraft name instrument name time

> > > > >

', ', ', ', ',

's'); 's'); 's'); 's'); 's');

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. [instid, found] = cspice_bodn2c( instnm ); if ( ~found ) txt = sprintf( 'Unable to determine ID for instrument: %d', ... instnm ); error(txt) end [shape, iframe, insite, bundry] = cspice_getfov( instid, ROOM );

Writing a Mice-based program

N IF

Complete source code - 2

Navigation and Ancillary Information Facility

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

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

N IF

Running the program

Navigation and Ancillary Information Facility Terminal Window

>> prog_geometry Enter setup file name Enter satellite name Enter satellite frame Enter spacecraft name Enter instrument name Enter time

> > > > > >

setup.ker PHOEBE IAU_PHOEBE CASSINI CASSINI_ISS_NAC 2004 jun 11 19:32:00 39.843719 4.195878 39.843719 5.048011 2089.169724 28.139479 18.247220 17.858309

Writing a Mice-based program

N IF
Latitude definitions:

Backup
Navigation and Ancillary Information Facility

P N
z-axis

Reference ellipsoid
Planetocentric latitude Planetodetic latitude

O
Writing a Mice-based program

x-y plane
22

N IF
Navigation and Ancillary Information Facility

Writing a CSPICE (C) Based Program

July 2013

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

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. Formulate an algorithm to compute the quantities of interest using SPICE. 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 and from spacecraft to target center. Illumination angles (phase, solar incidence, and emission) at the intercept point.

Writing a CSPICE-based program

N IF

Observation geometry
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

We want the boresight intercept on the surface, range from s/c to intercept, and illumination angles at the intercept point.

instrument fram e

inertial frame

When? TIME (UTC, TDB or TT) On what object? satnm In what frame? fixref
body-fixed frame sp acecraft frame spacecraft position

surface normal

instrument boresight

emission angle solar incidence angle

Phase angle

surface intersection

For which instrument? instnm For what spacecraft? scnm Using what model? setupf
Writing a CSPICE-based program

planetocentric longitude

planetocentric latitude

N IF

Needed Data
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

instrument frame

inertial frame

instrument boresight emission angle surface normal spacecraft position

phase angle solar incidence angle

surface intersection

body-fixed frame planetocentric longitude

planetocentric latitude

sun

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 satellites 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 boolean 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

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

N IF

Geometry Calculations: Summary

Navigation and Ancillary Information Facility */

/* Compute the boresight ray intersection with the surface of the satellite. 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 { ...

}
11

Writing a CSPICE-based program

N IF

Get Inputs - 1
Navigation and Ancillary Information Facility

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 prompt_c prompt_c prompt_c prompt_c
Writing a CSPICE-based program

( ( ( ( (

"Enter "Enter "Enter "Enter "Enter

satellite name satellite frame spacecraft name instrument name time

> > > > >

", ", ", ", ",

WORDSZ, WORDSZ, WORDSZ, WORDSZ, WORDSZ,

satnm fixref scnm instnm time

); ); ); ); );
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 satellites 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:
bodn2c_c ( instnm, &instid, &found ); if ( !found ) { setmsg_c ( "Instrument name # could not be " "translated to an ID code." ); errch_c ( "#", instnm ); sigerr_c ( "NAMENOTFOUND" ); } getfov_c ( instid, ROOM, WORDSZ, WORDSZ, shape, iframe, insite, &n, bundry );
Writing a CSPICE-based program

N IF
/* Prompt for prompt_c ( furnsh_c ( prompt_c ( prompt_c ( prompt_c ( prompt_c ( prompt_c (

Getting Inputs: Summary

Navigation and Ancillary Information Facility the user-supplied inputs "Enter setup file name > setupf ); "Enter satellite name > "Enter satellite frame > "Enter spacecraft name > "Enter instrument name > "Enter time > for our program */ ", FILESZ, setupf ); ", ", ", ", ", WORDSZ, WORDSZ, WORDSZ, WORDSZ, WORDSZ, satnm fixref scnm instnm 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. */

bodn2c_c ( instnm, &instid, &found ); if ( !found ) { setmsg_c ( "Instrument name # could not be " "translated to an ID code." ); errch_c ( "#", instnm ); sigerr_c ( "NAMENOTFOUND" ); } getfov_c ( instid, ROOM, WORDSZ, WORDSZ, shape, iframe, insite, &n, bundry );
Writing a CSPICE-based program

N IF

Display Results
for output. */ %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n",

Navigation and Ancillary Information Facility /* Display results. Convert angles from radians to degrees printf ( "\n" "Intercept planetocentric longitude (deg): "Intercept planetocentric latitude (deg): "Intercept planetodetic longitude (deg): "Intercept planetodetic latitude (deg): "Range from spacecraft to intercept point (km): "Intercept phase angle (deg): "Intercept solar incidence angle (deg): "Intercept emission angle (deg): 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

);

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

N IF

Complete Source Code - 1

Navigation and Ancillary Information Facility SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceDouble SpiceInt SpiceInt SpiceInt alt; bundry[ROOM][3]; emissn; et; f; insite[3]; srfvec[3]; pclat; pclon; pdlat; pdlon; phase; point [3]; r; radii [3]; re; rp; solar; trgepc; i; instid; n;
17

#include <stdio.h> #include "SpiceUsr.h" int main () { #define #define #define FILESZ WORDSZ ROOM 256 41 10

SpiceBoolean SpiceChar SpiceChar SpiceChar SpiceChar SpiceChar SpiceChar SpiceChar SpiceChar

found; iframe[WORDSZ]; instnm[WORDSZ]; satnm [WORDSZ]; fixref[WORDSZ]; scnm [WORDSZ]; setupf[FILESZ]; shape [WORDSZ]; time [WORDSZ];

Writing a CSPICE-based program

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. */ bodn2c_c ( instnm, &instid, &found ); if ( !found ) { setmsg_c ( "Instrument name # could not be " "translated to an ID code." ); errch_c ( "#", instnm ); sigerr_c ( "NAMENOTFOUND" ); } getfov_c ( instid, ROOM, WORDSZ, WORDSZ, shape, iframe, insite, &n, bundry );
Writing a CSPICE-based program

N IF

Complete Source Code - 3

Navigation and Ancillary Information Facility */

/* Compute the boresight ray intersection with the surface of the satellite. 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

N IF

Complete Source Code - 4

Navigation and Ancillary Information Facility "Intercept planetodetic longitude (deg): "Intercept planetodetic latitude (deg): "Range from spacecraft to intercept point (km): "Intercept phase angle (deg): "Intercept solar incidence angle (deg): "Intercept emission angle (deg): dpr_c() * pclon, dpr_c() * pclat, dpr_c() * pdlon, dpr_c() * pdlat, vnorm_c( srfvec ), dpr_c() * phase, dpr_c() * solar, dpr_c() * emissn %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n" %11.6f\n",

); } else { printf ( "No intercept point found at %s\n", time ); } return(0); }

Writing a CSPICE-based program

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 you 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

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

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

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

N IF

Running the Program - 2

Navigation and Ancillary Information Facility Terminal Window

Prompt> demo Enter setup file name Enter satellite name Enter satellite frame Enter spacecraft name Enter instrument name Enter time

> > > > > >

setup.ker PHOEBE IAU_PHOEBE CASSINI CASSINI_ISS_NAC 2004 jun 11 19:32:00 39.843719 4.195878 39.843719 5.048011 2089.169724 28.139479 18.247220 17.858309

Writing a CSPICE-based program

N IF
Latitude definitions:

Backup
Navigation and Ancillary Information Facility

P N
z-axis

Reference ellipsoid
Planetocentric latitude Planetodetic latitude

O
Writing a CSPICE-based program

x-y plane
26

N IF
Navigation and Ancillary Information Facility

Writing a SPICE (FORTRAN) Based Program

July 2013

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

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. Formulate an algorithm to compute the quantities of interest using SPICE. 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 and from spacecraft to target center. Illumination angles (phase, solar incidence, and emission) at the intercept point.

Writing a FORTRAN-based program

N IF

Observation geometry
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

We want the boresight intercept on the surface, range from s/c to intercept, and illumination angles at the intercept point.

instrument fram e

inertial frame

When? TIME (UTC, TDB or TT) On what object? SATNM In what frame? FIXREF
body-fixed frame sp acecraft frame spacecraft position

surface normal

instrument boresight

emission angle solar incidence angle

Phase angle

surface intersection

For which instrument? INSTNM For what spacecraft? SCNM Using what model? SETUPF
Writing a FORTRAN-based program

planetocentric longitude

planetocentric latitude

N IF

Needed Data
Navigation and Ancillary Information Facility
on-bo ard clock ephemeris time UTC time

instrument frame

inertial frame

instrument boresight emission angle surface normal spacecraft position

Phase angle solar incidence angle

surface intersection

body-fixed frame planetocentric longitude

planetocentric latitude

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 satellites 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

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 C 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 CALL RECGEO ( POINT, RE, F, PDLON, PDLAT, ALT )

The illumination angles we want are the outputs of ILLUM. Units are radians.
CALL ILUMIN ( 'Ellipsoid', SATNM, ET, FIXREF, . 'CN+S', SCNM, POINT, TRGEPC, SRFVEC, . PHASE, SOLAR, EMISSN )

Writing a FORTRAN-based program

N IF
C C

Geometry Calculations: Summary

Navigation and Ancillary Information Facility

Compute the boresight ray intersection with the surface of the satellite. CALL SINCPT ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM, IFRAME, . INSITE, POINT, TRGEPC, SRFVEC, FOUND )

C C

If an intercept is found, compute planetocentric and planetodetic latitude and longitude of the point. IF( FOUND ) THEN

C C

CALL RECLAT ( POINT, R, PCLON, PCLAT ) 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 CALL RECGEO ( POINT, RE, F, PDLON, PDLAT, ALT ) 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

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 CALL CALL CALL CALL PROMPT PROMPT PROMPT PROMPT PROMPT ( ( ( ( ( 'Enter 'Enter 'Enter 'Enter 'Enter satellite name satellite frame spacecraft name instrument name time > > > > > ', ', ', ', ', SATNM FIXREF SCNM INSTNM TIME ) ) ) ) )
12

Writing a FORTRAN-based program

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 satellites 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 BODN2C ( INSTNM, INSTID, FOUND ) IF ( .NOT. FOUND ) THEN CALL SETMSG ( 'Instrument name # could not be ' // . 'translated to an ID code.' ) CALL ERRCH ( '#', INSTNM ) CALL SIGERR ( 'NAMENOTFOUND' ) END IF CALL GETFOV ( INSTID, ROOM, SHAPE, . INSITE, N, BUNDRY
Writing a FORTRAN-based program

IFRAME, )
13

N IF
C

Getting Inputs: Summary

Navigation and Ancillary Information Facility

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 ) Get the epoch corresponding to the input time: CALL STR2ET ( TIME, ET ) Get the radii of the satellite. CALL BODVRD ( SATNM, 'RADII', 3, I, RADII ) Get the instrument boresight and frame name. CALL BODN2C ( INSTNM, INSTID, FOUND ) IF ( .NOT. FOUND ) THEN CALL SETMSG ( 'Instrument name # could not be ' // . 'translated to an ID code.' ) CALL ERRCH ( '#', INSTNM ) CALL SIGERR ( 'NAMENOTFOUND' ) END IF CALL GETFOV ( INSTID, ROOM, SHAPE, IFRAME, . INSITE, N, BUNDRY )
14

C C C

Writing a FORTRAN-based program

N IF
C C . . . . . . . . . .

Display Results
Navigation and Ancillary Information Facility degrees

Display results. Convert angles from radians to for output. WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetocentric longitude (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetocentric latitude (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetodetic longitude (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetodetic latitude (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Range from spacecraft to intercept point (km): VNORM(SRFVEC) WRITE ( *, '(1X,A,F12.6)' ) 'Intercept phase angle (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept solar incidence angle (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept emission angle (deg): DPR()*EMISSN

', ', ', ', ', ', ', ',

DPR()PCLON DPR()PCLAT DPR()PDLON DPR()PDLAT

DPR()*PHASE DPR()*SOLAR

ELSE WRITE (*,*) 'No intercept point found at '// TIME END IF
Writing a FORTRAN-based program

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

N IF
PROGRAM PROG26 IMPLICIT NONE DOUBLE PRECISION DOUBLE PRECISION INTEGER PARAMETER INTEGER PARAMETER INTEGER PARAMETER

Complete Source Code - 1

Navigation and Ancillary Information Facility DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE DOUBLE PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION PRECISION EMISSN ET F INSITE(3) SRFVEC(3) PCLAT PCLON PDLAT PDLON PHASE POINT (3) R RADII (3) RE RP SOLAR TRGEPC I INSTID N FOUND
17

DPR VNORM FILESZ ( FILESZ = WORDSZ ( WORDSZ = ROOM ( ROOM = IFRAME INSTNM SATNM FIXREF SCNM SETUPF SHAPE TIME ALT BUNDRY(3, ROOM)

255 ) 40 ) 10 )

CHARACTER*(WORDSZ) CHARACTER*(WORDSZ) CHARACTER*(WORDSZ) CHARACTER*(WORDSZ) CHARACTER*(WORDSZ) CHARACTER*(FILESZ) CHARACTER*(WORDSZ) CHARACTER*(WORDSZ) DOUBLE PRECISION DOUBLE PRECISION
Writing a FORTRAN-based program

INTEGER INTEGER INTEGER LOGICAL

N IF
C

Complete Source Code - 2

Navigation and Ancillary Information Facility

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 ) Get the epoch corresponding to the input time: CALL STR2ET ( TIME, ET ) Get the radii of the satellite. CALL BODVRD ( SATNM, 'RADII', 3, I, RADII ) Get the instrument boresight and frame name. CALL BODN2C ( INSTNM, INSTID, FOUND ) IF ( .NOT. FOUND ) THEN CALL SETMSG ( 'Instrument name # could not be ' // . 'translated to an ID code.' ) CALL ERRCH ( '#', INSTNM ) CALL SIGERR ( 'NAMENOTFOUND' ) END IF CALL GETFOV ( INSTID, ROOM, SHAPE, IFRAME, . INSITE, N, BUNDRY )

C C C

Writing a FORTRAN-based program

N IF
C C

Complete Source Code - 3

Navigation and Ancillary Information Facility

Compute the boresight ray intersection with the surface of the satellite. CALL SINCPT ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM, IFRAME, . INSITE, POINT, TRGEPC, SRFVEC, FOUND )

C C

If an intercept is found, compute planetocentric and planetodetic latitude and longitude of the point. IF( FOUND ) THEN CALL RECLAT ( POINT, R, PCLON, PCLAT ) 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 CALL RECGEO ( POINT, RE, F, PDLON, PDLAT, ALT ) Compute illumination angles at the surface point. . CALL ILUMIN ( 'Ellipsoid', SATNM, ET, FIXREF, 'CN+S', SCNM, POINT, TRGEPC, SRFVEC, PHASE, SOLAR, EMISSN ) Display results. Convert angles from radians to degrees for output. WRITE ( *, * ) WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetocentric longitude (deg): ', DPR()*PCLON
19

C C

Writing a FORTRAN-based program

N IF
. . . . . . . . .

Complete Source Code - 4

Navigation and Ancillary Information Facility

WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetocentric latitude (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetodetic longitude (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept planetodetic latitude (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Range from spacecraft to intercept point (km): VNORM(SRFVEC) WRITE ( *, '(1X,A,F12.6)' ) 'Intercept phase angle (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept solar incidence angle (deg): WRITE ( *, '(1X,A,F12.6)' ) 'Intercept emission angle (deg): DPR()*EMISSN

', ', ', ',

DPR()PCLAT DPR()PDLON DPR()*PDLAT

', ', ',

DPR()*PHASE DPR()*SOLAR

ELSE WRITE (*,*) 'No intercept point found at '// TIME END IF END

Writing a FORTRAN-based program

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

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

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

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

N IF

Running the Program - 2

Navigation and Ancillary Information Facility Terminal Window

Prompt> demo Enter setup file name Enter satellite name Enter satellite frame Enter spacecraft name Enter instrument name Enter time

> > > > > >

setup.ker PHOEBE IAU_PHOEBE CASSINI CASSINI_ISS_NAC 2004 jun 11 19:32:00 39.843719 4.195878 39.843719 5.048011 2089.169724 28.139479 18.247220 17.858309

Writing a FORTRAN-based program

N IF
Latitude definitions:

Backup
Navigation and Ancillary Information Facility

P N
z-axis

Reference ellipsoid
Planetocentric latitude Planetodetic latitude

O
Writing a FORTRAN-based program

x-y plane
26

N IF
Navigation and Ancillary Information Facility

Making an SPK File

July 2013

N IF

Table of Contents
Navigation and Ancillary Information Facility

Purpose Scope Assumptions about users 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 (subroutines) Adding comments Validation Merging

Finishing up, applicable to all methods

Special requirements for making SPKs to be used in DSN/SPS software for view period generation, scheduling, metric predicts generation, and related functions.
Applies only to those entities not making JPL NAV-style p-files
2

Making an SPK File

Issues affecting performance (reading efficiency) and usability

N IF

Making an SPK tutorial (this document) SPK (Ephemeris System) tutorial (focused on reading an SPK) SPK Required Reading (spk.req) MKSPK Users Guide (mkspk.ug) The source code headers provided as part of the SPK writer modules (subroutines) SPKMERGE Users Guide (spkmerge.ug) SPY Users Guide (spy.ug)

Making an SPK File

N IF

Brief Overview - 1
Navigation and Ancillary Information Facility

Understand the physics of your data and how that relates to SPK type. For instance:
Type 5 implies 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

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. 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 Toolkits 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

N IF
Navigation and Ancillary Information Facility

Summary of SPK Architecture

Making an SPK File

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

Segment n
Possibly present
- sometimes by choice - sometimes required

Making an SPK File

N IF
ID WORD ND NI

SPK File Structure - 1

Navigation and Ancillary Information Facility

A minimal SPK file, containing only one segment

Records are fixed-length: 1024 bytes IFNAME FWD BWD FREE BFF 0 PAD FTP 0 PAD
File record: One record. Comment area: Present only if used. If used, one or more records. Descriptor record: Contains 1 to 25 segment descriptors. One record. Segment ID record: Contains 1 to 25 segment IDs. One record. Data segment: One or more records.

Comment area text

N/P/C

D1 U U

Segment 1

ID WORD: Indicates file architecture and type ND, NI: Number of d.p. and integer descriptor components IFNAME: Internal file name FWD, BWD: Forward and backward linked list pointers FREE: First free DAF address BFF: Binary file format ID FTP: FTP corruption test string

N/P/C: Next, previous record pointers and descriptor count Dn: Descriptor for segment n In: Segment ID for segment n U: Unused space U*: Possibly unused space

Making an SPK File

N IF
ID WORD ND NI

SPK File Structure - 2

Navigation and Ancillary Information Facility

An SPK file containing 27 segments

Records are fixed-length: 1024 bytes IFNAME FWD BWD FREE BFF 0 PAD FTP 0 PAD
File record: One record Comment area: Always present but could be empty. One or more records. Descriptor record: Contains 1 to 25 segment descriptors. One record. Segment ID record: Contains 1 to 25 segment IDs. One or more records.

Comment area text

N/P/C

D1 D2 I2

I25

D25

Segment 1 Segment 2
... ...
Data segments: One or more records per segment. (Up to 25 segments.)

Segment 25
N/P/C D26

U*
Descriptor record: Contains 1 to 25 segment descriptors. One record. Segment ID record: Contains 1 to 25 segment IDs. One or more records.

D27

I26 I27

Segment 26 Segment 27
Making an SPK File
Diagram not to scale

Data segments: One or more records per segment. (Up to 25 segments.)

U*
12

N IF
File record

SPK File Structure - Description

Navigation and Ancillary Information Facility

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 50000 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 Segments of different types may be intermixed within a given SPK file

Making an SPK File

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 (Neptunes barycenter), given in the J2000 inertial reference frame, covering a specific period of time, and using the Hermite interpolation with variable length intervals SPK type (type 13)

An SPK segment must contain enough data to yield an objects 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

N IF
Navigation and Ancillary Information Facility

Discussion applicable to all SPK production methods

Making an SPK File

N IF
Type 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

The SPK Family

Navigation and Ancillary Information Facility
Description Notes Unique form produced at JPL; not likely to be useful to others. Velocity is obtained by differentiation. Used at JPL for planets. Evaluates quickly. Separate polynomial sets for position and velocity. Used at JPL for natural satellites. Not available for general use. Ok if motion very closely approximates two-body motion. Not available for general use. Not available for general use. Use Type 9 unless state spacing is truly uniform when measured in the TDB system. Versatile type; easy to use with MKSPK. Handles both near-earth and deep space versions.

Modified divided difference arrays Chebyshev polynomials for position; fixed length time intervals. Chebyshev polynomials for position and velocity; fixed length time intervals Special form used only by Hubble Space Telescope Discreet states using weighted two-body propagation Special form of trigonometric expansion of elements for Phobos and Deimos Precessing elements Lagrange interpolation of position and velocity; fixed length intervals between states Lagrange interpolation of position and velocity; variable length intervals between states Weighted two-line element sets (Space Command) Not used Hermite interpolation; fixed length intervals between states Hermite interpolation; variable length intervals between states Chebyshev polynomials for position and velocity, variable length time intervals Precessing conic elements propagator Special form used by ESAs Infrared Space Observatory Equinoctial elements Emulation of ESOCs DDID format

Use Type 13 unless state spacing is truly uniform when measured in the TDB system. Versatile type; easy to use with MKSPK. Use for DSN support. The most flexible of the Chebyshev types.

Not available for general use. Used for some satellites. Used for SMART-1, MEX, VEX, and Rosetta

Making an SPK File

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 non-JPL ephemeris producers and by users of NAIFs 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

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

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.

For good SPK reading performance, the total number of segments for any given body in a file should be kept under the dimension of the SPKBSR segment buffer, currently set to 50,000.
More details about reading efficiency are provided at the end of this tutorial. When reading data from multiple SPK files, a more stringent limit applies: the total number of loaded segments for any body, possibly contributed by multiple files, should be less than the SPKBSR segment buffer size. For best efficiency, the total number of segments loaded should be less than this buffer size.

N IF
Navigation and Ancillary Information Facility

Using NAIFs MKSPK Application Program

Making an SPK File

N IF
Setup file ASCII file of ephemeris data Optional comment file

Using the MKSPK Utility - 1

Navigation and Ancillary Information Facility

NAIFs MKSPK Program

SPK File

Suitable kinds of input ephemeris data are: - Table of Cartesian state vectors - Table of conic elements - One or more sets of equinoctial elements - One or more sets of Space Command twoline elements

Possible SPK data types produced are: - Type 05 - Type 08 - Type 09 - Type 10 - Type 12 - Type 13 - Type 15 - Type 17
27

Making an SPK File

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 --> Input Data Type Cartesian state vectors Conic elements Equinoctial elements Space Command Two-line elements

5 Y Y N N

8 Y Y N N

9 Y Y N N

10 N N N Y

12 Y Y N N

13 Y Y N N

15 Y Y N N

17 Y Y Y N

Y = Yes

N = No

These routines could be embedded in your existing trajectory propagator program, or they could be used to build a separate conversion program analogous to MKSPK.

Making an SPK File

N IF

What Routines To Use - 1

Navigation and Ancillary Information Facility

For all except SPK type 14

SPKOPN SPKWxx . . [SPKWxx] . . SPKCLS

Open a new SPK file. (Use SPKOPA to append to existing file.) Write a segment of SPK type xx

[ Write more segments ] [ Repeat as needed ] 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, module names are case-insensitive and have "cspice_" prepended.
Making an SPK File

N IF

What Routines To Use - 2

Navigation and Ancillary Information Facility

For SPK type 14

SPKOPN, SPKOPA SPK14B SPK14A [SPK14A] SPK14E SPK14B SPK14A [SPK14A] SPK14E etc. SPKCLS
Making an SPK File

Open file to add data Begin a new segment Add data to segment Add more data End the segment Begin a new segment Add data to segment Add more data End the segment
Repeat as needed

Close the file

[ ] indicates possible multiple occurrences

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

N IF
Navigation and Ancillary Information Facility

Finishing Up

Making an SPK File

N IF

Not Quite Done Yet

Navigation and Ancillary Information Facility

Youve now used either MKSPK or the appropriate SPK writer routines to produce an SPK file. To complete the job you should consider 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 Toolkits 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

N IF

Add Comments (metadata)

Navigation and Ancillary Information Facility

It is recommended that the producer of an SPK file add to the file, in the comment area, appropriate descriptive information.
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.

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 datanot only the states placed in the SPK file. Verify a uniformly good fit on the whole time interval covered by the file.
Making an SPK File

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 Users 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.

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

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 segments.

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 50,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

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

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

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

N IF

SPK Reading: Efficiency Issues - 7

Navigation and Ancillary Information Facility

Number of loaded SPK files:

Up to 1000 SPK files may be loaded at one time by an application. The "1000" 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 1000 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 1000 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 bodies of interest.

Making an SPK File

N IF

SPK Reading: Efficiency Issues - 8

Navigation and Ancillary Information Facility

One of the easiest ways to accomplish this 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

continues on next page

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 a 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 particular approach, however.

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 and provides on request a white paper explaining differences between various quaternion styles. Making a CK File

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 uniform rotation algorithm implemented in Type 3 CK, 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, SCLK ticks or ET, as specified using the INPUT_TIME_TYPE keyword
Making a CK File

Time tags must not have embedded spaces

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 following 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

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 spec file keyword assignments specify nadir and spacecraft velocity directions for the M01 spacecraft
DIRECTION_SPECS DIRECTION_SPECS DIRECTION_SPECS DIRECTION_SPECS DIRECTION_SPECS DIRECTION_SPECS += += += += += += ( 'ToMars = POSITION OF MARS ( 'FROM M01 ( 'CORRECTION NONE' ( 'scVelocity = VELOCITY OF M01 ( 'FROM MARS ( 'CORRECTION NONE' -' ) -' ) ) -' ) -' ) )

Making a CK File

N IF

PREDICKT - Orientations
Navigation and Ancillary Information Facility

An orientation is specified by:

defining that one of the frames axes (+X,+Y,+Z,-X,-Y,-Z) points exactly along one of the defined directions defining that another of the frames 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 spec file keyword assignments specify the nominal nadir orientation for the THEMIS instrument, flown on the M01 spacecraft
ORIENTATION_NAME PRIMARY SECONDARY BASE_FRAME += += += += 'CameratoMars' '+Z = ToMars' '+Y = scVelocity' 'J2000'

Making a CK File

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 CK-SPK CK-FRAMES CK-53000ORIENTATION CK-53000START CK-53000STOP = = += += += += 53 -53 -53000 'SOLUTION TO M01_THEMIS_IR = CameratoMars' @2004-FEB-10-00:00 @2004-FEB-15-00:00

Making a CK File

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 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 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

N IF

PREDICKT - Example (1)

Navigation and Ancillary Information Facility Terminal Window

Navigation and Ancillary Information Facility

Objectives for Science Observations

Commands and Activities

Mission Operations Logs

Scientists Notebook

Logical View

Science Plan Component

Sequence Component

Notebook Component

Component View*

* As originally envisioned by NAIF

Intro to EK Subsystem

N IF
Sequence Component (ESQ)

Nominal E-kernel Implementation

Navigation and Ancillary Information Facility

Science Plan Component (ESP)

Notebook Component (ENB)

Component View

Database Kernel

DBK

Web + DBK

Implementation*

* As originally implemented by NAIF

Intro to EK Subsystem

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

This component 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

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.)

Intro to EK Subsystem

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 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

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
Not of as much interest to flight project instrument and engineering teams as the other SPICE components Their perception is that EK information could be useful to future users of a missions data, but not so much to an active flight team, and since they are already very busy they have not enough time to contribute input to an EK

Unfortunately NAIF and other kernel producers seem unlikely to produce EK components in the future

Intro to EK Subsystem

N IF
Navigation and Ancillary Information Facility

SPICE Development Plans and Possibilities

July 2013

N IF

Higher Fidelity Shape Models

Navigation and Ancillary Information Facility

Extension of the shape model subsystem

Called Digital Shape Kernel (DSK) Add two new shape model capabilities tessellated plate model, for small, irregularly shaped bodies digital elevation model to the existing tri-axial shape model found in PCK Status An alpha-test prototype of the plate model has been given to several projects and persons
Date for release of a final version has not yet been set

Work on an alpha-test of the digital elevation model is ongoing

Date for release of a final version has not yet been set

Plans and Possibilities for Further Development

N IF

WebGeocalc
Navigation and Ancillary Information Facility

NAIF is implementing a client-server GUI interface to a SPICE geometry engine All you need is a standard browserit connects to a server holding a SPICE-based geometry engine and a large set of SPICE kernels How might this be useful to you?
Check your own SPICE-based code under development Obtain a quick back-of-the-envelope calculation Diagnose geometry problems Opens SPICE capabilities to non-programmers

Version 1.0 release expected around October 2013 See next two pages for visuals
Plans and Possibilities for Further Development 3

N IF

WebGeocalc Input Page

Navigation and Ancillary Information Facility

Example: compute the angular separation of Phobos and Mars as seen from the Mars Odyssey spacecraft during the period from Mar 01 to June 01, 2011, using a 12 hour time step.

Plans and Possibilities for Further Development

N IF

WebGeocalc Results Page

Navigation and Ancillary Information Facility

Angular separation of Phobos from Mars as seen from the Odyssey spacecraft. Both numeric and graphic results are provided.

Navigation and Ancillary Information Facility

NAIF solicits suggestions from the user community.

Caution: were a small team and have a large backlog, so we cant promise any particular action.

Were interested in programmatic ideas as well as technical ones.

Should NAIF promote use of SPICE beyond NASAs planetary science program? What amount of cooperation and interoperability with foreign partners is appropriate and achievable?

Plans and Possibilities for Further Development

N IF
Navigation and Ancillary Information Facility

Shape Model Subsystem Preview (DSK)

July 2013

N IF

DSK Shape Representations

Navigation and Ancillary Information Facility

The DSK subsystem will handle two representations of shape data

Digital elevation model

Tessellated plate model

DSK supplements the tri-axial ellipsoid shape model

DSK

N IF

Digital Elevation Model

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 Elevation can be defined as height above a reference ellipsoid

Example: image created from MGS laser altimeter (MOLA) Mars DEM

DSK

N IF

Tessellated Plate Model

Navigation and Ancillary Information Facility

Surface of 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 of similar resolution in terms of storage and computational speed

DSK

Phobos

Itokowa

N IF

DSK High-level Functionality

Navigation and Ancillary Information Facility

High-level functions include, but are not limited to, the following:
Compute sub-observer point on surface and height of observer above surface Compute intercept of ray with surface Determine whether a portion of a target bodys surface is within the FOV of specified instrument at specified time. Determine occultation/transit state of a point target Compute limb and terminator location Compute Illumination angles at a specified surface point

DSK

N IF

DSK Utility Programs

Navigation and Ancillary Information Facility

Create DSK files: import other surface shape data sets into SPICE DSK format Port DSK files Provide comment area access Summarize DSK file contents Subset or merge DSK files Down sample DSK files Convert one DSK data type to another Note: DSKs cannot be read if in non-native binary format
Use BINGO or TOXFR/TOBIN to change between binary formats
DSK

N IF

DSK API Examples

Navigation and Ancillary Information Facility

Get radius at surface point (inputs are in red, outputs in blue):

CALL DSKRAD ( TARGET, LON, LAT, RADIUS ) Inputs: target body name, longitude and latitude of point of interest Output: radius (distance from target center) at surface point

Find sub-observer point on target:

CALL SUBPT ( METHOD, TARGET, ET, ABCORR, OBSRVR, SPOINT, ALT ) SUBPT is a generic, high-level API. SUBPT doesnt assume the surface is modeled by a DSK. Input METHOD indicates surface model and sub-point definition
For ellipsoids, METHOD may be set to near point or intercept For DSKs, set METHOD to DSK intercept, indicating that the sub-point is defined as the closest intersection to the observer of the observer-target center ray with the surface, and a DSK shape model is to be used. Note that SPICE should not assume DSK is to be used just because a DSK for the target body is loaded; may be too inefficient for some applications. Caller must say which model is to be used.

Other inputs: target body name, epoch, aberration correction, observer name. Outputs: sub-observer point in Cartesian coordinates, expressed in the body-fixed frame associated with the target, and altitude of the observer above the sub-point.

DSK

N IF
LAT/LON and height above ellipsoid or distance from center of frame

Writing Shape and Orientation Kernels

Navigation and Ancillary Information Facility

MKDSK Program
(SPICE Toolkit)

DSK
Digital shape kernel Digital Terrain Shape Model

Lists of plate model vertices and associated plates

MKDSK Program
(SPICE Toolkit)

Tessellated Plates Shape Model

Axes dimensions for tri-axial ellipsoid

Text editor
(Usually done by NAIF)

Triaxial Ellipsoid Shape Model

Some source of rotation state information (pole RA/DEC and prime meridian location)
DSK

Text editor
(Usually done by NAIF)
Y

PCK
Planetary constants kernel containing rotation data for the body, and possibly tri-axial shape

Orientation

N IF

Using Shape and Orientation Kernels

Navigation and Ancillary Information Facility

DSK
Digital shape kernel Digital Terrain Shape Model Pick one* shape model
Shap e

Your Application Program

Tessellated Plates Shape Model

* Sometimes the triaxial model is needed in addition to one of the other two

SPICE modules

Triaxial Ellipsoid Shape Model

PCK

Your data, as needed

SPICE modules for obtaining rotation state and shape, and then computing derived quantities

Orientation
DSK

Planetary constants kernel containing rotation data for the body, and possibly tri-axial shape

N IF
History

DSK Development Status

Navigation and Ancillary Information Facility

A partial alpha-test DSK Toolkit was released in July, 2010 Available in Fortran, C, IDL and JNI Contains support only for the tessellated plate model data type The DSK File format used in this prototype has been finalized; the format will be supported by the official SPICE Toolkit. Work on the digital elevation model portion is ongoing now

Plans
Release date of a first official version of the DSK system is TBD Possibly towards the end of calendar 2013

DSK

SPICE Documentation Taxonomy

Arranged by Category

July 2013

General Reading, including installing the SPICE Toolkit Document Name File Name Installing the SPICE Toolkit Instructions for getting the Toolkit components from NAIF's FTP server Preparing your computer for programming with SPICE Toolkit Contents New features and major changes Installing_toolkit README

Location TUTOR GETTK

Description/Comments A collection of viewgraph-style packages providing tutorial information on nearly all components of the SPICE system. Description of the files to be FTP'd in order to get, install and use the SPICE Toolkit.

Preparing_for_programm ing dscriptn.txt whats.new

TUTOR T T Describes the structure and contents of the Toolkit Describes significant new features added to the Toolkit since the last version.

TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T= SPICE Toolkit, in the /doc subdirectory GETTK = Go to the desired language and then platform under ftp://naif.jpl.nasa.gov/pub/naif/toolkit

General SPICE Programming Document Name Must Useful SPICE Subroutines Permuted Index

File Name Mostused.html spicelib_idx.html, cspice_idx.html, icy_idx.html, mice_idx.html cspice icy mice summary_of_key_points *.f or *_c.c

Location T T

Description/Comments Practical but terse specifications, including examples, for many popular routines. Permuted index built from the Brief Abstract found in every routine. Helps focus your search for a routine that meets your needs. A discussion of how the product is produced and how to use it. (Note: only cspice is available in C toolkits; cspice and icy are available in IDL toolkits; cspice and mice are available in MATLAB toolkits.) Tips for getting started on programming with SPICE modules. Each module (subroutine) in SPICELIB and CSPICE contains an extensive "header" providing the detailed specifications for the routine needed by a programmer. Examples are included. IDL and MATLAB interface wrappers, providing some instructions on use of the named API. More detail is provided in the corresponding CSPICE header. A summary of numeric ID codes used throughout the SPICE system Reference for configuring and using the exception handling system built-in to SPICELIB and CSPICE A discussion of the most commonly encountered problems using SPICE

CSPICE Required Reading ICY Required Reading MICE Required Reading Summary of Key Points Module headers (Also wee "wrappers" below) ICY and MICE wrappers around corresponding CSPICE modules NAIF IDs Required Reading Error Required Reading Common Problems Required Reading

TUTOR T

/doc/html/<mice or icy>/index.html naif_ids error problems

T T T

TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T = SPICE Toolkit: Plain text, in the /doc subdirectory HTML under the /doc/html/ subdirectory

Ephemerides for spacecraft and solar system bodies (SPK Subsystem) Document Name File Name Location SPK Tutorial Making an SPK Tutorial Using Frames Tutorial SPK Required Reading Frames Required Reading NAIF IDs Required Reading SPC Required Reading Kernel Required REading BRIEF User's Guide SPACIT User's Guide Convert User's Guide spk making_an_spk using_frames spk frames naif_ids spc kernel brief spacit conver TUTOR TUTOR TUTOR T T T T T T T T

Description/Comments Tutorial on using SPK files Tutorial on making an SPK file Tutorial on using frames, including in SPK routines Reference for the SPK subsystem Reference for working with reference frames Summarizes numeric ID codes used throughout the SPICE system Reference for use of the "comment area" in binary kernels Reference for general specifications of text kernels BRIEF produces a concise summary of the contents/coverage of an SPK file. SPACIT provides file conversion, detailed summarization and read access to internal comments (metadata). Describes use of the command line utilities named TOBIN and TOXFR used to convert binary kernels to transfer format and vice-versa. Comment is used to add, extract, read and delete comments (metadata) in binary kernels. SPKMERGE is a utility program used to merge two or more SPK files, or to subset a single SPK file. SPKDIFF computes differences between geometric states obtained from two SPK files and either displays these or shows statistics about them. SPY is a utility for validating, inspecting and analyzing SPKs. MKSPK is a utility for making an SPK file from a set of state vectors or conic elements or two-line elements.

Comment User's Guide SPK Merge User's Guide SPKDIFF Users Guide

commnt spkmerge spkdiff

T T T

SPY Users Guide MKSPK Users Guide

spy.txt mkspk

UTIL T

TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T = SPICE Toolkit: Plain text, in the /doc subdirectory HTML under the /doc/html/ subdirectory UTIL = Utilities link on the NAIF website

Target body size, shape and orientation (PCK Subsystem) Document Name File Name PCK Tutorial High Accuracy Orientation and Body-fixed Frames for the Moon and Earth tutorial PCK Required Reading Frames Required Reading NAIF IDs Required Reading Kernel Required Reading pck lunar-earth_pck-fk

Location TUTOR TUTOR

Description/Comments Tutorial viewgraphs on using PC-kernels Tutorial viewgraphs on special orientation files (binary PCKs) and body-fixed frames for the moon and the earth Reference for the PCK subsystem Reference for working with reference frames Summarizes numeric ID codes used throughout the SPICE system Reference for general specifications of text kernels

pck frames naif_ids kernel

T T T T

TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T = SPICE Toolkit: Plain text, in the /doc subdirectory HTML under the /doc/html/ subdirectory

Instrument Information Pertinent to SPICE (IK Subsystem) Document Name File Name IK Tutorial IK Required Reading n/a Frames Required Reading NAIF IDs Required Reading Kernel Required Reading ik ik *.ti frames naif_ids kernel

Location TUTOR -D T T T

Description/Comments Tutorial viewgraphs on using I-kernels (Not yet written!) Look at an existing I-kernel; these are text files that contain substantial internal documentation Reference for working with reference frames Summarizes numeric ID codes used throughout the SPICE system Reference for general specifications of text kernels

D= Project Data on NAIF web pages (http://naif.jpl.nasa.gov/naif/data.html) TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T = SPICE Toolkit: Plain text, in the /doc subdirectory HTML under the /doc/html/ subdirectory

Orientation of a Spacecraft or Structure (CK Subsystem) Document Name File Name CK Tutorial Using Frames Tutorial CK Required Reading Frames Required Reading NAIF IDs Required Reading SPC Required Reading Rotations Required Reading CKBRIEF User's Guide SPACIT User's Guide Convert User's Guide Comment User's Guide DAFCAT User's Guide CKslicer Users Guide CKsmrg MSOPCK Users Guide FRMDIFF Users Guide ck using_frames ck frames naif_ids spc rotation ckbrief spacit convert commnt dafcat ckslicer.txt chsmrg.txt msopck frmdiff

Location TUTOR TUTOR T T T T T T T T T UTIL UTIL UTIL T T

Description/Comments Tutorial viewgraphs on using C-kernels Tutorial on using frames, including in transformation modules Reference for the CK subsystem Reference for working with reference frames Summarizes numeric ID codes used throughout SPICE Reference for use of the "comment area" in binary kernels Reference for construction and use of rotation matrices within the SPICE context CKBRIEF produces a concise summary of the contents/coverage of an SPK file. SPACIT provides file conversion, detailed summarization and read access to internal comments (metadata). Describes use of the command line utilities TOBIN and TOXFR used to convert binary kernels to transfer format and vice-versa. COMMENT is used to add, extract, read and delete comments (metadata) in binary kernels. DAFCAT provides a very simple and simplistic file merge capability for CK files. CKSLICER subsets a CK into another CK file. CKSMRG merges segments in Type 3 CK files. MSOPCK is a utility for making a CK file from orientation data in the form of quaternions, Euler angles or rotation matrices. Provides a statistical comparison of the orientations of two frames, one or both of which might be specified using CK(s).

Connectivity of Reference Frames (FK Subsystem) Document Name File Name Frames Tutorial Using Frames Dynamic Frames n/a Frames Required Reading NAIF IDs Required Reading Rotations Required Reading Kernel Required Reading FRMDIFF Users Guide fk using_frames dynamic_frames *.tf frames naif_ids rotation kernel frmdiff

Location TUTOR TUTOR TUTOR D T T T T T

Description/Comments Tutorial viewgraphs on contents of a Frames kernel Tutorial viewgraphs on using Frames kernels Tutorial on defining/implementing custom so-called dynamic frames Look at an existing Frames kernel; these are text files and contain substantial internal documentation Reference for the Frames subsystem Summarizes numeric ID codes used throughout the SPICE system Reference for construction and use of rotation matrices within the SPICE context Reference for general specifications of text kernels Provides a statistical comparison of the orientations of two frames, one or both of which might be specified using CK(s).

"EVENTS", broken down into three sub-products (EK Subsystem) Document Name File Name Location Introduction to EK subsystem EK Required Reading ek_intro ek TUTOR T

Description/Comments Tutorial Introduction to the Events subsystem Reference for the Events-kernel subsystem

TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T = SPICE Toolkit: Plain text, in the /doc subdirectory HTML under the /doc/html/ subdirectory

Time Conversion Document Name Time Tutorial Time Required Reading SCLK Required Reading CHRONOS User's Guide Kernel Required Reading time time SCLK

File Name

Location TUTOR T T T T

Description/Comments Tutorial viewgraphs on time conversions Reference on time systems (excluding SCLK) Reference on spacecraft clock time CHRONOS is a full-featured, flexible time conversion utility program Reference for general specifications of text kernels

chronos kernel

TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T = SPICE Toolkit: Plain text, in the /doc subdirectory HTML under the /doc/html/ subdirectory

Geometry Finder (GF Subsystem) Document Name Geometry Finder Tutorial Geomeetry Finder Required Reading

File Name geometry_finder gf

Location TUTOR T

Description/Comments Tutorial viewgraphs on geometry finder subsystem Reference on geometry finder

TUTOR = Tutorials on NAIF web pages (http://naif.jpl.nasa.gov/tutorials.html) T = SPICE Toolkit: Plain text, in the /doc subdirectory HTML under the /doc/html/ subdirectory

DC-07 Going Through SIA Public Review
No ratings yet
DC-07 Going Through SIA Public Review
45 pages
Differential Equations With Boundary-Value Problems, International Metric Edition, 9th Edition
No ratings yet
Differential Equations With Boundary-Value Problems, International Metric Edition, 9th Edition
6 pages
URC-300 CombinedHandout
100% (1)
URC-300 CombinedHandout
8 pages
Home Using MyRIO
No ratings yet
Home Using MyRIO
6 pages
Global Positioning System
No ratings yet
Global Positioning System
52 pages
GUI Programming - Java Programming Tutorial
No ratings yet
GUI Programming - Java Programming Tutorial
52 pages
AZLoop Final Design Package PDF
No ratings yet
AZLoop Final Design Package PDF
387 pages
NNG Reference Manual, Second Edition
From Everand
NNG Reference Manual, Second Edition
Garrett D'Amore
No ratings yet
AMME2500 Unit of Study Outline
No ratings yet
AMME2500 Unit of Study Outline
4 pages
1 Acceptable Use Policy For Orange Products & Services
No ratings yet
1 Acceptable Use Policy For Orange Products & Services
2 pages
GMAT R2016a User Guide
No ratings yet
GMAT R2016a User Guide
921 pages
UM0892 User Manual: STM32 ST-LINK Utility Software Description
No ratings yet
UM0892 User Manual: STM32 ST-LINK Utility Software Description
54 pages
Quantum Technology
No ratings yet
Quantum Technology
26 pages
Arduino Katalogs
0% (1)
Arduino Katalogs
230 pages
Digital Electronic Circuits: Goutam Saha
No ratings yet
Digital Electronic Circuits: Goutam Saha
13 pages
The Uses of Robots
No ratings yet
The Uses of Robots
9 pages
Linux Kernel Internals
100% (1)
Linux Kernel Internals
84 pages
Digital Integrated Circuits: Introduction To TTL
No ratings yet
Digital Integrated Circuits: Introduction To TTL
19 pages
RTOS
0% (1)
RTOS
49 pages
SPC TheSpaceDriveProjectFirstResultsonEMDriveandMach EffectThrusters
No ratings yet
SPC TheSpaceDriveProjectFirstResultsonEMDriveandMach EffectThrusters
11 pages
Arduino Ultrasonic Radar Project
No ratings yet
Arduino Ultrasonic Radar Project
12 pages
Free Programming Language Paradigms Cheat Sheet
No ratings yet
Free Programming Language Paradigms Cheat Sheet
5 pages
Unit 8 Digital Integrated Circuits
No ratings yet
Unit 8 Digital Integrated Circuits
43 pages
ICM7216
No ratings yet
ICM7216
17 pages
Microsoft AI 360 Model PDF
No ratings yet
Microsoft AI 360 Model PDF
13 pages
Ncube Brian T Final Year Project
No ratings yet
Ncube Brian T Final Year Project
61 pages
Application-Specific Integrated Circuit ASIC A Complete Guide
From Everand
Application-Specific Integrated Circuit ASIC A Complete Guide
Gerardus Blokdyk
No ratings yet
CH341A Mini Programmer Schematic and Drivers One Transistor PDF
No ratings yet
CH341A Mini Programmer Schematic and Drivers One Transistor PDF
4 pages
Modeling Guidelines For Code Generation
No ratings yet
Modeling Guidelines For Code Generation
48 pages
Brief Description of Shrdlu
No ratings yet
Brief Description of Shrdlu
6 pages
Python and Google App Engine
100% (1)
Python and Google App Engine
68 pages
Ground Station Design and Analysis for LEO Satellites Analytical Experimental and Simulation Approach 1st Edition Shkelzen Cakaj download pdf
100% (4)
Ground Station Design and Analysis for LEO Satellites Analytical Experimental and Simulation Approach 1st Edition Shkelzen Cakaj download pdf
44 pages
Fall in Love With I2C LCD Displays PDF
No ratings yet
Fall in Love With I2C LCD Displays PDF
7 pages
ASN.1 Summary
No ratings yet
ASN.1 Summary
8 pages
Java Native Interface
No ratings yet
Java Native Interface
21 pages
Image Segmentation: Unlocking Insights through Pixel Precision
From Everand
Image Segmentation: Unlocking Insights through Pixel Precision
Fouad Sabry
No ratings yet
The Science of Deep Learning
0% (1)
The Science of Deep Learning
2 pages
Smarter IT: Optimize IT Delivery, Accelerate Innovation: Inside
No ratings yet
Smarter IT: Optimize IT Delivery, Accelerate Innovation: Inside
15 pages
Autonomous Surveillance Robot (ASaR)
No ratings yet
Autonomous Surveillance Robot (ASaR)
11 pages
The Idea of Architecture, The User As Inhabitant: Design Through A Christopher Alexander Lens
No ratings yet
The Idea of Architecture, The User As Inhabitant: Design Through A Christopher Alexander Lens
11 pages
Egomotion Estimation Using Visual Odometry
No ratings yet
Egomotion Estimation Using Visual Odometry
40 pages
Az-220T00-A: Microsoft Azure Iot Developer: Module 1: Introduction To Iot and Azure Iot Services
No ratings yet
Az-220T00-A: Microsoft Azure Iot Developer: Module 1: Introduction To Iot and Azure Iot Services
8 pages
Interfacing LCD To Arduino. JHD162A
100% (1)
Interfacing LCD To Arduino. JHD162A
10 pages
Li Fi The Future Technology in Wireless Communication
No ratings yet
Li Fi The Future Technology in Wireless Communication
4 pages
Insect Detection Using Image Processing and IoT
No ratings yet
Insect Detection Using Image Processing and IoT
4 pages
Iot Present
No ratings yet
Iot Present
29 pages
Scilab Manual
No ratings yet
Scilab Manual
44 pages
Mach-Effect Thruster Model: Acta Astronautica September 2017
No ratings yet
Mach-Effect Thruster Model: Acta Astronautica September 2017
36 pages
Usability engineering The Ultimate Step-By-Step Guide
From Everand
Usability engineering The Ultimate Step-By-Step Guide
Gerardus Blokdyk
No ratings yet
Mpu 6050
No ratings yet
Mpu 6050
20 pages
Elements of Logic and Formal Science (C. West Churchman) (Z-Library)
No ratings yet
Elements of Logic and Formal Science (C. West Churchman) (Z-Library)
360 pages
UPSC ESE/IES Electrical Engineering Syllabus: Paper - I
No ratings yet
UPSC ESE/IES Electrical Engineering Syllabus: Paper - I
4 pages
The Super Long Distance Wifi of The Esp32 Lora With Arduino Ide
No ratings yet
The Super Long Distance Wifi of The Esp32 Lora With Arduino Ide
11 pages
13 Applications Xilinx
No ratings yet
13 Applications Xilinx
23 pages
Development and Implementation of RFID Technology PDF
No ratings yet
Development and Implementation of RFID Technology PDF
564 pages
22OCS02 IOT CONCEPTS AND APPLICATION QB (MECH,AUTO,CIVIL)
No ratings yet
22OCS02 IOT CONCEPTS AND APPLICATION QB (MECH,AUTO,CIVIL)
12 pages
Hardware Security A Hands-on Learning Approach 1st Edition by Swarup Bhunia, Mark M Tehranipoor ISBN 0128124784 9780128124789 - The ebook is available for quick download, easy access to content
No ratings yet
Hardware Security A Hands-on Learning Approach 1st Edition by Swarup Bhunia, Mark M Tehranipoor ISBN 0128124784 9780128124789 - The ebook is available for quick download, easy access to content
52 pages
Visual Odometry (Vo) : Csc2541, Feb 9, 2016 Presented by Patrick Mcgarey
No ratings yet
Visual Odometry (Vo) : Csc2541, Feb 9, 2016 Presented by Patrick Mcgarey
36 pages
Design of Efficient Multiplier Using VHDL
No ratings yet
Design of Efficient Multiplier Using VHDL
50 pages
Kinect for Windows SDK Programming Guide
From Everand
Kinect for Windows SDK Programming Guide
Abhijit Jana
4/5 (3)
Storage area network The Ultimate Step-By-Step Guide
From Everand
Storage area network The Ultimate Step-By-Step Guide
Gerardus Blokdyk
No ratings yet
How to Design Optimization Algorithms by Applying Natural Behavioral Patterns
From Everand
How to Design Optimization Algorithms by Applying Natural Behavioral Patterns
Rohollah Omidvar
No ratings yet
Mastering WebGL: Crafting Advanced 3D Web Experiences: WebGL Wizadry
From Everand
Mastering WebGL: Crafting Advanced 3D Web Experiences: WebGL Wizadry
Kameron Hussain
No ratings yet
The Numpy Pocketbook: Essentials on the Go
From Everand
The Numpy Pocketbook: Essentials on the Go
Silas Meadowlark
No ratings yet
Finite-state machine A Complete Guide
From Everand
Finite-state machine A Complete Guide
Gerardus Blokdyk
No ratings yet
Senior Physics Lecture Module Quantum Physics (Advanced) Semester 1, 2013
No ratings yet
Senior Physics Lecture Module Quantum Physics (Advanced) Semester 1, 2013
6 pages
Senior Physics Lecture Module Quantum Physics (Advanced) Semester 1, 2013
No ratings yet
Senior Physics Lecture Module Quantum Physics (Advanced) Semester 1, 2013
6 pages
Template For PRL/PRD Papers: PACS Numbers
No ratings yet
Template For PRL/PRD Papers: PACS Numbers
3 pages
PHYS2912 - Unit Outline
No ratings yet
PHYS2912 - Unit Outline
15 pages
Khyvbjlk
No ratings yet
Khyvbjlk
1 page
Chapter 4: Imperfections in Solids: There Is No Such A Thing As A Perfect Crystal!
No ratings yet
Chapter 4: Imperfections in Solids: There Is No Such A Thing As A Perfect Crystal!
24 pages
Composites: Increased Strength, Deflection Capacity and Stiffness
No ratings yet
Composites: Increased Strength, Deflection Capacity and Stiffness
2 pages
AERO1560 2012 Semester 1
No ratings yet
AERO1560 2012 Semester 1
5 pages
OAK Ridge National Laboratory: Basic Properties of Reference Crossply Carbon-Fiber Composite
No ratings yet
OAK Ridge National Laboratory: Basic Properties of Reference Crossply Carbon-Fiber Composite
60 pages
12 W 09
No ratings yet
12 W 09
6 pages
Some Useful Formulae: A A A A A A + + + +
No ratings yet
Some Useful Formulae: A A A A A A + + + +
3 pages
05 Acts
No ratings yet
05 Acts
93 pages
ENGG1802 2011 Semester 2
No ratings yet
ENGG1802 2011 Semester 2
4 pages
pump 13
No ratings yet
pump 13
7 pages
SQL Data Integrity
No ratings yet
SQL Data Integrity
7 pages
System Analysis
No ratings yet
System Analysis
2 pages
Lab+-+HTML+Smuggling+Attack
No ratings yet
Lab+-+HTML+Smuggling+Attack
7 pages
Aliasing in Digital Clippers and Compressors : PAUL KRAGHT, AES Associate Member
No ratings yet
Aliasing in Digital Clippers and Compressors : PAUL KRAGHT, AES Associate Member
6 pages
Typeclasses PDF
No ratings yet
Typeclasses PDF
3 pages
Wikihouse Manufacturing Guide
No ratings yet
Wikihouse Manufacturing Guide
11 pages
IRSE News 278 Jun 21
No ratings yet
IRSE News 278 Jun 21
40 pages
Lab2 PDF
No ratings yet
Lab2 PDF
3 pages
Oracle Tutorials
No ratings yet
Oracle Tutorials
301 pages
Video Editing N Animation
No ratings yet
Video Editing N Animation
4 pages
thermal printer for flow wrapper DS-1108
No ratings yet
thermal printer for flow wrapper DS-1108
19 pages
Enterprise IT at Cisco
No ratings yet
Enterprise IT at Cisco
3 pages
NNML_Mid_1_Objective[2]
No ratings yet
NNML_Mid_1_Objective[2]
16 pages
Airport Consulting - Summer 2011
No ratings yet
Airport Consulting - Summer 2011
20 pages
School Management System Modules Documentation
No ratings yet
School Management System Modules Documentation
20 pages
OAT unit-5
No ratings yet
OAT unit-5
8 pages
Project Report On Smart Dustbin Using IoT
100% (1)
Project Report On Smart Dustbin Using IoT
24 pages
Rfqa - Ict Css 9 Suarez-Mrg
No ratings yet
Rfqa - Ict Css 9 Suarez-Mrg
13 pages
Reverse Order Triangular, Trapezoidal and Pentagonal Fuzzy Numbers
No ratings yet
Reverse Order Triangular, Trapezoidal and Pentagonal Fuzzy Numbers
11 pages
Version Control System
No ratings yet
Version Control System
28 pages
3CO2 I Handout
No ratings yet
3CO2 I Handout
27 pages
Freelancers Websites
No ratings yet
Freelancers Websites
2 pages
Age Related Problems
No ratings yet
Age Related Problems
6 pages
Microprocessor Expriments
No ratings yet
Microprocessor Expriments
26 pages
Flowcharting
No ratings yet
Flowcharting
19 pages