void swpool_c ( ConstSpiceChar * agent,
SpiceInt nnames,
SpiceInt lenvals,
const void * names )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
agent I The name of an agent to be notified after updates.
nnames I The number of variables to associate with agent.
lenvals I Length of strings in the names array.
names I Variable names whose update causes the notice.
-Detailed_Input
agent is the name of a routine or entry point (agency) that
will want to know when a some variables in the kernel
pool have been updated.
nnames is the number of kernel pool variable names that will
be associated with agent.
lenvals is the length of the strings in the array names,
including the null terminators.
names is an array of names of variables in the kernel pool.
Whenever any of these is updated, a notice will be
posted for agent so that one can quickly check
whether needed data has been modified.
-Detailed_Output
None.
-Parameters
None.
-Files
None.
-Exceptions
1) If sufficient room is not available to hold a name or new agent,
a routine in the call tree for this routine will signal an error.
2) If either of the input string pointers are null, the error
SPICE(NULLPOINTER) will be signaled.
3) If any input string agent has length zero, the error
SPICE(EMPTYSTRING) will be signaled.
4) The caller must pass a value indicating the length of the strings
in the names array. If this value is not at least 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
-Particulars
The kernel pool is a convenient place to store a wide variety of
data needed by routines in CSPICE and routines that interface with
CSPICE routines. However, when a single name has a large quantity
of data associated with it, it becomes inefficient to constantly
query the kernel pool for values that are not updated on a frequent
basis.
This entry point allows a routine to instruct the kernel pool to
post a message whenever a particular value gets updated. In this
way, a routine can quickly determine whether or not data it requires
has been updated since the last time the data was accessed. This
makes it reasonable to buffer the data in local storage and update
it only when a variable in the kernel pool that affects this data
has been updated.
Note that swpool_c has a side effect. Whenever a call to swpool_c
is made, the agent specified in the calling sequence is added to the
list of agents that should be notified that an update of its
variables has occurred. In other words the code
swpool_c ( agent, nnames, lenvals, names );
cvpool_c ( agent, &update );
will always return update as SPICETRUE.
This feature allows for a slightly cleaner use of swpool_c and
cvpool_c as shown in the example below. Because swpool_c
automatically loads agent into the list of agents to notify of a
kernel pool update, you do not have to include the code for fetching
the initial values of the kernel variables in the initialization
portion of a subroutine. Instead, the code for the first fetch from
the pool is the same as the code for fetching when the pool is
updated.
-Examples
Suppose that you have an application subroutine, MYTASK, that
needs to access a large data set in the kernel pool. If this
data could be kept in local storage and kernel pool queries
performed only when the data in the kernel pool has been
updated, the routine can perform much more efficiently.
The code fragment below illustrates how you might make use of this
feature.
#include "SpiceUsr.h"
.
.
.
/.
On the first call to this routine establish those variables
that we will want to read from the kernel pool only when
new values have been assigned.
./
if ( first )
{
first = SPICEFALSE;
swpool_c ( "MYTASK", nnames, lenvals, names );
}
/.
If any of the variables has been updated, fetch them from the
kernel pool.
./
cvpool_c ( "MYTASK", &update );
if ( update )
{
for ( i = 0; i < NVAR; i++ )
{
gdpool_c( MYTASK_VAR[i], 1, NMAX, n[i], val[i], &found[i] );
}
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.3.0, 27-AUG-2002 (NJB)
Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.
-CSPICE Version 1.2.0, 28-AUG-2001 (NJB)
Const-qualified input array names.
-CSPICE Version 1.1.0, 14-FEB-2000 (NJB)
Calls to C2F_CreateStrArr replaced with calls to error-signaling
version of this routine: C2F_CreateStrArr_Sig.
-CSPICE Version 1.0.0, 05-JUN-1999 (NJB) (WLT)
-Index_Entries
Watch for an update to a kernel pool variable
Notify a routine of an update to a kernel pool variable
-&
*/
{ /* Begin swpool_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
chkin_c ( "swpool_c" );
/*
Make sure the input string pointer for agent is non-null
and that the length is sufficient.
*/
CHKFSTR ( CHK_STANDARD, "swpool_c", agent );
/*
Make sure the input string pointer for the names array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR ( CHK_STANDARD, "swpool_c", names, lenvals );
/*
Create a Fortran-style string array.
*/
C2F_MapStrArr ( "swpool_c",
nnames, lenvals, names, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "swpool_c" );
return;
}
/*
Call the f2c'd routine.
*/
swpool_ ( ( char * ) agent,
( integer * ) &nnames,
( char * ) fCvalsArr,
( ftnlen ) strlen(agent),
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "swpool_c" );
} /* End swpool_c */
void pckcov_c ( ConstSpiceChar * pck,
SpiceInt idcode,
SpiceCell * cover )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
pck I Name of PCK file.
idcode I Class ID code of PCK reference frame.
cover I/O Window giving coverage in `pck' for `idcode'.
-Detailed_Input
pck is the name of a binary PCK file.
idcode is the integer frame class ID code of a PCK reference
frame for which data are expected to exist in the
specified PCK file.
cover is an initialized CSPICE window data structure.
`cover' optionally may contain coverage data on
input; on output, the data already present in `cover'
will be combined with coverage found for the
reference frame designated by `idcode' in the file
`pck'.
If `cover' contains no data on input, its size and
cardinality still must be initialized.
-Detailed_Output
cover is a CSPICE window data structure which represents
the merged coverage for the reference frame having
frame class ID `idcode'. This is the set of time
intervals for which data for `idcode' are present in
the file `pck', merged with the set of time intervals
present in `cover' on input. The merged coverage is
represented as the union of one or more disjoint time
intervals. The window `cover' contains the pairs of
endpoints of these intervals.
The interval endpoints contained in `cover' are
ephemeris times, expressed as seconds past J2000
TDB.
See the Examples section below for a complete
example program showing how to retrieve the
endpoints from `cover'.
-Parameters
None.
-Exceptions
1) If the input file has transfer format, the error
SPICE(INVALIDFORMAT) is signaled.
2) If the input file is not a transfer file but has architecture
other than DAF, the error SPICE(BADARCHTYPE) is signaled.
3) If the input file is a binary DAF file of type other than
PCK, the error SPICE(BADFILETYPE) is signaled.
4) If the PCK file cannot be opened or read, the error will
be diagnosed by routines called by this routine. The output
window will not be modified.
5) If the size of the output window argument COVER is
insufficient to contain the actual number of intervals in the
coverage window for IDCODE, the error will be diagnosed by
routines called by this routine.
6) The error SPICE(EMPTYSTRING) is signaled if the input
string `pck' does not contain at least one character, since the
input string cannot be converted to a Fortran-style string in
this case.
7) The error SPICE(NULLPOINTER) is signaled if the input string
pointer `pck' is null.
-Files
This routine reads a PCK file.
-Particulars
This routine provides an API via which applications can determine
the coverage a specified PCK file provides for a specified
PCK class reference frame.
-Examples
1) This example demonstrates combined usage of pckcov_c and the
related PCK utility pckfrm_c.
Display the coverage for each object in a specified PCK file.
Find the set of objects in the file; for each object, find
and display the coverage.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define MAXIV 1000
#define WINSIZ ( 2 * MAXIV )
#define TIMLEN 51
#define MAXOBJ 1000
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SPICEINT_CELL ( ids, MAXOBJ );
SpiceChar lsk [ FILSIZ ];
SpiceChar pck [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceDouble b;
SpiceDouble e;
SpiceInt i;
SpiceInt j;
SpiceInt niv;
SpiceInt obj;
/.
Load a leapseconds kernel for output time conversion.
PCKCOV itself does not require a leapseconds kernel.
./
prompt_c ( "Name of leapseconds kernel > ", FILSIZ, lsk );
furnsh_c ( lsk );
/.
Get name of PCK file.
./
prompt_c ( "Name of PCK file > ", FILSIZ, pck );
/.
Find the set of frames in the PCK file.
./
pckfrm_c ( pck, &ids );
/.
We want to display the coverage for each frame. Loop over
the contents of the ID code set, find the coverage for
each item in the set, and display the coverage.
./
for ( i = 0; i < card_c( &ids ); i++ )
{
/.
Find the coverage window for the current frame.
Empty the coverage window each time so we don't
include data for the previous frame.
./
obj = SPICE_CELL_ELEM_I( &ids, i );
scard_c ( 0, &cover );
pckcov_c ( pck, obj, &cover );
/.
Get the number of intervals in the coverage window.
./
niv = wncard_c ( &cover );
/.
Display a simple banner.
./
printf ( "%s\n", "========================================" );
printf ( "Coverage for frame %ld\n", obj );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( j = 0; j < niv; j++ )
{
/.
Get the endpoints of the jth interval.
./
wnfetd_c ( &cover, j, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
j,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
}
return ( 0 );
}
2) Find the coverage for the frame designated by `idcode'
provided by the set of PCK files loaded via a metakernel.
(The metakernel must also specify a leapseconds kernel.)
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define LNSIZE 81
#define MAXCOV 100000
#define WINSIZ ( 2 * MAXCOV )
#define TIMLEN 51
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SpiceBoolean found;
SpiceChar file [ FILSIZ ];
SpiceChar idch [ LNSIZE ];
SpiceChar meta [ FILSIZ ];
SpiceChar source [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceChar type [ LNSIZE ];
SpiceDouble b;
SpiceDouble e;
SpiceInt count;
SpiceInt handle;
SpiceInt i;
SpiceInt idcode;
SpiceInt niv;
/.
Prompt for the metakernel name; load the metakernel.
The metakernel lists the PCK files whose coverage
for `idcode' we'd like to determine. The metakernel
must also specify a leapseconds kernel.
./
prompt_c ( "Name of metakernel > ", FILSIZ, meta );
furnsh_c ( meta );
/.
Get the ID code of interest.
./
prompt_c ( "Enter ID code > ", LNSIZE, idch );
prsint_c ( idch, &idcode );
/.
Find out how many kernels are loaded. Loop over the
kernels: for each loaded PCK file, add its coverage
for `idcode', if any, to the coverage window.
./
ktotal_c ( "PCK", &count );
for ( i = 0; i < count; i++ )
{
kdata_c ( i, "PCK", FILSIZ, LNSIZE, FILSIZ,
file, type, source, &handle, &found );
pckcov_c ( file, idcode, &cover );
}
/.
Display results.
Get the number of intervals in the coverage window.
./
niv = wncard_c ( &cover );
/.
Display a simple banner.
./
printf ( "\nCoverage for frame %ld\n", idcode );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( i = 0; i < niv; i++ )
{
/.
Get the endpoints of the ith interval.
./
wnfetd_c ( &cover, i, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
i,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
return ( 0 );
}
-Restrictions
1) If an error occurs while this routine is updating the window
`cover', the window may be corrupted.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.1, 01-JUL-2014 (NJB)
Updated index entries.
-CSPICE Version 1.0.0, 30-NOV-2007 (NJB)
-Index_Entries
get coverage window for binary pck reference frame
get coverage start and stop time for binary pck frame
-&
*/
{ /* Begin pckcov_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "pckcov_c" );
/*
Check the input string `pck' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "pckcov_c", pck );
/*
Make sure cell data type is d.p.
*/
CELLTYPECHK ( CHK_STANDARD, "pckcov_c", SPICE_DP, cover );
/*
Initialize the cell if necessary.
*/
CELLINIT ( cover );
/*
Call the f2c'd Fortran routine.
*/
pckcov_ ( ( char * ) pck,
( integer * ) &idcode,
( doublereal * ) (cover->base),
( ftnlen ) strlen(pck) );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, cover );
}
chkout_c ( "pckcov_c" );
} /* End pckcov_c */
void frmnam_c ( SpiceInt frcode,
SpiceInt lenout,
SpiceChar * frname )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
frcode I an integer code for a reference frame
lenout I Maximum length of output string.
frname O the name associated with the reference frame.
-Detailed_Input
frcode is an integer code for a reference frame.
lenout is the maximum number of characters that can be
accommodated in the output string. This count
includes room for the terminating null character.
For example, if the maximum allowed length of the
output string, including the terminating null, is 33
characters, then lenout should be set to 33.
-Detailed_Output
frname is the name associated with the reference frame.
It will be returned left-justified.
If frcode is not recognized as the name of a
known reference frame, frname will be returned
as an empty string.
If frname is not sufficiently long to hold the
name, it will be truncated on the right.
All reference frame names are 32 or fewer characters
in length. Thus declaring frname to be SpiceChar[33]
will ensure that the returned name will not be
truncated.
-Parameters
None.
-Exceptions
1) If frcode is not recognized as the name of a known reference
frame, frname will be returned as a blank.
2) If the output string pointer is null, the error SPICE(NULLPOINTER)
is signaled.
3) If the output string has length less than two characters, it
is too short to contain one character of output data plus a null
terminator, so it cannot be passed to the underlying Fortran
routine. In this event, the error SPICE(STRINGTOOSHORT) is
signaled.
4) If the length of frname (indicated by lenout) is at least two
characters but not large enough to contain the output string,
the output string will be truncated on the right.
-Files
None.
-Particulars
This routine retrieves the name of a reference frame associated
with a SPICE frame ID code.
The ID codes stored locally are scanned for a match with frcode.
If a match is found, the name stored locally will be returned
as the name for the frame.
If frcode is not a member of the list of internally stored
ID codes, the kernel pool will be examined to see if the
variable
FRAME_idcode_NAME
is present (where idcode is the decimal character equivalent
of frcode). If the variable is located and it has both
character type and dimension 1, the string value of the
kernel pool variable is returned as the name of the reference
frame.
Note that because the local information is always examined
first and searches of the kernel pool are performed only
after exhausting local information, it is not possible to
override the local name for any reference frame that is
known by this routine.
-Examples
Suppose you needed to create a message concerning a reference
frame and wish to use the name of the frame in the message.
Suppose further that you have only the frame ID code at your
disposal. You can capture the frame name using this routine
as shown here.
#include "SpiceUsr.h"
.
.
.
#define NAMELEN 33
SpiceChar frname [NAMELEN];
SpiceInt frcode;
frmnam_c ( frcode, NAMELEN, frname );
if ( iswhsp_c(frname) )
{
sprintf ( frname, "%ld", frcode );
}
printf ( "Concerning reference frame: %s\n", frname );
[Print the rest of your message.]
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
W.L. Taber (JPL)
B.V. Semenov (JPL)
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.2, 08-JAN-2014 (BVS)
Fixed typo in Examples (frname_c -> frmnam_c). Reordered
header sections.
-CSPICE Version 1.0.1, 26-MAR-2003 (NJB)
Fixed description of exception (4): replaced "lenout-1"
with "lenout." Removed spurious word "clock" from string
description.
-CSPICE Version 1.0.0, 13-AUG-2001 (NJB) (WLT)
-Index_Entries
Frame idcode to frame name translation
-&
*/
{ /* Begin frmnam_c */
/*
Participate in error tracing.
*/
chkin_c ( "frmnam_c" );
/*
Make sure the output frmnam has at least enough room for one output
character and a null terminator. Also check for a null pointer.
*/
CHKOSTR ( CHK_STANDARD, "frmnam_c", frname, lenout );
/*
Do the conversion.
*/
frmnam_ ( ( integer * ) &frcode,
( char * ) frname,
( ftnlen ) lenout-1 );
/*
Convert the Fortran string to a C string by placing a null
after the last non-blank character. This operation is valid
whether or not the CSPICE routine signaled an error.
*/
F2C_ConvertStr ( lenout, frname );
chkout_c ( "frmnam_c" );
} /* End frmnam_c */
void getelm_c ( SpiceInt frstyr,
SpiceInt lineln,
const void * lines,
SpiceDouble * epoch,
SpiceDouble * elems )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
frstyr I Year of earliest representable two-line elements.
lineln I Length of strings in lines array.
lines I A pair of "lines" containing two-line elements.
epoch O The epoch of the elements in seconds past J2000.
elems O The elements converted to SPICE units.
-Detailed_Input
frstyr is the first year possible for two line elements. Since
two line elements allow only two digits for the year, some
conventions must be followed concerning which century the
two digits refer to. frstyr is the year of the earliest
representable elements. The two-digit year is mapped to
the year in the interval from frstyr to frstyr + 99 that
has the same last two digits as the two digit year in the
element set. For example if frstyr is set to 1960 then
the two digit years are mapped as shown in the table
below:
Two-line Maps to
element year
00 2000
01 2001
02 2002
. .
. .
. .
58 2058
59 2059
--------------------
60 1960
61 1961
62 1962
. .
. .
. .
99 1999
Note that if Space Command should decide to represent
years in 21st century as 100 + the last two digits of the
year (for example: 2015 is represented as 115) instead of
simply dropping the first two digits of the year, this
routine will correctly map the year as long as you set
frstyr to some value between 1900 and 1999.
lines is a pair of lines of text that comprise a Space command
``two-line element'' set. lines should be declared
SpiceChar lines[2][lineln];
These text lines should be the same as they are presented
in the two-line element files available from Space
Command (formerly NORAD). Below is an example of a
two-line set for TOPEX.
TOPEX
1 22076U 92052A 97173.53461370 -.00000038 00000-0 10000-3 0 594
2 22076 66.0378 163.4372 0008359 278.7732 81.2337 12.80930736227550
-Detailed_Output
epoch is the epoch of the two line elements supplied via
the input array lines. Epoch is returned in TDB
seconds past J2000.
elems is an array containing the elements from the two line
set supplied via the array lines. The elements are
in units suitable for use by the CSPICE routine
ev2lin_.
Also note that the elements XNDD6O and BSTAR
incorporate the exponential factor present in the
input two line elements in LINES. (See particulars
below.
ELEMS [ 0 ] = XNDT2O in radians/minute**2
ELEMS [ 1 ] = XNDD6O in radians/minute**3
ELEMS [ 2 ] = BSTAR
ELEMS [ 3 ] = XINCL in radians
ELEMS [ 4 ] = XNODEO in radians
ELEMS [ 5 ] = EO
ELEMS [ 6 ] = OMEGAO in radians
ELEMS [ 7 ] = XMO in radians
ELEMS [ 8 ] = XNO in radians/minute
ELEMS [ 9 ] = EPOCH of the elements in seconds
past ephemeris epoch J2000.
-Parameters
None.
-Exceptions
No checking of the inputs is performed in this routine. However, this
routine does call other CSPICE routines. If one of these routines
detects an error it will diagnose it and signal an error.
-Files
You must have loaded a SPICE leapseconds kernel into the
kernel pool prior to caling this routine.
-Particulars
This routine parses a Space Command Two-line element set and returns
the orbital elements properly scaled and in units suitable for use
by other SPICE software. Input elements look like the following
---------------------------------------------------------------------
1 22076U 92052A 97173.53461370 -.00000038 00000-0 10000-3 0 594
2 22076 66.0378 163.4372 0008359 278.7732 81.2337 12.80930736227550
---------------------------------------------------------------------
^
123456789012345678901234567890123456789012345678901234567890123456789
1 2 3 4 5 6
The ``raw'' elements in the first and second lines are marked below.
Note that in several instances exponents and decimal points are
implied. Also note that input units are degrees, degrees/day**n and
revolutions/day.
DAY OF YEAR NDD60 BSTAR
vvvvvvvvvvvv vvvvvv vvvvvv
---------------------------------------------------------------------
1 22076U 92052A 97173.53461370 -.00000038 00000-0 10000-3 0 594
---------------------------------------------------------------------
^^ ^^^^^^^^^^ ^^ ^^
YEAR NDT20 IEXP IBEXP
The ``raw'' elements in the second line are marked below
NODE0 OMEGA N0
vvvvvvvv vvvvvvvv vvvvvvvvvvv
---------------------------------------------------------------------
2 22076 66.0378 163.4372 0008359 278.7732 81.2337 12.80930736227550
---------------------------------------------------------------------
^^^^^^^^ ^^^^^^^ ^^^^^^^^
Inclination Eccentricity M0
This routine extracts these values ``inserts'' the implied
decimal points and exponents and then converts the inputs
to units of radians, radians/minute, radians/minute**2, and
radians/minute**3
-Examples
Suppose you have a set of two-line elements and an array containing
the related geophysical constants necessary to evaluate a state.
The example below shows how you can use this routine together with
the routine EV2LIN to propagate a state to an epoch of interest.
#include <string.h>
#include <stdio.h>
#include "SpiceUsr.h"
SpiceDouble et;
SpiceDouble epoch;
SpiceInt frstyr;
.
.
.
/.
The parameters below will make it easier to make assignments
to the array GEOPHS required by EV2LIN.
J2 --- location of J2
J3 --- location of J3
J4 --- location if J4
KE --- location of KE = sqrt(GM) in eart-radii**1.5/MIN
QO --- location of upper bound of atmospheric model in KM
SO --- location of lower bound of atmospheric model in KM
ER --- location of earth equatorial radius in KM.
AE --- location of distance units/earth radius
./
#define J2 0
#define J3 1
#define J4 2
#define KE 3
#define QO 4
#define SO 5
#define ER 6
#define AE 7
/.
We set the lower bound for the years to be the beginning
of the space age.
./
frstyr = 1957;
/.
Read in the next two lines from the text file that contains
the two-line elements. We assume that file has been opened
properly and that we have set the ``file pointer'' to the
correct location for reading the next set of elements.
./
for ( i = 0; i < 2; i++ )
{
fgets ( line[i], lineln, textfile );
line[i][ strlen(line[i]) ] = '\0';
}
getelm_c ( frstyr, lineln, line, &epoch, elems );
/.
Set up the geophysical quantities. At last check these
were the values used by Space Command.
./
geophs[ J2 ] = 1.082616e-3;
geophs[ J3 ] = -2.53881e-6;
geophs[ J4 ] = -1.65597e-6;
geophs[ KE ] = 7.43669161e-2;
geophs[ QO ] = 120.0;
geophs[ SO ] = 78.0;
geophs[ ER ] = 6378.135;
geophs[ AE ] = 1.0;
/.
Now propagate the state using ev2lin_ to the epoch of
interest.
./
ev2lin_ ( &et, geophs, elems, state );
-Restrictions
The format of the two-line elements suffer from a "millenium"
problem---only two digits are used for the year of the elements. It
is not clear how Space Command will deal with this problem as the
year 2000 comes and goes. We hope that by adjusting the input frstyr
you should be able to use this routine well into the 21st century.
However, since we can't predict how others will resolve the millenium
problem we can't be sure that our approach will be addequate to deal
with the problem.
The approach taken to mapping the two-digit year to the full year is
given by the code below. Here, yr is the integer obtained by parsing
the two-digit year from the first line of the elements.
begyr = (frstyr/100)*100;
year = begyr + yr;
if ( year < frstyr )
{
year += 100;
}
This mapping will be changed if future two-line element
representations make this method of computing the full year
inaccurate.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.0.1, 15-NOV-2007 (EDW)
Minor edits to example section; the getelm_c call lacked
the 'lineln' argument, the use of 'et' implied a pointer
rather than a value.
-CSPICE Version 1.0.0, 06-AUG-1999 (NJB) (WLT)
-Index_Entries
Parse two-line elements
-&
*/
{ /* Begin getelm_c */
/*
Local constants
*/
#define NELTS 2
/*
Local variables
*/
SpiceChar ** cvalsPtr;
SpiceChar * fCvalsArr;
SpiceInt i;
SpiceInt fCvalsLen;
SpiceStatus status;
/*
Participate in error tracing.
*/
chkin_c ( "getelm_c" );
/*
Check the input line array for null pointer of insufficient string
length.
*/
CHKOSTR ( CHK_STANDARD, "getelm_c", lines, lineln );
/*
Convert the input string array to a Fortran-style string array.
We'll first allocate an array of character pointers to index
the values, initialize this array, and use it to produce
a dynamically allocated array of Fortran-style strings.
*/
cvalsPtr = ( SpiceChar ** ) malloc ( NELTS * sizeof(SpiceChar *) );
if ( cvalsPtr == 0 )
{
setmsg_c ( "Failure on malloc call to create pointer array "
"for line values." );
sigerr_c ( "SPICE(MALLOCFAILED)" );
chkout_c ( "getelm_c" );
return;
}
for ( i = 0; i < NELTS; i++ )
{
cvalsPtr[i] = (SpiceChar *)lines + ( i * lineln );
}
status = C2F_CreateStrArr ( NELTS,
( ConstSpiceChar ** ) cvalsPtr,
&fCvalsLen,
&fCvalsArr );
/* fCvalsArr[2*fCvalsLen] = '\0'; */
if ( status == SPICEFAILURE )
{
free ( cvalsPtr );
setmsg_c ( "C to Fortran string array conversion for `lines' "
"failed." );
sigerr_c ( "SPICE(STRINGCONVERROR)" );
chkout_c ( "getelm_c" );
return;
}
/*
Call the f2c'd routine.
*/
getelm_ ( ( integer * ) &frstyr,
( char * ) fCvalsArr,
( doublereal * ) epoch,
( doublereal * ) elems,
( ftnlen ) fCvalsLen );
/*
Clean up all of our dynamically allocated arrays.
*/
free ( cvalsPtr );
free ( fCvalsArr );
chkout_c ( "getelm_c" );
} /* End getelm_c */
void nplnpt_c ( ConstSpiceDouble linpt [3],
ConstSpiceDouble lindir [3],
ConstSpiceDouble point [3],
SpiceDouble pnear [3],
SpiceDouble * dist )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
linpt,
lindir I Point on a line and the line's direction vector.
point I A second point.
pnear O Nearest point on the line to point.
dist O Distance between point and pnear.
-Detailed_Input
linpt
lindir are, respectively, a point and a direction vector
that define a line in 3-dimensional space. The
line is the set of points
linpt + t * lindir
where t is any real number.
point is a point in 3-dimensional space.
-Detailed_Output
pnear is the nearest point on the input line to the input
point.
dist is the distance between the input line and input
point.
-Parameters
None.
-Exceptions
1) If the line direction vector lindir is the zero vector, the
error SPICE(ZEROVECTOR) is signaled.
-Files
None.
-Particulars
For every line L and point P, there is a unique closest point
on L to P. Call this closest point C. It is always true that
P - C is perpendicular to L, and the length of P - C is called
the "distance" between P and L.
-Examples
1) Suppose a line passes through the point ( 1, 2, 3 ) and
has direction vector ( 0, 1, 1 ). We wish to find the
closest point on the line to the point ( -6, 9, 10 ). We
can use the code fragment
#include "SpiceUsr.h"
.
.
.
LINPT[0] = 1.0;
LINPT[1] = 2.0;
LINPT[2] = 3.0;
LINDIR[0] = 0.0;
LINDIR[1] = 1.0;
LINDIR[2] = 1.0;
POINT[0] = -6.0;
POINT[1] = 9.0;
POINT[2] = 10.0;
nplnpt_c ( linpt, lindir, point, pnear, &dist );
After the call, pnear will take the value
( 1., 9., 10. );
dist will be 7.0.
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.0, 16-AUG-1999 (NJB)
-Index_Entries
distance between point and line
nearest point on line to point
-&
*/
{ /* Begin nplnpt_c */
/*
Local variables
*/
SpiceDouble trans [3];
/*
We need a real direction vector to work with.
*/
if ( vzero_c (lindir) )
{
chkin_c ( "nplnpt_c" );
setmsg_c ( "Direction vector must be non-zero." );
sigerr_c ( "SPICE(ZEROVECTOR)" );
chkout_c ( "nplnpt_c" );
return;
}
/*
We translate line and input point so as to put the line through
the origin. Then the nearest point on the translated line to the
translated point TRANS is the projection of TRANS onto the line.
*/
vsub_c ( point, linpt, trans );
vproj_c ( trans, lindir, pnear );
vadd_c ( pnear, linpt, pnear );
*dist = vdist_c ( pnear, point );
} /* End nplnpt_c */
void gfrr_c ( ConstSpiceChar * target,
ConstSpiceChar * abcorr,
ConstSpiceChar * obsrvr,
ConstSpiceChar * relate,
SpiceDouble refval,
SpiceDouble adjust,
SpiceDouble step,
SpiceInt nintvls,
SpiceCell * cnfine,
SpiceCell * result )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
SPICE_GF_CNVTOL P Convergence tolerance
target I Name of the target body.
abcorr I Aberration correction flag.
obsrvr I Name of the observing body.
relate I Relational operator.
refval I Reference value.
adjust I Adjustment value for absolute extrema searches.
step I Step size used for locating extrema and roots.
nintvls I Workspace window interval count.
cnfine I-O SPICE window to which the search is confined.
result O SPICE window containing results.
-Detailed_Input
target is the name of a target body. The target body is
an ephemeris object; its trajectory is given by
SPK data.
The string `target' is case-insensitive, and leading
and trailing blanks in `target' are not significant.
Optionally, you may supply a string containing the
integer ID code for the object. For example both
"MOON" and "301" are legitimate strings that indicate
the Moon is the target body.
The target and observer define a position vector which
points from the observer to the target; the time derivative
length of this vector is the "range rate" that serves as
the subject of the search performed by this routine.
abcorr indicates the aberration corrections to be applied to
the observer-target state vector to account for
one-way light time and stellar aberration.
Any aberration correction accepted by the SPICE
routine spkezr_c is accepted here. See the header
of spkezr_c for a detailed description of the
aberration correction options. For convenience,
the options are listed below:
"NONE" Apply no correction.
"LT" "Reception" case: correct for
one-way light time using a Newtonian
formulation.
"LT+S" "Reception" case: correct for
one-way light time and stellar
aberration using a Newtonian
formulation.
"CN" "Reception" case: converged
Newtonian light time correction.
"CN+S" "Reception" case: converged
Newtonian light time and stellar
aberration corrections.
"XLT" "Transmission" case: correct for
one-way light time using a Newtonian
formulation.
"XLT+S" "Transmission" case: correct for
one-way light time and stellar
aberration using a Newtonian
formulation.
"XCN" "Transmission" case: converged
Newtonian light time correction.
"XCN+S" "Transmission" case: converged
Newtonian light time and stellar
aberration corrections.
Case and blanks are not significant in the string
`abcorr'.
obsrvr is the name of the observing body. The observing body is
an ephemeris object; its trajectory is given by SPK
data. `obsrvr' is case-insensitive, and leading and
trailing blanks in `obsrvr' are not significant.
Optionally, you may supply a string containing the
integer ID code for the object. For example both "MOON"
and "301" are legitimate strings that indicate the Moon
is the observer.
relate is a relational operator used to define a constraint
on observer-target range rate. The result window found
by this routine indicates the time intervals where
the constraint is satisfied. Supported values of
`relate' and corresponding meanings are shown below:
">" Distance is greater than the reference
value `refval'.
"=" Distance is equal to the reference
value `refval'.
"<" Distance is less than the reference
value `refval'.
"ABSMAX" Distance is at an absolute maximum.
"ABSMIN" Distance is at an absolute minimum.
"LOCMAX" Distance is at a local maximum.
"LOCMIN" Distance is at a local minimum.
The caller may indicate that the region of interest
is the set of time intervals where the quantity is
within a specified distance of an absolute extremum.
The argument `adjust' (described below) is used to
specify this distance.
Local extrema are considered to exist only in the
interiors of the intervals comprising the confinement
window: a local extremum cannot exist at a boundary
point of the confinement window.
Case is not significant in the string `relate'.
refval is the reference value used together with the argument
`relate' to define an equality or inequality to be
satisfied by the range rate between the specified target
and observer. See the discussion of `relate' above for
further information.
The units of `refval' are km/sec.
adjust is a parameter used to modify searches for absolute
extrema: when `relate' is set to "ABSMAX" or "ABSMIN" and
`adjust' is set to a positive value, gfdist_c will find
times when the observer-target range rate is within
`adjust' km/sec of the specified extreme value.
If `adjust' is non-zero and a search for an absolute
minimum `min' is performed, the result window contains
time intervals when the observer-target range rate has
values between `min' and min+adjust.
If the search is for an absolute maximum `max', the
corresponding range is from max-adjust to `max'.
`adjust' is not used for searches for local extrema,
equality or inequality conditions.
step is the step size to be used in the search. `step' must
be short enough for a search using this step size
to locate the time intervals where the specified
range rate function is monotone increasing or
decreasing. However, `step' must not be *too* short, or
the search will take an unreasonable amount of time.
The choice of `step' affects the completeness but not
the precision of solutions found by this routine; the
precision is controlled by the convergence tolerance.
See the discussion of the parameter SPICE_GF_CNVTOL for
details.
`step' has units of TDB seconds.
nintvls is a parameter specifying the number of intervals that
can be accommodated by each of the dynamically allocated
windows used internally by this routine. `nintvls' should
be at least as large as the number of intervals within
the search region on which the specified range rate
function is monotone increasing or decreasing. See
the Examples section below for code examples illustrating
the use of this parameter.
cnfine is a SPICE window that confines the time period over
which the specified search is conducted. `cnfine' may
consist of a single interval or a collection of
intervals.
In some cases the confinement window can be used to
greatly reduce the time period that must be searched
for the desired solution. See the Particulars section
below for further discussion.
See the Examples section below for a code example
that shows how to create a confinement window.
-Detailed_Output
cnfine is the input confinement window, updated if necessary
so the control area of its data array indicates the
window's size and cardinality. The window data are
unchanged.
result is the window of intervals, contained within the
confinement window `cnfine', on which the specified
constraint is satisfied.
If `result' is non-empty on input, its contents will be
discarded before 'gfrr_c' conducts its search.
`result' must be declared with sufficient size to capture
the full set of time intervals within the search region
on which the specified constraint is satisfied.
If the search is for local extrema, or for absolute
extrema with `adjust' set to zero, then normally each
interval of `result' will be a singleton: the left and
right endpoints of each interval will be identical.
If no times within the confinement window satisfy the
constraint, `result' will be returned with a cardinality
of zero.
-Parameters
SPICE_GF_CNVTOL
is the convergence tolerance used for finding endpoints
of the intervals comprising the result window.
SPICE_GF_CNVTOL is used to determine when binary searches
for roots should terminate: when a root is bracketed
within an interval of length SPICE_GF_CNVTOL, the root is
considered to have been found.
The accuracy, as opposed to precision, of roots found
by this routine depends on the accuracy of the input
data. In most cases, the accuracy of solutions will be
inferior to their precision.
SPICE_GF_CNVTOL is declared in the header file SpiceGF.h.
-Exceptions
1) In order for this routine to produce correct results,
the step size must be appropriate for the problem at hand.
Step sizes that are too large may cause this routine to miss
roots; step sizes that are too small may cause this routine
to run unacceptably slowly and in some cases, find spurious
roots.
This routine does not diagnose invalid step sizes, except
that if the step size is non-positive, an error is signaled
by a routine in the call tree of this routine.
2) Due to numerical errors, in particular,
- Truncation error in time values
- Finite tolerance value
- Errors in computed geometric quantities
it is *normal* for the condition of interest to not always be
satisfied near the endpoints of the intervals comprising the
result window.
The result window may need to be contracted slightly by the
caller to achieve desired results. The SPICE window routine
wncond_c can be used to contract the result window.
3) If an error (typically cell overflow) occurs while performing
window arithmetic, the error will be diagnosed by a routine
in the call tree of this routine.
4) If the relational operator `relate' is not recognized, an
error is signaled by a routine in the call tree of this
routine.
5) If the aberration correction specifier contains an
unrecognized value, an error is signaled by a routine in the
call tree of this routine.
6) If 'adjust' is negative, the error SPICE(VALUEOUTOFRANGE) will
signal from a routine in the call tree of this routine.
A non-zero value for 'adjust' when 'relate' has any value other than
"ABSMIN" or "ABSMAX" causes the error SPICE(INVALIDVALUE) to
signal from a routine in the call tree of this routine.
7) If either of the input body names do not map to NAIF ID
codes, an error is signaled by a routine in the call tree of
this routine.
8) If required ephemerides or other kernel data are not
available, an error is signaled by a routine in the call tree
of this routine.
9) If the workspace interval count is less than 1, the error
SPICE(VALUEOUTOFRANGE) will be signaled.
10) If the required amount of workspace memory cannot be
allocated, the error SPICE(MALLOCFAILURE) will be
signaled.
11) If any input string argument pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
12) If any input string argument is empty, the error
SPICE(EMPTYSTRING) will be signaled.
13) If either input cell has type other than SpiceDouble,
the error SPICE(TYPEMISMATCH) is signaled.
-Files
Appropriate kernels must be loaded by the calling program before
this routine is called.
The following data are required:
- SPK data: ephemeris data for target and observer for the
time period defined by the confinement window must be
loaded. If aberration corrections are used, the states of
target and observer relative to the solar system barycenter
must be calculable from the available ephemeris data.
Typically ephemeris data are made available by loading one
or more SPK files via furnsh_c.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
-Particulars
This routine determines if the caller-specified constraint condition
on the geometric event (range rate) is satisfied for any time intervals
within the confinement window 'cnfine'. If one or more such time
intervals exist, those intervals are added to the 'result' window.
This routine provides a simpler, but less flexible interface
than does the routine gfevnt_c for conducting the searches for
observer-target range rate value events. Applications that require
support for progress reporting, interrupt handling, non-default step
or refinement functions, or non-default convergence tolerance should
call gfevnt_c rather than this routine.
Below we discuss in greater detail aspects of this routine's
solution process that are relevant to correct and efficient
use of this routine in user applications.
The Search Process
==================
Regardless of the type of constraint selected by the caller, this
routine starts the search for solutions by determining the time
periods, within the confinement window, over which the specified
range rate function is monotone increasing and monotone decreasing.
Each of these time periods is represented by a SPICE window. Having
found these windows, all of the range rate function's local extrema
within the confinement window are known. Absolute extrema then can
be found very easily.
Within any interval of these "monotone" windows, there will be at
most one solution of any equality constraint. Since the boundary
of the solution set for any inequality constraint is contained in
the union of
- the set of points where an equality constraint is met
- the boundary points of the confinement window
the solutions of both equality and inequality constraints can be
found easily once the monotone windows have been found.
Step Size
=========
The monotone windows (described above) are found via a two-step
search process. Each interval of the confinement window is
searched as follows: first, the input step size is used to
determine the time separation at which the sign of the rate of
change of range rate will be sampled. Starting at
the left endpoint of an interval, samples will be taken at each
step. If a change of sign is found, a root has been bracketed; at
that point, the time at which the range rate is zero can be
found by a refinement process, for example, via binary search.
Note that the optimal choice of step size depends on the lengths
of the intervals over which the range rate function is monotone:
the step size should be shorter than the shortest of these
intervals (within the confinement window).
The optimal step size is *not* necessarily related to the lengths
of the intervals comprising the result window. For example, if
the shortest monotone interval has length 10 days, and if the
shortest result window interval has length 5 minutes, a step size
of 9.9 days is still adequate to find all of the intervals in the
result window. In situations like this, the technique of using
monotone windows yields a dramatic efficiency improvement over a
state-based search that simply tests at each step whether the
specified constraint is satisfied. The latter type of search can
miss solution intervals if the step size is longer than the
shortest solution interval.
Having some knowledge of the relative geometry of the target and
observer can be a valuable aid in picking a reasonable step size.
In general, the user can compensate for lack of such knowledge by
picking a very short step size; the cost is increased computation
time.
Note that the step size is not related to the precision with which
the endpoints of the intervals of the result window are computed.
That precision level is controlled by the convergence tolerance.
Convergence Tolerance
=====================
As described above, the root-finding process used by this routine
involves first bracketing roots and then using a search process to
locate them. "Roots" include times when extrema are attained and
times when the geometric quantity function is equal to a reference
value or adjusted extremum. All endpoints of the intervals comprising
the result window are either endpoints of intervals of the confinement
window or roots.
Once a root has been bracketed, a refinement process is used to
narrow down the time interval within which the root must lie.
This refinement process terminates when the location of the root
has been determined to within an error margin called the
"convergence tolerance." The convergence tolerance used by this
routine is set via the parameter SPICE_GF_CNVTOL.
The value of SPICE_GF_CNVTOL is set to a "tight" value so that the
tolerance doesn't limit the accuracy of solutions found by this
routine. In general the accuracy of input data will be the limiting
factor.
The user may change the convergence tolerance from the default
SPICE_GF_CNVTOL value by calling the routine gfstol_c, e.g.
gfstol_c( tolerance value in seconds )
Call gfstol_c prior to calling this routine. All subsequent
searches will use the updated tolerance value.
Searches over time windows of long duration may require use of
larger tolerance values than the default: the tolerance must be
large enough so that it, when added to or subtracted from the
confinement window's lower and upper bounds, yields distinct time
values.
Setting the tolerance tighter than SPICE_GF_CNVTOL is unlikely to be
useful, since the results are unlikely to be more accurate.
Making the tolerance looser will speed up searches somewhat,
since a few convergence steps will be omitted. However, in most
cases, the step size is likely to have a much greater effect
on processing time than would the convergence tolerance.
The Confinement Window
======================
The simplest use of the confinement window is to specify a time
interval within which a solution is sought. However, the
confinement window can, in some cases, be used to make searches
more efficient. Sometimes it's possible to do an efficient search
to reduce the size of the time period over which a relatively
slow search of interest must be performed.
Consider the following example: suppose one wishes to find the
times when the range rate between Io and the Earth attains a global
minimum over some (lengthy) time interval. There is one local
minimum every few days. The required step size for this search
must be smaller than the shortest interval on which the range rate
is monotone increasing or decreasing; this step size will be less
than half the average time between local minima. However, we know
that a global minimum can't occur when the Jupiter-Sun-Earth
angle is greater than 90 degrees. We can use a step size of a
half year to find the time period, within our original time
interval, during which this angle is less than 90 degrees; this
time period becomes the confinement window for our Earth-Io
range rate search. This way we've used a quick (due to the large
step size) search to cut out about half of the search period over
which we must perform a slower search using a small step size.
-Examples
The numerical results shown for these examples may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: standard.tm
This meta-kernel is intended to support operation of SPICE
example programs. The kernels shown here should not be
assumed to contain adequate or correct versions of data
required by SPICE-based user applications.
In order for an application to use this meta-kernel, the
kernels referenced here must be present in the user's
current working directory.
The names and contents of the kernels referenced
by this meta-kernel are as follows:
File name Contents
--------- --------
de421.bsp Planetary ephemeris
pck00009.tpc Planet orientation and
radii
naif0009.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'pck00009.tpc',
'naif0009.tls' )
\begintext
Example:
Determine the time windows from January 1, 2007 UTC to
April 1, 2007 UTC for which the sun-moon range rate satisfies the
relation conditions with respect to a reference value of
0.3365 km/s radians (this range rate known to occur within the
search interval). Also determine the time windows corresponding
to the local maximum and minimum range rate, and the absolute
maximum and minimum range rate during the search interval.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "SpiceUsr.h"
#define MAXWIN 20000
#define TIMFMT "YYYY-MON-DD HR:MN:SC.###"
#define TIMLEN 41
#define NLOOPS 7
int main( int argc, char **argv )
{
/.
Create the needed windows. Note, one window
consists of two values, so the total number
of cell values to allocate is twice
the number of intervals.
./
SPICEDOUBLE_CELL ( result, 2*MAXWIN );
SPICEDOUBLE_CELL ( cnfine, 2 );
SpiceDouble begtim;
SpiceDouble endtim;
SpiceDouble step;
SpiceDouble adjust;
SpiceDouble refval;
SpiceDouble beg;
SpiceDouble end;
SpiceChar begstr [ TIMLEN ];
SpiceChar endstr [ TIMLEN ];
SpiceChar * target = "MOON";
SpiceChar * abcorr = "NONE";
SpiceChar * obsrvr = "SUN";
SpiceInt count;
SpiceInt i;
SpiceInt j;
ConstSpiceChar * relate [NLOOPS] = { "=",
"<",
">",
"LOCMIN",
"ABSMIN",
"LOCMAX",
"ABSMAX",
};
/.
Load kernels.
./
furnsh_c( "standard.tm" );
/.
Store the time bounds of our search interval in
the cnfine confinement window.
./
str2et_c( "2007 JAN 01", &begtim );
str2et_c( "2007 APR 01", &endtim );
wninsd_c ( begtim, endtim, &cnfine );
/.
Search using a step size of 1 day (in units of seconds).
The reference value is .3365 km/s. We're not using the
adjustment feature, so we set 'adjust' to zero.
./
step = spd_c();
adjust = 0.;
refval = .3365;
for ( j = 0; j < NLOOPS; j++ )
{
printf ( "Relation condition: %s \n", relate[j] );
/.
Perform the search. The SPICE window 'result' contains
the set of times when the condition is met.
./
gfrr_c ( target,
abcorr,
obsrvr,
relate[j],
refval,
adjust,
step,
MAXWIN,
&cnfine,
&result );
count = wncard_c( &result );
/.
Display the results.
./
if (count == 0 )
{
printf ( "Result window is empty.\n\n" );
}
else
{
for ( i = 0; i < count; i++ )
{
/.
Fetch the endpoints of the Ith interval
of the result window.
./
wnfetd_c ( &result, i, &beg, &end );
timout_c ( beg, TIMFMT, TIMLEN, begstr );
timout_c ( end, TIMFMT, TIMLEN, endstr );
printf ( "Start time, drdt = %s \n", begstr );
printf ( "Stop time, drdt = %s \n", endstr );
}
}
printf("\n");
}
return( 0 );
}
The program outputs:
Relation condition: =
Start time, drdt = 2007-JAN-02 00:35:19.574
Stop time, drdt = 2007-JAN-02 00:35:19.574
Start time, drdt = 2007-JAN-19 22:04:54.899
Stop time, drdt = 2007-JAN-19 22:04:54.899
Start time, drdt = 2007-FEB-01 23:30:13.428
Stop time, drdt = 2007-FEB-01 23:30:13.428
Start time, drdt = 2007-FEB-17 11:10:46.540
Stop time, drdt = 2007-FEB-17 11:10:46.540
Start time, drdt = 2007-MAR-04 15:50:19.929
Stop time, drdt = 2007-MAR-04 15:50:19.929
Start time, drdt = 2007-MAR-18 09:59:05.959
Stop time, drdt = 2007-MAR-18 09:59:05.959
Relation condition: <
Start time, drdt = 2007-JAN-02 00:35:19.574
Stop time, drdt = 2007-JAN-19 22:04:54.899
Start time, drdt = 2007-FEB-01 23:30:13.428
Stop time, drdt = 2007-FEB-17 11:10:46.540
Start time, drdt = 2007-MAR-04 15:50:19.929
Stop time, drdt = 2007-MAR-18 09:59:05.959
Relation condition: >
Start time, drdt = 2007-JAN-01 00:00:00.000
Stop time, drdt = 2007-JAN-02 00:35:19.574
Start time, drdt = 2007-JAN-19 22:04:54.899
Stop time, drdt = 2007-FEB-01 23:30:13.428
Start time, drdt = 2007-FEB-17 11:10:46.540
Stop time, drdt = 2007-MAR-04 15:50:19.929
Start time, drdt = 2007-MAR-18 09:59:05.959
Stop time, drdt = 2007-APR-01 00:00:00.000
Relation condition: LOCMIN
Start time, drdt = 2007-JAN-11 07:03:58.988
Stop time, drdt = 2007-JAN-11 07:03:58.988
Start time, drdt = 2007-FEB-10 06:26:15.439
Stop time, drdt = 2007-FEB-10 06:26:15.439
Start time, drdt = 2007-MAR-12 03:28:36.404
Stop time, drdt = 2007-MAR-12 03:28:36.404
Relation condition: ABSMIN
Start time, drdt = 2007-JAN-11 07:03:58.988
Stop time, drdt = 2007-JAN-11 07:03:58.988
Relation condition: LOCMAX
Start time, drdt = 2007-JAN-26 02:27:33.766
Stop time, drdt = 2007-JAN-26 02:27:33.766
Start time, drdt = 2007-FEB-24 09:35:07.816
Stop time, drdt = 2007-FEB-24 09:35:07.816
Start time, drdt = 2007-MAR-25 17:26:56.150
Stop time, drdt = 2007-MAR-25 17:26:56.150
Relation condition: ABSMAX
Start time, drdt = 2007-MAR-25 17:26:56.150
Stop time, drdt = 2007-MAR-25 17:26:56.150
-Restrictions
1) The kernel files to be used by this routine must be loaded
(normally using the CSPICE routine furnsh_c) before this
routine is called.
2) This routine has the side effect of re-initializing the
range rate quantity utility package. Callers may themselves
need to re-initialize the range rate quantity utility
package after calling this routine.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 1.0.1, 28-FEB-2013 (NJB) (EDW)
Header was updated to discuss use of gfstol_c.
Edit to comments to correct search description.
Edits to Example section, proper description of "standard.tm"
meta kernel.
-CSPICE Version 1.0.0, 26-AUG-2009 (EDW) (NJB)
-Index_Entries
GF range rate search
-&
*/
{ /* Begin gfrr_c */
/*
Local variables
*/
doublereal * work;
static SpiceInt nw = SPICE_GF_NWRR;
SpiceInt nBytes;
/*
Participate in error tracing.
*/
chkin_c ( "gfrr_c" );
/*
Make sure cell data types are d.p.
*/
CELLTYPECHK2 ( CHK_STANDARD, "gfrr_c", SPICE_DP, cnfine, result );
/*
Initialize the input cells if necessary.
*/
CELLINIT2 ( cnfine, result );
/*
Check the input strings to make sure each pointer is non-null
and each string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "gfrr_c", target );
CHKFSTR ( CHK_STANDARD, "gfrr_c", abcorr );
CHKFSTR ( CHK_STANDARD, "gfrr_c", obsrvr );
CHKFSTR ( CHK_STANDARD, "gfrr_c", relate );
/*
Check the workspace size; some mallocs have a violent
dislike for negative allocation amounts. To be safe,
rule out a count of zero intervals as well.
*/
if ( nintvls < 1 )
{
setmsg_c ( "The specified workspace interval count # was "
"less than the minimum allowed value of one (1)." );
errint_c ( "#", nintvls );
sigerr_c ( "SPICE(VALUEOUTOFRANGE)" );
chkout_c ( "gfrr_c" );
return;
}
/*
Allocate the workspace. 'nintvls' indicates the maximum number of
intervals returned in 'result'. An interval consists of
two values.
*/
nintvls = 2 * nintvls;
nBytes = ( nintvls + SPICE_CELL_CTRLSZ ) * nw * sizeof(SpiceDouble);
work = (doublereal *) alloc_SpiceMemory( nBytes );
if ( !work )
{
setmsg_c ( "Workspace allocation of # bytes failed due to "
"malloc failure" );
errint_c ( "#", nBytes );
sigerr_c ( "SPICE(MALLOCFAILED)" );
chkout_c ( "gfrr_c" );
return;
}
/*
Let the f2'd routine do the work.
*/
gfrr_( ( char * ) target,
( char * ) abcorr,
( char * ) obsrvr,
( char * ) relate,
( doublereal * ) &refval,
( doublereal * ) &adjust,
( doublereal * ) &step,
( doublereal * ) (cnfine->base),
( integer * ) &nintvls,
( integer * ) &nw,
( doublereal * ) work,
( doublereal * ) (result->base),
( ftnlen ) strlen(target),
( ftnlen ) strlen(abcorr),
( ftnlen ) strlen(obsrvr),
( ftnlen ) strlen(relate) );
/*
De-allocate the workspace.
*/
free_SpiceMemory( work );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, result ) ;
}
ALLOC_CHECK;
chkout_c ( "gfrr_c" );
} /* End gfrr_c */
void vprjp_c ( ConstSpiceDouble vin [3],
ConstSpicePlane * plane,
SpiceDouble vout [3] )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
vin I Vector to be projected.
plane I A CSPICE plane onto which vin is projected.
vout O Vector resulting from projection.
-Detailed_Input
vin is a 3-vector that is to be orthogonally projected
onto a specified plane.
plane is a CSPICE plane that represents the geometric
plane onto which vin is to be projected.
-Detailed_Output
vout is the vector resulting from the orthogonal
projection of vin onto plane. vout is the closest
point in the specified plane to vin.
-Parameters
None.
-Exceptions
1) Invalid input planes are diagnosed by the routine pl2nvc_c,
which is called by this routine.
-Files
None.
-Particulars
Projecting a vector v orthogonally onto a plane can be thought of
as finding the closest vector in the plane to v. This `closest
vector' always exists; it may be coincident with the original
vector.
Two related routines are vprjpi_c, which inverts an orthogonal
projection of a vector onto a plane, and vproj_c, which projects
a vector orthogonally onto another vector.
-Examples
1) Find the closest point in the ring plane of a planet to a
spacecraft located at positn (in body-fixed coordinates).
Suppose the vector normal is normal to the ring plane, and
that origin, which represents the body center, is in the
ring plane. Then we can make a `plane' with the code
pnv2pl_c ( origin, normal, &plane );
can find the projection by making the call
vprjp_c ( positn, &plane, proj );
-Restrictions
None.
-Literature_References
[1] `Calculus and Analytic Geometry', Thomas and Finney.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.0, 05-MAR-1999 (NJB)
-Index_Entries
vector projection onto plane
-&
*/
{ /* Begin vprjp_c */
/*
Local variables
*/
SpiceDouble constant;
SpiceDouble normal [3];
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "vprjp_c" );
/*
Obtain a unit vector normal to the input plane, and a constant
for the plane.
*/
pl2nvc_c ( plane, normal, &constant );
/*
Let the notation < a, b > indicate the inner product of vectors
a and b.
vin differs from its projection onto plane by some multiple of
normal. That multiple is
< vin - vout, normal > * normal
= ( < vin, normal > - < vout, normal > ) * normal
= ( < vin, normal > - const ) * normal
Subtracting this multiple of normal from vin yields vout.
*/
vlcom_c ( 1.0,
vin,
constant - vdot_c ( vin, normal ),
normal,
vout );
chkout_c ( "vprjp_c" );
} /* End vprjp_c */
void ckcov_c ( ConstSpiceChar * ck,
SpiceInt idcode,
SpiceBoolean needav,
ConstSpiceChar * level,
SpiceDouble tol,
ConstSpiceChar * timsys,
SpiceCell * cover )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
ck I Name of CK file.
idcode I ID code of object.
needav I Flag indicating whether angular velocity is needed.
level I Coverage level: "SEGMENT" OR "INTERVAL".
tol I Tolerance in ticks.
timsys I Time system used to represent coverage.
cover I/O Window giving coverage for `idcode'.
-Detailed_Input
ck is the name of a C-kernel.
idcode is the integer ID code of an object, normally a
spacecraft structure or instrument, for which
pointing data are expected to exist in the specified
CK file.
needav is a logical variable indicating whether only
segments having angular velocity are to be considered
when determining coverage. When `needav' is
SPICETRUE, segments without angular velocity don't
contribute to the coverage window; when `needav' is
SPICEFALSE, all segments for `idcode' may contribute
to the coverage window.
level is the level (granularity) at which the coverage
is examined. Allowed values and corresponding
meanings are:
"SEGMENT" The output coverage window contains
intervals defined by the start and
stop times of segments for the object
designated by `idcode'.
"INTERVAL" The output coverage window contains
interpolation intervals of segments
for the object designated by
`idcode'. For type 1 segments, which
don't have interpolation intervals,
each epoch associated with a pointing
instance is treated as a singleton
interval; these intervals are added
to the coverage window.
All interpolation intervals are
considered to lie within the segment
bounds for the purpose of this
summary: if an interpolation
interval extends beyond the segment
coverage interval, only its
intersection with the segment
coverage interval is considered to
contribute to the total coverage.
tol is a tolerance value expressed in ticks of the
spacecraft clock associated with IDCODE. Before each
interval is inserted into the coverage window, the
interval is intersected with the segment coverage
interval, then if the intersection is non-empty, it
is expanded by `tol': the left endpoint of the
intersection interval is reduced by `tol' and the
right endpoint is increased by `tol'. Adjusted
interval endpoints, when expressed as encoded SCLK,
never are less than zero ticks. Any intervals that
overlap as a result of the expansion are merged.
The coverage window returned when tol > 0 indicates
the coverage provided by the file to the CK readers
ckgpav_c and ckgp_c when that value of `tol' is
passed to them as an input.
timsys is a string indicating the time system used in the
output coverage window. `timsys' may have the
values:
"SCLK" Elements of `cover' are expressed in
encoded SCLK ("ticks"), where the
clock is associated with the object
designated by `idcode'.
"TDB" Elements of `cover' are expressed as
seconds past J2000 TDB.
cover is an initialized CSPICE window data structure.
`cover' optionally may contain coverage data on
input; on output, the data already present in `cover'
will be combined with coverage found for the object
designated by `idcode' in the file `ck'.
If `cover' contains no data on input, its size and
cardinality still must be initialized.
-Detailed_Output
cover is a CSPICE window data structure which represents
the merged coverage for `idcode'. When the coverage
level is "INTERVAL", this is the set of time
intervals for which data for `idcode' are present in
the file `ck', merged with the set of time intervals
present in `cover' on input. The merged coverage is
represented as the union of one or more disjoint time
intervals. The window `cover' contains the pairs of
endpoints of these intervals.
When the coverage level is "SEGMENT", `cover' is
computed in a manner similar to that described above,
but the coverage intervals used in the computation
are those of segments rather than interpolation
intervals within segments.
When `tol' is > 0, the intervals comprising the
coverage window for `idcode' are expanded by `tol'
and any intervals overlapping as a result are merged.
The resulting window is returned in `cover'. The
expanded window in no case extends beyond the segment
bounds in either direction by more than `tol'.
The interval endpoints contained in `cover' are
encoded spacecraft clock times if `timsys' is "SCLK";
otherwise the times are converted from encoded
spacecraft clock to seconds past J2000 TDB.
See the Examples section below for a complete example
program showing how to retrieve the endpoints from
`cover'.
-Parameters
None.
-Exceptions
1) If the input file has transfer format, the error
SPICE(INVALIDFORMAT) is signaled.
2) If the input file is not a transfer file but has architecture
other than DAF, the error SPICE(BADARCHTYPE) is signaled.
3) If the input file is a binary DAF file of type other than
CK, the error SPICE(BADFILETYPE) is signaled.
4) If the CK file cannot be opened or read, the error will
be diagnosed by routines called by this routine. The output
window will not be modified.
5) If the size of the output window argument `cover' is
insufficient to contain the actual number of intervals in the
coverage window for `idcode', the error will be diagnosed by
routines called by this routine.
6) If `tol' is negative, the error SPICE(VALUEOUTOFRANGE) is
signaled.
7) If `level' is not recognized, the error SPICE(INVALIDOPTION)
is signaled.
8) If `timsys' is not recognized, the error SPICE(INVALIDOPTION)
is signaled.
9) If a time conversion error occurs, the error will be
diagnosed by a routine in the call tree of this routine.
10) If the output time system is TDB, the CK subsystem must be
able to map `idcode' to the ID code of the associated
spacecraft clock. If this mapping cannot be performed, the
error will be diagnosed by a routine in the call tree of this
routine.
11) The error SPICE(EMPTYSTRING) is signaled if any of the input
strings `ck', `level', or `timsys' do not contain at least one
character, since such an input string cannot be converted to a
Fortran-style string in this case.
12) The error SPICE(NULLPOINTER) is signaled if the if any of the input
strings `ck', `level', or `timsys' are null.
-Files
This routine reads a C-kernel.
If the output time system is "TDB", then a leapseconds kernel
and an SCLK kernel for the spacecraft clock associated with
`idcode' must be loaded before this routine is called.
If the ID code of the clock associated with `idcode' is not
equal to
idcode / 1000
then the kernel variable
CK_<idcode>_SCLK
must be present in the kernel pool to identify the clock
associated with `idcode'. This variable must contain the ID code
to be used for conversion between SCLK and TDB. Normally this
variable is provided in a text kernel loaded via furnsh_c.
-Particulars
This routine provides an API via which applications can determine
the coverage a specified CK file provides for a specified
object.
-Examples
1) Display the interval-level coverage for each object in a
specified CK file. Use tolerance of zero ticks. Do not request
angular velocity. Express the results in the TDB time system.
Find the set of objects in the file. Loop over the contents of
the ID code set: find the coverage for each item in the set and
display the coverage.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define MAXIV 100000
#define WINSIZ ( 2 * MAXIV )
#define TIMLEN 51
#define MAXOBJ 1000
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SPICEINT_CELL ( ids, MAXOBJ );
SpiceChar ck [ FILSIZ ];
SpiceChar lsk [ FILSIZ ];
SpiceChar sclk [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceDouble b;
SpiceDouble e;
SpiceInt i;
SpiceInt j;
SpiceInt niv;
SpiceInt obj;
/.
Load a leapseconds kernel and SCLK kernel for output time
conversion. Note that we assume a single spacecraft clock is
associated with all of the objects in the CK.
./
prompt_c ( "Name of leapseconds kernel > ", FILSIZ, lsk );
furnsh_c ( lsk );
prompt_c ( "Name of SCLK kernel > ", FILSIZ, sclk );
furnsh_c ( sclk );
/.
Get name of CK file.
./
prompt_c ( "Name of CK file > ", FILSIZ, ck );
/.
Find the set of objects in the CK file.
./
ckobj_c ( ck, &ids );
/.
We want to display the coverage for each object. Loop over
the contents of the ID code set, find the coverage for
each item in the set, and display the coverage.
./
for ( i = 0; i < card_c( &ids ); i++ )
{
/.
Find the coverage window for the current object.
Empty the coverage window each time so we don't
include data for the previous object.
./
obj = SPICE_CELL_ELEM_I( &ids, i );
scard_c ( 0, &cover );
ckcov_c ( ck, obj, SPICEFALSE,
"INTERVAL", 0.0, "TDB", &cover );
/.
Get the number of intervals in the coverage window.
./
niv = wncard_c( &cover );
/.
Display a simple banner.
./
printf ( "%s\n", "========================================" );
printf ( "Coverage for object %ld\n", obj );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( j = 0; j < niv; j++ )
{
/.
Get the endpoints of the jth interval.
./
wnfetd_c ( &cover, j, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
j,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
printf ( "%s\n", "========================================" );
}
return ( 0 );
}
2) Find the segment-level coverage for the object designated by
IDCODE provided by the set of CK files loaded via a metakernel.
(The metakernel must also specify leapseconds and SCLK kernels.)
Use tolerance of zero ticks. Do not request angular velocity.
Express the results in the TDB time system.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local parameters
./
#define FILSIZ 256
#define LNSIZE 81
#define MAXCOV 100000
#define WINSIZ ( 2 * MAXCOV )
#define TIMLEN 51
/.
Local variables
./
SPICEDOUBLE_CELL ( cover, WINSIZ );
SpiceBoolean found;
SpiceChar file [ FILSIZ ];
SpiceChar idch [ LNSIZE ];
SpiceChar meta [ FILSIZ ];
SpiceChar source [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceChar type [ LNSIZE ];
SpiceDouble b;
SpiceDouble e;
SpiceInt count;
SpiceInt handle;
SpiceInt i;
SpiceInt idcode;
SpiceInt niv;
/.
Prompt for the metakernel name; load the metakernel.
The metakernel lists the CK files whose coverage
for `idcode' we'd like to determine. The metakernel
must also specify a leapseconds kernel and an SCLK
kernel for the clock associated with `idcode'.
./
prompt_c ( "Name of metakernel > ", FILSIZ, meta );
furnsh_c ( meta );
/.
Get the ID code of interest.
./
prompt_c ( "Enter ID code > ", LNSIZE, idch );
prsint_c ( idch, &idcode );
/.
Find out how many kernels are loaded. Loop over the
kernels: for each loaded CK file, add its coverage
for `idcode', if any, to the coverage window.
./
ktotal_c ( "CK", &count );
for ( i = 0; i < count; i++ )
{
kdata_c ( i, "CK", FILSIZ,
LNSIZE, FILSIZ, file,
type, source, &handle, &found );
ckcov_c ( file, idcode, SPICEFALSE,
"SEGMENT", 0.0, "TDB", &cover );
}
/.
Display results.
Get the number of intervals in the coverage window.
./
niv = wncard_c( &cover );
/.
Display a simple banner.
./
printf ( "\nCoverage for object %ld\n", idcode );
/.
Convert the coverage interval start and stop times to TDB
calendar strings.
./
for ( i = 0; i < niv; i++ )
{
/.
Get the endpoints of the ith interval.
./
wnfetd_c ( &cover, i, &b, &e );
/.
Convert the endpoints to TDB calendar
format time strings and display them.
./
timout_c ( b,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "\n"
"Interval: %ld\n"
"Start: %s\n",
i,
timstr );
timout_c ( e,
"YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",
TIMLEN,
timstr );
printf ( "Stop: %s\n", timstr );
}
return ( 0 );
}
-Restrictions
1) When this routine is used to accumulate coverage for `idcode'
provided by multiple CK files, the inputs `needav', `level', `tol',
and `timsys' must have the same values for all files in order
for the result to be meaningful.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.1, 30-NOV-2007 (NJB)
Corrected bug in first example program in header:
program now empties result window prior to collecting
data for each object. Updated examples to use wncard_c
rather than card_c. Updated second example to demonstrate
segment-level summary capability.
-CSPICE Version 1.0.0, 07-JAN-2005 (NJB)
-Index_Entries
get coverage window for ck object
-&
*/
{ /* Begin ckcov_c */
/*
Local variables
*/
logical need;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "ckcov_c" );
/*
Check the input string `ck' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ckcov_c", ck );
/*
Check the input string `level' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ckcov_c", level );
/*
Check the input string `timsys' to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ckcov_c", timsys );
/*
Make sure cell data type is d.p.
*/
CELLTYPECHK ( CHK_STANDARD, "ckcov_c", SPICE_DP, cover );
/*
Initialize the cell if necessary.
*/
CELLINIT ( cover );
/*
Call the f2c'd Fortran routine.
*/
need = needav;
ckcov_ ( ( char * ) ck,
( integer * ) &idcode,
( logical * ) &need,
( char * ) level,
( doublereal * ) &tol,
( char * ) timsys,
( doublereal * ) (cover->base),
( ftnlen ) strlen(ck),
( ftnlen ) strlen(level),
( ftnlen ) strlen(timsys) );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, cover );
}
chkout_c ( "ckcov_c" );
} /* End ckcov_c */
void qcktrc_c ( SpiceInt tracelen,
SpiceChar * trace )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
tracelen I Maximum length of output traceback string.
trace O A traceback string.
SPICE_ERROR_MAXMOD
P Maximum traceback module count.
SPICE_ERROR_MODLEN
P Maximum module name length.
SPICE_ERROR_TRCLEN
P Maximum length of output traceback string.
-Detailed_Input
None.
-Detailed_Output
trace is a list of module names, delimited by the string,
" --> ". An example would be
"SPUD --> SPAM --> FOOBAR".
The maximum length of the returned string is given
by the parameter SPICE_ERROR_TRCLEN. The value of this
parameter includes room for the terminating null.
In general, the meaning of the trace is as follows:
The first name in the list is the name of the first
module to check in (that hasn't yet checked out). The
last name is the name of the module at the end of the
call chain; this is the last module that checked in.
The meaning of the traceback depends on the state
of the error handling mechanism. There are two
cases:
1) In RETURN mode, when an error is signaled, the
traceback at that point is saved. trcdep_c,
trcnam_c, and qcktrc_c return values
pertaining to the saved traceback.
2) In all other modes, the traceback represents
the CURRENT call chain. trcdep_c, trcnam_c,
and qcktrc_c return values pertaining to the
current trace representation.
Any module names exceeding SPICE_ERROR_MODLEN
characters in length are truncated on the right.
-Parameters
The following parameters are declared in the header file SpiceErr.h:
SPICE_ERROR_MAXMOD is the maximum number of module names that can
be accommodated in the SPICE trace stack; this
is the maximum number of names that can appear
in the output traceback.
SPICE_ERROR_MODLEN is the maximum module name length that can be
accommodated by this routine.
SPICE_ERROR_TRCLEN is the maximum length of the string returned
by this routine. The value of this parameter
includes room for the terminating null.
-Exceptions
1) If the output string pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
2) If the output string has length less than 2 characters, the error
SPICE(STRINGTOOSHORT) will be signaled.
-Files
None.
-Particulars
This routine is part of the CSPICE error handling mechanism.
-Examples
1) Deliberately generate a SPICE error to demonstrate use of
this routine together with trcnam_c. We'll attempt to look up
a state vector via spkezr_c without first having loaded any
SPK files.
Example code begins here.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local constants
./
#define ACTION "RETURN"
/.
Local variables
./
SpiceChar * abcorr;
SpiceChar trace [ SPICE_ERROR_TRCLEN ];
SpiceChar * obsrvr;
SpiceChar * frame;
SpiceChar * target;
SpiceDouble et;
SpiceDouble lt;
SpiceDouble state [6];
/.
Set error handling action to RETURN so that this program
won't terminate when a SPICE error is signaled. Note that
the input string length argument is unused for a "SET"
operation.
./
erract_c ( "SET", 0, ACTION );
/.
Generate a SPICE error: call spkezr_c without first having
loaded an SPK file.
./
et = 0.0;
target = "Moon";
obsrvr = "Earth";
frame = "J2000";
abcorr = "NONE";
spkezr_c ( target, et, frame, abcorr, obsrvr, state, < );
if ( failed_c() )
{
/.
An error has been signaled. Fetch and display
the traceback.
./
qcktrc_c ( SPICE_ERROR_TRCLEN, trace );
printf ( "Traceback: \n%s\n", trace );
/.
Reset the error status so that CSPICE can resume normal
operation.
./
reset_c();
}
return ( 0 );
}
When this program was executed on a PC/Linux/gcc platform, the
output (which has been reformatted to fit in the available
space in this header) was:
====================================================================
============
Toolkit version: N0065
SPICE(NOLOADEDFILES) --
At least one SPK file needs to be loaded by SPKLEF before beginning
a search.
A traceback follows. The name of the highest level module is first.
spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS
====================================================================
============
Traceback:
spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS
-Restrictions
1) It is assumed no module names exceed SPICE_ERROR_MODLEN
characters in length.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Version
-CSPICE Version 1.0.0, 05-NOV-2013 (NJB) (KRG)
-Index_Entries
get quick traceback
-&
*/
{ /* Begin qcktrc_c */
/*
This routine does not check in unless an input error occurs.
*/
/*
Make sure the output string has at least enough room for one output
character and a null terminator. Also check for a null pointer.
We don't use the usual CHKOSTR macro here because we must reset
the error status before signaling an error.
*/
if ( trace == NULL )
{
reset_c ();
chkin_c ( "qcktrc_c" );
setmsg_c ( "The output string pointer 'trace' is null." );
sigerr_c ( "SPICE(NULLPOINTER)" );
chkout_c ( "qcktrc_c" );
return;
}
if ( tracelen < 2 )
{
reset_c ();
chkin_c ( "qcktrc_c" );
setmsg_c ( "The output string 'trace' has length #; the "
"minimum allowed length is 2 characters." );
errint_c ( "#", tracelen );
sigerr_c ( "SPICE(STRINGTOOSHORT)" );
chkout_c ( "qcktrc_c" );
return;
}
/*
Fetch the traceback.
*/
qcktrc_ ( ( char * ) trace,
( ftnlen ) tracelen-1 );
/*
Convert the output name string to a null-terminated,
C style string.
*/
F2C_ConvertStr ( tracelen, trace );
} /* End qcktrc_c */
void gfuds_c ( void ( * udfunc ) ( SpiceDouble et,
SpiceDouble * value ),
void ( * udqdec ) ( void ( * udfunc )
( SpiceDouble et,
SpiceDouble * value ),
SpiceDouble et,
SpiceBoolean * isdecr ),
ConstSpiceChar * relate,
SpiceDouble refval,
SpiceDouble adjust,
SpiceDouble step,
SpiceInt nintvls,
SpiceCell * cnfine,
SpiceCell * result )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
udfunc I Name of the routine that computes the scalar value
of interest at some time.
udqdec I Name of the routine that computes whether the
current state is decreasing.
relate I Operator that either looks for an extreme value
(max, min, local, absolute) or compares the
geometric quantity value and a number.
refval I Value used as reference for geometric quantity
condition.
adjust I Allowed variation for absolute extremal
geometric conditions.
step I Step size used for locating extrema and roots.
nintvls I Workspace window interval count
cnfine I-O SPICE window to which the search is restricted.
result O SPICE window containing results.
-Detailed_Input
udfunc the name of the external routine that returns the
value of the scalar quantity of interest at time ET.
The calling sequence for "udfunc" is:
udfunc ( et, &value )
where:
et an input double precision value
representing the TDB ephemeris seconds time
at which to determine the scalar value.
value is the value of the geometric quantity
at 'et'.
udqdec the name of the external routine that determines if
the scalar quantity calculated by "udfunc" is decreasing.
The calling sequence:
udqdec ( et, &isdecr )
where:
et an input double precision value representing
the TDB ephemeris seconds time at at which
to determine the time derivative of 'udfunc'.
isdecr a logical variable indicating whether
or not the scalar value returned by udfunc
is decreasing. 'isdecr' returns true if the
time derivative of "udfunc" at 'et' is negative.
relate the scalar string comparison operator indicating
the numeric constraint of interest. Values are:
">" value of scalar quantity greater than some
reference (refval).
"=" value of scalar quantity equal to some
reference (refval).
"<" value of scalar quantity less than some
reference (refval).
"ABSMAX" The scalar quantity is at an absolute
maximum.
"ABSMIN" The scalar quantity is at an absolute
minimum.
"LOCMAX" The scalar quantity is at a local
maximum.
"LOCMIN" The scalar quantity is at a local
minimum.
The caller may indicate that the region of interest
is the set of time intervals where the quantity is
within a specified distance of an absolute extremum.
The argument 'adjust' (described below) is used to
specified this distance.
Local extrema are considered to exist only in the
interiors of the intervals comprising the confinement
window: a local extremum cannot exist at a boundary
point of the confinement window.
relate is insensitive to case, leading and
trailing blanks.
refval is the reference value used to define an equality or
inequality to satisfied by the scalar quantity.
The units of refval are those of the scalar quantity.
adjust the amount by which the quantity is allowed to vary
from an absolute extremum.
If the search is for an absolute minimum is performed,
the resulting window contains time intervals when the
geometric quantity value has values between ABSMIN and
ABSMIN + adjust.
If the search is for an absolute maximum, the
corresponding range is between ABSMAX - adjust and
ABSMAX.
'adjust' is not used for searches for local extrema,
equality or inequality conditions and must have value
zero for such searches.
step the double precision time step size to use in
the search.
'step' must be short enough to for a search using this
step size to locate the time intervals where the
scalar quantity function is monotone increasing or
decreasing. However, 'step' must not be *too* short,
or the search will take an
The choice of 'step' affects the completeness but not
the precision of solutions found by this routine; the
precision is controlled by the convergence tolerance.
See the discussion of the parameter SPICE_GF_CNVTOL for
details.
'step' has units of TDB seconds.
nintvls an integer value specifying the number of intervals in the
the internal workspace array used by this routine. 'nintvls'
should be at least as large as the number of intervals
within the search region on which the specified observer-target
vector coordinate function is monotone increasing or decreasing.
It does no harm to pick a value of 'nintvls' larger than the
minimum required to execute the specified search, but if chosen
too small, the search will fail.
cnfine a double precision SPICE window that confines the time
period over which the specified search is conducted.
cnfine may consist of a single interval or a collection
of intervals.
In some cases the confinement window can be used to
greatly reduce the time period that must be searched
for the desired solution. See the Particulars section
below for further discussion.
See the Examples section below for a code example
that shows how to create a confinement window.
-Detailed_Output
cnfine is the input confinement window, updated if necessary
so the control area of its data array indicates the
window's size and cardinality. The window data are
unchanged.
result is a SPICE window representing the set of time
intervals, within the confinement period, when the
specified geometric event occurs.
If `result' is non-empty on input, its contents
will be discarded before gfuds_c conducts its
search.
-Parameters
None.
-Exceptions
1) In order for this routine to produce correct results,
the step size must be appropriate for the problem at hand.
Step sizes that are too large may cause this routine to miss
roots; step sizes that are too small may cause this routine
to run unacceptably slowly and in some cases, find spurious
roots.
This routine does not diagnose invalid step sizes, except
that if the step size is non-positive, an error is signaled
by a routine in the call tree of this routine.
2) Due to numerical errors, in particular,
- Truncation error in time values
- Finite tolerance value
- Errors in computed geometric quantities
it is *normal* for the condition of interest to not always be
satisfied near the endpoints of the intervals comprising the
result window.
The result window may need to be contracted slightly by the
caller to achieve desired results. The SPICE window routine
wncond_c can be used to contract the result window.
3) If an error (typically cell overflow) occurs while performing
window arithmetic, the error will be diagnosed by a routine
in the call tree of this routine.
4) If the relational operator `relate' is not recognized, an
error is signaled by a routine in the call tree of this
routine.
5) If 'adjust' is negative, the error SPICE(VALUEOUTOFRANGE) will
signal from a routine in the call tree of this routine.
A non-zero value for 'adjust' when 'relate' has any value other than
"ABSMIN" or "ABSMAX" causes the error SPICE(INVALIDVALUE) to
signal from a routine in the call tree of this routine.
6) If required ephemerides or other kernel data are not
available, an error is signaled by a routine in the call tree
of this routine.
7) If the workspace interval count is less than 1, the error
SPICE(VALUEOUTOFRANGE) will be signaled.
8) If the required amount of workspace memory cannot be
allocated, the error SPICE(MALLOCFAILURE) will be
signaled.
9) If any input string argument pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
10) If any input string argument is empty, the error
SPICE(EMPTYSTRING) will be signaled.
11) If either input cell has type other than SpiceDouble,
the error SPICE(TYPEMISMATCH) is signaled.
-Files
Appropriate kernels must be loaded by the calling program before
this routine is called.
If the scalar function requires access to ephemeris data:
- SPK data: ephemeris data for any body over the
time period defined by the confinement window must be
loaded. If aberration corrections are used, the states of
target and observer relative to the solar system barycenter
must be calculable from the available ephemeris data.
Typically ephemeris data are made available by loading one
or more SPK files via furnsh_c.
- If non-inertial reference frames are used, then PCK
files, frame kernels, C-kernels, and SCLK kernels may be
needed.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
-Particulars
This routine provides a simpler, but less flexible interface
than does the routine zzgfrel_ for conducting searches for events
corresponding to an arbitrary user defined scalar quantity
function. Applications that require support for progress
reporting, interrupt handling, non-default step or refinement
functions, or non-default convergence tolerance should call
zzgfrel_ rather than this routine.
This routine determines a set of one or more time intervals
within the confinement window when the scalar function
satisfies a caller-specified constraint. The resulting set of
intervals is returned as a SPICE window.
udqdec Default Template
=======================
The user must supply a routine to determine whether sign of the
time derivative of udfunc is positive or negative at 'et'. For
cases where udfunc is numerically well behaved, the user
may find it convenient to use a routine based on the below
template. uddc_c determines the truth of the expression
d (udfunc)
-- < 0
dt
using the library routine uddf_c to numerically calculate the
derivative of udfunc using a three-point estimation. Use
of gfdecr requires only changing the "udfunc" argument
to that of the user provided scalar function passed to gfuds_c
and defining the differential interval size, 'dt'. Please see
the Examples section for an example of gfdecr use.
void gfdecr ( SpiceDouble et, SpiceBoolean * isdecr )
{
SpiceDouble dt = h, double precision interval size;
uddc_c( udfunc, uddf_c, et, dt, isdecr );
return;
}
Below we discuss in greater detail aspects of this routine's
solution process that are relevant to correct and efficient
use of this routine in user applications.
The Search Process
==================
Regardless of the type of constraint selected by the caller, this
routine starts the search for solutions by determining the time
periods, within the confinement window, over which the specified
scalar function is monotone increasing and monotone
decreasing. Each of these time periods is represented by a SPICE
window. Having found these windows, all of the quantity
function's local extrema within the confinement window are known.
Absolute extrema then can be found very easily.
Within any interval of these "monotone" windows, there will be at
most one solution of any equality constraint. Since the boundary
of the solution set for any inequality constraint is the set
of points where an equality constraint is met, the solutions of
both equality and inequality constraints can be found easily
once the monotone windows have been found.
Step Size
=========
The monotone windows (described above) are found using a two-step
search process. Each interval of the confinement window is
searched as follows: first, the input step size is used to
determine the time separation at which the sign of the rate of
change of quantity function will be sampled. Starting at
the left endpoint of an interval, samples will be taken at each
step. If a change of sign is found, a root has been bracketed; at
that point, the time at which the time derivative of the quantity
function is zero can be found by a refinement process, for
example, using a binary search.
Note that the optimal choice of step size depends on the lengths
of the intervals over which the quantity function is monotone:
the step size should be shorter than the shortest of these
intervals (within the confinement window).
The optimal step size is *not* necessarily related to the lengths
of the intervals comprising the result window. For example, if
the shortest monotone interval has length 10 days, and if the
shortest result window interval has length 5 minutes, a step size
of 9.9 days is still adequate to find all of the intervals in the
result window. In situations like this, the technique of using
monotone windows yields a dramatic efficiency improvement over a
state-based search that simply tests at each step whether the
specified constraint is satisfied. The latter type of search can
miss solution intervals if the step size is shorter than the
shortest solution interval.
Having some knowledge of the relative geometry of the targets and
observer can be a valuable aid in picking a reasonable step size.
In general, the user can compensate for lack of such knowledge by
picking a very short step size; the cost is increased computation
time.
Note that the step size is not related to the precision with which
the endpoints of the intervals of the result window are computed.
That precision level is controlled by the convergence tolerance.
Convergence Tolerance
=====================
Once a root has been bracketed, a refinement process is used to
narrow down the time interval within which the root must lie.
This refinement process terminates when the location of the root
has been determined to within an error margin called the
"convergence tolerance." The convergence tolerance used by this
routine is set via the parameter SPICE_GF_CNVTOL.
The value of SPICE_GF_CNVTOL is set to a "tight" value so that the
tolerance doesn't become the limiting factor in the accuracy of
solutions found by this routine. In general the accuracy of input
data will be the limiting factor.
Making the tolerance tighter than SPICE_GF_CNVTOL is unlikely to
be useful, since the results are unlikely to be more accurate.
Making the tolerance looser will speed up searches somewhat,
since a few convergence steps will be omitted. However, in most
cases, the step size is likely to have a much greater affect
on processing time than would the convergence tolerance.
The Confinement Window
======================
The simplest use of the confinement window is to specify a time
interval within which a solution is sought. However, the
confinement window can, in some cases, be used to make searches
more efficient. Sometimes it's possible to do an efficient search
to reduce the size of the time period over which a relatively
slow search of interest must be performed.
-Examples
The numerical results shown for these examples may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
Conduct a search on the range-rate of the vector from the Sun
to the Moon. Define a function to calculate the value.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: standard.tm
This meta-kernel is intended to support operation of SPICE
example programs. The kernels shown here should not be
assumed to contain adequate or correct versions of data
required by SPICE-based user applications.
In order for an application to use this meta-kernel, the
kernels referenced here must be present in the user's
current working directory.
\begindata
KERNELS_TO_LOAD = ( 'de414.bsp',
'pck00008.tpc',
'naif0009.tls' )
\begintext
Code:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "SpiceUsr.h"
#include "SpiceZfc.h"
#include "SpiceZad.h"
#define MAXWIN 20000
#define TIMFMT "YYYY-MON-DD HR:MN:SC.###"
#define TIMLEN 41
#define NLOOPS 7
void gfq ( SpiceDouble et, SpiceDouble * value );
void gfdecrx ( void ( * udfunc ) ( SpiceDouble et,
SpiceDouble * value ),
SpiceDouble et,
SpiceBoolean * isdecr );
doublereal dvnorm_(doublereal *state);
int main( int argc, char **argv )
{
/.
Create the needed windows. Note, one interval
consists of two values, so the total number
of cell values to allocate is twice
the number of intervals.
./
SPICEDOUBLE_CELL ( result, 2*MAXWIN );
SPICEDOUBLE_CELL ( cnfine, 2 );
SpiceDouble begtim;
SpiceDouble endtim;
SpiceDouble step;
SpiceDouble adjust;
SpiceDouble refval;
SpiceDouble beg;
SpiceDouble end;
SpiceChar begstr [ TIMLEN ];
SpiceChar endstr [ TIMLEN ];
SpiceInt count;
SpiceInt i;
SpiceInt j;
ConstSpiceChar * relate [NLOOPS] = { "=",
"<",
">",
"LOCMIN",
"ABSMIN",
"LOCMAX",
"ABSMAX"
};
printf( "Compile date %s, %s\n\n", __DATE__, __TIME__ );
/.
Load kernels.
./
furnsh_c( "standard.tm" );
/.
Store the time bounds of our search interval in the 'cnfine'
confinement window.
./
str2et_c( "2007 JAN 01", &begtim );
str2et_c( "2007 APR 01", &endtim );
wninsd_c ( begtim, endtim, &cnfine );
/.
Search using a step size of 1 day (in units of seconds). The reference
value is .3365 km/s. We're not using the adjustment feature, so
we set 'adjust' to zero.
./
step = spd_c();
adjust = 0.;
refval = .3365;
for ( j = 0; j < NLOOPS; j++ )
{
printf ( "Relation condition: %s \n", relate[j] );
/.
Perform the search. The SPICE window 'result' contains
the set of times when the condition is met.
./
gfuds_c ( gfq,
gfdecrx,
relate[j],
refval,
adjust,
step,
MAXWIN,
&cnfine,
&result );
count = wncard_c( &result );
/.
Display the results.
./
if (count == 0 )
{
printf ( "Result window is empty.\n\n" );
}
else
{
for ( i = 0; i < count; i++ )
{
/.
Fetch the endpoints of the Ith interval
of the result window.
./
wnfetd_c ( &result, i, &beg, &end );
timout_c ( beg, TIMFMT, TIMLEN, begstr );
timout_c ( end, TIMFMT, TIMLEN, endstr );
printf ( "Start time, drdt = %s \n", begstr );
printf ( "Stop time, drdt = %s \n", endstr );
}
}
printf("\n");
}
kclear_c();
return( 0 );
}
/.
The user defined functions required by GFUDS.
gfq for udfunc
gfdecr for udqdec
./
/.
-Procedure Procedure gfq
./
void gfq ( SpiceDouble et, SpiceDouble * value )
/.
-Abstract
User defined geometric quantity function. In this case,
the range from the sun to the Moon at TDB time 'et'.
./
{
/. Initialization ./
SpiceInt targ = 301;
SpiceInt obs = 10;
SpiceChar * ref = "J2000";
SpiceChar * abcorr = "NONE";
SpiceDouble state [6];
SpiceDouble lt;
/.
Retrieve the vector from the Sun to the Moon in the J2000
frame, without aberration correction.
./
spkez_c ( targ, et, ref, abcorr, obs, state, < );
/.
Calculate the scalar range rate corresponding the
'state' vector.
./
*value = dvnorm_( state );
return;
}
/.
-Procedure gfdecrx
./
void gfdecrx ( void ( * udfunc ) ( SpiceDouble et,
SpiceDouble * value ),
SpiceDouble et,
SpiceBoolean * isdecr )
/.
-Abstract
User defined function to detect if the function derivative
is negative (the function is decreasing) at TDB time 'et'.
./
{
SpiceDouble dt = 10.;
/.
Determine if "udfunc" is decreasing at 'et'.
uddc_c - the GF function to determine if
the derivative of the user defined
function is negative at 'et'.
uddf_c - the SPICE function to numerically calculate the
derivative of 'udfunc' at 'et' for the
interval [et-dt, et+dt].
./
uddc_c( udfunc, et, dt, isdecr );
return;
}
The program outputs:
Relation condition: =
Start time, drdt = 2007-JAN-02 00:35:19.574
Stop time, drdt = 2007-JAN-02 00:35:19.574
Start time, drdt = 2007-JAN-19 22:04:54.899
Stop time, drdt = 2007-JAN-19 22:04:54.899
Start time, drdt = 2007-FEB-01 23:30:13.428
Stop time, drdt = 2007-FEB-01 23:30:13.428
Start time, drdt = 2007-FEB-17 11:10:46.540
Stop time, drdt = 2007-FEB-17 11:10:46.540
Start time, drdt = 2007-MAR-04 15:50:19.929
Stop time, drdt = 2007-MAR-04 15:50:19.929
Start time, drdt = 2007-MAR-18 09:59:05.959
Stop time, drdt = 2007-MAR-18 09:59:05.959
Relation condition: <
Start time, drdt = 2007-JAN-02 00:35:19.574
Stop time, drdt = 2007-JAN-19 22:04:54.899
Start time, drdt = 2007-FEB-01 23:30:13.428
Stop time, drdt = 2007-FEB-17 11:10:46.540
Start time, drdt = 2007-MAR-04 15:50:19.929
Stop time, drdt = 2007-MAR-18 09:59:05.959
Relation condition: >
Start time, drdt = 2007-JAN-01 00:00:00.000
Stop time, drdt = 2007-JAN-02 00:35:19.574
Start time, drdt = 2007-JAN-19 22:04:54.899
Stop time, drdt = 2007-FEB-01 23:30:13.428
Start time, drdt = 2007-FEB-17 11:10:46.540
Stop time, drdt = 2007-MAR-04 15:50:19.929
Start time, drdt = 2007-MAR-18 09:59:05.959
Stop time, drdt = 2007-APR-01 00:00:00.000
Relation condition: LOCMIN
Start time, drdt = 2007-JAN-11 07:03:58.988
Stop time, drdt = 2007-JAN-11 07:03:58.988
Start time, drdt = 2007-FEB-10 06:26:15.439
Stop time, drdt = 2007-FEB-10 06:26:15.439
Start time, drdt = 2007-MAR-12 03:28:36.404
Stop time, drdt = 2007-MAR-12 03:28:36.404
Relation condition: ABSMIN
Start time, drdt = 2007-JAN-11 07:03:58.988
Stop time, drdt = 2007-JAN-11 07:03:58.988
Relation condition: LOCMAX
Start time, drdt = 2007-JAN-26 02:27:33.766
Stop time, drdt = 2007-JAN-26 02:27:33.766
Start time, drdt = 2007-FEB-24 09:35:07.816
Stop time, drdt = 2007-FEB-24 09:35:07.816
Start time, drdt = 2007-MAR-25 17:26:56.150
Stop time, drdt = 2007-MAR-25 17:26:56.150
Relation condition: ABSMAX
Start time, drdt = 2007-MAR-25 17:26:56.150
Stop time, drdt = 2007-MAR-25 17:26:56.150
-Restrictions
1) Any kernel files required by this routine must be loaded
before this routine is called.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 1.0.0, 22-FEB-2010 (EDW)
-Index_Entries
GF user defined scalar function search
-&
*/
{ /* Begin gfuds_c */
/*
Local variables
*/
doublereal * work;
static SpiceInt nw = SPICE_GF_NWMAX;
SpiceInt nBytes;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfuds_c" );
/*
Make sure cell data types are d.p.
*/
CELLTYPECHK2 ( CHK_STANDARD, "gfuds_c", SPICE_DP, cnfine, result );
/*
Initialize the input cells if necessary.
*/
CELLINIT2 ( cnfine, result );
/*
Check the other input strings to make sure each pointer is non-null
and each string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "gfuds_c", relate );
/*
Store the input function pointers so these functions can be
called by the GF adapters.
*/
zzadsave_c ( UDFUNC, (void *)(udfunc) );
zzadsave_c ( UDQDEC, (void *)(udqdec) );
/*
Check the workspace size; some mallocs have a violent
dislike for negative allocation amounts. To be safe,
rule out a count of zero intervals as well.
*/
if ( nintvls < 1 )
{
setmsg_c ( "The specified workspace interval count # was "
"less than the minimum allowed value of one (1)." );
errint_c ( "#", nintvls );
sigerr_c ( "SPICE(VALUEOUTOFRANGE)" );
chkout_c ( "gfuds_c" );
return;
}
/*
Allocate the workspace. 'nintvls' indicates the maximum number of
intervals returned in 'result'. An interval consists of
two values.
*/
nintvls = 2 * nintvls;
nBytes = (nintvls + SPICE_CELL_CTRLSZ ) * nw * sizeof(SpiceDouble);
work = (doublereal *) alloc_SpiceMemory( nBytes );
if ( !work )
{
setmsg_c ( "Workspace allocation of # bytes failed due to "
"malloc failure" );
errint_c ( "#", nBytes );
sigerr_c ( "SPICE(MALLOCFAILED)" );
chkout_c ( "gfuds_c" );
return;
}
/*
Let the f2c'd routine do the work.
We pass the adapter functions, not those provided as inputs,
to the f2c'd routine:
zzadfunc_c adapter for udfunc
zzadqdec_c '' udqdec
*/
(void) gfuds_( ( U_fp ) zzadfunc_c,
( U_fp ) zzadqdec_c,
( char * ) relate,
( doublereal * ) &refval,
( doublereal * ) &adjust,
( doublereal * ) &step,
( doublereal * ) (cnfine->base),
( integer * ) &nintvls,
( integer * ) &nw,
( doublereal * ) work,
( doublereal * ) (result->base),
( ftnlen ) strlen(relate) );
/*
Always free dynamically allocated memory.
*/
free_SpiceMemory( work );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, result );
}
ALLOC_CHECK;
chkout_c ( "gfuds_c" );
} /* End gfuds_c */
int zzgfdsps_ ( integer * nlead,
char * string,
char * fmt,
integer * ntrail,
ftnlen stringLen,
ftnlen fmtLen )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
nlead I Number of leading blank lines to write.
string I The string to display.
fmt I Format in which the string is to be written.
ntrail I Number of trailing blank lines to write.
stringLen I Length of input argument `string'.
fmtLen I Length of input argument `fmt'.
-Detailed_Input
nlead is the number of blank lines to write before
writing the output text string.
string is a message to be displayed on the standard
output stream. This is a Fortran-style string
without a terminating null character.
fmt is a Fortran format specification used to write
the output string. This is a Fortran-style string
without a terminating null character.
FMT may be left to default ("A"), or may be used
to control the length of the string ("A10").
**NOTE**: this argument is provided only for
compatibility with the Fortran version of this
routine; the argument is currently ignored.
ntrail is the number of blank lines to write after
writing the output text string.
stringLen is the length of the input string `string'.
fmtLen is the length of the input string `fmt'.
-Detailed_Output
None. This program has no output arguments but writes to the
standard output stream.
-Parameters
None.
-Exceptions
1) If an error occurs when this routine attempts to
allocate memory dynamically, the error will be
diagnosed by routines in the call tree of this routine.
2) If the either of the input arguments `nlead' or `ntrail'
is non-positive, then no leading or trailing blank
lines will be written, respectively. This case is not
considered an error.
-Files
None.
-Particulars
This is an overlay routine for the f2c'd routine zzgfdsps_;
as such, this routine has an f2c-style calling sequence.
CSPICE GF routines should call this routine rather than
zzgfdsps_.
Since ANSI C supports the cursor control capabilities required
for GF progress reporting, it's not necessary to rely on ANSI
control sequences to effect cursor control.
This routine supports the default GF progress report display.
Output is written to the standard output stream; normally this
results in output on a terminal window.
After the output line is written, this routine moves the cursor
up and to the first column, so a subsequent call will overwrite
output from the current call.
-Examples
See calls made to this routine by the entry points of
zzgfrpwrk.
-Restrictions
The input Fortran format argument is ignored.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.0, 27-FEB-2009 (NJB)
-Index_Entries
GF output progress report string
-&
*/
{ /* Begin zzgfdsps_ */
/*
Local variables
*/
SpiceChar * CFmtPtr;
SpiceChar * CStringPtr;
SpiceInt i;
SpiceInt nl;
SpiceInt nt;
SpiceInt outlen;
/*
Participate in error tracing.
*/
chkin_c ( "zzgfdsps_" );
/*
The input strings are Fortran-style; they're not
null-terminated. Convert these to C-style strings
so we can work with them. We'll need to use dynamic
memory to hold the C-style strings.
*/
F2C_CreateStr_Sig ( stringLen, string, &CStringPtr );
if ( failed_c() )
{
/*
The CSPICE string utilities do their own clean-up of
allocated memory, so we won't attempt to free the
C string.
*/
chkout_c ( "zzgfdsps_" );
return (-1);
}
F2C_CreateStr_Sig ( fmtLen, fmt, &CFmtPtr );
if ( failed_c() )
{
/*
Failure at this point requires that we free the previous,
successfully allocated string.
*/
free ( CStringPtr );
chkout_c ( "zzgfdsps_" );
return(-1);
}
/*
Display any blank lines indicated by `nlead'.
*/
nl = *nlead;
nt = *ntrail;
for ( i = 0; i < nl; i++ )
{
putc ( '\n', stdout );
}
/*
Save the length of the output string.
*/
outlen = strlen( CStringPtr );
/*
Write the string to standard output without a trailing newline
character.
*/
printf ( "%s", CStringPtr );
/*
Force a write of any buffered, unwritten output data.
Without this call, progress report updates may not be displayed in a
timely fashion. There can be a long pause, followed by an
announcement that the task is 100% done. This behavior rather
defeats the purpose of the report.
*/
fflush ( stdout );
/*
Back up the cursor to the start of the line.
*/
for ( i = 0; i < outlen; i++ )
{
putc ( '\b', stdout );
}
/*
Display any blank lines indicated by `ntrail'.
*/
for ( i = 0; i < nt; i++ )
{
putc ( '\n', stdout );
}
/*
Free the dynamically allocated strings.
*/
free ( CStringPtr );
free ( CFmtPtr );
chkout_c ( "zzgfdsps_" );
return ( 0 );
} /* End zzgfdsps_ */
void psv2pl_c ( ConstSpiceDouble point[3],
ConstSpiceDouble span1[3],
ConstSpiceDouble span2[3],
SpicePlane * plane )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
point,
span1,
span2 I A point and two spanning vectors defining a plane.
plane O A CSPICE plane representing the plane.
-Detailed_Input
point,
span1,
span2 are, respectively, a point and two spanning vectors
that define a geometric plane in three-dimensional
space. The plane is the set of vectors
point + s * span1 + t * span2
where s and t are real numbers. The spanning
vectors span1 and span2 must be linearly
independent, but they need not be orthogonal or
unitized.
-Detailed_Output
plane is a CSPICE plane that represents the geometric
plane defined by point, span1, and span2.
-Parameters
None.
-Exceptions
1) If span1 and span2 are linearly dependent, then the vectors
point, span1, and span2 do not define a plane. The error
SPICE(DEGENERATECASE) is signaled.
-Files
None.
-Particulars
CSPICE geometry routines that deal with planes use the `plane'
data type to represent input and output planes. This data type
makes the subroutine interfaces simpler and more uniform.
The CSPICE routines that produce CSPICE planes from data that
define a plane are:
nvc2pl_c ( Normal vector and constant to plane )
nvp2pl_c ( Normal vector and point to plane )
psv2pl_c ( Point and spanning vectors to plane )
The CSPICE routines that convert CSPICE planes to data that
define a plane are:
pl2nvc_c ( Plane to normal vector and constant )
pl2nvp_c ( Plane to normal vector and point )
pl2psv_c ( Plane to point and spanning vectors )
Any of these last three routines may be used to convert this
routine's output, plane, to another representation of a
geometric plane.
-Examples
1) Project a vector v orthogonally onto a plane defined by
point, span1, and span2. proj is the projection we want; it
is the closest vector in the plane to v.
psv2pl_c ( point, span1, span2, &plane );
vprjp_c ( v, &plane, proj );
2) Find the plane determined by a spacecraft's position vector
relative to a central body and the spacecraft's velocity
vector. We assume that all vectors are given in the same
coordinate system.
/.
pos is the spacecraft's position, relative to
the central body. vel is the spacecraft's velocity
vector. pos is a point (vector, if you like) in
the orbit plane, and it is also one of the spanning
vectors of the plane.
./
psv2pl_c ( pos, pos, vel, &plane );
-Restrictions
None.
-Literature_References
[1] `Calculus and Analytic Geometry', Thomas and Finney.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.0, 05-MAR-1999 (NJB)
-Index_Entries
point and spanning vectors to plane
-&
*/
{ /* Begin psv2pl_c */
/*
This routine checks in only if an error is discovered.
*/
if ( return_c () )
{
return;
}
/*
Find the unitized cross product of SPAN1 and SPAN2; this is our
unit normal vector, or possibly its inverse.
*/
ucrss_c ( span1, span2, plane->normal );
if ( vzero_c ( plane->normal ) )
{
chkin_c ( "psv2pl_c" );
setmsg_c ( "Spanning vectors are parallel." );
sigerr_c ( "SPICE(DEGENERATECASE)" );
chkout_c ( "psv2pl_c" );
return;
}
/*
Find the plane constant corresponding to the unit normal
vector we've found.
*/
plane->constant = vdot_c ( plane->normal, point );
/*
The constant should be the distance of the plane from the
origin. If the constant is negative, negate both it and the
normal vector.
*/
if ( plane->constant < 0. )
{
plane->constant = - (plane->constant);
vminus_c ( plane->normal, plane->normal );
}
} /* End psv2pl_c */
void wninsd_c ( SpiceDouble left,
SpiceDouble right,
SpiceCell * window )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
left,
right I Left, right endpoints of new interval.
window I,O Input, output window.
-Detailed_Input
left,
right are the left and right endpoints of the interval
to be inserted.
window on input, is a CSPICE window containing zero or more
intervals.
window must be declared as a double precision
SpiceCell.
-Detailed_Output
window on output, is the original window following the
insertion of the interval from left to right.
-Parameters
None.
-Exceptions
1) If the input window does not have double precision type,
the error SPICE(TYPEMISMATCH) is signaled.
2) If left is greater than right, the error SPICE(BADENDPOINTS) is
signaled.
3) If the insertion of the interval causes an excess of elements,
the error SPICE(WINDOWEXCESS) is signaled.
-Files
None.
-Particulars
This routine inserts the interval from left to right into the
input window. If the new interval overlaps any of the intervals
in the window, the intervals are merged. Thus, the cardinality
of the input window can actually decrease as the result of an
insertion. However, because inserting an interval that is
disjoint from the other intervals in the window can increase the
cardinality of the window, the routine signals an error.
No other CSPICE unary window routine can increase the number of
intervals in the input window.
-Examples
Let window contain the intervals
[ 1, 3 ] [ 7, 11 ] [ 23, 27 ]
Then the following series of calls
wninsd_c ( 5.0, 5.0, &window ) (1)
wninsd_c ( 4.0, 8.0, &window ) (2)
wninsd_c ( 0.0, 30.0, &window ) (3)
produces the following series of windows
[ 1, 3 ] [ 5, 5 ] [ 7, 11 ] [ 23, 27 ] (1)
[ 1, 3 ] [ 4, 11 ] [ 23, 27 ] (2)
[ 0, 30 ] (3)
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
H.A. Neilan (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 29-JUL-2002 (NJB) (KRG) (HAN) (WLT) (IMU)
-Index_Entries
insert an interval into a d.p. window
-&
*/
{ /* Begin wninsd_c */
/*
Standard SPICE error handling.
*/
if ( return_c() )
{
return;
}
chkin_c ( "wninsd_c" );
/*
Make sure cell data type is d.p.
*/
CELLTYPECHK ( CHK_STANDARD, "wninsd_c", SPICE_DP, window );
/*
Initialize the cell if necessary.
*/
CELLINIT ( window );
/*
Let the f2c'd routine do the work.
*/
wninsd_ ( (doublereal * ) &left,
(doublereal * ) &right,
(doublereal * ) (window->base) );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, window );
}
chkout_c ( "wninsd_c" );
} /* End wninsd_c */
void vprjpi_c ( ConstSpiceDouble vin [3],
ConstSpicePlane * projpl,
ConstSpicePlane * invpl,
SpiceDouble vout [3],
SpiceBoolean * found )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
vin I The projected vector.
projpl I Plane containing vin.
invpl I Plane containing inverse image of vin.
vout O Inverse projection of vin.
found O Flag indicating whether vout could be calculated.
-Detailed_Input
vin,
projpl,
invpl are, respectively, a 3-vector, a CSPICE plane
containing the vector, and a CSPICE plane
containing the inverse image of the vector under
orthogonal projection onto projpl.
-Detailed_Output
vout is the inverse orthogonal projection of vin. This
is the vector lying in the plane invpl whose
orthogonal projection onto the plane projpl is
vin. vout is valid only when found (defined below)
is SPICETRUE. Otherwise, vout is undefined.
found indicates whether the inverse orthogonal projection
of vin could be computed. found is SPICETRUE if so,
SPICEFALSE otherwise.
-Parameters
None.
-Exceptions
1) If the geometric planes defined by projpl and invpl are
orthogonal, or nearly so, the inverse orthogonal projection
of vin may be undefined or have magnitude too large to
represent with double precision numbers. In either such
case, found will be set to SPICEFALSE.
2) Even when found is SPICETRUE, vout may be a vector of extremely
large magnitude, perhaps so large that it is impractical to
compute with it. It's up to you to make sure that this
situation does not occur in your application of this routine.
-Files
None.
-Particulars
Projecting a vector orthogonally onto a plane can be thought of
as finding the closest vector in the plane to the original vector.
This `closest vector' always exists; it may be coincident with the
original vector. Inverting an orthogonal projection means finding
the vector in a specified plane whose orthogonal projection onto
a second specified plane is a specified vector. The vector whose
projection is the specified vector is the inverse projection of
the specified vector, also called the `inverse image under
orthogonal projection' of the specified vector. This routine
finds the inverse orthogonal projection of a vector onto a plane.
Related routines are vprjp_c, which projects a vector onto a plane
orthogonally, and vproj_c, which projects a vector onto another
vector orthogonally.
-Examples
1) Suppose
vin = ( 0.0, 1.0, 0.0 ),
and that projpl has normal vector
projn = ( 0.0, 0.0, 1.0 ).
Also, let's suppose that invpl has normal vector and constant
invn = ( 0.0, 2.0, 2.0 )
invc = 4.0.
Then vin lies on the y-axis in the x-y plane, and we want to
find the vector vout lying in invpl such that the orthogonal
projection of vout the x-y plane is vin. Let the notation
< a, b > indicate the inner product of vectors a and b.
Since every point x in invpl satisfies the equation
< x, (0.0, 2.0, 2.0) > = 4.0,
we can verify by inspection that the vector
( 0.0, 1.0, 1.0 )
is in invpl and differs from vin by a multiple of projn. So
( 0.0, 1.0, 1.0 )
must be vout.
To find this result using CSPICE, we can create the
CSPICE planes projpl and invpl using the code fragment
nvp2pl_c ( projn, vin, &projpl );
nvc2pl_c ( invn, invc, &invpl );
and then perform the inverse projection using the call
vprjpi_c ( vin, &projpl, &invpl, vout );
vprjpi_c will return the value
vout = ( 0.0, 1.0, 1.0 );
-Restrictions
None.
-Literature_References
[1] `Calculus and Analytic Geometry', Thomas and Finney.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.1.0, 05-APR-2004 (NJB)
Computation of LIMIT was re-structured to avoid
run-time underflow warnings on some platforms.
-CSPICE Version 1.0.0, 05-MAR-1999 (NJB)
-Index_Entries
vector projection onto plane inverted
-&
*/
/*
-Revisions
-CSPICE Version 1.1.0, 05-APR-2004 (NJB)
Computation of LIMIT was re-structured to avoid run-time
underflow warnings on some platforms. In the revised code,
BOUND/dpmax_c() is never scaled by a number having absolute value
< 1.
-&
*/
{ /* Begin vprjpi_c */
/*
Local constants
*/
/*
BOUND is used to bound the magnitudes of the numbers that we
try to take the reciprocal of, since we can't necessarily invert
any non-zero number. We won't try to invert any numbers with
magnitude less than
BOUND / dpmax_c()
BOUND is chosen somewhat arbitrarily....
*/
#define BOUND 10.0
/*
Local variables
*/
SpiceDouble denom;
SpiceDouble invc;
SpiceDouble invn [3];
SpiceDouble limit;
SpiceDouble mult;
SpiceDouble numer;
SpiceDouble projc;
SpiceDouble projn [3];
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "vprjpi_c" );
/*
Unpack the planes.
*/
pl2nvc_c ( projpl, projn, &projc );
pl2nvc_c ( invpl, invn, &invc );
/*
We'll first discuss the computation of VOUT in the nominal case,
and then deal with the exceptional cases.
When projpl and invpl are not orthogonal to each other, the
inverse projection of vin will differ from vin by a multiple of
projn, the unit normal vector to projpl. We find this multiple
by using the fact that the inverse projection vout satisfies the
plane equation for the inverse projection plane invpl.
We have
vout = vin + mult * projn; (1)
since vout satisfies
< vout, invn > = invc
we must have
< vin + mult * projn, invn > = invc
which in turn implies
invc - < vin, invn >
mult = ------------------------. (2)
< projn, invn >
Having mult, we can compute vout according to equation (1).
Now, if the denominator in the above expression for mult is zero
or just too small, performing the division would cause a
divide-by-zero error or an overflow of mult. In either case, we
will avoid carrying out the division, and we'll set found to
SPICEFALSE.
Compute the numerator and denominator of the right side of (2).
*/
numer = invc - vdot_c ( vin, invn );
denom = vdot_c ( projn, invn );
/*
If the magnitude of the denominator is greater than
BOUND
limit = abs ( ---------- * numer ),
dpmax_c()
we can safely divide the numerator by the denominator, and the
magnitude of the result will be no greater than
dpmax_c()
----------- .
BOUND
Note that we have ruled out the case where numer and denom are
both zero by insisting on strict inequality in the comparison of
denom and limit:
*/
if ( fabs(numer) < 1.0 )
{
limit = fabs ( BOUND / dpmax_c() );
}
else
{
limit = fabs ( ( BOUND / dpmax_c() ) * numer );
}
*found = ( fabs (denom) > limit );
if ( *found )
{
/*
We'll compute vout after all.
*/
mult = numer / denom;
vlcom_c ( 1.0, vin, mult, projn, vout );
}
chkout_c ( "vprjpi_c" );
} /* End vprjpi_c */
void kdata_c ( SpiceInt which,
ConstSpiceChar * kind,
SpiceInt fillen,
SpiceInt typlen,
SpiceInt srclen,
SpiceChar * file,
SpiceChar * filtyp,
SpiceChar * source,
SpiceInt * handle,
SpiceBoolean * found )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
which I Index of kernel to fetch from the list of kernels.
kind I The kind of kernel to which fetches are limited.
fillen I Available space in output file string.
typlen I Available space in output kernel type string.
srclen I Available space in output source string.
file O The name of the kernel file.
filtyp O The type of the kernel.
source O Name of the source file used to load file.
handle O The handle attached to file.
found O SPICETRUE if the specified file could be located.
-Detailed_Input
which is the number of the kernel to fetch (matching the
type specified by kind) from the list of kernels that
have been loaded through the entry point furnsh_c but
that have not been unloaded through the entry point
unload_c.
The range of which is 0 to count-1, where count is
the number of kernels loaded via furnsh_c. This
count may be obtained by calling ktotal_c. See the
Examples section for an illustrative code fragment.
kind is a list of types of kernels to be considered when
fetching kernels from the list of loaded kernels. KIND
should consist of a list of words of kernels to
examine. Recognized types are
SPK --- All SPK files are counted in the total.
CK --- All CK files are counted in the total.
PCK --- All binary PCK files are counted in the
total.
EK --- All EK files are counted in the total.
TEXT --- All text kernels that are not meta-text
kernels are included in the total.
META --- All meta-text kernels are counted in the
total.
ALL --- Every type of kernel is counted in the
total.
kind is case insensitive. If a word appears in kind
that is not one of those listed above it is ignored.
See the entry point ktotal_c for examples of the use
of kind.
fillen is the amount of available space in the output file
string, including room for the terminating null.
Normally, this is the declared length of the output
string.
typlen is the amount of available space in the output kernel
type string.
srclen is the amount of available space in the output kernel
source string.
-Detailed_Output
file is the name of the file having index which in the
sequence of files of type kind currently loaded via
furnsh_c. file will be blank if there is no such kernel
is loaded.
filtyp is the type of the kernel specified by file. filtyp
will be empty if there is no file matching the
specification of which and kind.
source is the name of the source file that was used to
specify file as one to load. If file was loaded
directly via a call to furnsh_c, source will be empty.
If there is no file matching the specification of
which and kind, source will be empty.
handle is the handle attached to file if it is a binary
kernel. If file is a text kernel or meta-text kernel
handle will be zero. If there is no file matching
the specification of which and kind, handle will be
set to zero.
found is returned SPICETRUE if a file matching the
specification of which and kind exists. If there is no
such file, found will be set to SPICEFALSE.
-Parameters
None.
-Exceptions
1) If a file is not loaded matching the specification of which
and kind, found will be SPICEFALSE; file, filtyp, and source
will be empty and handle will be set to zero.
2) If any input or output character argument pointer is null, the
error SPICE(NULLPOINTER) will be signaled.
3) If any of the output string length arguments are less than 1, the
error SPICE(STRINGTOOSHORT) will be signaled.
4) If any output string has length at least 1 but is too short to
contain the output string, the corresponding is truncated on the
right. The output string is still null-terminated.
-Files
None.
-Particulars
This entry point allows you to determine which kernels have
been loaded via furnsh_c and to obtain information sufficient
to directly query those files.
-Examples
The following example shows how you could print a summary
of SPK files that have been loaded through the interface
furnsh_c.
#include <stdio.h>
#include "SpiceUsr.h"
#define FILLEN 128
#define TYPLEN 32
#define SRCLEN 128
SpiceInt which;
SpiceInt count;
SpiceInt handle;
SpiceChar file [FILLEN];
SpiceChar filtyp[TYPLEN];
SpiceChar source[SRCLEN];
SpiceBoolean found;
int main()
{
furnsh_c( "/kernels/standard.tm" );
ktotal_c ( "spk", &count );
if ( count == 0 )
{
printf ( "No SPK files loaded at this time.\n" );
}
else
{
printf ( "The loaded SPK files are: \n\n" );
}
for ( which = 0; which < count; which++ )
{
kdata_c ( which, "spk", FILLEN, TYPLEN, SRCLEN,
file, filtyp, source, &handle, &found );
printf ( "%s\n", file );
}
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.1.3, 02-MAY-2008 (EDW)
standard.ker renamed standard.tm
-CSPICE Version 1.1.2, 05-SEP-2007 (EDW)
Expanded Examples section to a full, compilable program.
-CSPICE Version 1.1.1, 29-DEC-2004 (LSE)
Corrected example code to match routine's argument list.
(2 arguments reversed)
-CSPICE Version 1.1.0, 02-FEB-2003 (EDW)
Corrected example code to match routine's argument list.
-CSPICE Version 1.0.0, 12-SEP-1999 (NJB) (WLT)
-Index_Entries
Retrieve information on loaded SPICE kernels
-&
*/
{ /* Begin kdata_c */
/*
Local variables
*/
logical fnd;
/*
Participate in error tracing.
*/
chkin_c ( "kdata_c" );
/*
Check the input string kind to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "kdata_c", kind );
/*
Make sure the output string file has at least enough room for one
output character and a null terminator. Also check for a null
pointer.
*/
CHKOSTR ( CHK_STANDARD, "kdata_c", file, fillen );
/*
Make sure the output string filtyp has at least enough room for one
output character and a null terminator. Also check for a null
pointer.
*/
CHKOSTR ( CHK_STANDARD, "kdata_c", filtyp, typlen );
/*
Make sure the output string source has at least enough room for one
output character and a null terminator. Also check for a null
pointer.
*/
CHKOSTR ( CHK_STANDARD, "kdata_c", source, srclen );
/*
Map the input index from C to Fortran style.
*/
which++;
/*
Call the f2c'd routine.
*/
kdata_ ( ( integer * ) &which,
( char * ) kind,
( char * ) file,
( char * ) filtyp,
( char * ) source,
( integer * ) handle,
( logical * ) &fnd,
( ftnlen ) strlen(kind),
( ftnlen ) fillen-1,
( ftnlen ) typlen-1,
( ftnlen ) srclen-1 );
/*
Convert the output strings from Fortran style to C style. Set
the SpiceBoolean output found flag.
*/
F2C_ConvertStr( fillen, file );
F2C_ConvertStr( typlen, filtyp );
F2C_ConvertStr( srclen, source );
*found = fnd;
chkout_c ( "kdata_c" );
} /* End kdata_c */
void dtpool_c ( ConstSpiceChar * name,
SpiceBoolean * found,
SpiceInt * n,
SpiceChar type [1] )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
name I Name of the variable whose value is to be returned.
found O True if variable is in pool.
n O Number of values returned for name.
type O Type of the variable: 'C', 'N', or 'X'
-Detailed_Input
name is the name of the variable whose values are to be
returned.
-Detailed_Output
found is SPICETRUE if the variable is in the pool;
SPICEFALSE if it is not.
n is the number of values associated with name.
If name is not present in the pool n will be returned
with the value 0.
type is a single character indicating the type of the variable
associated with name.
'C' if the data is character data
'N' if the data is numeric.
'X' if there is no variable name in the pool.
-Parameters
None.
-Exceptions
1) If the name requested is not in the kernel pool, found
will be set to SPICEFALSE, n to zero and type to 'X'.
2) If the input string pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
3) If the input string has length zero, the error SPICE(EMPTYSTRING)
will be signaled.
-Files
None.
-Particulars
This routine allows you to determine whether or not a kernel
pool variable is present and to determine its size and type
if it is.
-Examples
The following code fragment demonstrates how to determine the
properties of a stored kernel variable.
#include <stdio.h>
#include "SpiceUsr.h"
.
.
.
dtpool_c ( varnam, &found, &n, &type );
if ( found )
{
printf ( "\n"
"Properties of variable %s:\n"
"\n"
" Size: %d\n",
varnam,
n );
if ( type == 'C' )
{
printf ( " Type: Character\n" );
}
else
{
printf ( " Type: Numeric\n" );
}
}
else
{
printf ( "%s is not present in the kernel pool.\n", varnam );
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
W.L. Taber (JPL)
-Version
-CSPICE Version 1.1.0, 17-OCT-1999 (NJB)
Local type logical variable now used for found flag used in
interface of dtpool_.
-CSPICE Version 1.0.0, 10-MAR-1999 (NJB)
-Index_Entries
return summary information about a kernel pool variable
-&
*/
{ /* Begin dtpool_c */
/*
Local variables
*/
logical fnd;
/*
Participate in error tracing.
*/
chkin_c ( "dtpool_c" );
/*
Check the input string name to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "dtpool_c", name );
/*
Call the f2c'd routine.
*/
dtpool_ ( ( char * ) name,
( logical * ) &fnd,
( integer * ) n,
( char * ) type,
( ftnlen ) strlen(name),
( ftnlen ) 1 );
/*
Assign the SpiceBoolean found flag.
*/
*found = fnd;
chkout_c ( "dtpool_c" );
} /* End dtpool_c */
void dafrfr_c ( SpiceInt handle,
SpiceInt lenout,
SpiceInt * nd,
SpiceInt * ni,
SpiceChar * ifname,
SpiceInt * fward,
SpiceInt * bward,
SpiceInt * free )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of an open DAF file.
lenout I Available room in the output string `ifname'.
nd O Number of double precision components in summaries.
ni O Number of integer components in summaries.
ifname O Internal file name.
fward O Forward list pointer.
bward O Backward list pointer.
free O Free address pointer.
-Detailed_Input
handle is the handle assigned to a DAF file opened for
reading.
lenout is the maximum number of characters that can be
accommodated in the output string `ifname'. This count
includes room for the terminating null character.
DAF internal file names may contain up to 60
characters, so lenout normally should be set to 61.
-Detailed_Output
nd,
ni are the numbers of double precision and integer
components, respectively, in each array summary in
the specified file.
ifname is the internal file name stored in the first
(or file) record of the specified file. `ifname'
should be declared with the length specified by
`lenout'.
fward is the forward list pointer. This points to the
first summary record in the file. (Records between
the first record and the first summary record are
reserved when the file is created, and are invisible
to DAF routines.)
DAF list pointers are actually Fortran record numbers,
and as such, start at one.
bward is the backward list pointer. This points
to the final summary record in the file.
free is the free address pointer. This contains the
first free address in the file. (That is, the
initial address of the next array to be added
to the file.)
`free' is a DAF address; for compatiblity with
SPICELIB, the range of DAF addresses starts at 1.
-Parameters
None.
-Exceptions
1) If the handle passed to this routine is not the handle of an
open DAF file, the error will be signaled by a routine called
by this routine.
2) If the specified DAF file is not open for read access, the
error will be diagnosed by a routine called by this routine.
3) If the specified record cannot (for some reason) be read,
the error SPICE(DAFFRNOTFOUND) is signaled.
-Files
The input `handle' should refer to a DAF file open for read
or write access.
-Particulars
The file record of a DAF is the only record that contains
any global information about the file. This record is created
when the file is created, and is updated only when new arrays
are added.
Like character records, file records are not buffered.
-Examples
In the following example, the file record of a DAF is read
to determine the first free address in the file.
#include <stdio.h>
#include "SpiceUsr.h"
int main ( int argc, char ** argv )
{
#define IFNLEN 61
SpiceChar ifname[IFNLEN];
SpiceInt bward;
SpiceInt free;
SpiceInt fward;
SpiceInt handle;
SpiceInt nd;
SpiceInt ni;
dafopr_c ( argv[1], &handle );
dafrfr_c ( handle, IFNLEN, &nd, &ni, ifname, &fward, &bward, &free );
printf ( "First free DAF address is %ld.\n", free );
return ( 0 );
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 17-JUN-2009 (NJB) (KRG) (IMU)
-Index_Entries
read daf file record
-&
*/
{ /* Begin dafrfr_c */
/*
Participate in error tracing.
*/
chkin_c ( "dafrfr_c" );
dafrfr_ ( (integer *) &handle,
(integer *) nd,
(integer *) ni,
(char *) ifname,
(integer *) fward,
(integer *) bward,
(integer *) free,
(ftnlen ) lenout-1 );
/*
Convert the internal file name to a C-style string.
*/
F2C_ConvertStr ( lenout, ifname );
chkout_c ( "dafrfr_c" );
} /* End dafrfr_c */
void spkw09_c ( SpiceInt handle,
SpiceInt body,
SpiceInt center,
ConstSpiceChar * frame,
SpiceDouble first,
SpiceDouble last,
ConstSpiceChar * segid,
SpiceInt degree,
SpiceInt n,
ConstSpiceDouble states[][6],
ConstSpiceDouble epochs[] )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of an SPK file open for writing.
body I NAIF code for an ephemeris object.
center I NAIF code for center of motion of body.
frame I Reference frame name.
first I Start time of interval covered by segment.
last I End time of interval covered by segment.
segid I Segment identifier.
degree I Degree of interpolating polynomials.
n I Number of states.
states I Array of states.
epochs I Array of epochs corresponding to states.
maxdeg P Maximum allowed degree of interpolating polynomial.
-Detailed_Input
handle is the file handle of an SPK file that has been
opened for writing.
body is the NAIF integer code for an ephemeris object
whose state relative to another body is described
by the segment to be created.
center is the NAIF integer code for the center of motion
of the object identified by body.
frame is the NAIF name for a reference frame
relative to which the state information for body
is specified.
first,
last are, respectively, the start and stop times of
the time interval over which the segment defines
the state of body.
segid is the segment identifier. An SPK segment
identifier may contain up to 40 characters.
degree is the degree of the Lagrange polynomials used to
interpolate the states. All components of the
state vectors are interpolated by polynomials of
fixed degree.
n is the number of states in the input state vector
array.
states contains a time-ordered array of geometric states
( x, y, z, dx/dt, dy/dt, dz/dt, in kilometers and
kilometers per second ) of body relative to center,
specified relative to frame.
epochs is an array of epochs corresponding to the members
of the state array. The epochs are specified as
seconds past J2000, TDB.
-Detailed_Output
None. See $Particulars for a description of the effect of this
routine.
-Parameters
MAXDEG is the maximum allowed degree of the interpolating
polynomial. If the value of MAXDEG is increased,
the CSPICE routine spkpvn_ must be changed
accordingly. In particular, the size of the
record passed to spkrNN_ and spkeNN_ must be
increased, and comments describing the record size
must be changed.
The current value of MAXDEG is 15.
-Exceptions
If any of the following exceptions occur, this routine will return
without creating a new segment.
1) If frame is not a recognized name, the error
SPICE(INVALIDREFFRAME) is signaled.
2) If the last non-blank character of segid occurs past index 40,
the error SPICE(SEGIDTOOLONG) is signaled.
3) If segid contains any nonprintable characters, the error
SPICE(NONPRINTABLECHARS) is signaled.
4) If degree is not at least 1 or is greater than MAXDEG, the
error SPICE(INVALIDDEGREE) is signaled.
5) If the number of states n is not at least degree+1, the error
SPICE(TOOFEWSTATES) will be signaled.
6) If first is greater than or equal to last then the error
SPICE(BADDESCRTIMES) will be signaled.
7) If the elements of the array epochs are not in strictly
increasing order, the error SPICE(TIMESOUTOFORDER) will be
signaled.
8) If the first epoch epochs[0] is greater than first, the error
SPICE(BADDESCRTIMES) will be signaled.
9) If the last epoch epochs[n] is less than last, the error
SPICE(BADDESCRTIMES) will be signaled.
10) If either the input frame or segment ID string pointer is null,
the error SPICE(NULLPOINTER) is signaled.
11) If either the input frame or segment ID string is empty,
the error SPICE(EMPTYSTRING) is signaled.
-Files
A new type 9 SPK segment is written to the SPK file attached
to handle.
-Particulars
This routine writes an SPK type 09 data segment to the open SPK
file according to the format described in the type 09 section of
the SPK Required Reading. The SPK file must have been opened with
write access.
-Examples
Suppose that you have states and are prepared to produce
a segment of type 09 in an SPK file.
The following code fragment could be used to add the new segment
to a previously opened SPK file attached to HANDLE. The file must
have been opened with write access.
#include "SpiceUsr.h"
.
.
.
/.
Create a segment identifier.
./
#define SEGID "MY_SAMPLE_SPK_TYPE_9_SEGMENT"
/.
Write the segment.
./
spkw09_c ( handle, body, center, frame,
first, last, segid, degree,
n, states, epochs );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
K.R. Gehringer (JPL)
N.J. Bachman (JPL)
J.M. Lynch (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.0.0, 21-JUN-1999 (KRG) (NJB) (JML) (WLT)
-Index_Entries
write spk type_9 ephemeris data segment
-&
*/
{ /* Begin spkw09_c */
/*
Participate in error tracing.
*/
chkin_c ( "spkw09_c" );
/*
Check the input strings to make sure the pointers
are non-null and the string lengths are non-zero.
*/
CHKFSTR ( CHK_STANDARD, "spkw09_c", frame );
CHKFSTR ( CHK_STANDARD, "spkw09_c", segid );
/*
Write the segment.
*/
spkw09_ ( ( integer * ) &handle,
( integer * ) &body,
( integer * ) ¢er,
( char * ) frame,
( doublereal * ) &first,
( doublereal * ) &last,
( char * ) segid,
( integer * ) °ree,
( integer * ) &n,
( doublereal * ) states,
( doublereal * ) epochs,
( ftnlen ) strlen(frame),
( ftnlen ) strlen(segid) );
chkout_c ( "spkw09_c" );
} /* End spkw09_c */
void spkw02_c ( SpiceInt handle,
SpiceInt body,
SpiceInt center,
ConstSpiceChar * frame,
SpiceDouble first,
SpiceDouble last,
ConstSpiceChar * segid,
SpiceDouble intlen,
SpiceInt n,
SpiceInt polydg,
ConstSpiceDouble cdata [],
SpiceDouble btime )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of an SPK file open for writing.
body I Body code for ephemeris object.
center I Body code for the center of motion of the body.
frame I The reference frame of the states.
first I First valid time for which states can be computed.
last I Last valid time for which states can be computed.
segid I Segment identifier.
intlen I Length of time covered by logical record.
n I Number of coefficient sets.
polydg I Chebyshev polynomial degree.
cdata I Array of Chebyshev coefficients.
btime I Begin time of first logical record.
-Detailed_Input
handle DAF handle of an SPK file to which a type 2 segment
is to be added. The SPK file must be open for
writing.
body NAIF integer code for an ephemeris object whose
state relative to another body is described by the
segment to be created.
center NAIF integer code for the center of motion of the
object identified by body.
frame NAIF name for a reference frame relative to which
the state information for body is specified.
first,
last Start and stop times of the time interval over
which the segment defines the state of body.
segid Segment identifier. An SPK segment identifier may
contain up to 40 characters.
intlen Length of time, in seconds, covered by each set of
Chebyshev polynomial coefficients (each logical
record). Each set of Chebyshev coefficients must
cover this fixed time interval, intlen.
n Number of sets of Chebyshev polynomial coefficients
for coordinates (number of logical records) to be
stored in the segment. There is one set of
Chebyshev coefficients for each time period.
polydg Degree of each set of Chebyshev polynomials, i.e.
the number of Chebyshev coefficients per coordinate
minus one.
cdata Array containing all the sets of Chebyshev
polynomial coefficients to be placed in the
segment of the SPK file. The coefficients are
stored in cdata in order as follows:
the (degree + 1) coefficients for the first
coordinate of the first logical record
the coefficients for the second coordinate
the coefficients for the third coordinate
the coefficients for the first coordinate for
the second logical record, ...
and so on.
btime Begin time (seconds past J2000 TDB) of first set
of Chebyshev polynomial coefficients (first
logical record). first is an appropriate value
for btime.
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If the number of sets of coefficients is not positive
SPICE(NUMCOEFFSNOTPOS) is signalled.
2) If the interval length is not positive, SPICE(INTLENNOTPOS)
is signalled.
3) If the integer code for the reference frame is not recognized,
SPICE(INVALIDREFFRAME) is signalled.
4) If segment stop time is not greater then the begin time,
SPICE(BADDESCRTIMES) is signalled.
5) If the start time of the first record is not less than
or equal to the descriptor begin time, SPICE(BADDESCRTIMES)
is signalled.
6) If the end time of the last record is not greater than
or equal to the descriptor end time, SPICE(BADDESCRTIMES) is
signalled.
7) The error SPICE(EMPTYSTRING) is signaled if either input
string does not contain at least one character, since the
input strings cannot be converted to a Fortran-style string
in this case.
8) The error SPICE(NULLPOINTER) is signaled if either input string
pointer is null.
-Files
A new type 2 SPK segment is written to the SPK file attached
to handle.
-Particulars
This routine writes an SPK type 2 data segment to the designated
SPK file, according to the format described in the SPK Required
Reading.
Each segment can contain data for only one target, central body,
and reference frame. The Chebyshev polynomial degree and length
of time covered by each logical record are also fixed. However,
an arbitrary number of logical records of Chebyshev polynomial
coefficients can be written in each segment. Minimizing the
number of segments in an SPK file will help optimize how the SPICE
system accesses the file.
-Examples
Suppose that you have sets of Chebyshev polynomial coefficients
in an array CDATA pertaining to the position of the moon (NAIF ID
= 301), relative to the Earth-moon barycenter (NAIF ID = 3), in
the J2000 reference frame, and want to put these into a type 2
segment in an existing SPK file. The following code could be used
to add one new type 2 segment. To add multiple segments, put the
call to spkw02_c in a loop.
#include "SpiceUsr.h"
.
.
.
/.
First open the SPK file and get a handle for it.
./
spkopa_c ( spknam, &handle );
/.
Create a segment identifier.
./
segid = "MY_SAMPLE_SPK_TYPE_2_SEGMENT";
/.
Write the segment.
./
spkw02_c ( handle, 301, 3, "J2000",
first, last, segid, intlen,
n, polydg, cdata, btime );
/.
Close the file.
./
spkcls_c ( handle );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.S. Zukor (JPL)
-Version
-CSPICE Version 1.0.0, 21-JUL-1999 (NJB) (KSZ)
-Index_Entries
write spk type_2 data segment
-&
*/
{ /* Begin spkw02_c */
/*
Participate in error tracing.
*/
chkin_c ( "spkw02_c" );
/*
Check the input strings to make sure the pointers
are non-null and the string lengths are non-zero.
*/
CHKFSTR ( CHK_STANDARD, "spkw02_c", frame );
CHKFSTR ( CHK_STANDARD, "spkw02_c", segid );
/*
Write the segment.
*/
spkw02_ ( ( integer * ) &handle,
( integer * ) &body,
( integer * ) ¢er,
( char * ) frame,
( doublereal * ) &first,
( doublereal * ) &last,
( char * ) segid,
( doublereal * ) &intlen,
( integer * ) &n,
( integer * ) &polydg,
( doublereal * ) cdata,
( doublereal * ) &btime,
( ftnlen ) strlen(frame),
( ftnlen ) strlen(segid) );
chkout_c ( "spkw02_c" );
} /* End spkw02_c */
int zzadstep_c ( doublereal * time,
doublereal * step )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
time I Time from which the next step will be taken.
step O Time step to take.
-Detailed_Input
time is the input start time from which the algorithm is to
search forward for a state transition. `time' is expressed
as seconds past J2000 TDB.
-Detailed_Output
step is the output step size. `step' is the value stored via the
last call to gfsstp_c. Units are TDB seconds.
-Parameters
None.
-Exceptions
1) A run-time error will result if this routine is called before
a valid pointer to a CSPICE-style GF step size function has
been stored via a call to zzadsave_c.
The argument list of the stored function must match that of
gfstep_c.
-Files
None.
-Particulars
This routine is meant to be passed to f2c'd Fortran GF code
that requires a step size function input argument. The argument
list of this routine matches that of the f2c'd routine
gfstep_
This routine calls the CSPICE-style stepsize function passed
into a CSPICE wrapper for an intermediate-level GF function.
A pointer to this step size function must be stored via
a call to zzadsave_c before this routine is called.
When set properly, `step' indicates how far to advance `time' so
that `time' and `time+step' may bracket a state transition and
definitely do not bracket more than one state transition.
The calling application can change the step size value via the entry
point gfsstp_c.
-Examples
None.
-Restrictions
1) This function is intended only for internal use by GF routines.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
L.S. Elson (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 1.0.0, 24-MAR-2008 (NJB)
-Index_Entries
adapter for gf step size function
-&
*/
{ /* Begin zzadstep_c */
/*
Local variables
*/
void ( * fPtr ) ( SpiceDouble,
SpiceDouble * );
/*
Participate in error tracing.
*/
if ( return_c() )
{
return ( 0 );
}
chkin_c ( "zzadstep_c" );
/*
Retrieve the stored pointer for the passed-in function; cast
the pointer from (void *) to that of a function whose argument
list matches that of gfstep_c.
*/
fPtr = ( void (*) (SpiceDouble, SpiceDouble*) ) zzadget_c ( UDSTEP );
/*
Call the stored function.
*/
(*fPtr) ( (SpiceDouble)(*time), (SpiceDouble *)step );
chkout_c ( "zzadstep_c" );
return ( 0 );
} /* End zzadstep_c */
void spk14b_c ( SpiceInt handle,
ConstSpiceChar * segid,
SpiceInt body,
SpiceInt center,
ConstSpiceChar * frame,
SpiceDouble first,
SpiceDouble last,
SpiceInt chbdeg )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
handle I The handle of an SPK file open for writing.
segid I The string to use for segment identifier.
body I The NAIF ID code for the body of the segment.
center I The center of motion for body.
frame I The reference frame for this segment.
first I The first epoch for which the segment is valid.
last I The last epoch for which the segment is valid.
chbdeg I The degree of the Chebyshev Polynomial used.
-Detailed_Input
handle is the file handle of an SPK file that has been
opened for writing.
segid is the segment identifier. An SPK segment identifier
may contain up to 40 printing ASCII characters.
body is the NAIF ID for the body whose states are
to be recorded in an SPK file.
center is the NAIF ID for the center of motion associated
with body.
frame is the reference frame that states are referenced to,
for example "J2000".
first is the starting epoch, in TDB seconds past J2000, for
the ephemeris data to be placed into the segment.
last is the ending epoch, in TDB seconds past J2000, for
the ephemeris data to be placed into the segment.
chbdeg is the degree of the Chebyshev Polynomials used to
represent the ephemeris information stored in the
segment.
-Detailed_Output
None. The input data is used to create the segment summary
for the segment being started in the SPK file
associated with handle.
See the Particulars section for details about the
structure of a type 14 SPK segment.
-Parameters
None.
-Particulars
This routine begins writing a type 14 SPK segment to the open SPK
file that is associated with handle. The file must have been
opened with write access.
This routine is one of a set of three routines for creating and
adding data to type 14 SPK segments. These routines are:
spk14b_c: Begin a type 14 SPK segment. This routine must be
called before any data may be added to a type 14
segment.
spk14a_c: Add data to a type 14 SPK segment. This routine may be
called any number of times after a call to spk14b_c to
add type 14 records to the SPK segment that was
started.
spk14e_c: End a type 14 SPK segment. This routine is called to
make the type 14 segment a permanent addition to the
SPK file. Once this routine is called, no further type
14 records may be added to the segment. A new segment
must be started.
A type 14 SPK segment consists of coefficient sets for fixed order
Chebyshev polynomials over consecutive time intervals, where the
time intervals need not all be of the same length. The Chebyshev
polynomials represent the position, X, Y, and Z coordinates, and
the velocities, dX/dt, dY/dt, and dZ/dt, of body relative to
center.
The ephemeris data supplied to the type 14 SPK writer is packed
into an array as a sequence of records,
-----------------------------------------------------
| Record 1 | Record 2 | ... | Record N-1 | Record N |
-----------------------------------------------------
with each record has the following format.
------------------------------------------------
| The midpoint of the approximation interval |
------------------------------------------------
| The radius of the approximation interval |
------------------------------------------------
| chbdeg+1 coefficients for the X coordinate |
------------------------------------------------
| chbdeg+1 coefficients for the Y coordinate |
------------------------------------------------
| chbdeg+1 coefficients for the Z coordinate |
------------------------------------------------
| chbdeg+1 coefficients for the X velocity |
------------------------------------------------
| chbdeg+1 coefficients for the Y velocity |
------------------------------------------------
| chbdeg+1 coefficients for the Z velocity |
------------------------------------------------
-Examples
Assume we have the following for each of the examples that
follow.
handle is the handle of an SPK file opened with write
access.
segid is a character string of no more than 40 characters
which provides a pedigree for the data in the SPK
segment we will create.
body is the NAIF ID code for the body whose ephemeris
is to be placed into the file.
center is the center of motion for the ephemeris of body.
reffrm is the name of the SPICE reference frame for the
ephemeris.
first is the starting epoch, in seconds past J2000, for
the ephemeris data to be placed into the segment.
last is the ending epoch, in seconds past J2000, for
the ephemeris data to be placed into the segment.
Example 1:
For this example, we also assume that:
n is the number of type 14 records that we want to
put into a segment in an SPK file.
recrds contains n type 14 records packaged for the SPK
file.
etstrt contains the initial epochs for each of the
records contained in RECRDS, where
etstrt[i] < etstrt[i+1], i = 0, n-2
etstrt[1] <= first, etstrt[n-1] < last
etstrt[i+1], i = 0, n-2, is the ending epoch for
record i as well as the initial epoch for record
i+1.
Then the following code fragment demonstrates how to create a
type 14 SPK segment if all of the data for the segment is
available at one time.
#include "SpiceUsr.h"
.
.
.
#define SPK "example.bsp"
/.
If the segment is to be appended to an existing file, open
that file for "append" access. Otherwise, create a new file.
./
if ( exists_c(SPK) )
{
spkopa_c ( SPK, &handle );
}
else
{
/.
New files are supplied with an internal file name.
Comment area space may be reserved at this time; the
units are characters.
./
ifname = "Sample type 14 SPK file.";
ncomch = 1024;
spkopn_c ( SPK, ifname, ncomch, &handle );
}
/.
Begin the segment.
./
spk14b_c ( handle, segid, body, center, reffrm,
first, last, chbdeg );
/.
Add the data to the segment all at once.
./
spk14a_c ( handle, n, recrds, etstrt );
/.
End the segment, making the segment a permanent addition
to the SPK file.
./
spk14e_c ( handle );
.
.
.
/.
After all segments have been loaded, close the SPK file.
./
spkcls_c ( handle );
Example 2:
In this example we want to add type 14 SPK records, as described
above in the Particulars section, to the segments being written
as they are generated. The ability to write the records in this
way is useful if computer memory is limited. It may also be
convenient from a programming perspective to write the records
one at a time.
For this example, assume that we want to generate n type 14 SPK
records, one for each of n time intervals, writing them all to
the same segment in the SPK file. Let
n be the number of type 14 records that we want to
generate and put into a segment in an SPK file.
record be an array with enough room to hold a single type
14 record, i.e. record should have dimension at
least 6 * (chbdeg + 1 ) + 2.
start be an array of n times that are the beginning
epochs for each of the intervals of interest. The
times should be in increasing order and the start
time for the first interval should equal the
starting time for the segment.
start[i] < start[i+1], i = 0, n-2
start[0] = first
stop be an array of n times that are the ending epochs
for each of the intervals of interest. The times
should be in increasing order and the stop time for
interval i should equal the start time for interval
i+1, i.e., we want to have continuous coverage in
time across all of the records. Also, the stop time
for the last interval should equal the ending time
for the segment.
stop[i] < stop [i+1], i = 0, n-2
stop[i] = start[i+1], i = 0, n-2
stop[n-1] = last
genrec( time1, time2, record )
be a subroutine that generates a type 14 SPK record
for a time interval specified by time1 and time2.
Then the following code fragment demonstrates how to create a
type 14 SPK segment if all of the data for the segment is not
available at one time.
#include "SpiceUsr.h"
.
.
.
/.
Begin the segment.
./
spk14b_c ( handle, segid, body, center, reffrm,
first, last, chbdeg );
/.
Generate the records and write them to the segment in the
SPK file one at at time.
./
for ( i = 0; i < n; i++ )
{
genrec ( start[i], stop[i], record );
spk14a_c ( handle, 1, record, start+i );
}
/.
End the segment, making the segment a permanent addition
to the SPK file.
./
spk14e_c ( handle );
-Restrictions
The SPK file must be open with write access.
Only one segment may be written to a particular SPK file at a
time. All of the data for the segment must be written and the
segment must be ended before another segment may be started in
the file.
-Exceptions
1) If the degree of the Chebyshev Polynomial to be used for this
segment is negative, the error SPICE(INVALIDARGUMENT) will
be signaled.
2) Errors in the structure or content of the inputs other than the
degree of the Chebyshev Polynomial are diagnosed by routines
called by this one.
3) File access errors are diagnosed by routines in the call tree
of this routine.
4) If either the input frame or segment ID string pointer is null,
the error SPICE(NULLPOINTER) is signaled.
5) If either the input frame or segment ID string is empty,
the error SPICE(EMPTYSTRING) is signaled.
-Files
See handle in the Detailed_Input section.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Literature_References
None.
-Version
-CSPICE Version 1.0.1, 30-OCT-2006 (BVS)
Deleted "inertial" from the FRAME description in the Brief_I/O
section of the header.
-CSPICE Version 1.0.0, 29-JUL-1999 (NJB) (KRG)
-Index_Entries
begin writing a type_14 spk segment
-&
*/
{ /* Begin spk14b_c */
/*
Participate in error tracing.
*/
chkin_c ( "spk14b_c" );
/*
Check the input strings to make sure the pointers
are non-null and the string lengths are non-zero.
*/
CHKFSTR ( CHK_STANDARD, "spk14b_c", frame );
CHKFSTR ( CHK_STANDARD, "spk14b_c", segid );
/*
Call the f2c'd routine.
*/
spk14b_ ( ( integer * ) &handle,
( char * ) segid,
( integer * ) &body,
( integer * ) ¢er,
( char * ) frame,
( doublereal * ) &first,
( doublereal * ) &last,
( integer * ) &chbdeg,
( ftnlen ) strlen(segid),
( ftnlen ) strlen(frame) );
chkout_c ( "spk14b_c" );
} /* End spk14b_c */
void prsdp_c ( ConstSpiceChar * string,
SpiceDouble * dpval )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
string I String representing a d.p. number.
dpval O D.p. value obtained by parsing string.
-Detailed_Input
string is a string representing a double precision
number. Any string acceptable to the CSPICE
routine nparsd.c is allowed.
-Detailed_Output
dpval is the double precision number obtained by parsing
string.
-Parameters
None.
-Exceptions
1) If the input string pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
2) If the input string does not contain at least one character,
the error SPICE(EMPTYSTRING) will be signaled.
3) If the input string cannot be parsed, the error
SPICE(NOTADPNUMBER) is signalled.
-Files
None.
-Particulars
The purpose of this routine is to enable safe parsing of double
precision numbers without the necessity of in-line error checking.
This routine is based on the CSPICE routine nparsd.c.
-Examples
See the routine NPARSD for an examples of allowed strings.
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.1.2, 26-AUG-1999 (NJB)
Header was updated to list string exceptions.
-CSPICE Version 1.1.1, 25-MAR-1998 (EDW)
Minor corrections to header.
-CSPICE Version 1.1.0, 08-FEB-1998 (NJB)
References to C2F_CreateStr_Sig were removed; code was
cleaned up accordingly. String checks are now done using
the macro CHKFSTR.
-CSPICE Version 1.0.0, 25-OCT-1997
Based on SPICELIB Version 1.0.0, 22-JUL-1997 (NJB)
-Index_Entries
parse d.p. number with encapsulated error handling
-&
*/
{ /* Begin prsdp_c */
/*
Participate in error handling.
*/
chkin_c ( "prsdp_c");
/*
Check the input string to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "prsdp_c", string );
prsdp_ ( ( char * ) string,
( doublereal * ) dpval,
( ftnlen ) strlen(string) );
chkout_c ( "prsdp_c");
} /* End prsdp_c */
void gfsstp_c ( SpiceDouble step )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
step I Time step to take.
-Detailed_Input
step is the output step size to be returned by the next call
to gfstep_c. Units are TDB seconds.
`step' is used in the GF search root-bracketing process.
`step' indicates how far to advance the gfstep_c input
argument `time' so that `time' and time+step may bracket a
state transition and definitely do not bracket more than
one state transition.
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If the input step size is non-positive, the error
SPICE(INVALIDSTEP) is signaled. The stored step value
is not updated.
-Files
None.
-Particulars
This routine sets the step size to be returned by the
next call to gfstep_c.
-Examples
1) User applications can pass gfstep_c to mid-level GF API routines
expecting a step size routine as an input argument. Before such
a call is made, the value of the step to be returned by gfstep_c
must be set via a call to this routine.
For example, the GF API routine gfocce_c can be called as shown
in the code fragment below.
/.
Select a twenty-second step. We'll ignore any occultations
lasting less than 20 seconds.
./
step = 20.0;
gfsstp_c ( step );
/.
Perform the search.
./
gfocce_c ( "ANY",
"MOON", "ellipsoid", "IAU_MOON",
"SUN", "ellipsoid", "IAU_SUN",
"LT", "EARTH", CNVTOL,
gfstep_c, gfrefn_c, rpt,
gfrepi_c, gfrepu_c, gfrepf_c,
bail, gfbail_c, cnfine,
&result );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
L.S. Elson (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 2.0.1, 15-APR-2009 (LSE) (NJB)
-Index_Entries
GF set constant step size
-&
*/
{ /* Begin gfsstp_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfsstp_c" );
/*
Let the f2c'd routine do the work.
*/
gfsstp_ ( (doublereal * ) &step );
chkout_c ( "gfsstp_c" );
} /* End gfsstp_c */
void spk14e_c ( SpiceInt handle )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
handle I The handle of an SPK file open for writing.
-Detailed_Input
handle is the file handle of an SPK file that has been
opened for writing, and to which a type 14 segment is
being written.
-Detailed_Output
None. The type 14 segment in the SPK file associated with
handle will be ended, making the addition of the data
to the file permanent.
See the Particulars section for details about the
structure of a type 14 SPK segment.
-Parameters
None.
-Particulars
This routine ends a type 14 SPK segment which is being written to
the SPK file associated with handle. Ending the SPK segment is a
necessary step in the process of making the data a permanent part
of the SPK file.
This routine is one of a set of three routines for creating and
adding data to type 14 SPK segments. These routines are:
spk14b_c: Begin a type 14 SPK segment. This routine must be
called before any data may be added to a type 14
segment.
spk14a_c: Add data to a type 14 SPK segment. This routine may be
called any number of times after a call to SPK14B to
add type 14 records to the SPK segment that was
started.
spk14e_c: End a type 14 SPK segment. This routine is called to
make the type 14 segment a permanent addition to the
SPK file. Once this routine is called, no further type
14 records may be added to the segment. A new segment
must be started.
A type 14 SPK segment consists of coefficient sets for fixed order
Chebyshev polynomials over consecutive time intervals, where the
time intervals need not all be of the same length. The Chebyshev
polynomials represent the position, X, Y, and Z coordinates, and
the velocities, dX/dt, dY/dt, and dZ/dt, of a body relative to a
center of motion.
The ephemeris data supplied to the type 14 SPK writer routines is
packed into an array as a sequence of logical records,
-----------------------------------------------------
| Record 1 | Record 2 | ... | Record N-1 | Record N |
-----------------------------------------------------
with each record has the following format.
------------------------------------------------
| the midpoint of the approximation interval |
------------------------------------------------
| the radius of the approximation interval |
------------------------------------------------
| CHBDEG+1 coefficients for the X coordinate |
------------------------------------------------
| CHBDEG+1 coefficients for the Y coordinate |
------------------------------------------------
| CHBDEG+1 coefficients for the Z coordinate |
------------------------------------------------
| CHBDEG+1 coefficients for the X velocity |
------------------------------------------------
| CHBDEG+1 coefficients for the Y velocity |
------------------------------------------------
| CHBDEG+1 coefficients for the Z velocity |
------------------------------------------------
-Examples
Assume we have the following for each of the examples that
follow.
handle is the handle of an SPK file opened with write
access.
segid is a character string of no more than 40 characters
which provides a pedigree for the data in the SPK
segment we will create.
body is the NAIF ID code for the body whose ephemeris
is to be placed into the file.
center is the center of motion for the ephemeris of body.
reffrm is the name of the SPICE reference frame for the
ephemeris.
first is the starting epoch, in seconds past J2000, for
the ephemeris data to be placed into the segment.
last is the ending epoch, in seconds past J2000, for
the ephemeris data to be placed into the segment.
Example 1:
For this example, we also assume that:
n is the number of type 14 records that we want to
put into a segment in an SPK file.
recrds contains n type 14 records packaged for the SPK
file.
etstrt contains the initial epochs for each of the
records contained in RECRDS, where
etstrt[i] < etstrt[i+1], i = 0, n-2
etstrt[1] <= first, etstrt[n-1] < last
etstrt[i+1], i = 0, n-2, is the ending epoch for
record i as well as the initial epoch for record
i+1.
Then the following code fragment demonstrates how to create a
type 14 SPK segment if all of the data for the segment is
available at one time.
#include "SpiceUsr.h"
.
.
.
#define SPK "example.bsp"
/.
If the segment is to be appended to an existing file, open
that file for "append" access. Otherwise, create a new file.
./
if ( exists_c(SPK) )
{
spkopa_c ( SPK, &handle );
}
else
{
/.
New files are supplied with an internal file name.
Comment area space may be reserved at this time; the
units are characters.
./
ifname = "Sample type 14 SPK file.";
ncomch = 1024;
spkopn_c ( SPK, ifname, ncomch, &handle );
}
/.
Begin the segment.
./
spk14b_c ( handle, segid, body, center, reffrm,
first, last, chbdeg );
/.
Add the data to the segment all at once.
./
spk14a_c ( handle, n, recrds, etstrt );
/.
End the segment, making the segment a permanent addition
to the SPK file.
./
spk14e_c ( handle );
.
.
.
/.
After all segments have been loaded, close the SPK file.
./
spkcls_c ( handle );
Example 2:
In this example we want to add type 14 SPK records, as described
above in the Particulars section, to the segments being written
as they are generated. The ability to write the records in this
way is useful if computer memory is limited. It may also be
convenient from a programming perspective to write the records
one at a time.
For this example, assume that we want to generate n type 14 SPK
records, one for each of n time intervals, writing them all to
the same segment in the SPK file. Let
n be the number of type 14 records that we want to
generate and put into a segment in an SPK file.
record be an array with enough room to hold a single type
14 record, i.e. record should have dimension at
least 6 * (chbdeg + 1 ) + 2.
start be an array of n times that are the beginning
epochs for each of the intervals of interest. The
times should be in increasing order and the start
time for the first interval should equal the
starting time for the segment.
start[i] < start[i+1], i = 0, n-2
start[0] = first
stop be an array of n times that are the ending epochs
for each of the intervals of interest. The times
should be in increasing order and the stop time for
interval i should equal the start time for interval
i+1, i.e., we want to have continuous coverage in
time across all of the records. Also, the stop time
for the last interval should equal the ending time
for the segment.
stop[i] < stop [i+1], i = 0, n-2
stop[i] = start[i+1], i = 0, n-2
stop[n-1] = last
genrec( time1, time2, record )
be a subroutine that generates a type 14 SPK record
for a time interval specified by time1 and time2.
Then the following code fragment demonstrates how to create a
type 14 SPK segment if all of the data for the segment is not
available at one time.
#include "SpiceUsr.h"
.
.
.
/.
Begin the segment.
./
spk14b_c ( handle, segid, body, center, reffrm,
first, last, chbdeg );
/.
Generate the records and write them to the segment in the
SPK file one at at time.
./
for ( i = 0; i < n; i++ )
{
genrec ( start[i], stop[i], record );
spk14a_c ( handle, 1, record, start+i );
}
/.
End the segment, making the segment a permanent addition
to the SPK file.
./
spk14e_c ( handle );
-Restrictions
1) The type 14 SPK segment being closed must have been started by
the routine spk14b_c, the routine which begins a type 14 SPK
segment.
-Exceptions
None.
-Files
See the argument handle.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Literature_References
None.
-Version
-CSPICE Version 1.0.1, 16-JAN-2003 (EDW)
Trivial correction to the header.
-CSPICE Version 1.0.0, 29-JUL-1999 (NJB) (KRG)
-Index_Entries
end a type_14 spk segment
-&
*/
{ /* Begin spk14e_c */
/*
Participate in error tracing.
*/
chkin_c ( "spk14e_c" );
spk14e_ ( ( integer * ) &handle );
chkout_c ( "spk14e_c" );
} /* End spk14e_c */
void cklpf_c ( ConstSpiceChar * filename,
SpiceInt * handle )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
filename I Name of the CK file to be loaded.
handle O Loaded file's handle.
-Detailed_Input
filename is the name of a C-kernel file to be loaded.
-Detailed_Output
handle is an integer handle assigned to the file upon loading.
Almost every other CK routine will subsequently use
this number to refer to the file.
-Parameters
ftsize is the maximum number of pointing files that can
be loaded by CKLPF at any given time for use by the
readers.
-Exceptions
1) If an attempt is made to load more files than is specified
by the parameter ftsize, the error "SPICE(CKTOOMANYFILES)"
is signalled.
2) If an attempt is made to open more DAF files than is specified
by the parameter ftsize in DAFAH, an error is signalled by a
routine that this routine calls.
3) If the file specified by filename can not be opened, an error
is signalled by a routine that this routine calls.
4) If the file specified by filename has already been loaded,
it will become the "last-loaded" file. (The readers
search the last-loaded file first.)
-Files
The C-kernel file specified by filename is loaded. The file is
assigned an integer handle by CKLPF. Other CK routines will refer
to this file by its handle.
-Particulars
See Particulars in ckbsr.
If there is room for a new file, CKLPF opens the file for
reading. This routine must be called prior to a call to CKGP or
CKGPAV.
CK readers search files loaded with CKLPF in the reverse order
in which they were loaded. That is, last-loaded files are
searched first.
-Examples
ck_kern = "/kernels/mpf/ck/lander_nominal.bck";
cklpf_c ( ck_kern, &hand );
Also see the Example in ckbsr.for.
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
J.M. Lynch (JPL)
J.E. McLean (JPL)
M.J. Spencer (JPL)
R.E. Thurman (JPL)
I.M. Underwood (JPL)
E.D. Wright (JPL)
B.V. Semenov (JPL)
-Version
-CSPICE Version 2.0.1, 31-JAN-2008 (BVS)
Removed '-Revisions' from the header.
-CSPICE Version 2.0.0, 08-FEB-1998 (NJB)
Input argument filename changed to type ConstSpiceChar *;
name was changed to "filename" from "fname."
References to C2F_CreateStr_Sig were removed; code was
cleaned up accordingly. String checks are now done using
the macro CHKFSTR.
-CSPICE Version 1.0.0, 25-OCT-1997 (EDW)
-Index_Entries
load ck pointing file
-&
*/
{ /* Begin spklef_c */
/*
Participate in error tracing.
*/
chkin_c ( "cklpf_c" );
/*
Check the input string filename to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "cklpf_c", filename );
/*
Call the f2c'd Fortran routine.
*/
cklpf_ ( ( char * ) filename,
( integer * ) handle,
( ftnlen ) strlen(filename) );
chkout_c ( "cklpf_c" );
} /* end cklpf_c */
void spkcls_c ( SpiceInt handle )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
handle I Handle of the SPK file to be closed.
-Detailed_Input
handle The handle of the SPK file that is to be closed.
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If there are no segments in the file, the error
SPICE(NOSEGMENTSFOUND) will be signaled.
-Files
See argument handle.
-Particulars
Close the SPK file attached to handle.
-Examples
Suppose that you want to create a new SPK file called "new.spk"
that contains a single type 5 SPK segment and has room for at
least 5000 comment characters. The following code fragment should
take care of this for you, assuming that all of the variables
passed to the SPK type 5 segment writer have appropriate values
and no errors occur.
#include "SpiceUsr.h"
.
.
.
name = "new.spk";
ifname = "Test SPK file";
spkopn_c ( name, ifname, 5000, &handle );
spkw05 ( handle, objid, cntrid, cframe, etbeg,
etend, segmid, cntrgm, nstate, state,
epoch );
spkcls_c ( handle );
-Restrictions
None.
-Author_and_Institution
F.S. Turner (JPL)
-Literature_References
None.
-Version
-CSPICE Version 1.0.0, 16-MAR-1999 (FST)
-Index_Entries
close an spk file
-&
*/
{ /* Begin spkcls_c */
/*
Participate in error tracing.
*/
chkin_c ( "spkcls_c" );
spkcls_ ( ( integer * ) &handle );
chkout_c ( "spkcls_c" );
} /* End spkcls_c */
SpiceDouble vdotg_c ( ConstSpiceDouble * v1,
ConstSpiceDouble * v2,
SpiceInt ndim )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
v1 I First vector in the dot product.
v2 I Second vector in the dot product.
ndim I Dimension of v1 and v2.
The function returns the value of the dot product of v1 and v2.
-Detailed_Input
v1 This may be any double precision vector of arbitrary
dimension.
v2 This may be any double precision vector of arbitrary
dimension.
-Detailed_Output
The function returns the value of the dot product of v1 and v2.
-Parameters
None.
-Particulars
vdotg_c calculates the dot product of v1 and v2 by a simple
application of the definition. No error checking is
performed to prevent or recover from numeric overflow.
-Examples
Suppose that given two n-dimensional vectors, we want to change
one of the vectors until the two vectors are perpendicular.
The following code fragment demonstrates the use of vdot_c to do
so.
dot = vdotg_c ( v1, v2, ndim );
while ( dot != 0. )
{
/. change one of the vectors ./
....
dot = vdotg_c ( v1, v2, ndim );
}
-Restrictions
The user is responsible for determining that the vectors v1 and
v2 are not so large as to cause numeric overflow. In most cases
this won't present a problem.
-Exceptions
1) If ndim is not physically realistic, greater than zero, a
BADDIMENSION error is signaled. The value 0. is returned.
-Files
None.
-Author_and_Institution
W.M. Owen (JPL)
E.D. Wright (JPL)
-Literature_References
None.
-Version
-CSPICE Version 1.1.0, 22-OCT-1998 (NJB)
Made input vectors const. Converted check-in style to discovery.
-CSPICE Version 1.0.0, 31-MAR-1998 (EDW)
-Index_Entries
dot product of n-dimensional vectors
-&
*/
{ /* Begin vdotg_c */
/*
Local variables
*/
SpiceInt i;
SpiceDouble dot;
/*
Use discovery check-in.
*/
/* Initialize dot to zero. */
dot = 0.;
/* Check ndim is cool. Dimension is positive definite. */
if ( ndim <= 0 )
{
chkin_c ( "vdotg_c" );
SpiceError ( "Vector dimension less than or equal to zero",
"BADDIMENSION" );
chkout_c ( "vdotg_c" );
return ( 0. );
}
/* Do the calculation. Not very involved. */
for ( i = 0; i < ndim; i++ )
{
dot += v1[i] * v2[i];
}
/* Return the value. */
return dot;
} /* End vdotg_c */
void drdpgr_c ( ConstSpiceChar * body,
SpiceDouble lon,
SpiceDouble lat,
SpiceDouble alt,
SpiceDouble re,
SpiceDouble f,
SpiceDouble jacobi[3][3] )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
body I Name of body with which coordinates are associated.
lon I Planetographic longitude of a point (radians).
lat I Planetographic latitude of a point (radians).
alt I Altitude of a point above reference spheroid.
re I Equatorial radius of the reference spheroid.
f I Flattening coefficient.
jacobi O Matrix of partial derivatives.
-Detailed_Input
body Name of the body with which the planetographic
coordinate system is associated.
`body' is used by this routine to look up from the
kernel pool the prime meridian rate coefficient giving
the body's spin sense. See the Files and Particulars
header sections below for details.
lon Planetographic longitude of the input point. This is
the angle between the prime meridian and the meridian
containing the input point. For bodies having
prograde (aka direct) rotation, the direction of
increasing longitude is positive west: from the +X
axis of the rectangular coordinate system toward the
-Y axis. For bodies having retrograde rotation, the
direction of increasing longitude is positive east:
from the +X axis toward the +Y axis.
The earth, moon, and sun are exceptions:
planetographic longitude is measured positive east for
these bodies.
The default interpretation of longitude by this
and the other planetographic coordinate conversion
routines can be overridden; see the discussion in
Particulars below for details.
Longitude is measured in radians. On input, the range
of longitude is unrestricted.
lat Planetographic latitude of the input point. For a
point P on the reference spheroid, this is the angle
between the XY plane and the outward normal vector at
P. For a point P not on the reference spheroid, the
planetographic latitude is that of the closest point
to P on the spheroid.
Latitude is measured in radians. On input, the
range of latitude is unrestricted.
alt Altitude of point above the reference spheroid.
Units of `alt' must match those of `re'.
re Equatorial radius of a reference spheroid. This
spheroid is a volume of revolution: its horizontal
cross sections are circular. The shape of the
spheroid is defined by an equatorial radius `re' and
a polar radius `rp'. Units of `re' must match those of
`alt'.
f Flattening coefficient =
(re-rp) / re
where `rp' is the polar radius of the spheroid, and the
units of `rp' match those of `re'.
-Detailed_Output
JACOBI is the matrix of partial derivatives of the conversion
from planetographic to rectangular coordinates. It
has the form
.- -.
| DX/DLON DX/DLAT DX/DALT |
| DY/DLON DY/DLAT DY/DALT |
| DZ/DLON DZ/DLAT DZ/DALT |
`- -'
evaluated at the input values of `lon', `lat' and `alt'.
-Parameters
None.
-Exceptions
1) If the body name `body' cannot be mapped to a NAIF ID code,
and if `body' is not a string representation of an integer,
the error SPICE(IDCODENOTFOUND) will be signaled.
2) If the kernel variable
BODY<ID code>_PGR_POSITIVE_LON
is present in the kernel pool but has a value other
than one of
'EAST'
'WEST'
the error SPICE(INVALIDOPTION) will be signaled. Case
and blanks are ignored when these values are interpreted.
3) If polynomial coefficients for the prime meridian of `body'
are not available in the kernel pool, and if the kernel
variable BODY<ID code>_PGR_POSITIVE_LON is not present in
the kernel pool, the error SPICE(MISSINGDATA) will be signaled.
4) If the equatorial radius is non-positive, the error
SPICE(VALUEOUTOFRANGE) is signaled.
5) If the flattening coefficient is greater than or equal to one,
the error SPICE(VALUEOUTOFRANGE) is signaled.
6) The error SPICE(EMPTYSTRING) is signaled if the input
string `body' does not contain at least one character, since the
input string cannot be converted to a Fortran-style string in
this case.
7) The error SPICE(NULLPOINTER) is signaled if the input string
pointer `body' is null.
-Files
This routine expects a kernel variable giving body's prime
meridian angle as a function of time to be available in the
kernel pool. Normally this item is provided by loading a PCK
file. The required kernel variable is named
BODY<body ID>_PM
where <body ID> represents a string containing the NAIF integer
ID code for `body'. For example, if `body' is "JUPITER", then
the name of the kernel variable containing the prime meridian
angle coefficients is
BODY599_PM
See the PCK Required Reading for details concerning the prime
meridian kernel variable.
The optional kernel variable
BODY<body ID>_PGR_POSITIVE_LON
also is normally defined via loading a text kernel. When this
variable is present in the kernel pool, the prime meridian
coefficients for `body' are not required by this routine. See the
Particulars section below for details.
-Particulars
It is often convenient to describe the motion of an object in the
planetographic coordinate system. However, when performing
vector computations it's hard to beat rectangular coordinates.
To transform states given with respect to planetographic
coordinates to states with respect to rectangular coordinates,
one makes use of the Jacobian of the transformation between the
two systems.
Given a state in planetographic coordinates
( lon, lat, alt, dlon, dlat, dalt )
the velocity in rectangular coordinates is given by the matrix
equation:
t | t
(dx, dy, dz) = jacobi| * (dlon, dlat, dalt)
|(lon,lat,alt)
This routine computes the matrix
|
jacobi|
|(lon,lat,alt)
In the planetographic coordinate system, longitude is defined
using the spin sense of the body. Longitude is positive to the
west if the spin is prograde and positive to the east if the spin
is retrograde. The spin sense is given by the sign of the first
degree term of the time-dependent polynomial for the body's prime
meridian Euler angle "W": the spin is retrograde if this term is
negative and prograde otherwise. For the sun, planets, most
natural satellites, and selected asteroids, the polynomial
expression for W may be found in a SPICE PCK kernel.
The earth, moon, and sun are exceptions: planetographic longitude
is measured positive east for these bodies.
If you wish to override the default sense of positive longitude
for a particular body, you can do so by defining the kernel
variable
BODY<body ID>_PGR_POSITIVE_LON
where <body ID> represents the NAIF ID code of the body. This
variable may be assigned either of the values
'WEST'
'EAST'
For example, you can have this routine treat the longitude
of the earth as increasing to the west using the kernel
variable assignment
BODY399_PGR_POSITIVE_LON = 'WEST'
Normally such assignments are made by placing them in a text
kernel and loading that kernel via furnsh_c.
The definition of this kernel variable controls the behavior of
the CSPICE planetographic routines
pgrrec_c
recpgr_c
dpgrdr_c
drdpgr_c
It does not affect the other CSPICE coordinate conversion
routines.
-Examples
Numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as
input and the machine specific arithmetic implementation.
Find the planetographic state of the earth as seen from
Mars in the J2000 reference frame at January 1, 2005 TDB.
Map this state back to rectangular coordinates as a check.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local variables
./
SpiceDouble alt;
SpiceDouble drectn [3];
SpiceDouble et;
SpiceDouble f;
SpiceDouble jacobi [3][3];
SpiceDouble lat;
SpiceDouble lon;
SpiceDouble lt;
SpiceDouble pgrvel [3];
SpiceDouble radii [3];
SpiceDouble re;
SpiceDouble rectan [3];
SpiceDouble rp;
SpiceDouble state [6];
SpiceInt n;
/.
Load a PCK file containing a triaxial
ellipsoidal shape model and orientation
data for Mars.
./
furnsh_c ( "pck00008.tpc" );
/.
Load an SPK file giving ephemerides of earth and Mars.
./
furnsh_c ( "de405.bsp" );
/.
Load a leapseconds kernel to support time conversion.
./
furnsh_c ( "naif0007.tls" );
/.
Look up the radii for Mars. Although we
omit it here, we could first call badkpv_c
to make sure the variable BODY499_RADII
has three elements and numeric data type.
If the variable is not present in the kernel
pool, bodvrd_c will signal an error.
./
bodvrd_c ( "MARS", "RADII", 3, &n, radii );
/.
Compute flattening coefficient.
./
re = radii[0];
rp = radii[2];
f = ( re - rp ) / re;
/.
Look up the geometric state of earth as seen from Mars at
January 1, 2005 TDB, relative to the J2000 reference
frame.
./
str2et_c ( "January 1, 2005 TDB", &et);
spkezr_c ( "Earth", et, "J2000", "LT+S",
"Mars", state, < );
/.
Convert position to planetographic coordinates.
./
recpgr_c ( "mars", state, re, f, &lon, &lat, &alt );
/.
Convert velocity to planetographic coordinates.
./
dpgrdr_c ( "MARS", state[0], state[1], state[2],
re, f, jacobi );
mxv_c ( jacobi, state+3, pgrvel );
/.
As a check, convert the planetographic state back to
rectangular coordinates.
./
pgrrec_c ( "mars", lon, lat, alt, re, f, rectan );
drdpgr_c ( "mars", lon, lat, alt, re, f, jacobi );
mxv_c ( jacobi, pgrvel, drectn );
printf ( "\n"
"Rectangular coordinates:\n"
"\n"
" X (km) = %18.9e\n"
" Y (km) = %18.9e\n"
" Z (km) = %18.9e\n"
"\n"
"Rectangular velocity:\n"
"\n"
" dX/dt (km/s) = %18.9e\n"
" dY/dt (km/s) = %18.9e\n"
" dZ/dt (km/s) = %18.9e\n"
"\n"
"Ellipsoid shape parameters:\n"
"\n"
" Equatorial radius (km) = %18.9e\n"
" Polar radius (km) = %18.9e\n"
" Flattening coefficient = %18.9e\n"
"\n"
"Planetographic coordinates:\n"
"\n"
" Longitude (deg) = %18.9e\n"
" Latitude (deg) = %18.9e\n"
" Altitude (km) = %18.9e\n"
"\n"
"Planetographic velocity:\n"
"\n"
" d Longitude/dt (deg/s) = %18.9e\n"
" d Latitude/dt (deg/s) = %18.9e\n"
" d Altitude/dt (km/s) = %18.9e\n"
"\n"
"Rectangular coordinates from inverse mapping:\n"
"\n"
" X (km) = %18.9e\n"
" Y (km) = %18.9e\n"
" Z (km) = %18.9e\n"
"\n"
"Rectangular velocity from inverse mapping:\n"
"\n"
" dX/dt (km/s) = %18.9e\n"
" dY/dt (km/s) = %18.9e\n"
" dZ/dt (km/s) = %18.9e\n"
"\n",
state [0],
state [1],
state [2],
state [3],
state [4],
state [5],
re,
rp,
f,
lon / rpd_c(),
lat / rpd_c(),
alt,
pgrvel[0]/rpd_c(),
pgrvel[1]/rpd_c(),
pgrvel[2],
rectan [0],
rectan [1],
rectan [2],
drectn [0],
drectn [1],
drectn [2] );
return ( 0 );
}
Output from this program should be similar to the following
(rounding and formatting differ across platforms):
Rectangular coordinates:
X (km) = 1.460397325e+08
Y (km) = 2.785466068e+08
Z (km) = 1.197503153e+08
Rectangular velocity:
dX/dt (km/s) = -4.704288238e+01
dY/dt (km/s) = 9.070217780e+00
dZ/dt (km/s) = 4.756562739e+00
Ellipsoid shape parameters:
Equatorial radius (km) = 3.396190000e+03
Polar radius (km) = 3.376200000e+03
Flattening coefficient = 5.886007556e-03
Planetographic coordinates:
Longitude (deg) = 2.976676591e+02
Latitude (deg) = 2.084450403e+01
Altitude (km) = 3.365318254e+08
Planetographic velocity:
d Longitude/dt (deg/s) = -8.357386316e-06
d Latitude/dt (deg/s) = 1.593493548e-06
d Altitude/dt (km/s) = -1.121443268e+01
Rectangular coordinates from inverse mapping:
X (km) = 1.460397325e+08
Y (km) = 2.785466068e+08
Z (km) = 1.197503153e+08
Rectangular velocity from inverse mapping:
dX/dt (km/s) = -4.704288238e+01
dY/dt (km/s) = 9.070217780e+00
dZ/dt (km/s) = 4.756562739e+00
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.0.0, 26-DEC-2004 (NJB) (WLT)
-Index_Entries
Jacobian of rectangular w.r.t. planetographic coordinates
-&
*/
{ /* Begin drdpgr_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "drdpgr_c" );
/*
Check the input string body to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "drdpgr_c", body );
/*
Call the f2c'd Fortran routine.
*/
drdpgr_ ( ( char * ) body,
( doublereal * ) &lon,
( doublereal * ) &lat,
( doublereal * ) &alt,
( doublereal * ) &re,
( doublereal * ) &f,
( doublereal * ) jacobi,
( ftnlen ) strlen(body) );
/*
Convert Jacobian matrix to row-major order.
*/
xpose_c ( jacobi, jacobi );
chkout_c ( "drdpgr_c" );
} /* End drdpgr_c */
void ckw01_c ( SpiceInt handle,
SpiceDouble begtim,
SpiceDouble endtim,
SpiceInt inst,
ConstSpiceChar * ref,
SpiceBoolean avflag,
ConstSpiceChar * segid,
SpiceInt nrec,
ConstSpiceDouble sclkdp [],
ConstSpiceDouble quats [][4],
ConstSpiceDouble avvs [][3] )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of an open CK file.
begtim I The beginning encoded SCLK of the segment.
endtim I The ending encoded SCLK of the segment.
inst I The NAIF instrument ID code.
ref I The reference frame of the segment.
avflag I True if the segment will contain angular velocity.
segid I Segment identifier.
nrec I Number of pointing records.
sclkdp I Encoded SCLK times.
quats I Quaternions representing instrument pointing.
avvs I Angular velocity vectors.
-Detailed_Input
handle is the handle of the CK file to which the segment will
be written. The file must have been opened with write
access.
begtim is the beginning encoded SCLK time of the segment. This
value should be less than or equal to the first time in
the segment.
endtim is the encoded SCLK time at which the segment ends.
This value should be greater than or equal to the last
time in the segment.
inst is the NAIF integer ID code for the instrument.
ref is a character string which specifies the
reference frame of the segment. This should be one of
the frames supported by the SPICELIB routine NAMFRM
which is an entry point of FRAMEX.
avflag is a logical flag which indicates whether or not the
segment will contain angular velocity.
segid is the segment identifier. A CK segment identifier may
contain up to 40 characters, excluding the terminating
null.
nrec is the number of pointing instances in the segment.
sclkdp are the encoded spacecraft clock times associated with
each pointing instance. These times must be strictly
increasing.
quats is an array of SPICE-style quaternions representing a
sequence of C-matrices. See the discussion of "Quaternion
Styles" in the Particulars section below.
avvs are the angular velocity vectors (optional).
If avflag is FALSE then this array is ignored by the
routine, however it still must be supplied as part of
the calling sequence.
-Detailed_Output
None. See Files section.
-Parameters
None.
-Exceptions
1) If handle is not the handle of a C-kernel opened for writing
the error will be diagnosed by routines called by this
routine.
2) If segid is more than 40 characters long, the error
SPICE(SEGIDTOOLONG) is signaled.
3) If segid contains any nonprintable characters, the error
SPICE(NONPRINTABLECHARS) is signaled.
4) If the first encoded SCLK time is negative then the error
SPICE(INVALIDSCLKTIME) is signaled. If any subsequent times
are negative the error SPICE(TIMESOUTOFORDER) is signaled.
5) If the encoded SCLK times are not strictly increasing,
the error SPICE(TIMESOUTOFORDER) is signaled.
6) If begtim is greater than sclkdp[0] or endtim is less than
sclkdp[nrec-1], the error SPICE(INVALIDDESCRTIME) is
signaled.
7) If the name of the reference frame is not one of those
supported by the SPICELIB routine NAMFRM, the error
SPICE(INVALIDREFFRAME) is signaled.
8) If nrec, the number of pointing records, is less than or
equal to 0, the error SPICE(INVALIDNUMRECS) is signaled.
9) If any quaternion has magnitude zero, the error
SPICE(ZEROQUATERNION) is signaled.
-Files
This routine adds a type 1 segment to a C-kernel. The C-kernel
may be either a new one or an existing one opened for writing.
-Particulars
For a detailed description of a type 1 CK segment please see the
CK Required Reading.
This routine relieves the user from performing the repetitive
calls to the DAF routines necessary to construct a CK segment.
Quaternion Styles
-----------------
There are different "styles" of quaternions used in
science and engineering applications. Quaternion styles
are characterized by
- The order of quaternion elements
- The quaternion multiplication formula
- The convention for associating quaternions
with rotation matrices
Two of the commonly used styles are
- "SPICE"
> Invented by Sir William Rowan Hamilton
> Frequently used in mathematics and physics textbooks
- "Engineering"
> Widely used in aerospace engineering applications
CSPICE function interfaces ALWAYS use SPICE quaternions.
Quaternions of any other style must be converted to SPICE
quaternions before they are passed to CSPICE functions.
Relationship between SPICE and Engineering Quaternions
------------------------------------------------------
Let M be a rotation matrix such that for any vector V,
M*V
is the result of rotating V by theta radians in the
counterclockwise direction about unit rotation axis vector A.
Then the SPICE quaternions representing M are
(+/-) ( cos(theta/2),
sin(theta/2) A(1),
sin(theta/2) A(2),
sin(theta/2) A(3) )
while the engineering quaternions representing M are
(+/-) ( -sin(theta/2) A(1),
-sin(theta/2) A(2),
-sin(theta/2) A(3),
cos(theta/2) )
For both styles of quaternions, if a quaternion q represents
a rotation matrix M, then -q represents M as well.
Given an engineering quaternion
QENG = ( q0, q1, q2, q3 )
the equivalent SPICE quaternion is
QSPICE = ( q3, -q0, -q1, -q2 )
Associating SPICE Quaternions with Rotation Matrices
----------------------------------------------------
Let FROM and TO be two right-handed reference frames, for
example, an inertial frame and a spacecraft-fixed frame. Let the
symbols
V , V
FROM TO
denote, respectively, an arbitrary vector expressed relative to
the FROM and TO frames. Let M denote the transformation matrix
that transforms vectors from frame FROM to frame TO; then
V = M * V
TO FROM
where the expression on the right hand side represents left
multiplication of the vector by the matrix.
Then if the unit-length SPICE quaternion q represents M, where
q = (q0, q1, q2, q3)
the elements of M are derived from the elements of q as follows:
+- -+
| 2 2 |
| 1 - 2*( q2 + q3 ) 2*(q1*q2 - q0*q3) 2*(q1*q3 + q0*q2) |
| |
| |
| 2 2 |
M = | 2*(q1*q2 + q0*q3) 1 - 2*( q1 + q3 ) 2*(q2*q3 - q0*q1) |
| |
| |
| 2 2 |
| 2*(q1*q3 - q0*q2) 2*(q2*q3 + q0*q1) 1 - 2*( q1 + q2 ) |
| |
+- -+
Note that substituting the elements of -q for those of q in the
right hand side leaves each element of M unchanged; this shows
that if a quaternion q represents a matrix M, then so does the
quaternion -q.
To map the rotation matrix M to a unit quaternion, we start by
decomposing the rotation matrix as a sum of symmetric
and skew-symmetric parts:
2
M = [ I + (1-cos(theta)) OMEGA ] + [ sin(theta) OMEGA ]
symmetric skew-symmetric
OMEGA is a skew-symmetric matrix of the form
+- -+
| 0 -n3 n2 |
| |
OMEGA = | n3 0 -n1 |
| |
| -n2 n1 0 |
+- -+
The vector N of matrix entries (n1, n2, n3) is the rotation axis
of M and theta is M's rotation angle. Note that N and theta
are not unique.
Let
C = cos(theta/2)
S = sin(theta/2)
Then the unit quaternions Q corresponding to M are
Q = +/- ( C, S*n1, S*n2, S*n3 )
The mappings between quaternions and the corresponding rotations
are carried out by the CSPICE routines
q2m_c {quaternion to matrix}
m2q_c {matrix to quaternion}
m2q_c always returns a quaternion with scalar part greater than
or equal to zero.
SPICE Quaternion Multiplication Formula
---------------------------------------
Given a SPICE quaternion
Q = ( q0, q1, q2, q3 )
corresponding to rotation axis A and angle theta as above, we can
represent Q using "scalar + vector" notation as follows:
s = q0 = cos(theta/2)
v = ( q1, q2, q3 ) = sin(theta/2) * A
Q = s + v
Let Q1 and Q2 be SPICE quaternions with respective scalar
and vector parts s1, s2 and v1, v2:
Q1 = s1 + v1
Q2 = s2 + v2
We represent the dot product of v1 and v2 by
<v1, v2>
and the cross product of v1 and v2 by
v1 x v2
Then the SPICE quaternion product is
Q1*Q2 = s1*s2 - <v1,v2> + s1*v2 + s2*v1 + (v1 x v2)
If Q1 and Q2 represent the rotation matrices M1 and M2
respectively, then the quaternion product
Q1*Q2
represents the matrix product
M1*M2
-Examples
This example writes a type 1 C-kernel segment for the
Galileo scan platform to a previously opened file attached to
handle.
/.
Include CSPICE interface definitions.
./
#include "SpiceUsr.h"
.
.
.
/.
Assume arrays of quaternions, angular velocities, and the
associated SCLK times are produced elsewhere.
./
.
.
.
/.
The subroutine ckw01_c needs the following items for the
segment descriptor:
1) SCLK limits of the segment.
2) Instrument code.
3) Reference frame.
4) The angular velocity flag.
./
begtim = (SpiceChar *) sclk[0];
endtim = (SpiceChar *) sclk[nrec-1];
inst = -77001;
ref = "J2000";
avflag = SPICETRUE;
segid = "GLL SCAN PLT - DATA TYPE 1";
/.
Write the segment.
./
ckw01_c ( handle, begtim, endtim, inst, ref, avflag,
segid, nrec, sclkdp, quats, avvs );
.
.
.
/.
After all segments are written, close the C-kernel.
./
ckcls_c ( handle );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
K.R. Gehringer (JPL)
N.J. Bachman (JPL)
J.M. Lynch (JPL)
-Version
-CSPICE Version 2.0.0, 01-JUN-2010 (NJB)
The check for non-unit quaternions has been replaced
with a check for zero-length quaternions. (The
implementation of the check is located in ckw01_.)
-CSPICE Version 1.3.2, 27-FEB-2008 (NJB)
Updated header; added information about SPICE
quaternion conventions.
-CSPICE Version 1.3.1, 12-JUN-2006 (NJB)
Corrected typo in example, the sclk indexes for the begtim
and endtim assignments used FORTRAN convention.
-CSPICE Version 1.3.0, 28-AUG-2001 (NJB)
Changed prototype: inputs sclkdp, quats, and avvs are now
const-qualified. Implemented interface macros for casting
these inputs to const.
-CSPICE Version 1.2.0, 02-SEP-1999 (NJB)
Local type logical variable now used for angular velocity
flag used in interface of ckw01_.
-CSPICE Version 1.1.0, 08-FEB-1998 (NJB)
References to C2F_CreateStr_Sig were removed; code was
cleaned up accordingly. String checks are now done using
the macro CHKFSTR.
-CSPICE Version 1.0.0, 25-OCT-1997 (NJB)
Based on SPICELIB Version 2.0.0, 28-DEC-1993 (WLT)
-Index_Entries
write ck type_1 pointing data segment
-&
*/
{ /* Begin ckw01_c */
/*
Local variables
*/
logical avf;
/*
Participate in error handling.
*/
chkin_c ( "ckw01_c" );
/*
Check the input strings to make sure the pointers
are non-null and the string lengths are non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ckw01_c", ref );
CHKFSTR ( CHK_STANDARD, "ckw01_c", segid );
/*
Get a type logical copy of the a.v. flag.
*/
avf = avflag;
/*
Write the segment. Note that the quaternion and angular velocity
arrays DO NOT require transposition!
*/
ckw01_( ( integer * ) &handle,
( doublereal * ) &begtim,
( doublereal * ) &endtim,
( integer * ) &inst,
( char * ) ref,
( logical * ) &avf,
( char * ) segid,
( integer * ) &nrec,
( doublereal * ) sclkdp,
( doublereal * ) quats,
( doublereal * ) avvs,
( ftnlen ) strlen(ref),
( ftnlen ) strlen(segid) );
chkout_c ( "ckw01_c" );
} /* End ckw01_c */
void pcpool_c ( ConstSpiceChar * name,
SpiceInt n,
SpiceInt lenvals,
const void * cvals )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
name I The kernel pool name to associate with cvals.
n I The number of values to insert.
lenvals I The lengths of the strings in the array cvals.
cvals I An array of strings to insert into the kernel pool.
-Detailed_Input
name is the name of the kernel pool variable to associate
with the values supplied in the array cvals. 'name' is
restricted to a length of 32 characters or less.
n is the number of values to insert into the kernel pool.
lenvals is the length of the strings in the array cvals,
including the null terminators.
cvals is an array of strings to insert into the kernel
pool. cvals should be declared as follows:
char cvals[n][lenvals];
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If name is already present in the kernel pool and there
is sufficient room to hold all values supplied in values,
the old values associated with name will be overwritten.
2) If there is not sufficient room to insert a new variable
into the kernel pool and name is not already present in
the kernel pool, the error SPICE(KERNELPOOLFULL) is
signaled by a routine in the call tree to this routine.
3) If there is not sufficient room to insert the values associated
with name, the error SPICE(NOMOREROOM) will be signaled.
4) If either input string pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
5) If the input string name has length zero, the error
SPICE(EMPTYSTRING) will be signaled.
6) If the input cvals string length is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
7) The error 'SPICE(BADVARNAME)' signals if the kernel pool
variable name length exceeds 32.
-Files
None.
-Particulars
This entry point provides a programmatic interface for inserting
character data into the SPICE kernel pool without reading an
external file.
-Examples
The following example program shows how a topocentric frame for a
point on the surface of the earth may be defined at run time using
pcpool_c, pdpool_c, and pipool_c. In this example, the surface
point is associated with the body code 300000. To facilitate
testing, the location of the surface point coincides with that of
the DSN station DSS-12; the reference frame MYTOPO defined here
coincides with the reference frame DSS-12_TOPO.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
The first angle is the negative of the longitude of the
surface point; the second angle is the negative of the
point's colatitude.
./
SpiceDouble angles [3] = { -243.1945102442646,
-54.7000629043147,
180.0 };
SpiceDouble et = 0.0;
SpiceDouble rmat [3][3];
SpiceInt axes [3] = { 3, 2, 3 };
SpiceInt center = 300000;
SpiceInt frclass = 4;
SpiceInt frclsid = 1500000;
SpiceInt frcode = 1500000;
/.
Define the MYTOPO reference frame.
Note that the third argument in the pcpool_c calls is
the length of the final string argument, including the
terminating null character.
./
pipool_c ( "FRAME_MYTOPO", 1, &frcode );
pcpool_c ( "FRAME_1500000_NAME", 1, 7, "MYTOPO" );
pipool_c ( "FRAME_1500000_CLASS", 1, &frclass );
pipool_c ( "FRAME_1500000_CLASS_ID", 1, &frclsid );
pipool_c ( "FRAME_1500000_CENTER", 1, ¢er );
pcpool_c ( "OBJECT_300000_FRAME", 1, 7, "MYTOPO" );
pcpool_c ( "TKFRAME_MYTOPO_RELATIVE", 1, 7, "ITRF93" );
pcpool_c ( "TKFRAME_MYTOPO_SPEC", 1, 7, "ANGLES" );
pcpool_c ( "TKFRAME_MYTOPO_UNITS", 1, 8, "DEGREES" );
pipool_c ( "TKFRAME_MYTOPO_AXES", 3, axes );
pdpool_c ( "TKFRAME_MYTOPO_ANGLES", 3, angles );
/.
Load a high precision binary earth PCK. Also load a
topocentric frame kernel for DSN stations. The file names
shown here are simply examples; users should replace these
with the names of appropriate kernels.
./
furnsh_c ( "earth_000101_060207_051116.bpc" );
furnsh_c ( "earth_topo_050714.tf" );
/.
Look up transformation from DSS-12_TOPO frame to MYTOPO frame.
This transformation should differ by round-off error from
the identity matrix.
./
pxform_c ( "DSS-12_TOPO", "MYTOPO", et, rmat );
printf ( "\n"
"DSS-12_TOPO to MYTOPO transformation at "
"et %23.16e = \n"
"\n"
" %25.16f %25.16f %25.16f\n"
" %25.16f %25.16f %25.16f\n"
" %25.16f %25.16f %25.16f\n",
et,
rmat[0][0], rmat[0][1], rmat[0][2],
rmat[1][0], rmat[1][1], rmat[1][2],
rmat[2][0], rmat[2][1], rmat[2][2] );
return ( 0 );
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.3.3, 17-JAN-2014 (NJB)
Updated Index_Entries section.
-CSPICE Version 1.3.2, 10-FEB-2010 (EDW)
Added mention of the restriction on kernel pool variable
names to 32 characters or less.
Reordered header sections to conform to SPICE convention.
-CSPICE Version 1.3.1, 17-NOV-2005 (NJB)
Replaced code fragment in Examples section of header with
smaller, complete program.
-CSPICE Version 1.3.0, 12-JUL-2002 (NJB)
Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.
-CSPICE Version 1.2.0, 28-AUG-2001 (NJB)
Const-qualified input array cvals.
-CSPICE Version 1.1.0, 14-FEB-2000 (NJB)
Calls to C2F_CreateStrArr replaced with calls to error-signaling
version of this routine: C2F_CreateStrArr_Sig.
-CSPICE Version 1.0.0, 18-JUN-1999 (NJB) (WLT)
-Index_Entries
Set the value of a character_variable in the kernel_pool
-&
*/
{ /* Begin pcpool_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
chkin_c ( "pcpool_c" );
/*
Check the input kernel variable name to make sure the pointer is
non-null and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "pcpool_c", name );
/*
Make sure the input string pointer for the cvals array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR ( CHK_STANDARD, "pcpool_c", cvals, lenvals );
/*
Create a Fortran-style string array.
*/
C2F_MapStrArr ( "pcpool_c",
n, lenvals, cvals, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "pcpool_c" );
return;
}
/*
Call the f2c'd routine.
*/
pcpool_ ( ( char * ) name,
( integer * ) &n,
( char * ) fCvalsArr,
( ftnlen ) strlen(name),
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "pcpool_c" );
} /* End pcpool_c */