SP2XML User's Guide
===========================================================================
Last revised on 2002 APR 19 by B. V. Semenov.
Abstract
--------------------------------------------------------
SP2XML is a program that computes an array of states of a target as seen
from an observer in a specified reference frame between specified begin
and end times with fixed time step and writes this array into an XML
file.
Summary
--------------------------------------------------------
SP2XML is a command line program that computes an array of states --
Cartesian position and velocity -- of a target as seen from an observer
in a specified reference frame between specified begin and end times
with fixed time step and writes this array into an XML file. It is
essentially a fixed time step loop wrapped around the highest level
SPICE interface SPKEZR.
If the data from the kernel file set provided to the program is
sufficient to compute requested states at each time point, the program
will produce an output file and will exit with 0 status. If an error
occurs during execution, the program will print an appropriate error
message to standard output, return with non-zero status, and will not
produce an output file.
Usage
--------------------------------------------------------
To generate an Ephemeris XML (EML) file SP2XML should be run with the
following command line arguments:
> SP2XML -K|-KERNELS
-O|-OBSERVER
-F|-FRAME
-B|-BEGIN
-E|-END
-S|-STEP
-X|-XML
[-P|-PICTURE ]
All command line keys are case insensitive and the order, in which they
are specified, is insignificant. If an unknown key is specified, the
program treats it as a part of the value preceding it. The only optional
key is ``-P|-PICTURE', which is indicated by [].
The command line options above have the following meanings:
-K|-KERNELS this is used to specify either the name of a meta
kernel file listing SPICE kernels or a list of
the kernels to be loaded into the program.
Refer to the section ``Loading SPICE Kernels'' of
this document for details on using these two ways
of loading the data. Also see KERNEL.REQ document
for general information regarding loading SPICE
kernels.
-T|-TARGET this is used to specify the name or NAIF ID of
the target body. For example either ``SUN'' or
``10'' will tell the program that the states of
the Sun should be computed.
See NAIF_IDS.REQ Document for for the list of
built-in names and IDs and for an explanation of
how name-ID pairs can defined using the text
kernel files.
-O|-OBSERVER this is used to specify the name or NAIF ID of
the observing body. For example either ``MER-A''
or ``-253'' will tell the program that the states
should be computed ``as seen'' from MER-A rover.
See NAIF_IDS.REQ Document for for the list of
built-in names and IDs and for an explanation of
how name-ID pairs can defined using the text
kernel files.
-F|-FRAME this is used to specify the name the reference
frame with respect to which the states should be
computed. This can be the name of one of the
built-in frames -- for example ``J2000'' for
J2000 Inertial frame or ``IAU_MARS'' for Mars
body-fixed rotating frame -- or the name of a
user defined frame recognized by SPICE in the
context of all loaded SPICE kernels -- for
example ``MER-A_LOCAL_LEVEL'' frame if it's
defined in one of the loaded Frames Kernel files.
See Frames kernels files(s) for the project of
your interest to the list of project specific
frames.
See FRAMES.REQ document for a list of built-in
frames and general information about SPICE Frames
subsystem.
-C|-CORRECTION this is used to specify the aberration correction
supported by the SPKEZR interface.
To compute positions and velocities of the
near-by objects -- meters, kilometers, or
hundreds of kilometers away -- the aberration
correction ``NONE'' is probably more than
adequate.
For the distant objects, for which the light time
and stellar aberration effects greatly affect
their apparent position, the aberration
correction ``LT+S'' should be used.
See ``Appendix 4: Aberration Corrections'' for
more details.
-B|-BEGIN this is used to specify the begin time of the
interval for which the states should be computed.
Although SPICE provides great flexibility in the
ways of specifying input times (see ``Appendix 1:
Input Time Formats Specification'' for details),
the
``YYYY-MM-DDTHR.MN.SC.###''
format is suggested and should be adequate for
most applications.
-E|-END this is used to specify the end time of the
interval for which the states should be computed.
Although SPICE provides great flexibility in the
ways of specifying input times (see ``Appendix 1:
Input Time Formats Specification'' for details),
the
``YYYY-MM-DDTHR.MN.SC.###''
format is suggested and should be adequate for
most applications.
-S|-STEP this is used to specify the time step time with
which the states should be computed. The step
should be specified as a number of recognized
time units with the units identifier included,
for example ``10 seconds'', ``15 minutes''.
See ``Appendix 2: Input Duration Format
Specification'' for details regarding duration
format specification.
-X|-XML this is used to specify the name of the output
XML file.
-P|-PICTURE this optional key is used to specify the output
number format picture, the default value of which
is the scientific notation given to 14 decimal
digit (+2.2587718739265E+03).
See ``Appendix 3: Output Number Format
Specification'' for details regarding output
number format specification.
To generate an XML schema file with the fixed name ``eml.xsd'' SP2XML
should be run with the following command line arguments:
% SP2XML -M|-SCHEMA
If ``-USAGE'', ``-U'' or nothing is provided on the command line, SP2XML
displays usage information:
% SP2XML [-U|-USAGE]
SP2XML displays help information if the ``-HELP'' or ``-H'' key is
specified on the command line:
% SP2XML -H|-HELP
If ``-VERSION'' or ``-V'' is provided on the command line, SP2XML
displays version information:
% SP2XML -V|-VERSION
Loading SPICE Kernels
--------------------------------------------------------
The kernels files to be loaded can be provided by listing them after a
single -K|-KERNELS option:
... -KERNELS ...
or by the standard SPICE interface -- listing them in a meta kernel with
the KERNELS_TO_LOAD parameter:
\begindata
KERNELS_TO_LOAD = (
'LSK file',
'SCLK file ',
'PCK file',
'SPK file',
'...',
'CK file',
'...',
'FK file'
)
\begintext
and providing the name of this meta kernel after -K|-KERNELS command
line option:
... -KERNELS
SPICE-based Ephemeris State Table
Sun as seen from MER-A on 2004-01-28
SP2XML command line:
sp2xml -k mera_vm53a2.furnsh -t sun -o mer-a \
-f mer-a_local_level -c lt+s \
-b 2004-01-28 00:00 -e 2004-01-29 00:00 \
-s 10 minutes -x mera_sun_040128.eml
Output EML File ``mera_sun_040128.eml'' (lines are wrapped by 60
character margin):
Phobos as seen from MER-A on 2004-01-30
SP2XML command line:
sp2xml -k mera_vm53a2.furnsh -t phobos -o mer-a \
-f mer-a_local_level -c lt+s \
-b 2004-01-30 00:00 -e 2004-01-31 00:00 \
-s 300 seconds -x mera_phobos_040130.eml
Output EML File ``mera_phobos_040130.eml'' (lines are wrapped by 60
character margin):
Mars-01 as seen from MER-B on 2004-02-12
SP2XML command line:
sp2xml -k merb_tm20b2.furnsh -t M01 -o mer-b \
-f mer-b_local_level -c lt+s \
-b 2004-02-12 00:00 -e 2004-02-13 00:00 \
-s 60 seconds -x merb_m01_040212.eml
Output EML File ``merb_m01_040212.eml'' (lines are wrapped by 60
character margin):
Mars Express as seen from MER-A on 2004-03-12
SP2XML command line:
sp2xml -k merb_tm20b2.furnsh -t MARS EXPRESS -o mer-b \
-f mer-b_local_level -c lt+s \
-b 2004-03-12 00:00 -e 2004-03-13 00:00 \
-s 2 minutes -x merb_mex_040312.eml
Output EML File ``merb_mex_040312.eml'' (lines are wrapped by 60
character margin):
Appendixes
===========================================================================
Appendix 1: Input Time Formats Specification
--------------------------------------------------------
Start and stop times provided using the corresponding command line keys
must be specified as time strings that can be parsed by the SPICE STR2ET
routine. Below is an extract from the STR2ET subroutine header,
explaining acceptable formats and providing some examples.
The variety of ways people have developed for representing
times is enormous. It is unlikely that any single subroutine
can accommodate the wide variety of custom time formats that
have arisen in various computing contexts. However, we
believe that this routine will correctly interpret most time
formats used throughout the planetary science community.
For example this routine supports ISO time formats, UNIX
`date` output formats, VMS time formats, MS-DOS formats,
etc. One obvious omission from the strings recognized by
this routine are strings of the form
93234.1829 or 1993234.1829
Some readers may recognize this as the epoch that is 0.1829
days past the beginning of the 234'th day of 1993. However,
other readers may regard this interpretation as a bit
obscure.
Below we outline some of the rules used in the interpretation
of strings. A more complete discussion of the interpretation
of strings is given in the routine TPARTV.
Default Behavior
----------------
consider the string
1988 June 13, 3:29:48
There is nothing in this string to indicate what time system
the date and time belong to. Moreover, there is nothing to
indicate whether the time is based on a 24-hour clock or
twelve hour clock.
In the absence of such indicators, the default interpretation
of this string is to regard the time of day to be a time on
a 24-hour clock in the UTC time system. The date is a date
on the Gregorian Calendar (this is the calendar used in nearly
all western societies).
Labels
------
If you add more information to the string, STR2ET can then
make a more informed interpretation of the time string.
For example:
1988 June 13, 3:29:48 P.M.
is still regarded as a UTC epoch. However, with the addition
of the 'P.M.' label it is now interpreted as the same epoch
as the unlabeled epoch 1988 June 13, 15:29:48. Similarly
1988 June 13, 12:29:48 A.M.
is interpreted as
1988 June 13, 00:29:48
For the record: 12:00 A.M. corresponds to Midnight (00:00 on the
24 hour clock. 12:00 P.M. corresponds to Noon. (12:00) on the
24 hour clock.
You may add still further indicators to the string. For example
1988 June 13, 3:29:48 P.M. PST
is interpreted as an epoch in the Pacific Standard Time system.
This is equivalent to
1988 June 13, 07:29:48 UT
The following U.S. time zones are recognized.
EST --- Eastern Standard Time ( UTC-5:00 )
CST --- Central Standard Time ( UTC-6:00 )
MST --- Mountain Standard Time ( UTC-7:00 )
PST --- Pacific Standard Time ( UTC-8:00 )
EDT --- Eastern Daylight Time ( UTC-4:00 )
CDT --- Central Daylight Time ( UTC-5:00 )
MDT --- Mountain Daylight Time ( UTC-6:00 )
PDT --- Pacific Daylight Time ( UTC-7:00 )
Any other time zone may be specified by
representing its offset from UTC.
This notation starts with the letters 'UTC' followed by a
'+' for time zones east of Greenwich and '-' for time zones
west of Greenwich. This is followed by the number of hours
to add or subtract from UTC. This is optionally followed
by a colon ':' and the number of minutes to add or subtract
to get the local time zone. Thus to specify the time zone of
Calcutta (which is 5 and 1/2 hours ahead of UTC) you would
specify the time zone to be UTC+5:30. To specify the time zone
of Newfoundland (which is 3 and 1/2 hours behind UTC) use the
offset notation UTC-3:30.
For the Record: Leapseconds occur at the same time in all
time zones. In other words, the seconds component of a time
string is the same for any time zone as is the seconds
component of UTC. Thus the following are all legitimate
ways to represent an epoch of some event that occurred
in the leapsecond
1995 December 31 23:59:60.5 (UTC)
1996 January 1, 05:29:60.5 (UTC+5:30 --- Calcutta Time)
1995 December 31, 20:29:60.5 (UTC-3:30 --- Newfoundland)
1995 December 31 18:59:60.5 (EST)
1995 December 31 17:59:60.5 (CST)
1995 December 31 16:59:60.5 (MST)
1995 December 31 15:59:60.5 (PST)
In addition to specifying time zones, you may specify
that the string be interpreted as a formal calendar
representation in either the Barycentric Dynamical Time system
(TDB) or the Terrestrial Dynamical Time system (TDT). In
These systems there are no leapseconds. Times in TDB
are written as
1988 June 13, 12:29:48 TDB
TDT times are written as:
1988 June 13, 12:29:48 TDT
Finally, you may explicitly state that the time system is UT
1988 June 13, 12:29:48 UTC.
Note that you may not specify two different time systems
simultaneously. For example
1988 June 13, 12:29:48 PDT TDT
You might be able to make some kind of reasonable guess as
to the meaning of this string, but we've decided to regard
such strings as errors.
Abbreviating Years
------------------
Although it can lead to confusion, many people are in the
habit of abbreviating years when they write them in dates.
For example
99 Jan 13, 12:28:24
Upon seeing such a string, most of us would regard this
as being 1999 January 13, 12:28:24 and not January 13 of
the year 99. This routine interprets years that are less
than 100 as belonging either to the 1900's or 2000's. Years
greater than 68 ( 69 - 99 ) are regarded as being an
abbreviation with the '19' suppressed (1969 - 1999). Years
smaller than 69 ( 00 - 68 ) are regarded as being an
abbreviation with the '20' suppressed (2000 - 2068).
Note that in general it is usually a good idea to write
out the year. Or if you'd like to save some typing
abbreviate 1999 as '99.
If you need to specify an epoch whose year
is less than 1000, we recommend that you specify the era
along with the year. For example if you want to specify
the year 13 A.D. write it as
13 A.D. Jan 12
When specifying the era it should immediately follow the year.
Both the A.D. and B.C. eras are supported.
Changing Default Behavior
-------------------------
As discussed above, if a string is unlabelled, it is regarded
as representing a string in the UTC time system on the
Gregorian calendar. Abbreviated years are
regarded as abbreviations of the years from 1969 to 2068.
You may modify these defaults through the routines TIMDEF
and TSETYR (an entry point of TEXPYR).
You may:
Set the calendar to be Gregorian, Julian or a mixture of
the two using TIMDEF;
Set the time system to be UTC, TDB, TDT or any time zone
using TIMDEF;
Set the range of year abbreviations to be any 100 year
interval using TSETYR.
See the routines TEXPYR and TIMDEF for details on changing
defaults.
These alterations affect only the interpretation of unlabelled
strings. If an input string is labelled the specification
in the label is used.
If some component of a date or time is "out-of-range" STR2ET
regards the string as erroneous. Below is a list of
erroneous strings and why they are regarded as such.
1997 Jan 32 12:29:29 --- there are only 31 days in January
'98 Jan 12 13:29:29 A.M. --- Hours must be between 1 and 12
inclusive when A.M. or P.M. is
specified.
1997 Feb 29, 12:29:20.0 --- February has only 28 days in
1997. This would be ok if the
year was 1996.
1992 Mar 12 12:62:20 --- Minutes must be between 0 and 59
inclusive.
1993 Mar 18 15:29:60.5 --- Seconds is out of range for this
date. It would not be out of
range for Dec 31 23:59:60.5 or
Jun 30 23:59:60.5 because these
can be leapseconds (UTC).
Specifics On Interpretation of the Input String
-----------------------------------------------
The process of examining the string to determine its meaning
is called "parsing" the string. The string is parsed by first
determining its recognizable substrings (integers, punctuation
marks, names of months, names of weekdays, time systems, time
zones, etc.) These recognizable substrings are called the
tokens of the input string. The meaning of some tokens are
immediately determined. For example named months, weekdays and
time systems have clear meanings. However, the meaning of
a numeric component must be deciphered from its magnitude
and location in the string relative to the immediately recognized
components of the input string.
To determine the meaning of the numeric tokens in the input
string, a set of "production rules" and transformations are
applied to the full set of tokens in the string. These
transformations are repeated until the meaning of every token
has been determined or until further transformations yield
no new clues into the meaning of the numeric tokens.
1) Unless the substring 'JD' or 'jd' is present, the string is
assumed to be a calendar format (day-month-year or year and
day of year). If the substring JD or jd is present, the
string is assumed to represent a Julian date.
2) If the Julian date specifier is not present, any integer
greater than 999 is regarded as being a year specification.
3) A dash '-' can represent a minus sign only if it precedes
the first digit in the string and the string contains
the Julian date specifier (JD). (No negative years,
months, days, etc are allowed).
4) Numeric components of a time string must be separated
by a character that is not a digit or decimal point.
Only one decimal component is allowed. For example
1994219.12819 is sometimes interpreted as the
219th day of 1994 + 0.12819 days. STR2ET does not
support such strings.
No exponential components are allowed. For example you
can't input 1993 Jun 23 23:00:01.202E-4 you have
to explicitly list all zeros that follow the decimal
point: i.e. 1993 Jun 23 23:00:00.0001202
5) The single colon (:) when used to separate numeric
components of a string is interpreted as separating
Hours, Minutes, and Seconds of time.
6) If a double slash (//) or double colon (::) follows
a pair of integers, those integers are assumed to
represent the year and day of year.
7) A quote followed by an integer less than 100 is regarded
as an abbreviated year. For example: '93 would be regarded
as the 93rd year of the reference century. See TEXPYR
for further discussion of abbreviated years.
8) An integer followed by 'B.C.' or 'A.D.' is regarded as
a year in the era associated with that abbreviation.
9) All dates are regarded as belonging to the extended
Gregorian Calendar (the Gregorian calendar is the calendar
currently used by western society). See the routine TIMDEF
to modify this behavior.
10) If the International Standard Organization (ISO)
date-time separator (T) is present in the string
ISO allowed token patterns are examined for a match
with the current token list. If no match is found the
search is abandoned and appropriate diagnostic messages
are generated.
11) If two delimiters are found in succession in the time
string, the time string is diagnosed as an erroneous
string. ( Delimiters are comma, white space, dash, forward
slash, period, day of year mark "//" or "::" )
Note the delimiters do not have to be the same. The pair
of characters ",-" counts as two successive delimiters.
12) White space and commas serve only to delimit tokens in the
input string. They do not affect the meaning of any
of the tokens.
13) If an integer is greater than 1000 (and the 'JD' label
is not present, the integer is regarded as a year.
14) When the size of the integer components does not clearly
specify a year the following patterns are assumed
Calendar Format
Year Month Day
Month Day Year
Year Day Month
Where Month is the name of a month, not its numeric
value.
When integer components are separated by slashes (/)
as in 3/4/5. Month, Day, Year is assumed (2005 March 4)
Day of Year Format.
If a day of year marker is present (// or ::) the
pattern
I-I// or I-I:: (where I stands for an integer)
is interpreted as Year Day-of-Year. However, I-I/ is
regarded as ambiguous.
Examples
--------
Below is a sampling of some of the time formats that
are acceptable as inputs to STR2ET and the way they
are interpreted. A complete discussion
of permissible formats is given in the SPICE routine
TPARTV as well as the reference file time.req
located in the /doc directory of the toolkit. "na"
means Not Applicable.
ISO (T) Formats
String Year Mon DOY DOM HR Min Sec
---------------------------- ---- --- --- --- -- --- ------
1996-12-18T12:28:28 1996 Dec na 18 12 28 28
1986-01-18T12 1986 Jan na 18 12 00 00
1986-01-18T12:19 1986 Jan na 18 12 19 00
1986-01-18T12:19:52.18 1986 Jan na 18 12 19 52.18
1995-08T18:28:12 1995 na 008 na 18 28 12
1995-18T 1995 na 018 na 00 00 00
Calendar Formats
String Year Mon DOM HR Min Sec
---------------------------- ---- --- --- -- --- ------
Tue Aug 6 11:10:57 1996 1996 Aug 06 11 10 57
1 DEC 1997 12:28:29.192 1997 Dec 01 12 28 29.192
2/3/1996 17:18:12.002 1996 Feb 03 17 18 12.002
Mar 2 12:18:17.287 1993 1993 Mar 02 12 18 17.287
1992 11:18:28 3 Jul 1992 Jul 03 11 18 28
June 12, 1989 01:21 1989 Jun 12 01 21 00
1978/3/12 23:28:59.29 1978 Mar 12 23 28 59.29
17JUN1982 18:28:28 1982 Jun 17 18 28 28
13:28:28.128 1992 27 Jun 1992 Jun 27 13 28 28.128
1972 27 jun 12:29 1972 Jun 27 12 29 00
'93 Jan 23 12:29:47.289 1993* Jan 23 12 29 47.289
27 Jan 3, 19:12:28.182 2027* Jan 03 19 12 28.182
23 A.D. APR 4, 18:28:29.29 0023** Apr 04 18 28 29.29
18 B.C. Jun 3, 12:29:28.291 -017** Jun 03 12 29 28.291
29 Jun 30 12:29:29.298 2029+ Jun 30 12 29 29.298
29 Jun '30 12:29:29.298 2030* Jun 29 12 29 29.298
Day of Year Formats
String Year DOY HR Min Sec
---------------------------- ---- --- -- --- ------
1997-162::12:18:28.827 1997 162 12 18 28.827
162-1996/12:28:28.287 1996 162 12 28 28.287
1993-321/12:28:28.287 1993 231 12 28 28.287
1992 183// 12 18 19 1992 183 12 18 19
17:28:01.287 1992-272// 1992 272 17 28 01.287
17:28:01.282 272-1994// 1994 272 17 28 01.282
'92-271/ 12:28:30.291 1992* 271 12 28 30.291
92-182/ 18:28:28.281 1992* 182 18 28 28.281
182-92/ 12:29:29.192 0182+ 092 12 29 29.192
182-'92/ 12:28:29.182 1992 182 12 28 29.182
Julian Date Strings
jd 28272.291 Julian Date 28272.291
2451515.2981 (JD) Julian Date 2451515.2981
2451515.2981 JD Julian Date 2451515.2981
Abbreviations Used in Tables
na --- Not Applicable
Mon --- Month
DOY --- Day of Year
DOM --- Day of Month
Wkday --- Weekday
Hr --- Hour
Min --- Minutes
Sec --- Seconds
* The default interpretation of a year that has been abbreviated
with a leading quote as in 'xy (such as '92) is to treat
the year as 19xy if xy > 68 and to treat it is 20xy otherwise.
Thus '70 is interpreted as 1970 and '67 is treated as 2067.
However, you may change the "split point" and centuries through
use of the SPICE routine TSETYR which is an entry point in
the SPICE module TEXPYR. See that routine for a discussion of
how you may reset the split point.
** All epochs are regarded as belonging to the Gregorian
calendar. We formally extend the Gregorian calendar backward
and forward in time for all epochs.
+ When a day of year format or calendar format string is
input and neither of the integer components of the date
is greater than 1000, the first integer
is regarded as being the year.
...
Appendix 2: Input Duration Format Specification
--------------------------------------------------------
The step should be specified as a number of recognized time units with
the units identifier included, for example ``10 seconds'', ``15
minutes''. The following unit specification are recognized:
SECONDS
MINUTES
HOURS
DAYS
JULIAN_YEARS
TROPICAL_YEARS
YEARS
Note that all unit identifiers are plurals; the singular and abbreviated
forms are not supported.
Appendix 3: Output Number Format Specification
--------------------------------------------------------
On output the state components are formatted as DP numbers in accordance
with a format picture specification recognized by SPICE's DPFMT routine.
Below is an extract from the DPFMT subroutine header explaining
acceptable specifications of an output DP format picture and providing
some examples.
Format Picture Construction Rules
---------------------------------
A format picture is a string used to describe the format of
the output string. There are four special characters
recognized by DPFMT --- a leading + or -, a leading
zero ( '0' ) or a zero that follows a leading + or -,
and the first decimal point of the string.
All other non-blank characters are regarded as
equivalent. The picture ends at the first blank
character. The effects associated with the various
characters in a picture are spelled out in the
description of the output STRING.
The following pictures are treated as errors.
' ', '+', '-', '.', '+.', '-.'
If the first character of the picture is a minus sign,
the first character in the output string will be
a blank if the number is non-negative, a minus sign
if the number is negative.
If the first character of the picture is a plus sign,
the first character of the output string will be a
plus if the number is positive, a blank if the number
is zero, and a minus sign if the number is negative.
If the first character of the string is NOT a sign
(plus or minus) the first character of the output
string will be a minus sign if the number is negative
and will be the first character of the integer part
of the number otherwise.
The integer portion of STRING will contain the same
number of characters as appear before the decimal point
(or last character if there is no decimal point) but
after a leading + or -.
If the picture begins with any of the following
'+0', '-0', or '0'
it is said to have a leading zero. If a picture has
a leading zero and the integer portion is not large
enough to fill up the integer space specified by
PICTUR, STRING will be zero padded from the sign (if
one is required) up to the first character of the
integer part of the number.
If picture does NOT have a leading zero and
the integer portion is not large enough to fill up
the space specified by PICTUR, STRING will be blank
padded on the left between the sign (if one is required)
and the first character of the integer part of the
number.
If a decimal point ( '.' ) is present in PICTUR it
will be present following the integer portion of
STRING. Moreover, the decimal portion of STRING will
contain the same number of digits as there are
non-blank characters following the decimal point in
PICTUR. However, only the first 14 digits starting
with the first non-zero digit are meaningful.
If the format specified by PICTUR does not provide
enough room for the integer portion of X, the routine
determines whether or not the number of characters
present in the picture is sufficient to create a
representation for X using scientific notation. If
so, the output is displayed using scientific notation
(leading signs if they are present in PICTUR, will
also appear in STRING). If the format specified
by PICTUR is too short to accommodate scientific
notation, the output string is filled with '*' to
the same length as the length of PICTUR. Leading
signs are not preserved in this overflow case.
Examples
--------
Suppose that X has the binary representation of PI.
Then the table below illustrates the strings that
would be produced by a variety of different pictures.
PICTUR | STRING
-------------------------------
'0x.xxx' | '03.142'
'xx.xxx' | ' 3.142'
'+xxx.yyyy' | '+ 3.1416'
'-.yyyy' | '******'
'xxxxxxxx' | ' 3'
'00xx' | '0003'
'-00.0000000' | ' 03.1415927'
'00' | '03'
'x.' | '3.'
'.mynumber' | '3.142E+00'
'my dog spot' | ' 3'
'my.dog spot' | ' 3.142'
'+my.dog,spot' | '+ 3.14159265'
Suppose that X has the binary representation of 2/3.
Then the table below illustrates the strings that
would be produced by a variety of different pictures.
PICTUR | STRING
-------------------------------
'+x.xxx' | '+0.667'
'+xx.xxx' | '+ 0.667'
'xxx.yyyy' | ' 0.6667'
'.yyyy' | '.6667'
'xxxxxxxx' | ' 1'
'00xx' | '0001'
'-0.0000000' | ' 0.6666667'
'00' | '01'
'x.' | '1.'
'mynumber' | ' 1'
'my dog spot' | ' 1'
'my.dog spot' | ' 0.667'
'my.dog,spot' | ' 0.66666667'
Suppose that X has the binary representation of
-8/9. Then the table below illustrates the strings
that would be produced by a variety of different
pictures.
PICTUR | STRING
-------------------------------
'+x.xxx' | '-0.889'
'-00.xxxx' | '-00.8889'
'xxx.xxx' | ' -0.889'
'000.000' | '-00.889'
Appendix 4: Aberration Corrections
--------------------------------------------------------
For those who need to know all the details regarding the aberration
correction supported by SPICE, this is the description extracted from
SPICE's primary interface SPKEZR:
Aberration corrections supported by SPKEZR
==========================================
The following values of ABCORR apply to the "reception" case in
which photons depart from the target's location at the light-time
corrected epoch ET-LT and *arrive* at the observer's location at
ET:
'LT' Correct for one-way light time (also
called "planetary aberration") using a
Newtonian formulation. This correction
yields the state of the target at the
moment it emitted photons arriving at
the observer at ET.
The light time correction involves
iterative solution of the light time
equation (see Particulars for details).
The solution invoked by the 'LT' option
uses one iteration.
'LT+S' Correct for one-way light time and
stellar aberration using a Newtonian
formulation. This option modifies the
state obtained with the 'LT' option to
account for the observer's velocity
relative to the solar system
barycenter. The result is the apparent
state of the target---the position and
velocity of the target as seen by the
observer.
'CN' Converged Newtonian light time
correction. In solving the light time
equation, the 'CN' correction iterates
until the solution converges (three
iterations on all supported platforms).
The 'CN' correction typically does not
substantially improve accuracy because
the errors made by ignoring
relativistic effects may be larger than
the improvement afforded by obtaining
convergence of the light time solution.
The 'CN' correction computation also
requires a significantly greater number
of CPU cycles than does the
one-iteration light time correction.
'CN+S' Converged Newtonian light time
and stellar aberration corrections.
The following values of ABCORR apply to the "transmission" case
in which photons *depart* from the observer's location at ET and
arrive at the target's location at the light-time corrected epoch
ET+LT:
'XLT' "Transmission" case: correct for
one-way light time using a Newtonian
formulation. This correction yields the
state of the target at the moment it
receives photons emitted from the
observer's location at ET.
'XLT+S' "Transmission" case: correct for
one-way light time and stellar
aberration using a Newtonian
formulation This option modifies the
state obtained with the 'XLT' option to
account for the observer's velocity
relative to the solar system
barycenter. The position component of
the computed target state indicates the
direction that photons emitted from the
observer's location must be "aimed" to
hit the target.
'XCN' "Transmission" case: converged
Newtonian light time correction.
'XCN+S' "Transmission" case: converged
Newtonian light time and stellar
aberration corrections.
Neither special nor general relativistic effects are accounted
for in the aberration corrections applied by this routine.
Aberration corrections particulars
==================================
In space science or engineering applications one frequently
wishes to know where to point a remote sensing instrument, such
as an optical camera or radio antenna, in order to observe or
otherwise receive radiation from a target. This pointing problem
is complicated by the finite speed of light: one needs to point
to where the target appears to be as opposed to where it actually
is at the epoch of observation. We use the adjectives
"geometric," "uncorrected," or "true" to refer to an actual
position or state of a target at a specified epoch. When a
geometric position or state vector is modified to reflect how it
appears to an observer, we describe that vector by any of the
terms "apparent," "corrected," "aberration corrected," or "light
time and stellar aberration corrected."
The SPICE Toolkit can correct for two phenomena affecting the
apparent location of an object: one-way light time (also called
"planetary aberration") and stellar aberration. Correcting for
one-way light time is done by computing, given an observer and
observation epoch, where a target was when the observed photons
departed the target's location. The vector from the observer to
this computed target location is called a "light time corrected"
vector. The light time correction depends on the motion of the
target, but it is independent of the velocity of the observer
relative to the solar system barycenter. Relativistic effects
such as light bending and gravitational delay are not accounted
for in the light time correction performed by this routine.
The velocity of the observer also affects the apparent location
of a target: photons arriving at the observer are subject to a
"raindrop effect" whereby their velocity relative to the observer
is, using a Newtonian approximation, the photons' velocity
relative to the solar system barycenter minus the velocity of the
observer relative to the solar system barycenter. This effect is
called "stellar aberration." Stellar aberration is independent
of the velocity of the target. The stellar aberration formula
used by this routine is non-relativistic.
Stellar aberration corrections are applied after light time
corrections: the light time corrected target position vector is
used as an input to the stellar aberration correction.
When light time and stellar aberration corrections are both
applied to a geometric position vector, the resulting position
vector indicates where the target "appears to be" from the
observer's location.
As opposed to computing the apparent position of a target, one
may wish to compute the pointing direction required for
transmission of photons to the target. This requires correction
of the geometric target position for the effects of light time
and stellar aberration, but in this case the corrections are
computed for radiation traveling from the observer to the target.
The "transmission" light time correction yields the target's
location as it will be when photons emitted from the observer's
location at ET arrive at the target. The transmission stellar
aberration correction is the inverse of the traditional stellar
aberration correction: it indicates the direction in which
radiation should be emitted so that, using a Newtonian
approximation, the sum of the velocity of the radiation relative
to the observer and of the observer's velocity, relative to the
solar system barycenter, yields a velocity vector that points in
the direction of the light time corrected position of the target.
One may reasonably object to using the term "observer" in the
transmission case, in which radiation is emitted from the
observer's location. The terminology was retained for
consistency with earlier documentation.
Below, we indicate the aberration corrections to use for some
common applications:
1) Find the apparent direction of a target for a remote-sensing
observation:
Use 'LT+S': apply both light time and stellar
aberration corrections.
Note that using light time corrections alone ('LT') is
generally not a good way to obtain an approximation to an
apparent target vector: since light time and stellar
aberration corrections often partially cancel each other,
it may be more accurate to use no correction at all than to
use light time alone.
2) Find the corrected pointing direction to radiate a signal
to a target:
Use 'XLT+S': apply both light time and stellar
aberration corrections for transmission.
3) Obtain an uncorrected state vector derived directly from
data in an SPK file:
Use 'NONE'.
4) Compute the apparent position of a target body relative
to a star or other distant object:
Use 'LT' or 'LT+S' as needed to match the correction
applied to the position of the distant object. For
example, if a star position is obtained from a catalog,
the position vector may not be corrected for stellar
aberration. In this case, to find the angular
separation of the star and the limb of a planet, the
vector from the observer to the planet should be
corrected for light time but not stellar aberration.
5) Use a geometric state vector as a low-accuracy estimate
of the apparent state for an application where execution
speed is critical:
Use 'NONE'.
6) While this routine cannot perform the relativistic
aberration corrections required to compute states
with the highest possible accuracy, it can supply the
geometric states required as inputs to these computations:
Use 'NONE', then apply high-accuracy aberration
corrections (not available in the SPICE Toolkit).
Below, we discuss in more detail how the aberration corrections
applied by this routine are computed.
Geometric case
==============
SPKEZR begins by computing the geometric position T(ET) of the
target body relative to the solar system barycenter (SSB).
Subtracting the geometric position of the observer O(ET) gives
the geometric position of the target body relative to the
observer. The one-way light time, LT, is given by
| T(ET) - O(ET) |
LT = -------------------
c
The geometric relationship between the observer, target, and
solar system barycenter is as shown:
SSB ---> O(ET)
| /
| /
| /
| / T(ET) - O(ET)
V V
T(ET)
The returned state consists of the position vector
T(ET) - O(ET)
and a velocity obtained by taking the difference of the
corresponding velocities. In the geometric case, the
returned velocity is actually the time derivative of the
position.
Reception case
==============
When any of the options 'LT', 'CN', 'LT+S', 'CN+S' is
selected, SPKEZR computes the position of the target body at
epoch ET-LT, where LT is the one-way light time. Let T(t) and
O(t) represent the positions of the target and observer
relative to the solar system barycenter at time t; then LT is
the solution of the light-time equation
| T(ET-LT) - O(ET) |
LT = ------------------------ (1)
c
The ratio
| T(ET) - O(ET) |
--------------------- (2)
c
is used as a first approximation to LT; inserting (2) into the
RHS of the light-time equation (1) yields the "one-iteration"
estimate of the one-way light time. Repeating the process
until the estimates of LT converge yields the "converged
Newtonian" light time estimate.
Subtracting the geometric position of the observer O(ET) gives
the position of the target body relative to the observer:
T(ET-LT) - O(ET).
SSB ---> O(ET)
| \ |
| \ |
| \ | T(ET-LT) - O(ET)
| \ |
V V V
T(ET) T(ET-LT)
The position component of the light time corrected state
is the vector
T(ET-LT) - O(ET)
The velocity component of the light time corrected state
is the difference
T_vel(ET-LT) - O_vel(ET)
where T_vel and O_vel are, respectively, the velocities of the
target and observer relative to the solar system barycenter at
the epochs ET-LT and ET. This is NOT the derivative of the
light time corrected position because this does not take into
account the time derivative of LT.
If correction for stellar aberration is requested, the target
position is rotated toward the solar system
barycenter-relative velocity vector of the observer. The
rotation is computed as follows:
Let r be the light time corrected vector from the observer
to the object, and v be the velocity of the observer with
respect to the solar system barycenter. Let w be the angle
between them. The aberration angle phi is given by
sin(phi) = v sin(w) / c
Let h be the vector given by the cross product
h = r X v
Rotate r by phi radians about h to obtain the apparent
position of the object.
The velocity component of the output state STARG is
not corrected for stellar aberration.
Transmission case
==================
When any of the options 'XLT', 'XCN', 'XLT+S', 'XCN+S' is
selected, SPKEZR computes the position of the target body T at
epoch ET+LT, where LT is the one-way light time. LT is the
solution of the light-time equation
| T(ET+LT) - O(ET) |
LT = ------------------------ (3)
c
Subtracting the geometric position of the observer, O(ET),
gives the position of the target body relative to the
observer: T(ET-LT) - O(ET).
SSB --> O(ET)
/ | *
/ | * T(ET+LT) - O(ET)
/ |*
/ *|
V V V
T(ET+LT) T(ET)
The position component of the light-time corrected state
is the vector
T(ET+LT) - O(ET)
The velocity component of the light-time corrected state
consists of the difference
T_vel(ET+LT) - O_vel(ET)
where T_vel and O_vel are, respectively, the velocities of the
target and observer relative to the solar system barycenter at
the epochs ET+LT and ET. This is NOT the derivative of the
light time corrected position because this does not take into
account the time derivative of LT.
If correction for stellar aberration is requested, the target
position is rotated away from the solar system barycenter-
relative velocity vector of the observer. The rotation is
computed as in the reception case, but the sign of the
rotation angle is negated.
The velocity component of the output state STARG is
not corrected for stellar aberration.
Precision of light time corrections
===================================
Corrections using one iteration of the light time solution
----------------------------------------------------------
When the requested aberration correction is 'LT', 'LT+S',
'XLT', or 'XLT+S', only one iteration is performed in the
algorithm used to compute LT.
The relative error in this computation
| LT_ACTUAL - LT_COMPUTED | / LT_ACTUAL
is at most
(V/C)**2
----------
1 - (V/C)
which is well approximated by (V/C)**2, where V is the
velocity of the target relative to an inertial frame and C is
the speed of light.
For nearly all objects in the solar system V is less than 60
km/sec. The value of C is 300000 km/sec. Thus the one
iteration solution for LT has a potential relative error of
not more than 4*10**-8. This is a potential light time error
of approximately 2*10**-5 seconds per astronomical unit of
distance separating the observer and target. Given the bound
on V cited above:
As long as the observer and target are
separated by less than 50 astronomical units,
the error in the light time returned using
the one-iteration light time corrections
is less than 1 millisecond.
Converged corrections
---------------------
When the requested aberration correction is 'CN', 'CN+S',
'XCN', or 'XCN+S', three iterations are performed in the
computation of LT. The relative error present in this
solution is at most
(V/C)**4
----------
1 - (V/C)
which is well approximated by (V/C)**4. Mathematically the
precision of this computation is better than a nanosecond for
any pair of objects in the solar system.
However, to model the actual light time between target and
observer one must take into account effects due to general
relativity. These may be as high as a few hundredth of a
millisecond for some objects.
When one considers the extra time required to compute the
converged newtonian light time together with the real gain in
accuracy, it is unlikely that you will want to request either
the 'CN' or 'CN+S' light time corrections.
Relativistic Corrections
=========================
This routine does not attempt to perform either general or
special relativistic corrections in computing the various
aberration corrections. For many applications relativistic
corrections are not worth the expense of added computation
cycles. If however, your application requires these additional
corrections we suggest you consult the astronomical almanac (page
B36) for a discussion of how to carry out these corrections.