void gfrepu_c ( SpiceDouble ivbeg,
SpiceDouble ivend,
SpiceDouble time )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
ivbeg I Start time of work interval.
ivend I End time of work interval.
time I Current time being examined in the search process.
-Detailed_Input
ivbeg,
ivend are the bounds of a time interval. Normally this interval
is contained within the confinement window `cnfine' passed to
gfrepi_c on the latest call to that function, but this is
not a requirement.
In order for a meaningful progress report to be displayed,
`ivbeg' and `ivend' must satisfy the following constraints:
- `ivbeg' must be less than or equal to `ivend'.
- Over a search pass, the sum of the differences
ivend - ivbeg
for all calls to this routine made during the pass
must equal the measure (that is, the sum of the
lengths of the intervals) of the confinement window
`cnfine'.
time is the current time reached in the search for an event.
`time' must lie in the interval
ivbeg : ivend
inclusive. The input values of `time' for a given interval
need not form an increasing sequence.
-Detailed_Output
None. This routine does perform console I/O when progress
reporting is enabled.
-Parameters
None.
-Exceptions
1) If `ivbeg' and `ivend' are in decreasing order, the error
SPICE(BADENDPOINTS) is signaled.
2) If `time' is not in the closed interval [ivbeg, ivend], the
error SPICE(VALUEOUTOFRANGE) is signaled.
3) Any I/O errors resulting from writing to standard output will be
diagnosed by routines in the call tree of this routine.
-Files
None.
-Particulars
This is one of three GF progress reporting routines that cooperate
in order to display a report via console I/O. These routines may
be used by SPICE-based applications as inputs to mid-level GF
search routines.
Developers wishing to use their own GF progress reporting routines
must design them with the same interfaces and should assign them the
same progress reporting roles as those of these routines.
The GF progress reporting API routines are written to simplify
reporting of work (such as searching for a geometric event) over a
particular window. This is an important feature for interactive
programs that may "go away" from the user's control for a
considerable length of time. It allows the user to see that
something is still going on (although maybe not too quickly).
The three routines constituting the GF progress reporting API
are:
gfrepi_c is used to prepare the reporting mechanism for a search
pass. It is used to store the confinement window and
progress report message prefix and suffix, and to
initialize parameters associated with the reporting of
the job in progress.
gfrepu_c is used to notify the progress reporting system that
a specified increment of work has been completed
since the last call to gfrepu_c or gfrepi_c, whichever
occurred most recently.
gfrepf_c is used to "finish" the reporting of work (set the
completion value to 100%.
-Examples
1) This example shows how to call a mid-level GF search API that
requires as input progress reporting routines.
If custom progress reporting routines are available, they
can replace gfrepi_c, gfrepu_c, and gfrepf_c in any GF API calls.
The code fragment below is from the first code example in the
header of
gfocce_c.c
Only the portions of that program relevant to use of the
progress reporting routines are copied here.
/.
Select a twenty-second step. We'll ignore any occultations
lasting less than 20 seconds.
./
gfsstp_c ( 20.0 );
/.
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 1.0.0, 28-FEB-2009 (NJB) (LSE) (WLT) (IMU) (EDW)
-Index_Entries
GF update progress report
-&
*/{ /* Begin gfrepu_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfrepu_c" );
/*
Let the f2c'd routine do the work.
*/
gfrepu_ ( ( doublereal * ) &ivbeg,
( doublereal * ) &ivend,
( doublereal * ) &time );
chkout_c ( "gfrepu_c" );
} /* End gfrepu_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 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 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 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 gfrepf_c ( void )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
None.
-Detailed_Input
None.
-Detailed_Output
None. This routine does perform console I/O when progress
reporting is enabled.
-Parameters
None
-Exceptions
1) Any I/O errors resulting from writing to standard output
will be diagnosed by routines in the call tree of this
routine.
-Files
None.
-Particulars
This is one of three GF progress reporting routines that cooperate
in order to display a report via console I/O. These routines may
be used by SPICE-based applications as inputs to mid-level GF
search routines.
Developers wishing to use their own GF progress reporting routines
must design them with the same interfaces and should assign them the
same progress reporting roles as those of these routines.
The GF progress reporting API routines are written to simplify
reporting of work (such as searching for a geometric event) over a
particular window. This is an important feature for interactive
programs that may "go away" from the user's control for a
considerable length of time. It allows the user to see that
something is still going on (although maybe not too quickly).
The three routines constituting the GF progress reporting API
are:
gfrepi_c is used to prepare the reporting mechanism for a search
pass. It is used to store the confinement window and
progress report message prefix and suffix, and to
initialize parameters associated with the reporting of
the job in progress.
gfrepu_c is used to notify the progress reporting system that
a specified increment of work has been completed
since the last call to gfrepu_c or gfrepi_c, whichever
occurred most recently.
gfrepf_c is used to "finish" the reporting of work (set the
completion value to 100%.
-Examples
1) This example shows how to call a mid-level GF search API that
requires as input progress reporting routines.
If custom progress reporting routines are available, they
can replace gfrepi_c, gfrepu_c, and gfrepf_c in any GF API calls.
The code fragment below is from the first code example in the
header of
gfocce_c.c
Only the portions of that program relevant to use of the
progress reporting routines are copied here. Deleted portions
of code are indicated by ellipses.
/.
Select a twenty-second step. We'll ignore any occultations
lasting less than 20 seconds.
./
gfsstp_c ( 20.0 );
/.
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)
L.S. Elson (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 1.0.0, 28-FEB-2009 (NJB) (LSE) (WLT) (IMU) (EDW)
-Index_Entries
GF finish a progress report
-&
*/
{ /* Begin gfrepf_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfrepf_c" );
/*
Let the f2c'd routine do the work.
*/
gfrepf_ () ;
chkout_c ( "gfrepf_c" );
} /* End gfrepf_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 uddc_c ( void ( * udfunc ) ( SpiceDouble x,
SpiceDouble * value ),
SpiceDouble x,
SpiceDouble dx,
SpiceBoolean * isdecr )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
udfunc I The routine that computes the scalar value
of interest.
x I Independent variable of 'udfunc'.
dx I Interval from 'x' for derivative calculation.
isdecr O Boolean indicating if the derivative is negative.
-Detailed_Input
udfunc the routine that returns the value of the scalar quantity
function of interest at X. The calling sequence for UDFUNC is:
udfunc ( x, &value );
where:
x the double precision value of the
independent variable of the function
at which to determine the scalar value.
value the double precision value returned by
'udfunc' at 'x'.
Functionally:
value = udfunc ( x )
x a scalar double precision value at which to determine
the derivative of 'udfunc'.
For many SPICE uses, 'x' will represent ephemeris time,
expressed as seconds past J2000 TDB.
dx a scalar double precision value representing half the
interval in units of 'x' separating the evaluation
values of 'udfunc'; the evaluations occur at (x + dx)
and (x - dx).
'dx' may be negative but must be non-zero.
-Detailed_Output
isdecr a scalar boolean indicating if the first derivative
of 'udfunc' with respect to time at 'et' is less than
zero.
Functionally:
d udfunc(x) |
-- | < 0
dx |
x
-Parameters
None.
-Exceptions
1) A routine in the call tree of this routine signals
SPICE(DIVIDEBYZERO) if DX has a value of zero.
-Files
If the evaluation of 'udfunc' requires SPICE kernel data, the
appropriate kernels must be loaded before calling this routine.
- SPK data: the calling application must load ephemeris data
for the targets, observer, and any intermediate objects in
a chain connecting the targets and observer for the time
used in the evaluation. 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.
- If non-inertial reference frames are used, then PCK
files, frame kernels, C-kernels, and SCLK kernels may be
needed.
Such kernel data are normally loaded once per program run, NOT
every time this routine is called.
-Particulars
None.
-Examples
See gfuds_c.
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 1.0.0, 31-MAR-2010 (EDW)
-Index_Entries
first derivative less-than zero
-&
*/
{
SpiceDouble deriv;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "uddc_c" );
*isdecr = SPICEFALSE;
uddf_c ( udfunc, x, dx, &deriv );
if ( failed_c() )
{
chkout_c ( "uddc_c" );
return;
}
*isdecr = deriv < 0.;
chkout_c ( "uddc_c" );
return;
}
void dasac_c ( SpiceInt handle,
SpiceInt n,
SpiceInt buflen,
const void * buffer )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I DAS handle of a file opened with write access.
n I Number of comments to put into the comment area.
buflen I Line length associated with buffer.
buffer I Buffer of lines to be put into the comment area.
-Detailed_Input
handle The file handle of a binary DAS file which has been
opened with write access.
n The number of strings in buffer that are to be
appended to the comment area of the binary DAS file
attached to handle.
buflen is the common length of the strings in buffer, including the
terminating nulls.
buffer A buffer containing comments which are to be added
to the comment area of the binary DAS file attached
to handle. buffer should be declared as follows:
ConstSpiceChar buffer [n][buflen]
Each string in buffer is null-terminated.
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If the number of comments to be added is not positive, the
error SPICE(INVALIDARGUMENT) will be signaled.
2) If a non-null, non printing ASCII character is encountered in the
comments, the error SPICE(ILLEGALCHARACTER) will be
signaled.
3) If the binary DAS file attached to handle is not open for
write access, an error will be signaled by a routine called
by this routine.
4) If the input buffer pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
5) If the input buffer string length buflen is not at least 2,
the error SPICE(STRINGTOOSHORT) will be signaled.
-Files
See argument handle in Detailed_Input.
-Particulars
Binary DAS files contain a data area which is reserved for storing
annotations or descriptive textual information about the data
contained in a file. This area is referred to as the "comment
area" of the file. The comment area of a DAS file is a line
oriented medium for storing textual information. The comment
area preserves any leading or embedded white space in the line(s)
of text which are stored so that the appearance of the
information will be unchanged when it is retrieved (extracted) at
some other time. Trailing blanks, however, are NOT preserved,
due to the way that character strings are represented in
standard Fortran 77.
This routine will take a buffer of text lines and add (append)
them to the comment area of a binary DAS file. If there are no
comments in the comment area of the file, then space will be
allocated and the text lines in buffer will then placed into the
comment area. The text lines may contain only printable ASCII
characters (decimal values 32 - 126).
There is no maximum length imposed on the significant portion
of a text line that may be placed into the comment area of a
DAS file. The maximum length of a line stored in the comment
area should be reasonable, however, so that they may be easily
extracted. A good value for this would be 255 characters, as
this can easily accommodate "screen width" lines as well as
long lines which may contain some other form of information.
-Examples
Let
handle be the handle for a DAS file which has been opened
with write access.
n be the number of lines of text to be added to the
comment area of the binary DAS file attached to
handle.
BUFLEN be the declared line length of the buffer.
buffer is a list of text lines to be added to the comment
area of the binary DAS file attached to handle.
The call
dasac_c ( handle, n, BUFLEN, buffer );
will append the first n line(s) in buffer to the comment area
of the binary DAS file attached to handle.
-Restrictions
1) This routine uses constants that are specific to the ASCII
character sequence. The results of using this routine with
a different character sequence are unpredictable.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Version
-CSPICE Version 1.1.0, 02-MAR-2003 (NJB)
Added error check in wrapper for non-positive
buffer line count.
-CSPICE Version 1.0.0, 25-FEB-2003 (NJB) (KRG)
-Index_Entries
add comments to a binary das file
append comments to a das file comment area
-&
*/
{ /* Begin dasac_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "dasac_c" );
/*
Check the line count of the input buffer.
*/
if ( n < 1 )
{
setmsg_c ( "Comment buffer line count n = #; must be positive." );
errint_c ( "#", n );
sigerr_c ( "SPICE(INVALIDARGUMENT)" );
chkout_c ( "dasac_c" );
return;
}
/*
Check the input buffer for null pointer or short lines.
*/
CHKOSTR ( CHK_STANDARD, "dasac_c", buffer, buflen );
/*
Map the input buffer to a Fortran-style buffer.
*/
C2F_MapStrArr ( "dasac_c", n, buflen, buffer, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "dasac_c" );
return;
}
/*
Call the f2c'd routine.
*/
dasac_ ( ( integer * ) &handle,
( integer * ) &n,
( char * ) fCvalsArr,
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "dasac_c" );
} /* End dasac_c */
int zzadqdec_c ( U_fp udfunc,
doublereal * et,
logical * xbool )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
udfunc I Name of scalar function of interest.
et I Epoch of interest in TDB seconds.
xbool O Boolean value at `et'.
-Detailed_Input
udfunc the name of the external routine that returns the
value of the scalar quantity of interest at time `et'.
et a double precision value representing
ephemeris time, expressed as seconds past
J2000 TDB, at which to evaluate "udfunb."
-Detailed_Output
xbool the value of the boolean quantity function at `et'.
-Parameters
None.
-Exceptions
1) A run-time error will result if this routine is called before
a valid pointer to a CSPICE-style function has been stored via
a call to zzadqdec_c.
The argument list of the stored function must match that of
udqdec (refer to gfuds_c.c).
-Files
None.
-Particulars
This routine is meant to be passed to f2c'd Fortran GF code that
requires a derivative sign test function as an argument.
This routine calls the CSPICE-style derivative test function
passed to a CSPICE wrapper for use by an intermediate-level GF
function. A pointer to this function must be stored via a call
to zzadsave_c before this routine is called.
-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 2.0.0, 23-OCT-2013 (EDW)
-CSPICE Version 1.0.0, 21-DEC-2008 (EDW)
-Index_Entries
adapter for gf user defined boolean quantity
-&
*/
{ /* Begin zzadqdec_c */
/*
Local variables
*/
void ( * fPtr ) ( void ( * ) ( SpiceDouble,
SpiceDouble *),
SpiceDouble,
SpiceBoolean * );
void ( * fPtr2) ( SpiceDouble,
SpiceDouble * );
SpiceBoolean bool_loc;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return ( 0 );
}
chkin_c ( "zzadqdec_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 "udqdec."
*/
fPtr = ( void (*) ( void ( * ) ( SpiceDouble, SpiceDouble *),
SpiceDouble,
SpiceBoolean*) ) zzadget_c ( UDQDEC );
/*
Retrieve the stored pointer for the user defined scalar function. The
'udfunc' pointer passed to zzadqdec_c as an argument corresponds to
the adapter for the scalar function, but the function pointer
argument in 'fPtr' requires the non-adapter pointer. Ignore 'udfunc'.
*/
fPtr2= ( void (*) (SpiceDouble, SpiceDouble*) ) zzadget_c ( UDFUNC );
/*
Call the stored function.
*/
(*fPtr) ( fPtr2, (SpiceDouble)(*et), (SpiceBoolean *) &bool_loc );
/*
Cast the "SpiceBoolean" to "logical" to prevent any future size mismatches
or compiler warnings.
*/
*xbool = (logical) bool_loc;
chkout_c ( "zzadqdec_c" );
return ( 0 );
} /* End zzadqdec_c */
int zzadrefn_c ( doublereal * t1,
doublereal * t2,
logical * s1,
logical * s2,
doublereal * t )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
t1 I One of two times bracketing a state change.
t2 I The other time that brackets a state change.
s1 I State at t1.
s2 I State at t2.
t O New time at which to check for transition.
-Detailed_Input
t1 One of two times bracketing a state change.
`t1' is expressed as seconds past J2000 TDB.
t2 The other time that brackets a state change.
`t2' is expressed as seconds past J2000 TDB.
n1 Number of times state state of interest
matched the value at t1.
n2 Number of times state state of interest
matched the value at t2.
-Detailed_Output
t is the value returned by the stored, passed-in
refinement function.
-Parameters
None.
-Exceptions
1) A run-time error will result if this routine is called before
a valid pointer to a CSPICE-style GF refinement function has
been stored via a call to zzadsave_c.
The argument list of the stored function must match that of
gfrefn_c.
-Files
None.
-Particulars
This routine is meant to be passed to f2c'd Fortran GF code
that requires a refinement function input argument. The argument
list of this routine matches that of the f2c'd routine
gfrefn_
This routine calls the CSPICE-style refinement function passed
into a CSPICE wrapper for an intermediate-level GF function.
A pointer to this refinement function must be stored via
a call to zzadsave_c before this routine is called.
-Examples
None.
-Restrictions
No errors are returned by this routine.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.0, 09-MAR-2009 (NJB)
-Index_Entries
adapter for gf refinement function
-&
*/
{ /* Begin zzadrefn_c */
/*
Local variables
*/
SpiceBoolean bs1;
SpiceBoolean bs2;
void ( * fPtr ) ( SpiceDouble,
SpiceDouble,
SpiceBoolean,
SpiceBoolean,
SpiceDouble * );
/*
Participate in error tracing.
*/
if ( return_c() )
{
return ( 0 );
}
chkin_c ( "zzadrefn_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 gfrefn_c.
*/
fPtr = ( void (*) ( SpiceDouble,
SpiceDouble,
SpiceBoolean,
SpiceBoolean,
SpiceDouble * ) ) zzadget_c ( UDREFN );
/*
Call the stored function.
*/
bs1 = (SpiceBoolean) (*s1);
bs2 = (SpiceBoolean) (*s2);
(*fPtr) ( (SpiceDouble ) (*t1),
(SpiceDouble ) (*t2),
bs1,
bs2,
(SpiceDouble *) t );
chkout_c ( "zzadrefn_c" );
return ( 0 );
} /* End zzadrefn_c */
void srfxpt_c ( ConstSpiceChar * method,
ConstSpiceChar * target,
SpiceDouble et,
ConstSpiceChar * abcorr,
ConstSpiceChar * obsrvr,
ConstSpiceChar * dref,
ConstSpiceDouble dvec [3],
SpiceDouble spoint [3],
SpiceDouble * dist,
SpiceDouble * trgepc,
SpiceDouble obspos [3],
SpiceBoolean * found )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
method I Computation method.
target I Name of target body.
et I Epoch in ephemeris seconds past J2000 TDB.
abcorr I Aberration correction.
obsrvr I Name of observing body.
dref I Reference frame of input direction vector.
dvec I Ray's direction vector.
spoint O Surface intercept point on the target body.
dist O Distance from the observer to the intercept point.
trgepc O Intercept epoch.
obspos O Observer position relative to target center.
found O Flag indicating whether intercept was found.
-Detailed_Input
method is a short string providing parameters defining
the computation method to be used. Parameters
include, but are not limited to, the shape model
used to represent the surface of the target body.
The only choice currently supported is
"Ellipsoid" The intercept computation uses
a triaxial ellipsoid to model
the surface of the target body.
The ellipsoid's radii must be
available in the kernel pool.
Neither case nor white space are significant in
`method'. For example, the string " eLLipsoid " is
valid.
In a later Toolkit release, this argument will be
used to invoke a wider range of surface
representations. For example, it will be possible to
represent the target body's surface using a digital
model.
target is the name of the target body. `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.
When the target body's surface is represented by a
tri-axial ellipsoid, this routine assumes that a kernel
variable representing the ellipsoid's radii is present
in the kernel pool. Normally the kernel variable would
be defined by loading a PCK file.
et is the epoch of participation of the observer, expressed
as ephemeris seconds past J2000 TDB: `et' is the epoch
at which the observer's state is computed.
When aberration corrections are not used, `et' is also
the epoch at which the state and orientation of the
target body are computed.
When aberration corrections are used, `et' is the epoch
at which the observer's state relative to the solar
system barycenter is computed; in this case the position
and orientation of the target body are computed at et-lt
or et+lt, where `lt' is the one-way light time between
the intercept point and the observer, and the sign
applied to lt depends on the selected correction. See
the description of `abcorr' below for details.
abcorr indicates the aberration correction to be applied
when computing the observer-target state and the
orientation of the target body. `abcorr' may be any of
the following.
"NONE" Apply no correction. Return the
geometric surface intercept point on the
target body.
Let `lt' represent the one-way light time between the
observer and the surface intercept point (note: NOT
between the observer and the target body's center).
The following values of `abcorr' apply to the
"reception" case in which photons depart from the
intercept point's location at the light-time
corrected epoch et-lt and *arrive* at the observer's
location at `et':
"LT" Correct for one-way light time (also
called "planetary aberration") using a
Newtonian formulation. This correction
yields the location of the surface
intercept point at the moment it
emitted photons arriving at the
observer at `et'.
The light time correction uses an
iterative solution of the light time
equation. The solution invoked by the
"LT" option uses one iteration.
Both the target state as seen by the
observer, and rotation of the target
body, are corrected for light time.
"LT+S" Correct for one-way light time and
stellar aberration using a Newtonian
formulation. This option modifies the
state obtained with the "LT" option to
account for the observer's velocity
relative to the solar system
barycenter. The result is the apparent
surface intercept point as seen by the
observer.
"CN" Converged Newtonian light time
correction. In solving the light time
equation, the "CN" correction iterates
until the solution converges. Both the
state and rotation of the target body
are corrected for light time.
"CN+S" Converged Newtonian light time
and stellar aberration corrections.
The following values of `abcorr' apply to the
"transmission" case in which photons *depart* from
the observer's location at `et' and arrive at the
intercept point at the light-time corrected epoch
et+lt:
"XLT" "Transmission" case: correct for
one-way light time using a Newtonian
formulation. This correction yields the
intercept location at the moment it
receives photons emitted from the
observer's location at `et'.
The light time correction uses an
iterative solution of the light time
equation. The solution invoked by the
"LT" option uses one iteration.
Both the target state as seen by the
observer, and rotation of the target
body, are corrected for light time.
"XLT+S" "Transmission" case: correct for
one-way light time and stellar
aberration using a Newtonian
formulation This option modifies the
intercept obtained with the "XLT"
option to account for the observer's
velocity relative to the solar system
barycenter.
"XCN" Converged Newtonian light time
correction. This is the same as "XLT"
correction but with further iterations
to a converged Newtonian light time
solution.
"XCN+S" "Transmission" case: converged
Newtonian light time and stellar
aberration corrections.
obsrvr is the name of the observing body. This is typically
a spacecraft, the earth, or a surface point on the
earth. `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
"EARTH" and "399" are legitimate strings that indicate
the earth is the observer.
dref is the name of the reference frame relative to which the
input direction vector is expressed. This may be any
frame supported by the SPICE system, including built-in
frames (documented in the Frames Required Reading) and
frames defined by a loaded frame kernel (FK).
When `dref' designates a non-inertial frame, the
orientation of the frame is evaluated at an epoch
dependent on the frame's center and, if the center is
not the observer, on the selected aberration
correction. See the description of the direction
vector `dvec' for details.
dvec Pointing vector emanating from the observer. The
intercept with the target body's surface of the ray
defined by the observer and `dvec' is sought.
`dvec' is specified relative to the reference frame
designated by `dref'.
Non-inertial reference frames are treated as follows:
if the center of the frame is at the observer's
location, the frame is evaluated at `et'. If the
frame's center is located elsewhere, then letting
`ltcent' be the one-way light time between the observer
and the central body associated with the frame, the
orientation of the frame is evaluated at et-ltcent,
et+ltcent, or `et' depending on whether the requested
aberration correction is, respectively, for received
radiation, transmitted radiation, or is omitted.
`ltcent' is computed using the method indicated by
`abcorr'.
-Detailed_Output
spoint is the surface intercept point on the target body of
the ray defined by the observer and the direction
vector. If the ray intersects the target body in
multiple points, the selected intersection point is
the one closest to the observer. The output
argument `found' (see below) indicates whether an
intercept was found.
`spoint' is expressed in Cartesian coordinates,
relative to the body-fixed frame associated with the
target body. The body-fixed target frame is
evaluated at the intercept epoch `trgepc' (see
description below).
When light time correction is used, the duration of
light travel between `spoint' to the observer is
considered to be the one way light time. When both
light time and stellar aberration corrections are
used, `spoint' is selected such that, when `spoint' is
corrected for light time and the vector from the
observer to the light-time corrected location of
`spoint' is corrected for stellar aberration, the
resulting vector is parallel to the ray defined by
the observer's location and `dvec'.
The components of `spoint' are given in units of km.
dist is the distance between the observer and the surface
intercept on the target body. `dist' is given in units
of km.
trgepc is the "intercept epoch." This is the epoch at which
the ray defined by `obsrvr' and `dvec' intercepts the
target surface at `spoint'. `trgepc' is defined as
follows: letting `lt' be the one-way light time between
the observer and the intercept point, `trgepc' is the
epoch et-lt, et+lt, or `et' depending on whether the
requested aberration correction is, respectively, for
received radiation, transmitted radiation, or
omitted. `lt' is computed using the method indicated by
`abcorr'.
`trgepc' is expressed as seconds past J2000 TDB.
obspos is the vector from the center of the target body at
epoch `trgepc' to the observer at epoch `et'. `obspos' is
expressed in the target body-fixed reference frame
evaluated at `trgepc'. (This is the frame relative to
which `spoint' is given.)
`obspos' is returned to simplify various related
computations that would otherwise be cumbersome. For
example, the vector `xvec' from the observer to `spoint'
can be calculated via the call
vsub_c ( spoint, obspos, xvec );
The components of `obspos' are given in units of km.
found A logical flag indicating whether or not the ray
intersects the target. If an intersection exists
`found' will be returned as SPICETRUE. If the ray misses
the target, `found' will be returned as SPICEFALSE.
-Parameters
None.
-Exceptions
If any of the listed errors occur, the output arguments are
left unchanged.
1) If the input argument `method' is not recognized, the error
SPICE(INVALIDMETHOD) is signaled.
2) If `obsrvr' and `target' map to the same NAIF integer ID codes,
the error SPICE(BODIESNOTDISTINCT) is signaled.
3) If frame definition data enabling the evaluation of the state
of the target relative to the observer in target body-fixed
coordinates have not been loaded prior to calling srfxpt_c, the
error will be diagnosed and signaled by a routine in the call
tree of this routine.
4) If the specified aberration correction is not recognized, the
error will be diagnosed and signaled by a routine in the call
tree of this routine.
5) If insufficient ephemeris data have been loaded prior to
calling srfxpt_c, the error will be diagnosed and signaled by a
routine in the call tree of this routine. Note that when
light time correction is used, sufficient ephemeris data
must be available to propagate the states of both observer
and target to the solar system barycenter.
6) If the computation method has been specified as "Ellipsoid"
and triaxial radii of the target body have not been loaded
into the kernel pool prior to calling srfxpt_c, the error will
be diagnosed and signaled by a routine in the call tree of
this routine.
7) The target must be an extended body: if any of the radii of
the target body are non-positive, the error will be diagnosed
and signaled by routines in the call tree of this routine.
8) If PCK data supplying a rotation model for the target body
have not been loaded prior to calling srfxpt_c, the error will
be diagnosed and signaled by a routine in the call tree of
this routine.
9) If the reference frame designated by `dref' is not recognized,
the error SPICE(NOTSUPPORTED) will be signaled.
10) If the direction vector `dvec' is the zero vector, the error
SPICE(ZEROVECTOR) will be signaled.
11) If any of the input string pointers `method', `target',
`abcorr', `obsrvr', or `dref' are null, the error
SPICE(NULLPOINTER) will be signaled.
12) If any of the input strings referred to by `method', `target',
`abcorr', `obsrvr', or `dref' contain no data characters, the
error SPICE(EMPTYSTRING) will be signaled.
-Files
Appropriate SPK, PCK, and frame kernels must be loaded by the
calling program before this routine is called. CK, SCLK, and
IK kernels may be required as well.
The following data are required:
- SPK data: ephemeris data for target and observer 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.
- PCK data: if the computation method is specified as
"Ellipsoid," triaxial radii for the target body must be
loaded into the kernel pool. Typically this is done by
loading a text PCK file via furnsh_c.
- Further PCK data: rotation data for the target body must
be loaded. These may be provided in a text or binary PCK
file.
- Frame data: if a frame definition is required to convert
the observer and target states to the body-fixed frame of
the target, that definition must be available in the kernel
pool. Similarly, the frame definition required to map
between the frame designated by `dref' and the target
body-fixed frame must be available. Typically the
definitions of frames not already built-in to SPICE are
supplied by loading a frame kernel.
The following data may be required:
- CK data: if the frame to which `dref' refers is fixed to
a spacecraft instrument or structure, at least one CK file will
be needed to permit transformation of vectors between that
frame and both J2000 and the target body-fixed frame.
- SCLK data: if a CK file is needed, an associated SCLK kernel
is required to enable conversion between encoded SCLK
(used to time-tag CK data) and barycentric dynamical time
(TDB).
- IK data: one or more I-kernels may be required to
enable transformation of vectors from an instrument-fixed
frame to a spacecraft-fixed frame whose attitude is given
by a C-kernel.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
-Particulars
Given a ray defined by a direction vector and the location of an
observer, srfxpt_c computes the surface intercept point of the ray
on a specified target body. srfxpt_c also determines the distance
between the observer and the surface intercept point.
When aberration corrections are used, this routine finds the
value of `spoint' such that, if `spoint' is regarded as an ephemeris
object, after the selected aberration corrections are applied to
the vector from the observer to `spoint', the resulting vector is
parallel to the direction vector `dvec'.
This routine computes light time corrections using light time
between the observer and the surface intercept point, as opposed
to the center of the target. Similarly, stellar aberration
corrections done by this routine are based on the direction of
the vector from the observer to the light-time corrected
intercept point, not to the target center. This technique avoids
errors due to the differential between aberration corrections
across the target body. Therefore it's valid to use aberration
corrections with this routine even when the observer is very
close to the intercept point, in particular when the
observer-intercept point distance is much less than the
observer-target center distance. It's also valid to use stellar
aberration corrections even when the intercept point is near or
on the limb (as may occur in occultation computations using a
point target).
When comparing surface intercept point computations with results
from sources other than SPICE, it's essential to make sure the
same geometric definitions are used.
-Examples
The numerical results shown for this example 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.
Example 1
---------
The following program computes surface intercept points on
Mars for the boresight and FOV boundary vectors of the
MGS MOC narrow angle camera. The intercepts are computed
for a single observation epoch. Light time and stellar
aberration corrections are used. For simplicity, camera
distortion is ignored.
#include <stdio.h>
#include <string.h>
#include "SpiceUsr.h"
#include "SpiceZmc.h"
int main()
{
/.
Local parameters
./
#define ABCLEN 20
#define LNSIZE 81
#define METLEN 41
#define NAMLEN 33
#define TIMLEN 51
#define SHPLEN 81
#define NCORNR 4
/.
Local variables
./
SpiceBoolean found;
SpiceChar * abcorr = "LT+S";
SpiceChar * camera = "MGS_MOC_NA";
SpiceChar dref [NAMLEN];
SpiceChar * method = "Ellipsoid";
SpiceChar * obsrvr = "MGS";
SpiceChar shape [ SHPLEN ];
SpiceChar * target = "Mars";
SpiceChar title [ LNSIZE ];
SpiceChar * utc = "2003 OCT 13 06:00:00 UTC";
SpiceDouble bounds [NCORNR][3];
SpiceDouble bsight [3];
SpiceDouble dist;
SpiceDouble dvec [3];
SpiceDouble et;
SpiceDouble lat;
SpiceDouble lon;
SpiceDouble obspos [3];
SpiceDouble radius;
SpiceDouble spoint [3];
SpiceDouble trgepc;
SpiceInt camid;
SpiceInt i;
SpiceInt n;
/.
Load kernel files:
- Leapseconds kernel
- MGS SCLK kernel
- Text PCK file
- Planetary SPK file
- MGS I-kernel
- MGS spacecraft bus C-kernel
- MGS SPK file
./
furnsh_c ( "naif0007.tls" );
furnsh_c ( "mgs_sclkscet_00052.tsc" );
furnsh_c ( "mars_iau2000_v0.tpc" );
furnsh_c ( "de405s.bsp" );
furnsh_c ( "mgs_moc_v20.ti" );
furnsh_c ( "mgs_sc_ext12.bc" );
furnsh_c ( "mgs_ext12.bsp" );
/.
Convert the UTC request time to ET (seconds past
J2000, TDB).
./
str2et_c ( utc, &et );
/.
Get the MGS MOC Narrow angle camera (MGS_MOC_NA)
ID code. Then look up the field of view (FOV)
parameters.
./
bodn2c_c ( camera, &camid, &found );
if ( !found )
{
setmsg_c ( "Could not find ID code for "
"instrument #." );
errch_c ( "#", camera );
sigerr_c ( "SPICE(NOTRANSLATION)" );
}
getfov_c ( camid, NCORNR, SHPLEN, NAMLEN,
shape, dref, bsight, &n, bounds );
printf ( "\n"
"Surface Intercept Locations for Camera\n"
"FOV Boundary and Boresight Vectors\n"
"\n"
" Instrument: %s\n"
" Epoch: %s\n"
" Aberration correction: %s\n"
"\n",
camera, utc, abcorr );
/.
Now compute and display the surface intercepts for the
boresight and all of the FOV boundary vectors.
./
for ( i = 0; i <= NCORNR; i++ )
{
if ( i < NCORNR )
{
sprintf ( title, "Corner vector %ld", i );
vequ_c ( bounds[i], dvec );
}
else
{
strcpy ( title, "Boresight vector" );
vequ_c ( bsight, dvec );
}
/.
Compute the surface intercept point using
the specified aberration corrections.
srfxpt_c will signal an error if required kernel
data are unavailable. See example (2) below for
a suggestion on detecting absence of C-kernel
data prior to calling srfxpt_c.
./
srfxpt_c ( method,
target, et, abcorr,
obsrvr, dref, dvec,
spoint, &dist, &trgepc, obspos, &found );
if ( found )
{
/.
Convert rectangular coordinates to planetocentric
latitude and longitude. Convert radians to degrees.
./
reclat_c ( spoint, &radius, &lon, &lat );
lon *= dpr_c ();
lat *= dpr_c ();
/.
Display the results.
./
printf ( "\n"
"%s\n", title );
sprintf ( title, " Vector in %s frame = ", dref );
printf ( "\n"
"%s\n", title );
if ( i < NCORNR )
{
printf ( " %18.10e %18.10e %18.10e\n",
bounds[i][0], bounds[i][1], bounds[i][2] );
}
else
{
printf ( " %18.10e %18.10e %18.10e\n",
bsight[0], bsight[1], bsight[2] );
}
printf ( "\n"
" Intercept:\n"
"\n"
" Radius (km) = %18.10e\n"
" Planetocentric Latitude (deg) = %18.10e\n"
" Planetocentric Longitude (deg) = %18.10e\n"
" Range (km) = %18.10e\n"
"\n",
radius, lat, lon, dist );
}
else
{
printf ( "\n"
"Intercept not found.\n"
"\n" );
}
}
return ( 0 );
}
When this program is executed, the output will be:
Surface Intercept Locations for Camera
FOV Boundary and Boresight Vectors
Instrument: MGS_MOC_NA
Epoch: 2003 OCT 13 06:00:00 UTC
Aberration correction: LT+S
Corner vector 0
Vector in MGS_MOC_NA frame =
1.8571383810e-06 -3.8015622659e-03 9.9999277403e-01
Intercept:
Radius (km) = 3.3849412615e+03
Planetocentric Latitude (deg) = -4.8477118861e+01
Planetocentric Longitude (deg) = -1.2347365507e+02
Range (km) = 3.8898362745e+02
Corner vector 1
Vector in MGS_MOC_NA frame =
1.8571383810e-06 3.8015622659e-03 9.9999277403e-01
Intercept:
Radius (km) = 3.3849398244e+03
Planetocentric Latitude (deg) = -4.8481272936e+01
Planetocentric Longitude (deg) = -1.2339839939e+02
Range (km) = 3.8897565851e+02
Corner vector 2
Vector in MGS_MOC_NA frame =
-1.8571383810e-06 3.8015622659e-03 9.9999277403e-01
Intercept:
Radius (km) = 3.3849398156e+03
Planetocentric Latitude (deg) = -4.8481298506e+01
Planetocentric Longitude (deg) = -1.2339840260e+02
Range (km) = 3.8897519958e+02
Corner vector 3
Vector in MGS_MOC_NA frame =
-1.8571383810e-06 -3.8015622659e-03 9.9999277403e-01
Intercept:
Radius (km) = 3.3849412527e+03
Planetocentric Latitude (deg) = -4.8477144435e+01
Planetocentric Longitude (deg) = -1.2347365823e+02
Range (km) = 3.8898316850e+02
Boresight vector
Vector in MGS_MOC_NA frame =
0.0000000000e+00 0.0000000000e+00 1.0000000000e+00
Intercept:
Radius (km) = 3.3849405358e+03
Planetocentric Latitude (deg) = -4.8479216591e+01
Planetocentric Longitude (deg) = -1.2343603019e+02
Range (km) = 3.8897626607e+02
Example 2
---------
srfxpt_c will signal an error if required kernel data are
unavailable: for example, in the program of Example 1, if the
C-kernel containing data for the MGS bus had a gap at epoch `et',
srfxpt_c would be unable to transform the direction vector `dvec'
from the reference frame fixed to the camera to the reference
frame fixed to the target body.
We could modify the code of Example 1 as shown below to test for
the availability of C-kernel data. We would add the declarations
shown, and we'd call the C-kernel reader ckgp_c to find whether the
desired pointing was available. Depending on the value of the
`found' flag returned by ckgp_c, we'd go on to compute the surface
intercept point or respond to the error condition.
.
.
.
/.
Local parameters
./
#define BUSID ( -94000 )
#define MGS ( -94 )
.
.
.
/.
Local variables
./
SpiceDouble clkout;
SpiceDouble cmat [3][3];
SpiceDouble sclkdp;
.
.
.
/.
Look up the transformation from the J2000 frame to the
MGS spacecraft frame. To do this, we'll need to represent
our observation epoch in terms of MGS encoded SCLK.
./
sce2c_c ( MGS, et, &sclkdp );
/.
Look up the spacecraft attitude from the C-kernel.
./
ckgp_c ( BUSID, sclkdp, 0., "J2000",
cmat, &clkout, &found );
if ( found )
{
[Proceed to compute intercept point]
}
else
{
[Handle case where pointing is unavailable
for the epoch of interest]
}
.
.
.
-Restrictions
A cautionary note: if aberration corrections are used, and
if `dref' is the target body-fixed frame, the epoch at which that
frame is evaluated is offset from `et' by the light time between the
observer and the *center* of the target body. This light time
normally will differ from the light time between the observer and
intercept point. Consequently the orientation of the target
body-fixed frame at `trgepc' will not match that of the target
body-fixed frame at the epoch associated with `dref'. As a result,
various derived quantities may not be as expected: for example,
`obspos' would not be the inverse of the aberration-corrected
position of the target as seen by the observer.
In many applications the errors arising from this frame
discrepancy may be insignificant; however a safe approach is to
always use as `dref' a frame other than the target body-fixed
frame.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.3, 19-MAY-2010 (BVS)
Index line now states that this routine is deprecated.
-CSPICE Version 1.0.2, 07-FEB-2008 (NJB)
Abstract now states that this routine is deprecated.
Header typo was corrected; reference to vminus_c was replaced
with reference to vsub_c.
-CSPICE Version 1.0.1, 22-JUL-2004 (NJB)
Made trivial change to description of `obsrvr' in
Detailed Input header section.
-CSPICE Version 1.0.0, 27-FEB-2004 (NJB)
-Index_Entries
DEPRECATED surface intercept point
-&
*/
{ /* Begin srfxpt_c */
/*
Local variables
*/
logical fnd;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "srfxpt_c" );
/*
Check the input string arguments:
method
target
abcorr
obsrvr
dref
Make sure each pointer is non-null and each string contains
at least one data character: that is, one character
preceding the null terminator.
*/
CHKFSTR ( CHK_STANDARD, "srfxpt_c", method );
CHKFSTR ( CHK_STANDARD, "srfxpt_c", target );
CHKFSTR ( CHK_STANDARD, "srfxpt_c", abcorr );
CHKFSTR ( CHK_STANDARD, "srfxpt_c", obsrvr );
CHKFSTR ( CHK_STANDARD, "srfxpt_c", dref );
/*
Call the f2c'd SPICELIB function.
*/
srfxpt_ ( (char *) method,
(char *) target,
(doublereal *) &et,
(char *) abcorr,
(char *) obsrvr,
(char *) dref,
(doublereal *) dvec,
(doublereal *) spoint,
(doublereal *) dist,
(doublereal *) trgepc,
(doublereal *) obspos,
(logical *) &fnd,
(ftnlen ) strlen(method),
(ftnlen ) strlen(target),
(ftnlen ) strlen(abcorr),
(ftnlen ) strlen(obsrvr),
(ftnlen ) strlen(dref) );
/*
Move the found flag into a variable of type SpiceBoolean.
The SpiceBoolean type may have a different size than
the logical type.
*/
*found = fnd;
chkout_c ( "srfxpt_c" );
} /* End srfxpt_c */
void gfstep_c ( SpiceDouble time,
SpiceDouble * step )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
time I Ignored ET value.
step O Time step to take.
-Detailed_Input
time is an ignored double precision number. This argument
is present so the argument list of this routine is
compatible with the GF step size routine argument list
specification.
When this routine is called from within the GF
root-finding system, either the initial ET value of the
current interval of the confinement window, or the
value resulting from the last search step, is passed in
via the `time' argument.
-Detailed_Output
step is the output step size. This is the value set by the
most recent call to gfsstp_c. Units are TDB seconds.
`step' is used in the GF search root-bracketing process.
`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.
-Parameters
None.
-Exceptions
1) If this routine is called before a step size has been
set via a call to gfsstp_c, the error SPICE(NOTINITIALIZED)
is signaled.
-Files
None.
-Particulars
This routine returns the time step set by the most recent call to
gfsstp_c.
-Examples
1) User applications can pass gfstep_c to mid-level GF API routines
expecting a step size routine as an input argument. 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)
L.S. Elson (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 1.0.0, 15-APR-2009 (LSE) (NJB)
-Index_Entries
GF get constant step size
-&
*/
{ /* Begin gfstep_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfstep_c" );
/*
Let the f2c'd routine do the work.
*/
gfstep_ ( ( doublereal * ) &time,
( doublereal * ) step );
chkout_c ( "gfstep_c" );
} /* End gfstep_c */
void gfpa_c ( ConstSpiceChar * target,
ConstSpiceChar * illmn,
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.
illmn I Name of the illuminating 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. 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.
Case and leading or trailing blanks are not significant
in the string `target'.
illmn the string name of the illuminating body. This will
normally be "SUN" but the algorithm can use any
ephemeris object
Case and leading or trailing blanks are not significant
in the string `illmn'.
abcorr indicates the aberration corrections to be applied to
the observer-target position 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 allowed aberation 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.
Note that this routine accepts only reception mode
aberration corrections.
Case and leading or trailing blanks are not significant
in the string `abcorr'.
obsrvr is the name of the observing body. 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.
Case and leading or trailing blanks are not significant
in the string `obsrvr'.
relate is a relational operator used to define a constraint on
the phase angle. 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:
">" The phase angle value is greater than the
reference value REFVAL.
"=" The phase angle value is equal to the
reference value REFVAL.
"<" The phase angle value is less than the
reference value REFVAL.
"ABSMAX" The phase angle value is at an absolute
maximum.
"ABSMIN" The phase angle value is at an absolute
minimum.
"LOCMAX" The phase angle value is at a local
maximum.
"LOCMIN" The phase angle value is at a local
minimum.
`relate' may be used to specify an "adjusted" absolute
extremum constraint: this requires the phase angle
to be within a specified offset relative to an
absolute extremum. The argument `adjust' (described
below) is used to specify this offset.
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 and leading or trailing blanks are 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 phase angle. See the discussion of
`relate' above for further information.
The units of `refval' are radians.
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, gfpa_c will
find times when the phase angle is within
`adjust' radians 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 phase angle 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 shorter than any maximal time interval on which the
specified phase angle function is monotone increasing or
decreasing. That is, if the confinement window is
partitioned into alternating intervals on which the
phase angle function is either monotone increasing or
decreasing, `step' must be shorter than any of these
intervals.
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
workspace windows used internally by this routine.
In many cases, it's not necessary to compute an accurate
estimate of how many intervals are needed; rather, the
user can pick a size considerably larger than what's
really required.
However, since excessively large arrays can prevent
applications from compiling, linking, or running
properly, sometimes `nintvls' must be set according to
the actual workspace requirement. A rule of thumb for
the number of intervals needed is
nintvls = 2*n + ( m / step )
where
n is the number of intervals in the confinement
window
m is the measure of the confinement window, in
units of seconds
`step' is the search step size in seconds
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.
The endpoints of the time intervals comprising `cnfine'
are interpreted as seconds past J2000 TDB.
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
phase angle constraint is satisfied.
The endpoints of the time intervals comprising `result'
are interpreted as seconds past J2000 TDB.
If `result' is non-empty on input, its contents will be
discarded before gfpa_c conducts its search.
-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, an error is signaled by 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 the output SPICE window `result' has insufficient capacity to
contain the number of intervals on which the specified geometric
condition is met, the error will be diagnosed by a routine in
the call tree of this routine. If the result window has size
less than 2, the error SPICE(INVALIDDIMENSION) will be signaled
by this routine.
12) If any input string argument pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
13) If any input string argument is empty, the error
SPICE(EMPTYSTRING) will be signaled.
14) If either input cell has type other than SpiceDouble,
the error SPICE(TYPEMISMATCH) is signaled.
15) An error signals from a routine in the call tree of
this routine for any transmit mode aberration correction.
-Files
Appropriate SPK and PCK kernels must be loaded by the calling
program before this routine is called.
The following data are required:
- SPK data: the calling application must load ephemeris data
for the targets, observer, and any intermediate objects in
a chain connecting the targets and observer that cover the
time period specified by the window CNFINE. 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 using
furnsh_c.
Kernel data are normally loaded once per program run, NOT every
time this routine is called.
-Particulars
ILLMN OBS
ILLMN as seen * /
from TARG at | /
ET - LT. | /
>|..../< phase angle
| /
. | /
. | /
. * TARG as seen from OBS
SEP . TARG at ET
. /
/
*
This routine determines if the caller-specified constraint
condition on the geometric event (phase angle) 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 searches for
illuminator-target-observer phase angle value events.
Applications that require support for progress reporting,
interrupt handling, non-default step or refinement functions
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
phase angle 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 phase angle
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 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 phase angle 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
phase angle 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 phase angle 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,
illumination source, 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. See the "CASCADE"
example program in gf.req for a demonstration.
-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 December 1, 2006 UTC to
January 31, 2007 UTC for which the sun-moon-earth configuration
phase angle satisfies the relation conditions with respect to a
reference value of .57598845 radians (the phase angle at
January 1, 2007 00:00:00.000 UTC, 33.001707 degrees). Also
determine the time windows corresponding to the local maximum and
minimum phase angles, and the absolute maximum and minimum phase
angles during the search interval. The configuration defines the
sun as the illuminator, the moon as the target, and the earth as
the observer.
#include <stdio.h>
#include "SpiceUsr.h"
#define TIMFMT "YYYY MON DD HR:MN:SC.###"
#define NINTVL 5000
#define TIMLEN 41
#define NLOOPS 7
int main()
{
/.
Local variables
./
SpiceChar begstr [ TIMLEN ];
SpiceChar endstr [ TIMLEN ];
SPICEDOUBLE_CELL ( cnfine, 2 );
SPICEDOUBLE_CELL ( result, NINTVL*2 );
SpiceDouble adjust;
SpiceDouble et0;
SpiceDouble et1;
SpiceDouble phaseq;
SpiceDouble refval;
SpiceDouble start;
SpiceDouble step;
SpiceDouble stop;
SpiceInt i;
SpiceInt j;
/.
Define the values for target, observer, illuminator, and
aberration correction.
./
ConstSpiceChar * target = "moon";
ConstSpiceChar * illmn = "sun";
ConstSpiceChar * abcorr = "lt+s";
ConstSpiceChar * obsrvr = "earth";
ConstSpiceChar * relate [NLOOPS] = { "=",
"<",
">",
"LOCMIN",
"ABSMIN",
"LOCMAX",
"ABSMAX",
};
/.
Load kernels.
./
furnsh_c ( "standard.tm" );
/.
Store the time bounds of our search interval in
the confinement window.
./
str2et_c ( "2006 DEC 01", &et0 );
str2et_c ( "2007 JAN 31", &et1 );
wninsd_c ( et0, et1, &cnfine );
/.
Search using a step size of 1 day (in units of seconds).
The reference value is 0.57598845 radians. We're not using the
adjustment feature, so we set ADJUST to zero.
./
step = spd_c();
refval = 0.57598845;
adjust = 0.0;
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.
./
gfpa_c ( target, illmn, abcorr, obsrvr,
relate[j], refval, adjust, step,
NINTVL, &cnfine, &result );
/.
Display the results.
./
if ( wncard_c(&result) == 0 )
{
printf ( "Result window is empty.\n\n" );
}
else
{
for ( i = 0; i < wncard_c(&result); i++ )
{
/.
Fetch the endpoints of the Ith interval
of the result window.
./
wnfetd_c ( &result, i, &start, &stop );
phaseq = phaseq_c ( start, target, illmn, obsrvr, abcorr );
timout_c ( start, TIMFMT, TIMLEN, begstr );
printf ( "Start time = %s %16.9f\n", begstr, phaseq );
phaseq = phaseq_c ( stop, target, illmn, obsrvr, abcorr );
timout_c ( stop, TIMFMT, TIMLEN, endstr );
printf ( "Stop time = %s %16.9f\n", endstr, phaseq );
}
printf("\n");
}
}
return ( 0 );
}
The program outputs:
Relation condition: =
Start time = 2006 DEC 02 13:31:34.414 0.575988450
Stop time = 2006 DEC 02 13:31:34.414 0.575988450
Start time = 2006 DEC 07 14:07:55.470 0.575988450
Stop time = 2006 DEC 07 14:07:55.470 0.575988450
Start time = 2006 DEC 31 23:59:59.997 0.575988450
Stop time = 2006 DEC 31 23:59:59.997 0.575988450
Start time = 2007 JAN 06 08:16:25.512 0.575988450
Stop time = 2007 JAN 06 08:16:25.512 0.575988450
Start time = 2007 JAN 30 11:41:32.557 0.575988450
Stop time = 2007 JAN 30 11:41:32.557 0.575988450
Relation condition: <
Start time = 2006 DEC 02 13:31:34.414 0.575988450
Stop time = 2006 DEC 07 14:07:55.470 0.575988450
Start time = 2006 DEC 31 23:59:59.997 0.575988450
Stop time = 2007 JAN 06 08:16:25.512 0.575988450
Start time = 2007 JAN 30 11:41:32.557 0.575988450
Stop time = 2007 JAN 31 00:00:00.000 0.468279091
Relation condition: >
Start time = 2006 DEC 01 00:00:00.000 0.940714974
Stop time = 2006 DEC 02 13:31:34.414 0.575988450
Start time = 2006 DEC 07 14:07:55.470 0.575988450
Stop time = 2006 DEC 31 23:59:59.997 0.575988450
Start time = 2007 JAN 06 08:16:25.512 0.575988450
Stop time = 2007 JAN 30 11:41:32.557 0.575988450
Relation condition: LOCMIN
Start time = 2006 DEC 05 00:16:50.317 0.086121423
Stop time = 2006 DEC 05 00:16:50.317 0.086121423
Start time = 2007 JAN 03 14:18:31.977 0.079899769
Stop time = 2007 JAN 03 14:18:31.977 0.079899769
Relation condition: ABSMIN
Start time = 2007 JAN 03 14:18:31.977 0.079899769
Stop time = 2007 JAN 03 14:18:31.977 0.079899769
Relation condition: LOCMAX
Start time = 2006 DEC 20 14:09:10.392 3.055062862
Stop time = 2006 DEC 20 14:09:10.392 3.055062862
Start time = 2007 JAN 19 04:27:54.600 3.074603891
Stop time = 2007 JAN 19 04:27:54.600 3.074603891
Relation condition: ABSMAX
Start time = 2007 JAN 19 04:27:54.600 3.074603891
Stop time = 2007 JAN 19 04:27:54.600 3.074603891
-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.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
E.D. Wright (JPL)
-Version
-CSPICE Version 1.0.0, 15-JUL-2014 (EDW) (NJB)
-Index_Entries
GF phase angle search
-&
*/
{ /* Begin gfpa_c */
/*
Static local variables
*/
static SpiceInt nw = SPICE_GF_NWPA;
/*
Local variables
*/
doublereal * work;
SpiceInt nBytes;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfpa_c" );
/*
Make sure cell data types are d.p.
*/
CELLTYPECHK2 ( CHK_STANDARD, "gfpa_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, "gfpa_c", target );
CHKFSTR ( CHK_STANDARD, "gfpa_c", illmn );
CHKFSTR ( CHK_STANDARD, "gfpa_c", abcorr );
CHKFSTR ( CHK_STANDARD, "gfpa_c", obsrvr );
CHKFSTR ( CHK_STANDARD, "gfpa_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 (1)." );
errint_c ( "#", nintvls );
sigerr_c ( "SPICE(VALUEOUTOFRANGE)" );
chkout_c ( "gfpa_c" );
return;
}
/*
Allocate the workspace.
We have `nw' "doublereal" cells, each having cell size 2*nintvls.
Each cell also has a control area containing SPICE_CELL_CTRLSZ
double precision values.
*/
nintvls = nintvls * 2;
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(MALLOCFAILURE)" );
chkout_c ( "gfpa_c" );
return;
}
/*
Let the f2'd routine do the work.
*/
gfpa_ ( ( char * ) target,
( char * ) illmn,
( 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(illmn),
( 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 ( "gfpa_c" );
} /* End gfpa_c */
void wnintd_c ( SpiceCell * a,
SpiceCell * b,
SpiceCell * c )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
a,
b I Input windows.
c O Intersection of a and b.
-Detailed_Input
a,
b are CSPICE windows, each of which contains zero or more
intervals.
a and b must be declared as double precision
SpiceCells.
-Detailed_Output
c is the output CSPICE window, containing the intersection
of a and b---every point contained in both a and b.
c must be declared as a double precision SpiceCell.
c must be distinct from both a and b.
-Parameters
None.
-Exceptions
1) If any of the function arguments are SpiceCells of type
other than double precision, the error SPICE(TYPEMISMATCH)
is signaled.
2) If the intersection of the two windows results in an excess of
elements, the error SPICE(WINDOWEXCESS) is signaled.
-Files
None.
-Particulars
The intersection of two windows contains every point contained
both in the first window and in the second window.
-Examples
Let a contain the intervals
[ 1, 3 ] [ 7, 11 ] [ 23, 27 ]
and b contain the intervals
[ 2, 4 ] [ 8, 10 ] [ 16, 18 ]
Then the intersection of a and b contains the intervals
[ 2, 3 ] [ 8, 10 ]
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
H.A. Neilan (JPL)
B.V. Semenov (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.1, 11-FEB-2013 (BVS)
Corrected typo in Brief I/O section.
-CSPICE Version 1.0.0, 29-JUL-2002 (NJB) (HAN) (WLT) (IMU)
-Index_Entries
intersect two d.p. windows
-&
*/
{ /* Begin wnintd_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "wnintd_c" );
/*
Make sure cell data types are d.p.
*/
CELLTYPECHK3 ( CHK_STANDARD, "wnintd_c", SPICE_DP, a, b, c );
/*
Initialize the cells if necessary.
*/
CELLINIT3 ( a, b, c );
/*
Let the f2c'd routine do the work.
*/
wnintd_ ( (doublereal * ) (a->base),
(doublereal * ) (b->base),
(doublereal * ) (c->base) );
/*
Sync the output cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, c );
}
chkout_c ( "wnintd_c" );
} /* End wnintd_c */
void errprt_c ( ConstSpiceChar * op,
SpiceInt lenout,
SpiceChar * list )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
op I The operation: "GET" or "SET".
lenout I Length of list for output.
list I/O Specification of error messages to be output.
-Detailed_Input
op indicates the operation to be performed. Possible
values are "GET" and "SET".
"SET" means, "the following list specifies the default
selection of error messages to be output." These are
the messages that will be output to the default error
output device (selected by errdev_c) when an error is
detected.
"GET" means, "return the current list of error output
items." This is the exact list that was set by the
last call to this routine with the "SET" option.
The option can be specified in mixed case. For example,
the following call will work:
errprt_c ( "SeT", lenout, "ALL" )
lenout is the allowed length of list when list is returning a
the error message list. The size described by lenout
should be large enough to hold any possible output plus 1.
list is a list of error message items. The items
are delimited by commas. The items that can be
in the list are the words:
1. SHORT ...indicates the short error message
2. EXPLAIN ...the explanation of the short message
3. LONG ...the long error message
4. TRACEBACK ...the traceback
5. ALL ...indicates "output all messages"
6. NONE ...indicates "don't output any messages"
7. DEFAULT ...same as ALL, but includes default
message
A "list" is a character string containing some or
all of the above words, delimited by commas. Examples
are:
1. "SHORT, EXPLAIN"
2. "SHORT, LONG"
3. "ALL"
4. "NONE"
5. "ALL, NONE, ALL, SHORT, NONE"
Each word in the list can be thought of as
"flipping a switch" to enable or disable the output
of the message(s) indicated by the word. The
words are acted on in the order they occur in the
list, starting with the leftmost word. As examples,
consider the sample lists above.
The effect of the first list above, "SHORT, EXPLAIN",
is to enable the output of the short error message
and the explanatory text corresponding to it.
The effect of the second list is to enable the output
of the short and long messages.
The effect of the third list is to enable the output of
all of the error messages (short, long, explanation
of the short message, and traceback).
The effect of the fourth list is to disable output of
all of the messages.
The effect of the fifth list is to disable output of
all of the messages. The reason for this is that
the words in the list are responded to in order,
from left to right, and "NONE" is the last word.
If any words other than SHORT, LONG, EXPLAIN, ALL,
DEFAULT, TRACEBACK or NONE appear in list, those words
that are recognized are responded to. The words
that are not recognized are diagnosed as
erroneous, and error messages are generated
for each such unrecognized word.
The length of list is caller-defined, but only
the first 100 characters of list will be saved
for later retrieval.
Only the first 10 items in the list are used;
the rest are ignored.
-Detailed_Output
list is a list of error message items. The value of
list is that set by the last call to this routine
using the "SET" option. See "Detailed Input"
for a description of the possible values and
meanings of list.
The initial value returned is "DEFAULT".
Only the first 100 characters of list are saved
when the list is set; any additional characters
are truncated. Therefore, the first 100
characters, at most, of the saved value of list
will be returned.
-Parameters
None.
-Exceptions
1) If the input argument op does not indicate a valid operation,
the error SPICE(INVALIDOPERATION) will be signaled.
2) If the input argument list does not indicate a valid list of
error message types, the error SPICE(INVALIDLISTITEM) will be
signaled.
3) The error SPICE(EMPTYSTRING) is signalled if the input
string does not contain at least one character, since the
input string cannot be converted to a Fortran-style string
in this case.
4) The error SPICE(NULLPOINTER) is signalled if the input string
pointer is null.
5) The user must pass a value indicating the length of the output
string, when list is an output. If this value is not at least 2,
the error SPICE(STRINGTOOSHORT) is signaled.
Also, this routine is part of the CSPICE error
handling mechanism.
-Files
None.
-Particulars
Please read the "required reading"!
This routine is intended to be used in conjunction with
errdev_c, which selects the default output device to which
the error messages selected by this routine will be
output.
Additionally, the error response action must be
something other than "IGNORE" if the error messages
are to be output. Possible choices of the error
response action are "RETURN", "REPORT", "ABORT", "DEFAULT", and
"IGNORE". Use erract_c to set the error response action.
Only the first 100 characters of list are saved.
The default set of error messages that are output is the
set specified by "DEFAULT"; i.e., all of them, including
the "default" message.
-Examples
1. In this example, we select as the output device
the file, SPUD.DAT, and then select the error
messages to be output. We choose the short
error message and the traceback. Since a
different set of messages may have been selected
previously, we clear the old setting by putting
the word, "NONE", at the beginning of the list.
/.
Set the error output device to SPUD.DAT:
./
errdev_c ( "SET", lenout, "SPUD.DAT" );
/.
Choose error messages:
./
errprt_c ( "SET", lenout, "NONE, SHORT, TRACEBACK" );
2. In this example we are retrieving the error message list.
/.
Declare the output string and its size.
./
#define LENOUT 50
SpiceChar list[ LENOUT ];
errdev_c ( "GET", LENOUT, list );
-Restrictions
The device to which the selected error messages will
be written must be selected via errdev_c; otherwise,
messages will be written to the initial default device.
Only the first 100 characters of list are saved.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.3.0, 24-JUN-2003 (NJB)
Bug fix: case of invalid operation keyword is now
diagnosed, as per the Exceptions section of the header.
-CSPICE Version 2.0.0, 09-FEB-1998 (NJB) (EDW)
Input argument op was changed to type ConstSpiceChar *.
Re-implemented routine without dynamically allocated, temporary
strings.
Corrected errors in examples in which the call sequence
was incorrect.
-CSPICE Version 1.0.0, 25-OCT-1997 (EDW)
-Index_Entries
get/set error output items
-&
*/
{ /* Begin errprt_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "errprt_c" );
/*
Check the input string op to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "errprt_c", op );
if ( eqstr_c ( op, "SET") )
{
/*
Operation is SET. The argument "list" will be an input string.
Check "list" as well.
*/
CHKFSTR ( CHK_STANDARD, "errprt_c", list );
errprt_( ( char * ) op,
( char * ) list,
( ftnlen ) strlen(op),
( ftnlen ) strlen(list) );
}
else if ( eqstr_c (op, "GET" ) )
{
/*
Operation is GET. "list" will be an output string.
Make sure the output string has at least enough room for one
output character and a null terminator. Also check for a null
pointer.
*/
CHKOSTR ( CHK_STANDARD, "errprt_c", list, lenout );
/*
After the routine call, create a C string from the
Fortran output string.
*/
errprt_( ( char * ) op,
( char * ) list,
( ftnlen ) strlen(op),
( ftnlen ) lenout-1 );
F2C_ConvertStr( lenout, list );
}
else
{
setmsg_c ( "Input argument op had value: # "
"Valid choices are GET or SET." );
errch_c ( "#", op );
sigerr_c ( "SPICE(INVALIDOPERATION)" );
chkout_c ( "errprt_c" );
return;
}
chkout_c ( "errprt_c" );
} /* End errprt_c */
void gfsubc_c ( ConstSpiceChar * target,
ConstSpiceChar * fixref,
ConstSpiceChar * method,
ConstSpiceChar * abcorr,
ConstSpiceChar * obsrvr,
ConstSpiceChar * crdsys,
ConstSpiceChar * coord,
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
fixref I Body fixed frame associated with 'target'
method I Name of method type for subpoint calculation
abcorr I Aberration correction flag
obsrvr I Name of the observing body
crdsys I Name of the coordinate system containing 'coord'
coord I Name of the coordinate of interest
relate I Operator that either looks for an extreme value
(max, min, local, absolute) or compares the
coordinate value and refval
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 restricted
result O SPICE window containing results
-Detailed_Input
target the string name of a target body. Optionally, you may
supply the integer ID code for the object as an
integer string. 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
that points from the observer to the target.
fixref the string name of the body-fixed, body-centered
reference frame associated with the target body target.
The SPICE frame subsystem must recognize the 'fixref' name.
method the string name of the method to use for the subpoint
calculation. The accepted values for method:
'Near point: ellipsoid' The sub-observer point
computation uses a
triaxial ellipsoid to
model the surface of the
target body. The
sub-observer point is
defined as the nearest
point on the target
relative to the
observer.
'Intercept: ellipsoid' The sub-observer point
computation uses a
triaxial ellipsoid to
model the surface of the
target body. The
sub-observer point is
defined as the target
surface intercept of the
line containing the
observer and the
target's center.
The method string lacks sensitivity to case, embedded, leading
and trailing blanks.
abcorr the string description of the aberration corrections to apply
to the state evaluations to account for one-way light time
and stellar aberration.
This routine accepts the same aberration corrections as does
the SPICE routine SPKEZR. See the header of SPKEZR 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.
The abcorr string lacks sensitivity to case, and to embedded,
leading and trailing blanks.
obsrvr the string naming the observing body. Optionally, you
may supply the ID code of the object as an integer
string. For example, both 'EARTH' and '399' are
legitimate strings to supply to indicate the
observer is Earth.
crdsys the string name of the coordinate system for which the
coordinate of interest is a member.
coord the string name of the coordinate of interest in crdsys.
The supported coordinate systems and coordinate names are:
The supported coordinate systems and coordinate names are:
Coordinate System (CRDSYS) Coordinates (COORD) Range
'RECTANGULAR' 'X'
'Y'
'Z'
'LATITUDINAL' 'RADIUS'
'LONGITUDE' (-Pi,Pi]
'LATITUDE' [-Pi/2,Pi/2]
'RA/DEC' 'RANGE'
'RIGHT ASCENSION' [0,2Pi)
'DECLINATION' [-Pi/2,Pi/2]
'SPHERICAL' 'RADIUS'
'COLATITUDE' [0,Pi]
'LONGITUDE' (-Pi,Pi]
'CYLINDRICAL' 'RADIUS'
'LONGITUDE' [0,2Pi)
'Z'
'GEODETIC' 'LONGITUDE' (-Pi,Pi]
'LATITUDE' [-Pi/2,Pi/2]
'ALTITUDE'
'PLANETOGRAPHIC' 'LONGITUDE' [0,2Pi)
'LATITUDE' [-Pi/2,Pi/2]
'ALTITUDE'
The ALTITUDE coordinates have a constant value
of zero +/- roundoff for ellipsoid targets.
Limit searches for coordinate events in the GEODETIC and
PLANETOGRAPHIC coordinate systems to TARGET bodies with
axial symmetry in the equatorial plane, i.e. equality
of the body X and Y radii (oblate or prolate spheroids).
relate the string or character describing the relational operator
used to define a constraint on the selected coordinate of the
subpoint vector. 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:
'>' Separation is greater than the reference
value refval.
'=' Separation is equal to the reference
value refval.
'<' Separation is less than the reference
value refval.
'ABSMAX' Separation is at an absolute maximum.
'ABSMIN' Separation is at an absolute minimum.
'LOCMAX' Separation is at a local maximum.
'LOCMIN' Separation 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 measure of an absolute extremum.
The argument ADJUST (described below) is used to
specify this measure.
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.
The relate string lacks sensitivity to case, leading
and trailing blanks.
refval the double precision reference value used together with
relate argument to define an equality or inequality to
satisfy by the selected coordinate of the subpoint
vector. See the discussion of relate above for
further information.
The units of refval correspond to the type as defined
by coord, radians for angular measures, kilometers for
distance measures.
adjust a double precision value used to modify searches for
absolute extrema: when 'relate' is set to ABSMAX or ABSMIN and
'adjust' is set to a positive value, gfsubc_c finds times
when the position vector coordinate is within adjust
radians/kilometers of the specified extreme value.
For 'relate' set to ABSMAX, the result window contains
time intervals when the position vector coordinate has
values between ABSMAX - adjust and ABSMAX.
For 'relate' set to ABSMIN, the result window contains
time intervals when the position vector coordinate has
values between ABSMIN and ABSMIN + adjust.
'adjust' is not used for searches for local extrema,
equality or inequality conditions.
step the double precision time step size to use in the search.
step must be short enough for a search using this step
size to locate the time intervals where coordinate function
of the subpoint vector 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.
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 the SPICE 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 gfsubc_c conducts its
search.
result must be declared and initialized 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 has the value 1.0e-6. Units are TDB
seconds.
-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, an error is signaled by 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 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 the workspace interval count 'nintvls' is less than 1, the
error SPICE(VALUEOUTOFRANGE) will be signaled.
12) If the required amount of workspace memory cannot be
allocated, the error SPICE(MALLOCFAILURE) will be
signaled.
-Files
Appropriate SPK and PCK kernels must be loaded by the
calling program before this routine is called.
The following data are required:
- SPK data: the calling application must load ephemeris data
for the targets, observer, and any intermediate objects in
a chain connecting the targets and observer that cover the time
period specified by the window CNFINE. 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 using
FURNSH.
- PCK data: bodies modeled as triaxial ellipsoids must have
semi-axis lengths provided by variables in the kernel pool.
Typically these data are made available by loading a text
PCK file using FURNSH.
- If non-inertial reference frames are used, then PCK
files, frame kernels, C-kernels, and SCLK kernels may be
needed.
Such 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 gfevnt_c for conducting searches for
subpoint position vector coordinate 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.
This routine determines a set of one or more time intervals
within the confinement window when the selected coordinate of
the subpoint position vector satisfies a caller-specified
constraint. The resulting set of intervals is returned as a SPICE
window.
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
coordinate 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 coordinate
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 coordinate 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 coordinate
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 coordinate 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 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" are both times when local extrema are
attained and times when the distance function is equal to a
reference value. 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 by the parameter SPICE_GF_CNVTOL.
The value of SPICE_GF_CNVTOL is set to a "tight" value in the f2c'd
routine 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.
To use a different tolerance value, a lower-level GF routine such
as gfevnt_c must be called. 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 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.
Practical use of the coordinate search capability would likely
consist of searches over multiple coordinate constraints to find
time intervals that satisfies the constraints. An effective
technique to accomplish such a search is to use the result
window from one search as the confinement window of the next.
Longitude and Right Ascension
=============================
The cyclic nature of the longitude and right ascension coordinates
produces branch cuts at +/- 180 degrees longitude and 0-360
longitude. Round-off error may cause solutions near these branches
to cross the branch. Use of the SPICE routine wncond_c will contract
solution windows by some epsilon, reducing the measure of the
windows and eliminating the branch crossing. A one millisecond
contraction will in most cases eliminate numerical round-off caused
branch crossings.
-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.
The example shown below requires a "standard" set of SPICE
kernels. We list these kernels in a meta kernel named 'standard.tm'.
KPL/MK
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
--------- --------
de414.bsp Planetary ephemeris
pck00008.tpc Planet orientation and
radii
naif0008.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( '/kernels/gen/lsk/naif0008.tls'
'/kernels/gen/spk/de414.bsp'
'/kernels/gen/pck/pck00008.tpc'
)
Example:
Find the time during 2007 for which the subpoint position vector
of the sun on earth in the IAU_EARTH frame lies within a geodetic
latitude-longitude "box" defined as
16 degrees <= latitude <= 17 degrees
85 degrees <= longitude <= 86 degrees
This problem requires four searches, each search on one of the
box restrictions. The user needs also realize the temporal
behavior of latitude greatly differs from that of the longitude. The
sub-observer point latitude varies between approximately 23.44 degrees
and -23.44 degrees during the year. The sub-observer point longitude
varies between -180 degrees and 180 degrees in one day.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "SpiceUsr.h"
#define MAXWIN 100
#define TIMFMT "YYYY-MON-DD HR:MN:SC.###### (TDB) ::TDB ::RND"
#define STRLEN 64
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 equals twice
the number of intervals.
./
SPICEDOUBLE_CELL ( result1, 2*MAXWIN );
SPICEDOUBLE_CELL ( result2, 2*MAXWIN );
SPICEDOUBLE_CELL ( result3, 2*MAXWIN );
SPICEDOUBLE_CELL ( result4, 2*MAXWIN );
SPICEDOUBLE_CELL ( cnfine, 2 );
SpiceDouble begtim;
SpiceDouble endtim;
SpiceDouble step;
SpiceDouble adjust;
SpiceDouble refval;
SpiceDouble beg;
SpiceDouble end;
SpiceChar begstr [ STRLEN ];
SpiceChar endstr [ STRLEN ];
SpiceChar * target = "EARTH";
SpiceChar * obsrvr = "SUN";
SpiceChar * fixref = "IAU_EARTH";
SpiceChar * method = "Near point: ellipsoid";
SpiceChar * crdsys = "GEODETIC";
SpiceChar * abcorr = "NONE";
SpiceInt count;
SpiceInt i;
/.
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( "2008 JAN 01", &endtim );
wninsd_c ( begtim, endtim, &cnfine );
/.
Perform four searches to determine the times when the
latitude-longitude box restriction conditions apply to
the subpoint vector.
Perform the searches such that the result window of a search
serves as the confinement window of the subsequent search.
Since the latitude coordinate varies slowly and is well behaved
over the time of the confinement window, search first for the
windows satisfying the latitude requirements, then use that result
as confinement for the longitude search.
./
/.
The latitude varies relatively slowly, ~46 degrees during the
year. The extrema occur approximately every six months.
Search using a step size less than half that value (180 days).
For this example use ninety days (in units of seconds).
./
step = (90.)*spd_c();
adjust = 0.;
{
SpiceChar * coord = "LATITUDE";
SpiceChar * relate = ">";
refval = 16. *rpd_c();
gfsubc_c ( target, fixref,
method, abcorr, obsrvr,
crdsys, coord,
relate, refval,
adjust, step,
MAXWIN,
&cnfine, &result1 );
}
{
SpiceChar * coord = "LATITUDE";
SpiceChar * relate = "<";
refval = 17. *rpd_c();
gfsubc_c ( target, fixref,
method, abcorr, obsrvr,
crdsys, coord,
relate, refval,
adjust, step,
MAXWIN,
&result1, &result2 );
}
/.
Now the longitude search.
./
/.
Reset the stepsize to something appropriate for the 360
degrees in 24 hours domain. The longitude shows near
linear behavior so use a stepsize less than half the period
of twelve hours. Ten hours will suffice in this case.
./
step = (10./24.)*spd_c();
{
SpiceChar * coord = "LONGITUDE";
SpiceChar * relate = ">";
refval = 85. *rpd_c();
gfsubc_c ( target, fixref,
method, abcorr, obsrvr,
crdsys, coord,
relate, refval,
adjust, step,
MAXWIN,
&result2, &result3 );
/.
Contract the endpoints of each window to account
for possible round-off error at the -180/180 degree branch.
A contraction value of a millisecond should eliminate
any round-off caused branch crossing.
./
wncond_c( 1e-3, 1e-3, &result3 );
}
{
SpiceChar * coord = "LONGITUDE";
SpiceChar * relate = "<";
refval = 86. *rpd_c();
gfsubc_c ( target, fixref,
method, abcorr, obsrvr,
crdsys, coord,
relate, refval,
adjust, step,
MAXWIN,
&result3, &result4 );
}
/.
List the beginning and ending points in each interval
if result contains data.
./
count = wncard_c( &result4 );
/.
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 ( &result4, i, &beg, &end );
timout_c ( beg, TIMFMT, STRLEN, begstr );
timout_c ( end, TIMFMT, STRLEN, endstr );
printf ( "Interval %d\n", i + 1);
printf ( "Beginning TDB %s \n", begstr );
printf ( "Ending TDB %s \n\n", endstr );
}
}
kclear_c();
return( 0 );
}
The program outputs:
Interval 1
Beginning TDB 2007-MAY-05 06:14:04.637735 (TDB)
Ending TDB 2007-MAY-05 06:18:04.621908 (TDB)
Interval 2
Beginning TDB 2007-MAY-06 06:13:59.583483 (TDB)
Ending TDB 2007-MAY-06 06:17:59.569239 (TDB)
Interval 3
Beginning TDB 2007-MAY-07 06:13:55.102939 (TDB)
Ending TDB 2007-MAY-07 06:17:55.090299 (TDB)
Interval 4
Beginning TDB 2007-MAY-08 06:13:51.202604 (TDB)
Ending TDB 2007-MAY-08 06:17:51.191583 (TDB)
Interval 5
Beginning TDB 2007-AUG-06 06:23:17.282927 (TDB)
Ending TDB 2007-AUG-06 06:27:17.264009 (TDB)
Interval 6
Beginning TDB 2007-AUG-07 06:23:10.545441 (TDB)
Ending TDB 2007-AUG-07 06:27:10.524926 (TDB)
Interval 7
Beginning TDB 2007-AUG-08 06:23:03.233996 (TDB)
Ending TDB 2007-AUG-08 06:27:03.211889 (TDB)
-Restrictions
1) The kernel files to be used by this routine must be loaded
(normally via the CSPICE routine furnsh_c) before this routine
is called.
2) This routine has the side effect of re-initializing the
coordinate quantity utility package. Callers may
need to re-initialize the 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, 26-AUG-2009, EDW (JPL)
Edit to Example description, replaced "intercept" with
"sub-observer point."
Correction of several typos.
-CSPICE Version 1.0.0, 10-FEB-2009 (NJB) (EDW)
-Index_Entries
GF subpoint coordinate search
-&
*/
{ /* Begin gfsubc_c */
/*
Local variables
*/
doublereal * work;
SpiceInt nBytes;
static SpiceInt nw = SPICE_GF_NWMAX;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfsubc_c" );
/*
Make sure cell data types are d.p.
*/
CELLTYPECHK2 ( CHK_STANDARD, "gfsubc_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, "gfsubc_c", target );
CHKFSTR ( CHK_STANDARD, "gfsubc_c", fixref );
CHKFSTR ( CHK_STANDARD, "gfsubc_c", method );
CHKFSTR ( CHK_STANDARD, "gfsubc_c", abcorr );
CHKFSTR ( CHK_STANDARD, "gfsubc_c", obsrvr );
CHKFSTR ( CHK_STANDARD, "gfsubc_c", crdsys );
CHKFSTR ( CHK_STANDARD, "gfsubc_c", coord );
CHKFSTR ( CHK_STANDARD, "gfsubc_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 ( "gfposc_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 ( "gfsubc_c" );
return;
}
/*
Let the f2'd routine do the work.
*/
gfsubc_ ( ( char * ) target,
( char * ) fixref,
( char * ) method,
( char * ) abcorr,
( char * ) obsrvr,
( char * ) crdsys,
( char * ) coord,
( 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(fixref),
( ftnlen ) strlen(method),
( ftnlen ) strlen(abcorr),
( ftnlen ) strlen(obsrvr),
( ftnlen ) strlen(crdsys),
( ftnlen ) strlen(coord),
( 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 ( "gfsubc_c" );
} /* End gfsubc_c */
void gfposc_c ( ConstSpiceChar * target,
ConstSpiceChar * frame,
ConstSpiceChar * abcorr,
ConstSpiceChar * obsrvr,
ConstSpiceChar * crdsys,
ConstSpiceChar * coord,
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
frame I Name of the reference frame for coordinate calculations
abcorr I Aberration correction flag
obsrvr I Name of the observing body
crdsys I Name of the coordinate system containing COORD
coord I Name of the coordinate of interest
relate I Operator that either looks for an extreme value
(max, min, local, absolute) or compares the
coordinate value and refval
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 restricted
result O SPICE window containing results
-Detailed_Input
target the string name of a target body. Optionally, you may
supply the integer ID code for the object as an
integer string. 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
that points from the observer to the target.
frame the string name of the reference frame in which to perform
state look-ups and coordinate calculations.
The SPICE frame subsystem must recognize the 'frame' name.
abcorr the string description of the aberration corrections to apply
to the state evaluations to account for one-way light time
and stellar aberration.
This routine accepts the same aberration corrections as does
the SPICE routine SPKEZR. See the header of SPKEZR 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.
The abcorr string lacks sensitivity to case, and to embedded,
leading and trailing blanks.
obsrvr the string naming the observing body. Optionally, you
may supply the ID code of the object as an integer
string. For example, both 'EARTH' and '399' are
legitimate strings to supply to indicate the
observer is Earth.
crdsys the string name of the coordinate system for which the
coordinate of interest is a member.
coord the string name of the coordinate of interest in crdsys.
The supported coordinate systems and coordinate names are:
Coordinate System (CRDSYS) Coordinates (COORD) Range
'RECTANGULAR' 'X'
'Y'
'Z'
'LATITUDINAL' 'RADIUS'
'LONGITUDE' (-Pi,Pi]
'LATITUDE' [-Pi/2,Pi/2]
'RA/DEC' 'RANGE'
'RIGHT ASCENSION' [0,2Pi)
'DECLINATION' [-Pi/2,Pi/2]
'SPHERICAL' 'RADIUS'
'COLATITUDE' [0,Pi]
'LONGITUDE' (-Pi,Pi]
'CYLINDRICAL' 'RADIUS'
'LONGITUDE' [0,2Pi)
'Z'
'GEODETIC' 'LONGITUDE' (-Pi,Pi]
'LATITUDE' [-Pi/2,Pi/2]
'ALTITUDE'
'PLANETOGRAPHIC' 'LONGITUDE' [0,2Pi)
'LATITUDE' [-Pi/2,Pi/2]
'ALTITUDE'
Limit searches for coordinate events in the GEODETIC and
PLANETOGRAPHIC coordinate systems to TARGET bodies with
axial symmetry in the equatorial plane, i.e. equality
of the body X and Y radii (oblate or prolate spheroids).
relate the string or character describing the relational operator
used to define a constraint on the selected coordinate of the
observer-target vector. 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:
'>' Separation is greater than the reference
value refval.
'=' Separation is equal to the reference
value refval.
'<' Separation is less than the reference
value refval.
'ABSMAX' Separation is at an absolute maximum.
'ABSMIN' Separation is at an absolute minimum.
'LOCMAX' Separation is at a local maximum.
'LOCMIN' Separation 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 measure of an absolute extremum.
The argument ADJUST (described below) is used to
specify this measure.
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.
The relate string lacks sensitivity to case, leading
and trailing blanks.
refval the double precision reference value used together with
relate argument to define an equality or inequality to
satisfy by the selected coordinate of the observer-target
vector. See the discussion of relate above for
further information.
The units of refval correspond to the type as defined
by coord, radians for angular measures, kilometers for
distance measures.
adjust a double precision value used to modify searches for
absolute extrema: when relate is set to ABSMAX or ABSMIN and
adjust is set to a positive value, gfposc_c finds times when the
observer-target vector coordinate is within adjust
radians/kilometers of the specified extreme value.
For relate set to ABSMAX, the result window contains
time intervals when the observer-target vector coordinate has
values between ABSMAX - adjust and ABSMAX.
For relate set to ABSMIN, the result window contains
time intervals when the observer-target vector coordinate has
values between ABSMIN and ABSMIN + adjust.
adjust is not used for searches for local extrema,
equality or inequality conditions.
step the double precision time step size to use in the search.
step must be short enough for a search using this step
size to locate the time intervals where coordinate function
of the observer-target vector 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.
step has units of 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 the SPICE 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 gfposc_c conducts its
search.
result must be declared and initialized 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 has the value 1.0e-6. Units are TDB
seconds.
-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, an error is signaled by 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 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 the workspace interval count 'nintvls' is less than 1, the
error SPICE(VALUEOUTOFRANGE) will be signaled.
12) If the required amount of workspace memory cannot be
allocated, the error SPICE(MALLOCFAILURE) will be
signaled.
-Files
Appropriate SPK and PCK kernels must be loaded by the
calling program before this routine is called.
The following data are required:
- SPK data: the calling application must load ephemeris data
for the targets, observer, and any intermediate objects in
a chain connecting the targets and observer that cover the time
period specified by the window CNFINE. 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 using
FURNSH.
- PCK data: bodies modeled as triaxial ellipsoids must have
semi-axis lengths provided by variables in the kernel pool.
Typically these data are made available by loading a text
PCK file using FURNSH.
- If non-inertial reference frames are used, then PCK
files, frame kernels, C-kernels, and SCLK kernels may be
needed.
Such 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 gfevnt_c for conducting searches for
observer-target vector coordinate 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.
This routine determines a set of one or more time intervals
within the confinement window when the selected coordinate of
the observer-target vector satisfies a caller-specified
constraint. The resulting set of intervals is returned as a SPICE
window.
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
coordinate 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 coordinate
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 coordinate 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 coordinate
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 coordinate 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 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" are both times when local extrema are
attained and times when the distance function is equal to a
reference value. 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 by the parameter SPICE_GF_CNVTOL.
The value of SPICE_GF_CNVTOL is set to a "tight" value in the f2c'd
routine 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.
To use a different tolerance value, a lower-level GF routine such
as gfevnt_c must be called. 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 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.
Practical use of the coordinate search capability would likely
consist of searches over multiple coordinate constraints to find
time intervals that satisfies the constraints. An effective
technique to accomplish such a search is to use the result
window from one search as the confinement window of the next.
Longitude and Right Ascension
=============================
The cyclic nature of the longitude and right ascension coordinates
produces branch cuts at +/- 180 degrees longitude and 0-360
longitude. Round-off error may cause solutions near these branches
to cross the branch. Use of the SPICE routine wncond_c will contract
solution windows by some epsilon, reducing the measure of the
windows and eliminating the branch crossing. A one millisecond
contraction will in most cases eliminate numerical round-off caused
branch crossings.
-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.
The examples shown below require a "standard" set of SPICE
kernels. We list these kernels in a meta kernel named 'standard.tm'.
KPL/MK
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
--------- --------
de414.bsp Planetary ephemeris
pck00008.tpc Planet orientation and radii
naif0009.tls Leapseconds kernel
earthstns_itrf93_050714.bsp SPK for DSN Station Locations
earth_topo_050714.tf Topocentric DSN stations frame
definitions
earth_000101_080120_071029.bpc High precision earth PCK
\begindata
KERNELS_TO_LOAD = (
'/kernels/gen/lsk/naif0008.tls'
'/kernels/gen/spk/de414.bsp'
'/kernels/gen/pck/pck00008.tpc'
'/kernels/gen/spk/earthstns_itrf93_050714.bsp',
'/kernels/gen/fk/earth_topo_050714.tf',
'/kernels/gen/pck/earth_000101_080120_071029.bpc',
)
Example(1):
Find the time during 2007 for which the latitude of the
Earth-Sun vector in IAU_EARTH frame has the maximum value,
i.e. the latitude of the Tropic of Cancer.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "SpiceUsr.h"
#define MAXWIN 750
#define TIMFMT "YYYY-MON-DD HR:MN:SC.###### (TDB) ::TDB ::RND"
#define TIMLEN 41
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 * relate = "ABSMAX";
SpiceChar * crdsys = "LATITUDINAL";
SpiceChar * coord = "LATITUDE";
SpiceChar * targ = "SUN";
SpiceChar * obsrvr = "EARTH";
SpiceChar * frame = "IAU_EARTH";
SpiceChar * abcorr = "NONE";
SpiceInt count;
SpiceInt i;
/.
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( "2008 JAN 01", &endtim );
wninsd_c ( begtim, endtim, &cnfine );
/.
The latitude varies relatively slowly, ~46 degrees during the
year. The extrema occur approximately every six months.
Search using a step size less than half that value (180 days).
For this example use ninety days (in units of seconds).
./
step = (90.)*spd_c();
adjust = 0.;
refval = 0;
/.
List the beginning and ending points in each interval
if result contains data.
./
gfposc_c ( targ,
frame,
abcorr,
obsrvr,
crdsys,
coord,
relate,
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 );
if ( beg == end )
{
timout_c ( beg, TIMFMT, TIMLEN, begstr );
printf ( "Event time: %s\n", begstr );
}
else
{
timout_c ( beg, TIMFMT, TIMLEN, begstr );
timout_c ( end, TIMFMT, TIMLEN, endstr );
printf ( "Interval %d\n", i + 1);
printf ( "From : %s \n", begstr );
printf ( "To : %s \n", endstr );
printf( " \n" );
}
}
}
kclear_c();
return( 0 );
}
The program outputs:
Event time: 2007-JUN-21 17:54:13.166910 (TDB)
Example(2):
A minor modification of the program listed in Example 1; find the
time during 2007 for which the latitude of the Earth-Sun vector
in IAU_EARTH frame has the minimum value, i.e. the latitude of
the Tropic of Capricorn.
Edit the example program, assign:
SpiceChar * relate = "ABSMIN";
The program outputs:
Event time: 2007-DEC-22 06:04:32.630160 (TDB)
Example(3):
Find the time during 2007 for which the Z component of the
Earth-Sun vector in IAU_EARTH frame has value 0, i.e. crosses
the equatorial plane (this also defines a zero latitude).
The search should return two times, one for an ascending
passage and one for descending.
Edit the example program, assign:
SpiceChar * relate = "=";
SpiceChar * crdsys = "RECTANGULAR";
SpiceChar * coord = "Z";
Note, this RELATE operator refers to the REFVAL value,
assigned to 0.D0 for this example.
The program outputs:
Event time: 2007-MAR-21 00:01:25.495120 (TDB)
Event time: 2007-SEP-23 09:46:39.574124 (TDB)
Example(4):
Find the times between Jan 1, 2007 and Jan 1, 2008 corresponding
to the apoapsis on the Moon's orbit around the Earth (note, the
GFDIST routine can also perform this search).
Edit the example program, assign:
This search requires a change in the step size since the Moon's
orbit about the earth (earth-moon barycenter) has a twenty-eight
day period. Use a step size something less than half that value.
In this case, we use twelve days.
SpiceChar * relate = "LOCMAX";
SpiceChar * crdsys = "SPHERICAL";
SpiceChar * coord = "RADIUS";
SpiceChar * targ = "MOON";
SpiceChar * frame = "J2000";
step = 12.*spd_c();
The program outputs:
Event time: 2007-JAN-10 16:26:18.805837 (TDB)
Event time: 2007-FEB-07 12:39:35.078525 (TDB)
Event time: 2007-MAR-07 03:38:07.334769 (TDB)
Event time: 2007-APR-03 08:38:55.222606 (TDB)
Event time: 2007-APR-30 10:56:49.847027 (TDB)
Event time: 2007-MAY-27 22:03:28.857783 (TDB)
Event time: 2007-JUN-24 14:26:23.639351 (TDB)
Event time: 2007-JUL-22 08:43:50.135565 (TDB)
Event time: 2007-AUG-19 03:28:33.538169 (TDB)
Event time: 2007-SEP-15 21:07:13.964698 (TDB)
Event time: 2007-OCT-13 09:52:30.819372 (TDB)
Event time: 2007-NOV-09 12:32:50.070555 (TDB)
Event time: 2007-DEC-06 16:54:31.225504 (TDB)
Example(5):
Find times between Jan 1, 2007 and Jan 1, 2008 when the latitude
(elevation) of the observer-target vector between DSS 17 and the
Moon, as observed in the DSS 17 topocentric (station) frame,
exceeds 83 degrees.
Edit the example program, assign:
This search uses a step size of four hours since the time
for all declination zero-to-max-to-zero passes within
the search window exceeds eight hours.
SpiceChar * relate = ">";
SpiceChar * crdsys = "LATITUDINAL";
SpiceChar * coord = "LATITUDE";
SpiceChar * targ = "MOON";
SpiceChar * obsrvr = "DSS-17";
SpiceChar * frame = "DSS-17_TOPO";
step = (4./24.)*spd_c();
refval = 83. * rpd_c();
The program outputs:
Interval 1
From : 2007-FEB-26 03:18:48.229806 (TDB)
To : 2007-FEB-26 03:31:29.734169 (TDB)
Interval 2
From : 2007-MAR-25 01:12:38.551183 (TDB)
To : 2007-MAR-25 01:23:53.908601 (TDB)
-Restrictions
1) The kernel files to be used by this routine must be loaded
(normally via the CSPICE routine furnsh_c) before this routine
is called.
2) This routine has the side effect of re-initializing the
coordinate quantity utility package. Callers may
need to re-initialize the 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, 26-AUG-2009 (EDW)
Correction of several typos.
-CSPICE Version 1.0.0, 10-FEB-2009 (NJB) (EDW)
-Index_Entries
GF position coordinate search
-&
*/
{ /* Begin gfposc_c */
/*
Local variables
*/
doublereal * work;
SpiceInt nBytes;
static SpiceInt nw = SPICE_GF_NWMAX;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfposc_c" );
/*
Make sure cell data types are d.p.
*/
CELLTYPECHK2 ( CHK_STANDARD, "gfposc_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, "gfposc_c", target );
CHKFSTR ( CHK_STANDARD, "gfposc_c", frame );
CHKFSTR ( CHK_STANDARD, "gfposc_c", abcorr );
CHKFSTR ( CHK_STANDARD, "gfposc_c", obsrvr );
CHKFSTR ( CHK_STANDARD, "gfposc_c", crdsys );
CHKFSTR ( CHK_STANDARD, "gfposc_c", coord );
CHKFSTR ( CHK_STANDARD, "gfposc_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 ( "gfposc_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 ( "gfposc_c" );
return;
}
/*
Let the f2'd routine do the work.
*/
gfposc_( ( char * ) target,
( char * ) frame,
( char * ) abcorr,
( char * ) obsrvr,
( char * ) crdsys,
( char * ) coord,
( 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(frame),
( ftnlen ) strlen(abcorr),
( ftnlen ) strlen(obsrvr),
( ftnlen ) strlen(crdsys),
( ftnlen ) strlen(coord),
( 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 ( "gfposc_c" );
} /* End gfposc_c */
void spkw18_c ( SpiceInt handle,
SpiceSPK18Subtype subtyp,
SpiceInt body,
SpiceInt center,
ConstSpiceChar * frame,
SpiceDouble first,
SpiceDouble last,
ConstSpiceChar * segid,
SpiceInt degree,
SpiceInt n,
const void * packts,
ConstSpiceDouble epochs[] )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of an SPK file open for writing.
subtyp I SPK type 18 subtype code.
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.
subtyp is an integer code indicating the subtype of the
the segment to be created.
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 nominal degree of the polynomials used to
interpolate the states contained in the input
packets. All components of the state vectors are
interpolated by polynomials of the specified
degree, except near the segment boundaries,
or if the total number of states in the segment
is too few to allow interpolation using the
specified degree.
n is the number of packets in the input packet
array.
packts contains a time-ordered array of data packets
representing geometric states of body relative
to center, specified relative to frame. The
packet structure depends on the segment subtype
as follows:
Type 0 (indicated by code S18TP0):
x, y, z, dx/dt, dy/dt, dz/dt,
vx, vy, vz, dvx/dt, dvy/dt, dvz/dt
where x, y, z represent Cartesian position
components and vx, vy, vz represent Cartesian
velocity components. Note well: vx, vy, and
vz *are not necessarily equal* to the time
derivatives of x, y, and z. This packet
structure mimics that of the Rosetta/MEX orbit
file from which the data are taken.
Type 1 (indicated by code S18TP1):
x, y, z, dx/dt, dy/dt, dz/dt
where x, y, z represent Cartesian position
components and vx, vy, vz represent Cartesian
velocity components.
Position units are kilometers, velocity units
are kilometers per second, and acceleration units
are kilometers per second per second.
epochs is an array of epochs corresponding to the members
of the packets 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.
-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 window size implied by DEGREE is odd, the error
SPICE(INVALIDDEGREE) is signaled.
6) If the number of packets n is not at least 1,
the error SPICE(TOOFEWSTATES) will be signaled.
7) If first is greater than or equal to last then the error
SPICE(BADDESCRTIMES) will be signaled.
8) If the elements of the array epochs are not in strictly
increasing order, the error SPICE(TIMESOUTOFORDER) will be
signaled.
9) If the first epoch epochs[0] is greater than first, the error
SPICE(BADDESCRTIMES) will be signaled.
10) If the last epoch epochs[n-1] is less than last, the error
SPICE(BADDESCRTIMES) will be signaled.
11) If either the input frame or segment ID string pointer is null,
the error SPICE(NULLPOINTER) is signaled.
12) If either the input frame or segment ID string is empty,
the error SPICE(EMPTYSTRING) is signaled.
-Files
A new type 18 SPK segment is written to the SPK file attached
to HANDLE.
-Particulars
This routine writes an SPK type 18 data segment to the open SPK
file according to the format described in the type 18 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 18 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_18_SEGMENT"
/.
Write the segment.
./
spkw18_c ( handle, subtyp, body, center,
frame, first, last, segid,
degree, n, states, epochs );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.1, 29-APR-2003 (NJB)
Description of error condition arising from invalid window
size was corrected.
-CSPICE Version 1.0.0, 16-AUG-2002 (NJB)
-Index_Entries
write spk type_18 ephemeris data segment
-&
*/
{ /* Begin spkw18_c */
/*
Local variables
*/
SpiceInt locSubtype;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "spkw18_c" );
/*
Check the input strings to make sure the pointers
are non-null and the string lengths are non-zero.
*/
CHKFSTR ( CHK_STANDARD, "spkw18_c", frame );
CHKFSTR ( CHK_STANDARD, "spkw18_c", segid );
locSubtype = (SpiceInt) subtyp;
/*
Write the segment.
*/
spkw18_ ( ( integer * ) &handle,
( integer * ) &locSubtype,
( integer * ) &body,
( integer * ) ¢er,
( char * ) frame,
( doublereal * ) &first,
( doublereal * ) &last,
( char * ) segid,
( integer * ) °ree,
( integer * ) &n,
( doublereal * ) packts,
( doublereal * ) epochs,
( ftnlen ) strlen(frame),
( ftnlen ) strlen(segid) );
chkout_c ( "spkw18_c" );
} /* End spkw18_c */
void pgrrec_c ( ConstSpiceChar * body,
SpiceDouble lon,
SpiceDouble lat,
SpiceDouble alt,
SpiceDouble re,
SpiceDouble f,
SpiceDouble rectan[3] )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
body I Body with which coordinate system is 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.
rectan O Rectangular coordinates of the point.
-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
rectan The rectangular coordinates of the input point. See
the discussion below in the Particulars header section
for details.
The units associated with `rectan' are those associated
with the inputs `alt' and `re'.
-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
Given the planetographic coordinates of a point, this routine
returns the body-fixed rectangular coordinates of the point. The
body-fixed rectangular frame is that having the X-axis pass
through the 0 degree latitude 0 degree longitude direction, the
Z-axis pass through the 90 degree latitude direction, and the
Y-axis equal to the cross product of the unit Z-axis and X-axis
vectors.
The planetographic definition of latitude is identical to the
planetodetic (also called "geodetic" in SPICE documentation)
definition. In the planetographic coordinate system, latitude is
defined using a reference spheroid. The spheroid is
characterized by an equatorial radius and a polar radius. For a
point P on the spheroid, latitude is defined as the angle between
the X-Y plane and the outward surface normal at P. For a point P
off the spheroid, latitude is defined as the latitude of the
nearest point to P on the spheroid. Note if P is an interior
point, for example, if P is at the center of the spheroid, there
may not be a unique nearest point to P.
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.
1) Find the rectangular coordinates of the point having Mars
planetographic coordinates:
longitude = 90 degrees west
latitude = 45 degrees north
altitude = 300 km
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local variables
./
SpiceDouble alt;
SpiceDouble f;
SpiceDouble lat;
SpiceDouble lon;
SpiceDouble radii [3];
SpiceDouble re;
SpiceDouble rectan [3];
SpiceDouble rp;
SpiceInt n;
/.
Load a PCK file containing a triaxial
ellipsoidal shape model and orientation
data for Mars.
./
furnsh_c ( "pck00008.tpc" );
/.
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;
/.
Do the conversion. Note that we must provide
longitude and latitude in radians.
./
lon = 90.0 * rpd_c();
lat = 45.0 * rpd_c();
alt = 3.e2;
pgrrec_c ( "mars", lon, lat, alt, re, f, rectan );
printf ( "\n"
"Planetographic coordinates:\n"
"\n"
" Longitude (deg) = %18.9e\n"
" Latitude (deg) = %18.9e\n"
" Altitude (km) = %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"
"Rectangular coordinates:\n"
"\n"
" X (km) = %18.9e\n"
" Y (km) = %18.9e\n"
" Z (km) = %18.9e\n"
"\n",
lon / rpd_c(),
lat / rpd_c(),
alt,
re,
rp,
f,
rectan[0],
rectan[1],
rectan[2] );
return ( 0 );
}
Output from this program should be similar to the following
(rounding and formatting differ across platforms):
Planetographic coordinates:
Longitude (deg) = 9.000000000e+01
Latitude (deg) = 4.500000000e+01
Altitude (km) = 3.000000000e+02
Ellipsoid shape parameters:
Equatorial radius (km) = 3.396190000e+03
Polar radius (km) = 3.376200000e+03
Flattening coefficient = 5.886007556e-03
Rectangular coordinates:
X (km) = 1.604650025e-13
Y (km) = -2.620678915e+03
Z (km) = 2.592408909e+03
2) Below is a table showing a variety of rectangular coordinates
and the corresponding Mars planetographic coordinates. The
values are computed using the reference spheroid having radii
Equatorial radius: 3397
Polar radius: 3375
Note: the values shown above may not be current or suitable
for your application.
Corresponding rectangular and planetographic coordinates are
listed to three decimal places.
rectan[0] rectan[1] rectan[2] lon lat alt
------------------------------------------------------------------
3397.000 0.000 0.000 0.000 0.000 0.000
-3397.000 0.000 0.000 180.000 0.000 0.000
-3407.000 0.000 0.000 180.000 0.000 10.000
-3387.000 0.000 0.000 180.000 0.000 -10.000
0.000 -3397.000 0.000 90.000 0.000 0.000
0.000 3397.000 0.000 270.000 0.000 0.000
0.000 0.000 3375.000 0.000 90.000 0.000
0.000 0.000 -3375.000 0.000 -90.000 0.000
0.000 0.000 0.000 0.000 90.000 -3375.000
3) Below we show the analogous relationships for the earth,
using the reference ellipsoid radii
Equatorial radius: 6378.140
Polar radius: 6356.750
Note the change in longitudes for points on the +/- Y axis
for the earth vs the Mars values.
rectan[0] rectan[1] rectan[2] lon lat alt
------------------------------------------------------------------
6378.140 0.000 0.000 0.000 0.000 0.000
-6378.140 0.000 0.000 180.000 0.000 0.000
-6388.140 0.000 0.000 180.000 0.000 10.000
-6368.140 0.000 0.000 180.000 0.000 -10.000
0.000 -6378.140 0.000 270.000 0.000 0.000
0.000 6378.140 0.000 90.000 0.000 0.000
0.000 0.000 6356.750 0.000 90.000 0.000
0.000 0.000 -6356.750 0.000 -90.000 0.000
0.000 0.000 0.000 0.000 90.000 -6356.750
-Restrictions
None.
-Author_and_Institution
C.H. Acton (JPL)
N.J. Bachman (JPL)
H.A. Neilan (JPL)
B.V. Semenov (JPL)
W.L. Taber (JPL)
-Literature_References
None.
-Version
-CSPICE Version 1.0.0, 26-DEC-2004 (CHA) (NJB) (HAN) (BVS) (WLT)
-Index_Entries
convert planetographic to rectangular coordinates
-&
*/
{ /* Begin pgrrec_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "pgrrec_c" );
/*
Check the input string body to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "pgrrec_c", body );
/*
Call the f2c'd Fortran routine.
*/
pgrrec_ ( ( char * ) body,
( doublereal * ) &lon,
( doublereal * ) &lat,
( doublereal * ) &alt,
( doublereal * ) &re,
( doublereal * ) &f,
( doublereal * ) rectan,
( ftnlen ) strlen(body) );
chkout_c ( "pgrrec_c" );
} /* End pgrrec_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 dasec_c ( SpiceInt handle,
SpiceInt bufsiz,
SpiceInt buflen,
SpiceInt * n,
void * buffer,
SpiceBoolean * done )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of binary DAS file open with read access.
bufsiz I Maximum size, in lines, of buffer.
buflen I Line length associated with buffer.
n O Number of comments extracted from the DAS file.
buffer O Buffer in which extracted comments are placed.
done O Indicates whether all comments have been extracted.
-Detailed_Input
handle The file handle of a binary DAS file which has been
opened with read access.
bufsiz The maximum number of comments that may be placed into
buffer. This would typically be the declared array size
for the C character string array passed into this
routine.
buflen is the common length of the strings in buffer, including the
terminating nulls.
-Detailed_Output
n The number of comment lines extracted from the comment area
of the binary DAS file attached to handle. This number will
be <= bufsiz on output. If n == bufsiz and done !=
SPICETRUE then there are more comments left to extract. If
n == 0, then done == SPICETRUE, i.e., there were no
comments in the comment area. If there are comments in the
comment area, or comments remaining after the extraction
process has begun, n > 0, always.
buffer A list of at most bufsiz comments which have been
extracted from the comment area of the binary DAS
file attached to handle. buffer should be declared as
follows:
ConstSpiceChar buffer [bufsiz][buflen]
Each string in buffer is null-terminated.
done A boolean flag indicating whether or not all of the
comment lines from the comment area of the DAS file have
been read. This variable has the value SPICETRUE after the
last comment line has been read. It will have the value
SPICEFALSE otherwise.
If there are no comments in the comment area, this
variable will have the value SPICETRUE, and n == 0.
-Parameters
None.
-Exceptions
1) If the size of the output line buffer is is not positive,
the error SPICE(INVALIDARGUMENT) will be signaled.
2) If a comment line in a DAS file is longer than the length
of a character string array element of BUFFER, the error
SPICE(COMMENTTOOLONG) will be signaled.
3) If there is a mismatch between the number of comment
characters found and the number of comment characters
expected, the error SPICE(BADDASCOMMENTAREA) will be
signaled.
4) If the binary DAS file attached to HANDLE is not open for
reading, an error will be signaled by a routine called by
this routine.
5) If the input buffer pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
6) If the input buffer string length buflen is not at least 2,
the error SPICE(STRINGTOOSHORT) will be signaled.
-Files
See argument handle in $ Detailed_Input.
-Particulars
Binary DAS files contain an area which is reserved for storing
annotations or descriptive textual information describing the data
contained in a file. This area is referred to as the "comment
area" of the file. The comment area of a DAS file is a line
oriented medium for storing textual information. The comment
area preserves any leading or embedded white space in the line(s)
of text which are stored, so that the appearance of the of
information will be unchanged when it is retrieved (extracted) at
some other time. Trailing blanks, however, are NOT preserved,
due to the way that character strings are represented in
standard Fortran 77.
This routine will read the comments from the comment area of
a binary DAS file, placing them into a line buffer. If the line
buffer is not large enough to hold the entire comment area,
the portion read will be returned to the caller, and the done
flag will be set to SPICEFALSE. This allows the comment area to be
read in "chunks," a buffer at a time. After all of the comment
lines have been read, the done flag will be set to SPICETRUE.
After all of the comments in DAS file have been read, the next
call to this routine will start reading comments at the start
of the comment area.
This routine can be used to "simultaneously" extract comments
from the comment areas of multiple binary DAS files.
-Examples
1) The following example will extract the entire comment area of a
binary DAS file attached to HANDLE, displaying the comments on
the terminal screen.
#include <stdio.h>
#include "SpiceUsr.h"
int main( int argc, char ** argv )
{
#define LNSIZE 81
#define MAXBUF 25
SpiceBoolean done;
SpiceChar buffer [MAXBUF][LNSIZE];
SpiceChar * filename;
SpiceInt handle;
SpiceInt i;
SpiceInt n;
filename = argv[1];
dasopr_ ( filename, &handle, (ftnlen)strlen(filename) );
done = SPICEFALSE;
while ( !done )
{
dasec_c( handle, MAXBUF, LNSIZE, &n, buffer, &done );
for ( i = 0; i < n; i++ )
{
printf ( "%s\n", buffer[i] );
}
}
return ( 0 );
}
-Restrictions
1) The comment area may consist only of printing ASCII characters,
decimal values 32 - 126.
2) There is NO maximum length imposed on the significant portion
of a text line that may be placed into the comment area of a
DAS file. The maximum length of a line stored in the comment
area should be kept reasonable, so that they may be easily
extracted. A good value for this would be 255 characters, as
this can easily accommodate "screen width" lines as well as
long lines which may contain some other form of information.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Version
-CSPICE Version 1.0.0, 24-FEB-2003 (NJB) (KRG)
-Index_Entries
extract comments from a das file
-&
*/
{ /* Begin dasec_c */
/*
Local variables
*/
logical locDone;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "dasec_c" );
/*
Make sure the output string has at least enough room for one output
character and a null terminator. Also check for a null pointer.
*/
CHKOSTR ( CHK_STANDARD, "dasec_c", buffer, buflen );
/*
Call the f2c'd routine.
*/
dasec_ ( (integer *) &handle,
(integer *) &bufsiz,
(integer *) n,
(char *) buffer,
(logical *) &locDone,
(ftnlen ) buflen-1 );
/*
Convert the output array from Fortran to C style.
*/
if ( *n > 0 );
{
F2C_ConvertTrStrArr ( *n, buflen, (SpiceChar *)buffer );
}
/*
Set the "done" flag.
*/
*done = (SpiceBoolean) locDone;
chkout_c ( "dasec_c" );
} /* End dasec_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 */
void bodvrd_c ( ConstSpiceChar * bodynm,
ConstSpiceChar * item,
SpiceInt maxn,
SpiceInt * dim,
SpiceDouble * values )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
bodynm I Body name.
item I Item for which values are desired. ("RADII",
"NUT_PREC_ANGLES", etc. )
maxn I Maximum number of values that may be returned.
dim O Number of values returned.
values O Values.
-Detailed_Input
bodynm is the name of the body for which `item' is requested.
`bodynm' is case-insensitive, and leading and trailing
blanks in `bodynm' are not significant. Optionally, you
may supply the integer ID code for the object as an
integer string. For example both "MOON" and "301" are
legitimate strings that indicate the moon is the body
of interest.
item is the item to be returned. Together, the NAIF ID
code of the body and the item name combine to form a
kernel variable name, e.g.,
"BODY599_RADII"
"BODY401_POLE_RA"
The values associated with the kernel variable having
the name constructed as shown are sought. Below
we'll take the shortcut of calling this kernel variable
the "requested kernel variable."
Note that `item' *is* case-sensitive. This attribute
is inherited from the case-sensitivity of kernel
variable names.
maxn is the maximum number of values that may be returned.
The output array `values' must be declared with size at
least `maxn'. It's an error to supply an output array
that is too small to hold all of the values associated
with the requested kernel variable.
-Detailed_Output
dim is the number of values returned; this is always the
number of values associated with the requested kernel
variable unless an error has been signaled.
values is the array of values associated with the requested
kernel variable. If `values' is too small to hold all
of the values associated with the kernel variable, the
returned values of `dim' and `values' are undefined.
-Parameters
None.
-Exceptions
1) If the input body name cannot be translated to an ID code,
and if the name is not a string representation of an integer
(for example, "399"), the error SPICE(NOTRANSLATION) is
signaled.
2) If the requested kernel variable is not found in the kernel
pool, the error SPICE(KERNELVARNOTFOUND) is signaled.
3) If the requested kernel variable is found but the associated
values aren't numeric, the error SPICE(TYPEMISMATCH) is
signaled.
4) The output array `values' must be declared with sufficient size
to contain all of the values associated with the requested kernel
variable. If the dimension of `values' indicated by `maxn' is
too small to contain the requested values, the error
SPICE(ARRAYTOOSMALL) is signaled.
5) If the input dimension `maxn' indicates there is more room
in `values' than there really is---for example, if `maxn' is
10 but `values' is declared with dimension 5---and the dimension
of the requested kernel variable is larger than the actual
dimension of `values', then this routine may overwrite
memory. The results are unpredictable.
6) If either of the input string pointers `bodynm' or `item'
are null, the error SPICE(NULLPOINTER) will be signaled.
7) If either of the input strings referred to by `bodynm' or `item'
contain no data characters, the error SPICE(EMPTYSTRING) will
be signaled.
-Files
None.
-Particulars
This routine simplifies looking up PCK kernel variables by
constructing names of requested kernel variables and by performing
error checking.
This routine is intended for use in cases where the maximum number
of values that may be returned is known at compile time. The caller
fetches all of the values associated with the specified kernel
variable via a single call to this routine. If the number of values
to be fetched cannot be known until run time, the lower-level
routine gdpool_c should be used instead. gdpool_c supports fetching
arbitrary amounts of data in multiple "chunks."
This routine is intended for use in cases where the requested kernel
variable is expected to be present in the kernel pool. If the
variable is not found or has the wrong data type, this routine
signals an error. In cases where it is appropriate to indicate
absence of an expected kernel variable by returning a boolean "found
flag" with the value SPICEFALSE, again the routine gdpool_c should
be used.
-Examples
1) When the kernel variable
BODY399_RADII
is present in the kernel pool---normally because a PCK
defining this variable has been loaded---the call
bodvrd_c ( "EARTH", "RADII", 3, &dim, values );
returns the dimension and values associated with the variable
"BODY399_RADII", for example,
dim == 3
value[0] == 6378.140
value[1] == 6378.140
value[2] == 6356.755
2) The call
bodvrd_c ( "earth", "RADII", 3, &dim, values );
will produce the same results shown in example (1),
since the case of the input argument `bodynm' is
not significant.
3) The call
bodvrd_c ( "399", "RADII", 3, &dim, values );
will produce the same results shown in example (1),
since strings containing integer codes are accepted
by this routine.
4) The call
bodvrd_c ( "EARTH", "radii", 3, &dim, values );
usually will cause a SPICE(KERNELVARNOTFOUND) error to be
signaled, because this call will attempt to look up the
values associated with a kernel variable of the name
"BODY399_radii"
Since kernel variable names are case sensitive, this
name is not considered to match the name
"BODY399_RADII"
which normally would be present after a text PCK
containing data for all planets and satellites has
been loaded.
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
B.V. Semenov (JPL)
W.L. Taber (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.1, 12-APR-2006 (NJB)
Header fix: output argument `dim' is now preceded by
an ampersand in example calls to bodvrd_c.c.
-CSPICE Version 1.0.0, 22-FEB-2004 (NJB)
-Index_Entries
fetch constants for a body from the kernel pool
physical constants for a body
-&
*/
{ /* Begin bodvrd_c */
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "bodvrd_c" );
/*
Check the input strings.
*/
CHKFSTR ( CHK_STANDARD, "bodvrd_c", bodynm );
CHKFSTR ( CHK_STANDARD, "bodvrd_c", item );
/*
Call the f2c'd SPICELIB function.
*/
bodvrd_ ( (char *) bodynm,
(char *) item,
(integer *) &maxn,
(integer *) dim,
(doublereal *) values,
(ftnlen ) strlen(bodynm),
(ftnlen ) strlen(item) );
chkout_c ( "bodvrd_c" );
} /* End bodvrd_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 gfoclt_c ( ConstSpiceChar * occtyp,
ConstSpiceChar * front,
ConstSpiceChar * fshape,
ConstSpiceChar * fframe,
ConstSpiceChar * back,
ConstSpiceChar * bshape,
ConstSpiceChar * bframe,
ConstSpiceChar * abcorr,
ConstSpiceChar * obsrvr,
SpiceDouble step,
SpiceCell * cnfine,
SpiceCell * result )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
--------------- --- -------------------------------------------------
SPICE_GF_CNVTOL P Convergence tolerance.
occtyp I Type of occultation.
front I Name of body occulting the other.
fshape I Type of shape model used for front body.
fframe I Body-fixed, body-centered frame for front body.
back I Name of body occulted by the other.
bshape I Type of shape model used for back body.
bframe I Body-fixed, body-centered frame for back body.
abcorr I Aberration correction flag.
obsrvr I Name of the observing body.
step I Step size in seconds for finding occultation
events.
cnfine I-O SPICE window to which the search is restricted.
result O SPICE window containing results.
-Detailed_Input
occtyp indicates the type of occultation that is to be found.
Note that transits are considered to be a type of
occultation.
Supported values and corresponding definitions are:
"FULL" denotes the full occultation
of the body designated by
`back' by the body designated
by `front', as seen from
the location of the observer.
In other words, the occulted
body is completely invisible
as seen from the observer's
location.
"ANNULAR" denotes an annular
occultation: the body
designated by `front' blocks
part of, but not the limb of,
the body designated by `back',
as seen from the location of
the observer.
"PARTIAL" denotes a partial, non-annular
occultation: the body designated
by `front' blocks part, but not
all, of the limb of the body
designated by `back', as seen
from the location of the
observer.
"ANY" denotes any of the above three
types of occultations:
"PARTIAL", "ANNULAR", or
"FULL".
"ANY" should be used to search
for times when the body
designated by `front' blocks
any part of the body designated
by `back'.
The option "ANY" must be used
if either the front or back
target body is modeled as
a point.
Case and leading or trailing blanks are not
significant in the string `occtyp'.
front is the name of the target body that occults---that is,
passes in front of---the other. Optionally, you may
supply the integer NAIF ID code for the body as a
string. For example both "MOON" and "301" are
legitimate strings that designate the Moon.
Case and leading or trailing blanks are not
significant in the string `front'.
fshape is a string indicating the geometric model used to
represent the shape of the front target body. The
supported options are:
"ELLIPSOID" Use a triaxial ellipsoid model
with radius values provided via the
kernel pool. A kernel variable
having a name of the form
"BODYnnn_RADII"
where nnn represents the NAIF
integer code associated with the
body, must be present in the kernel
pool. This variable must be
associated with three numeric
values giving the lengths of the
ellipsoid's X, Y, and Z semi-axes.
"POINT" Treat the body as a single point.
When a point target is specified,
the occultation type must be
set to "ANY".
At least one of the target bodies `front' and `back' must
be modeled as an ellipsoid.
Case and leading or trailing blanks are not
significant in the string `fshape'.
fframe is the name of the body-fixed, body-centered reference
frame associated with the front target body. Examples
of such names are "IAU_SATURN" (for Saturn) and
"ITRF93" (for the Earth).
If the front target body is modeled as a point, `fframe'
should be left empty or blank.
Case and leading or trailing blanks bracketing a
non-blank frame name are not significant in the string
`fframe'.
back is the name of the target body that is occulted
by---that is, passes in back of---the other.
Optionally, you may supply the integer NAIF ID code
for the body as a string. For example both "MOON" and
"301" are legitimate strings that designate the Moon.
Case and leading or trailing blanks are not
significant in the string `back'.
bshape is the shape specification for the body designated by
`back'. The supported options are those for `fshape'. See
the description of `fshape' above for details.
bframe is the name of the body-fixed, body-centered reference
frame associated with the ``back'' target body.
Examples of such names are "IAU_SATURN" (for Saturn)
and "ITRF93" (for the Earth).
If the back target body is modeled as a point, `bframe'
should be left empty or blank.
Case and leading or trailing blanks bracketing a
non-blank frame name are not significant in the string
`bframe'.
abcorr indicates the aberration corrections to be applied to
the state of each target body to account for one-way
light time. Stellar aberration corrections are
ignored if specified, since these corrections don't
improve the accuracy of the occultation determination.
See the header of the SPICE routine spkezr_c for a
detailed description of the aberration correction
options. For convenience, the options supported by
this routine are listed below:
"NONE" Apply no correction.
"LT" "Reception" case: correct for
one-way light time using a Newtonian
formulation.
"CN" "Reception" case: converged
Newtonian light time correction.
"XLT" "Transmission" case: correct for
one-way light time using a Newtonian
formulation.
"XCN" "Transmission" case: converged
Newtonian light time correction.
Case and blanks are not significant in the string
`abcorr'.
obsrvr is the name of the body from which the occultation is
observed. Optionally, you may supply the integer NAIF
ID code for the body as a string.
Case and leading or trailing blanks are not
significant in the string `obsrvr'.
step is the step size to be used in the search. `step' must
be shorter than any interval, within the confinement
window, over which the specified condition is met. In
other words, `step' must be shorter than the shortest
occultation event that the user wishes to detect; `step'
must also be shorter than the shortest time interval
between two occultation events that occur within the
confinement window (see below). 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.
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.
The endpoints of the time intervals comprising `cnfine'
are interpreted as seconds past J2000 TDB.
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 occultation occurs.
The endpoints of the time intervals comprising `result'
are interpreted as seconds past J2000 TDB.
If `result' is non-empty on input, its contents
will be discarded before gfoclt_c conducts its
search.
-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, the error
SPICE(INVALIDSTEPSIZE) will be signaled.
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 name of either target or the observer cannot be translated
to a NAIF ID code, the error will be diagnosed by a routine
in the call tree of this routine.
4) If the radii of a target body modeled as an ellipsoid cannot
be determined by searching the kernel pool for a kernel
variable having a name of the form
"BODYnnn_RADII"
where nnn represents the NAIF integer code associated with
the body, the error will be diagnosed by a routine in the
call tree of this routine.
5) If either of the target bodies `front' or `back' coincides with
the observer body `obsrvr', the error will be diagnosed by a
routine in the call tree of this routine.
6) If the body designated by `front' coincides with that
designated by `back', the error will be diagnosed by a routine
in the call tree of this routine.
7) If either of the body model specifiers `fshape' or `bshape'
is not recognized, the error will be diagnosed by a routine
in the call tree of this routine.
8) If both of the body model specifiers `fshape' and `bshape'
specify point targets, the error will be diagnosed by a
routine in the call tree of this routine.
9) If a target body-fixed reference frame associated with a
non-point target is not recognized, the error will be
diagnosed by a routine in the call tree of this routine.
10) If a target body-fixed reference frame is not centered at
the corresponding target body, the error will be
diagnosed by a routine in the call tree of this routine.
11) If the loaded kernels provide insufficient data to
compute any required state vector, the deficiency will
be diagnosed by a routine in the call tree of this routine.
12) If an error occurs while reading an SPK or other kernel file,
the error will be diagnosed by a routine in the call tree
of this routine.
13) If the output SPICE window `result' has insufficient capacity
to contain the number of intervals on which the specified
occultation condition is met, the error will be diagnosed
by a routine in the call tree of this routine.
14) If a point target is specified and the occultation
type is set to a valid value other than "ANY", the
error will be diagnosed by a routine in the call tree
of this routine.
15) Invalid occultation types will be diagnosed by a routine in
the call tree of this routine.
16) Invalid aberration correction specifications will be
diagnosed by a routine in the call tree of this routine.
17) If any input string argument pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
18) If any input string argument, other than `fframe' or `bframe',
is empty, the error SPICE(EMPTYSTRING) will be signaled.
-Files
Appropriate SPICE kernels must be loaded by the calling program
before this routine is called.
The following data are required:
- SPK data: the calling application must load ephemeris data
for the target, source and observer that cover the time
period specified by the window `cnfine'. 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.
- PCK data: bodies modeled as triaxial ellipsoids must have
semi-axis lengths provided by variables in the kernel pool.
Typically these data are made available by loading a text
PCK file via furnsh_c.
- FK data: if either of the reference frames designated by
`bframe' or `fframe' are not built in to the SPICE system,
one or more FKs specifying these frames must be loaded.
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 CSPICE routine gfocce_c for conducting searches for
occultation events. Applications that require support for
progress reporting, interrupt handling, non-default step or
refinement functions, or non-default convergence tolerance should
call gfocce_c rather than this routine.
This routine determines a set of one or more time intervals
within the confinement window when a specified type of
occultation occurs. The resulting set of intervals is returned as
a SPICE window.
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
==================
The search for occultations is treated as a search for state
transitions: times are sought when the state of the `back' body
changes from "not occulted" to "occulted" or vice versa.
Step Size
=========
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 occultation state will be sampled. Starting at the left
endpoint of the interval, samples of the occultation state will be
taken at each step. If a state change is detected, a root has been
bracketed; at that point, the "root"--the time at which the state
change occurs---is 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 occultation state is constant:
the step size should be shorter than the shortest occultation
duration and the shortest period between occultations, within
the confinement window.
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 limit the accuracy of solutions found by this
routine. In general the accuracy of input data will be the limiting
factor.
To use a different tolerance value, a lower-level GF routine such as
gfocce_c must be called. 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 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.
The confinement window also can be used to restrict a search to
a time window over which required data (typically ephemeris
data, in the case of occultation searches) are known to be
available.
In some cases, the confinement window 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. See the "CASCADE"
example program in gf.req for a demonstration.
-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.
1) Find occultations of the Sun by the Moon (that is, solar
eclipses) as seen from the center of the Earth over the month
December, 2001.
Use light time corrections to model apparent positions of Sun
and Moon. Stellar aberration corrections are not specified
because they don't affect occultation computations.
We select a step size of 3 minutes, which means we
ignore occultation events lasting less than 3 minutes,
if any exist.
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 = ( 'de421.bsp',
'pck00008.tpc',
'naif0009.tls' )
\begintext
Example code begins here.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local constants
./
#define TIMFMT "YYYY MON DD HR:MN:SC.###### (TDB)::TDB"
#define MAXWIN 200
#define TIMLEN 41
/.
Local variables
./
SPICEDOUBLE_CELL ( cnfine, MAXWIN );
SPICEDOUBLE_CELL ( result, MAXWIN );
SpiceChar * win0;
SpiceChar * win1;
SpiceChar begstr [ TIMLEN ];
SpiceChar endstr [ TIMLEN ];
SpiceDouble et0;
SpiceDouble et1;
SpiceDouble left;
SpiceDouble right;
SpiceDouble step;
SpiceInt i;
/.
Load kernels.
./
furnsh_c ( "standard.tm" );
/.
Obtain the TDB time bounds of the confinement
window, which is a single interval in this case.
./
win0 = "2001 DEC 01 00:00:00 TDB";
win1 = "2002 JAN 01 00:00:00 TDB";
str2et_c ( win0, &et0 );
str2et_c ( win1, &et1 );
/.
Insert the time bounds into the confinement
window.
./
wninsd_c ( et0, et1, &cnfine );
/.
Select a 3-minute step. We'll ignore any occultations
lasting less than 3 minutes. Units are TDB seconds.
./
step = 180.0;
/.
Perform the search.
./
gfoclt_c ( "any",
"moon", "ellipsoid", "iau_moon",
"sun", "ellipsoid", "iau_sun",
"lt", "earth", step,
&cnfine, &result );
if ( wncard_c(&result) == 0 )
{
printf ( "No occultation was found.\n" );
}
else
{
for ( i = 0; i < wncard_c(&result); i++ )
{
/.
Fetch and display each occultation interval.
./
wnfetd_c ( &result, i, &left, &right );
timout_c ( left, TIMFMT, TIMLEN, begstr );
timout_c ( right, TIMFMT, TIMLEN, endstr );
printf ( "Interval %ld\n"
" Start time: %s\n"
" Stop time: %s\n",
i, begstr, endstr );
}
}
return ( 0 );
}
When this program was executed on a PC/Linux/gcc platform, the
output was:
Interval 0
Start time: 2001 DEC 14 20:10:14.195952 (TDB)
Stop time: 2001 DEC 14 21:35:50.317994 (TDB)
2) Find occultations of Titan by Saturn or of Saturn by
Titan as seen from the center of the Earth over the
last four months of 2008. Model both target bodies as
ellipsoids. Search for every type of occultation.
Use light time corrections to model apparent positions of
Saturn and Titan. Stellar aberration corrections are not
specified because they don't affect occultation computations.
We select a step size of 15 minutes, which means we
ignore occultation events lasting less than 15 minutes,
if any exist.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: gfoclt_ex2.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
sat288.bsp Satellite ephemeris for
Saturn
pck00008.tpc Planet orientation and
radii
naif0009.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'sat288.bsp',
'pck00008.tpc',
'naif0009.tls' )
\begintext
End of meta-kernel
Example code begins here.
#include <stdio.h>
#include <string.h>
#include "SpiceUsr.h"
int main()
{
/.
Local constants
./
#define TIMFMT "YYYY MON DD HR:MN:SC.###### (TDB)::TDB"
#define MAXWIN 200
#define TIMLEN 41
#define LNSIZE 81
#define NTYPES 4
/.
Local variables
./
SPICEDOUBLE_CELL ( cnfine, MAXWIN );
SPICEDOUBLE_CELL ( result, MAXWIN );
SpiceChar * back;
SpiceChar * bframe;
SpiceChar * front;
SpiceChar * fframe;
SpiceChar line [ LNSIZE ];
SpiceChar * obsrvr;
SpiceChar * occtyp [ NTYPES ] =
{
"FULL",
"ANNULAR",
"PARTIAL",
"ANY"
};
SpiceChar * templt [ NTYPES ] =
{
"Condition: # occultation of # by #",
"Condition: # occultation of # by #",
"Condition: # occultation of # by #",
"Condition: # occultation of # by #"
};
SpiceChar timstr [ TIMLEN ];
SpiceChar title [ LNSIZE ];
SpiceChar * win0;
SpiceChar * win1;
SpiceDouble et0;
SpiceDouble et1;
SpiceDouble finish;
SpiceDouble start;
SpiceDouble step;
SpiceInt i;
SpiceInt j;
SpiceInt k;
/.
Load kernels.
./
furnsh_c ( "gfoclt_ex2.tm" );
/.
Obtain the TDB time bounds of the confinement
window, which is a single interval in this case.
./
win0 = "2008 SEP 01 00:00:00 TDB";
win1 = "2009 JAN 01 00:00:00 TDB";
str2et_c ( win0, &et0 );
str2et_c ( win1, &et1 );
/.
Insert the time bounds into the confinement
window.
./
wninsd_c ( et0, et1, &cnfine );
/.
Select a 15-minute step. We'll ignore any occultations
lasting less than 15 minutes. Units are TDB seconds.
./
step = 900.0;
/.
The observation location is the Earth.
./
obsrvr = "Earth";
/.
Loop over the occultation types.
./
for ( i = 0; i < NTYPES; i++ )
{
/.
For each type, do a search for both transits of
Titan across Saturn and occultations of Titan by
Saturn.
./
for ( j = 0; j < 2; j++ )
{
if ( j == 0 )
{
front = "TITAN";
fframe = "IAU_TITAN";
back = "SATURN";
bframe = "IAU_SATURN";
}
else
{
front = "SATURN";
fframe = "IAU_SATURN";
back = "TITAN";
bframe = "IAU_TITAN";
}
/.
Perform the search. The target body shapes
are modeled as ellipsoids.
./
gfoclt_c ( occtyp[i],
front, "ellipsoid", fframe,
back, "ellipsoid", bframe,
"lt", obsrvr, step,
&cnfine, &result );
/.
Display the results.
./
printf ( "\n" );
/.
Substitute the occultation type and target
body names into the title string:
./
repmc_c ( templt[i], "#", occtyp[i], LNSIZE, title );
repmc_c ( title, "#", back, LNSIZE, title );
repmc_c ( title, "#", front, LNSIZE, title );
printf ( "%s\n", title );
if ( wncard_c(&result) == 0 )
{
printf ( " Result window is empty: "
"no occultation was found.\n" );
}
else
{
printf ( " Result window start, stop times:\n" );
for ( k = 0; k < wncard_c(&result); k++ )
{
/.
Fetch the endpoints of the kth interval
of the result window.
./
wnfetd_c ( &result, k, &start, &finish );
/.
Call strncpy with a length of 7 to include
a terminating null.
./
strncpy ( line, " # #", 7 );
timout_c ( start, TIMFMT, TIMLEN, timstr );
repmc_c ( line, "#", timstr, LNSIZE, line );
timout_c ( finish, TIMFMT, TIMLEN, timstr );
repmc_c ( line, "#", timstr, LNSIZE, line );
printf ( "%s\n", line );
}
}
/.
We've finished displaying the results of the
current search.
./
}
/.
We've finished displaying the results of the
searches using the current occultation type.
./
}
printf ( "\n" );
return ( 0 );
}
When this program was executed on a PC/Linux/gcc platform, the
output was:
Condition: FULL occultation of SATURN by TITAN
Result window is empty: no occultation was found.
Condition: FULL occultation of TITAN by SATURN
Result window start, stop times:
2008 OCT 27 22:08:01.627053 (TDB) 2008 OCT 28 01:05:03.375236 (TDB)
2008 NOV 12 21:21:59.252262 (TDB) 2008 NOV 13 02:06:05.053051 (TDB)
2008 NOV 28 20:49:02.402832 (TDB) 2008 NOV 29 02:13:58.986344 (TDB)
2008 DEC 14 20:05:09.246177 (TDB) 2008 DEC 15 01:44:53.523002 (TDB)
2008 DEC 30 19:00:56.577073 (TDB) 2008 DEC 31 00:42:43.222909 (TDB)
Condition: ANNULAR occultation of SATURN by TITAN
Result window start, stop times:
2008 OCT 19 21:29:20.599087 (TDB) 2008 OCT 19 22:53:34.518737 (TDB)
2008 NOV 04 20:15:38.620368 (TDB) 2008 NOV 05 00:18:59.139978 (TDB)
2008 NOV 20 19:38:59.647712 (TDB) 2008 NOV 21 00:35:26.725908 (TDB)
2008 DEC 06 18:58:34.073268 (TDB) 2008 DEC 07 00:16:17.647040 (TDB)
2008 DEC 22 18:02:46.288289 (TDB) 2008 DEC 22 23:26:52.712459 (TDB)
Condition: ANNULAR occultation of TITAN by SATURN
Result window is empty: no occultation was found.
Condition: PARTIAL occultation of SATURN by TITAN
Result window start, stop times:
2008 OCT 19 20:44:30.326771 (TDB) 2008 OCT 19 21:29:20.599087 (TDB)
2008 OCT 19 22:53:34.518737 (TDB) 2008 OCT 19 23:38:26.250580 (TDB)
2008 NOV 04 19:54:40.339331 (TDB) 2008 NOV 04 20:15:38.620368 (TDB)
2008 NOV 05 00:18:59.139978 (TDB) 2008 NOV 05 00:39:58.612935 (TDB)
2008 NOV 20 19:21:46.689523 (TDB) 2008 NOV 20 19:38:59.647712 (TDB)
2008 NOV 21 00:35:26.725908 (TDB) 2008 NOV 21 00:52:40.604703 (TDB)
2008 DEC 06 18:42:36.100544 (TDB) 2008 DEC 06 18:58:34.073268 (TDB)
2008 DEC 07 00:16:17.647040 (TDB) 2008 DEC 07 00:32:16.324244 (TDB)
2008 DEC 22 17:47:10.776722 (TDB) 2008 DEC 22 18:02:46.288289 (TDB)
2008 DEC 22 23:26:52.712459 (TDB) 2008 DEC 22 23:42:28.850542 (TDB)
Condition: PARTIAL occultation of TITAN by SATURN
Result window start, stop times:
2008 OCT 27 21:37:16.970175 (TDB) 2008 OCT 27 22:08:01.627053 (TDB)
2008 OCT 28 01:05:03.375236 (TDB) 2008 OCT 28 01:35:49.266506 (TDB)
2008 NOV 12 21:01:47.105498 (TDB) 2008 NOV 12 21:21:59.252262 (TDB)
2008 NOV 13 02:06:05.053051 (TDB) 2008 NOV 13 02:26:18.227357 (TDB)
2008 NOV 28 20:31:28.522707 (TDB) 2008 NOV 28 20:49:02.402832 (TDB)
2008 NOV 29 02:13:58.986344 (TDB) 2008 NOV 29 02:31:33.691598 (TDB)
2008 DEC 14 19:48:27.094229 (TDB) 2008 DEC 14 20:05:09.246177 (TDB)
2008 DEC 15 01:44:53.523002 (TDB) 2008 DEC 15 02:01:36.360243 (TDB)
2008 DEC 30 18:44:23.485898 (TDB) 2008 DEC 30 19:00:56.577073 (TDB)
2008 DEC 31 00:42:43.222909 (TDB) 2008 DEC 31 00:59:17.030568 (TDB)
Condition: ANY occultation of SATURN by TITAN
Result window start, stop times:
2008 OCT 19 20:44:30.326771 (TDB) 2008 OCT 19 23:38:26.250580 (TDB)
2008 NOV 04 19:54:40.339331 (TDB) 2008 NOV 05 00:39:58.612935 (TDB)
2008 NOV 20 19:21:46.689523 (TDB) 2008 NOV 21 00:52:40.604703 (TDB)
2008 DEC 06 18:42:36.100544 (TDB) 2008 DEC 07 00:32:16.324244 (TDB)
2008 DEC 22 17:47:10.776722 (TDB) 2008 DEC 22 23:42:28.850542 (TDB)
Condition: ANY occultation of TITAN by SATURN
Result window start, stop times:
2008 OCT 27 21:37:16.970175 (TDB) 2008 OCT 28 01:35:49.266506 (TDB)
2008 NOV 12 21:01:47.105498 (TDB) 2008 NOV 13 02:26:18.227357 (TDB)
2008 NOV 28 20:31:28.522707 (TDB) 2008 NOV 29 02:31:33.691598 (TDB)
2008 DEC 14 19:48:27.094229 (TDB) 2008 DEC 15 02:01:36.360243 (TDB)
2008 DEC 30 18:44:23.485898 (TDB) 2008 DEC 31 00:59:17.030568 (TDB)
-Restrictions
The kernel files to be used by gfoclt_c must be loaded (normally via
the CSPICE routine furnsh_c) before gfoclt_c is called.
-Literature_References
None.
-Author_and_Institution
N. J. Bachman (JPL)
L. S. Elson (JPL)
E. D. Wright (JPL)
-Version
-CSPICE Version 1.0.0, 07-APR-2009 (NJB) (LSE) (EDW)
-Index_Entries
GF occultation search
-&
*/
{ /* Begin gfoclt_c */
/*
Local variables
*/
static const SpiceChar * blankStr = " ";
SpiceChar * bFrameStr;
SpiceChar * fFrameStr;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "gfoclt_c" );
/*
Make sure cell data types are d.p.
*/
CELLTYPECHK2 ( CHK_STANDARD, "gfoclt_c", SPICE_DP, cnfine, result );
/*
Initialize the input cells if necessary.
*/
CELLINIT2 ( cnfine, result );
/*
The input frame names are special cases because we allow the caller
to pass in empty strings. If either of these strings are empty,
we pass a null-terminated string containing one blank character to
the underlying f2c'd routine.
First make sure the frame name pointers are non-null.
*/
CHKPTR ( CHK_STANDARD, "gfoclt_c", bframe );
CHKPTR ( CHK_STANDARD, "gfoclt_c", fframe );
/*
Use the input frame strings if they're non-empty; otherwise
use blank strings for the frame names.
*/
if ( bframe[0] )
{
bFrameStr = (SpiceChar *) bframe;
}
else
{
bFrameStr = (SpiceChar *) blankStr;
}
if ( fframe[0] )
{
fFrameStr = (SpiceChar *) fframe;
}
else
{
fFrameStr = (SpiceChar *) blankStr;
}
/*
Check the other input strings to make sure each pointer is non-null
and each string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "gfoclt_c", occtyp );
CHKFSTR ( CHK_STANDARD, "gfoclt_c", front );
CHKFSTR ( CHK_STANDARD, "gfoclt_c", fshape );
CHKFSTR ( CHK_STANDARD, "gfoclt_c", back );
CHKFSTR ( CHK_STANDARD, "gfoclt_c", bshape );
CHKFSTR ( CHK_STANDARD, "gfoclt_c", abcorr );
CHKFSTR ( CHK_STANDARD, "gfoclt_c", obsrvr );
/*
Let the f2c'd routine do the work.
*/
gfoclt_ ( (char *) occtyp,
(char *) front,
(char *) fshape,
(char *) fFrameStr,
(char *) back,
(char *) bshape,
(char *) bFrameStr,
(char *) abcorr,
(char *) obsrvr,
(doublereal *) &step,
(doublereal *) cnfine->base,
(doublereal *) result->base,
(ftnlen ) strlen(occtyp),
(ftnlen ) strlen(front),
(ftnlen ) strlen(fshape),
(ftnlen ) strlen(fframe),
(ftnlen ) strlen(back),
(ftnlen ) strlen(bshape),
(ftnlen ) strlen(bframe),
(ftnlen ) strlen(abcorr),
(ftnlen ) strlen(obsrvr) );
/*
Sync the output result cell.
*/
if ( !failed_c() )
{
zzsynccl_c ( F2C, result );
}
chkout_c ( "gfoclt_c" );
} /* End gfoclt_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 */
SpiceDouble lspcn_c ( ConstSpiceChar * body,
SpiceDouble et,
ConstSpiceChar * abcorr )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
body I Name of central body.
et I Epoch in seconds past J2000 TDB.
abcorr I Aberration correction.
The function returns the value of L_s for the specified body
at the specified time.
-Detailed_Input
body is the name of the central body, typically a planet.
et is the epoch at which the longitude of the sun (L_s) is
to be computed. `et' is expressed as seconds past J2000
TDB (Barycentric Dynamical Time).
abcorr indicates the aberration corrections to be applied
when computing the longitude of the sun. `abcorr'
may be any of the following.
"NONE" Apply no correction.
"LT" Correct the position of the sun,
relative to the central body, for
planetary (light time) aberration.
"LT+S" Correct the position of the sun,
relative to the central body, for
planetary and stellar aberrations.
-Detailed_Output
The function returns the planetocentric longitude of the sun,
often called "L_s," for the specified body at the specified time.
This is the longitude of the body-sun vector in a right-handed
frame whose basis vectors are defined as follows:
- The positive Z direction is given by the instantaneous
angular velocity vector of the orbit of the body about
the sun.
- The positive X direction is that of the cross product of the
instantaneous north spin axis of the body with the
positive Z direction.
- The positive Y direction is Z x X.
Units are radians; the range is 0 to 2*pi. Longitudes are
positive to the east.
-Parameters
None.
-Exceptions
1) If the input body name cannot be translated to an ID code,
and if the name is not a string representation of an integer
(for example, "399"), the error SPICE(NOTRANSLATION) is
signaled.
2) If no SPK (ephemeris) file has been loaded prior to calling
this routine, or if the SPK data has insufficient coverage, an
error will be diagnosed and signaled by a routine in the call
tree of this routine.
3) If a PCK file containing rotational elements for the central
body has not been loaded prior to calling this routine, an
error will be diagnosed and signaled by a routine called by a
routine in the call tree of this routine.
4) If the instantaneous angular velocity and spin axis of `body'
are parallel, the error will be diagnosed and signaled by a
routine in the call tree of this routine.
5) 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.
6) The error SPICE(NULLPOINTER) is signaled if the input string
pointer `body' is null.
-Files
1) An SPK file (or file) containing ephemeris data sufficient to
compute the geometric state of the central body relative to
the sun at `et' must be loaded before this routine is called. If
light time correction is used, data must be available that
enable computation of the state the sun relative to the solar
system barycenter at the light-time corrected epoch. If
stellar aberration correction is used, data must be available
that enable computation of the state the central body relative
to the solar system barycenter at `et'.
2) A PCK file containing rotational elements for the central body
must be loaded before this routine is called.
-Particulars
The direction of the vernal equinox for the central body is
determined from the instantaneous equatorial and orbital planes
of the central body. This equinox definition is specified in
reference [1]. The "instantaneous orbital plane" is interpreted
in this routine as the plane normal to the cross product of the
position and velocity of the central body relative to the sun.
The geometric state of the central body relative to the sun is
used for this normal vector computation. The "instantaneous
equatorial plane" is normal to the central body's north pole
at the requested epoch. The pole direction is determined from
rotational elements loaded via a PCK file.
The result returned by this routine will depend on the
ephemeris data and rotational elements used. The result may
differ from that given in any particular version of the
Astronomical Almanac, due to differences in these input data,
and due to differences in precision of the computations.
-Examples
1) A simple program that computes L_s for a body and time
supplied interactively. The geometric state of the sun is
used.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
#define ABCORR "NONE"
#define FILSIZ 256
#define NAMLEN 37
#define TIMLEN 41
#define ABCORR "NONE"
SpiceChar body [ NAMLEN ];
SpiceChar lsk [ FILSIZ ];
SpiceChar pck [ FILSIZ ];
SpiceChar spk [ FILSIZ ];
SpiceChar timstr [ TIMLEN ];
SpiceDouble et;
SpiceDouble lon;
prompt_c ( "Enter name of leapseconds kernel > ", FILSIZ, lsk );
prompt_c ( "Enter name of PCK file > ", FILSIZ, pck );
prompt_c ( "Enter name of SPK file > ", FILSIZ, spk );
furnsh_c ( spk );
furnsh_c ( lsk );
furnsh_c ( pck );
printf ( "\n"
"Kernels have been loaded.\n"
"\n" );
while ( SPICETRUE )
{
prompt_c ( "Enter name of central body > ",
NAMLEN,
body );
prompt_c ( "Enter calendar, JD, or DOY time > ",
TIMLEN,
timstr );
str2et_c ( timstr, &et );
/.
Convert longitude to degrees.
./
lon = dpr_c() * lspcn_c ( body, et, ABCORR );
printf ( "\n"
"Central body = %s\n"
"Time = %s\n"
"Planetocentric L_s (deg.) = %f\n"
"\n",
body,
timstr,
lon );
}
return ( 0 );
}
-Restrictions
None.
-Literature_References
[1] "The Astronomical Almanac for the Year 2005." U.S. Government
Printing Office, Washington, D.C., 1984, page L9.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.0, 06-JAN-2005 (NJB)
-Index_Entries
planetocentric longitude of sun
compute L_s
compute Ls
compute L_sub_s
-&
*/
{ /* Begin lspcn_c */
/*
Local variables
*/
SpiceDouble retval;
/*
Give the function an initial value:
*/
retval = 0.0;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return ( retval );
}
chkin_c ( "lspcn_c" );
/*
Check the input string body to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR_VAL ( CHK_STANDARD, "lspcn_c", body, retval );
/*
Call the f2c'd Fortran routine.
*/
retval = lspcn_ ( ( char * ) body,
( doublereal * ) &et,
( char * ) abcorr,
( ftnlen ) strlen(body),
( ftnlen ) strlen(abcorr) );
chkout_c ( "lspcn_c" );
return ( retval );
} /* End lspcn_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 fovray_c ( ConstSpiceChar * inst,
ConstSpiceDouble raydir [3],
ConstSpiceChar * rframe,
ConstSpiceChar * abcorr,
ConstSpiceChar * observer,
SpiceDouble * et,
SpiceBoolean * visible )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
--------------- --- ------------------------------------------------
inst I Name or ID code string of the instrument.
raydir I Ray's direction vector.
rframe I Body-fixed, body-centered frame for target body.
abcorr I Aberration correction flag.
observer I Name or ID code string of the observer.
et I Time of the observation (seconds past J2000).
visible O Visibility flag (SPICETRUE/SPICEFALSE).
-Detailed_Input
inst indicates the name of an instrument, such as a
spacecraft-mounted framing camera. The field of view
(FOV) of the instrument will be used to determine if
the direction from the observer to a target,
represented as a ray, is visible with respect to the
instrument.
The position of the instrument `inst' is considered to
coincide with that of the ephemeris object `observer' (see
description below).
The size of the instrument's FOV is constrained by the
following: There must be a vector A such that all of
the instrument's FOV boundary vectors have an angular
separation from A of less than (pi/2)-MARGIN radians
(see description below). For FOVs that are circular or
elliptical, the vector A is the boresight. For FOVs
that are rectangular or polygonal, the vector A is
calculated.
See the header of the CSPICE routine getfov_c for a
description of the required parameters associated with
an instrument.
Both object names and NAIF IDs are accepted. For
example, both "CASSINI_ISS_NAC" and "-82360" are
accepted. Case and leading or trailing blanks are not
significant in the string.
raydir is the direction vector associated with a ray
representing a target. The ray emanates from the
location of the ephemeris object designated by the
input argument `observer' and is expressed relative to the
reference frame designated by `rframe' (see descriptions
below).
rframe is the name of the reference frame associated with
the input ray's direction vector `raydir'. Note: `rframe'
does not need to be the instrument's reference frame.
Since light time corrections are not supported for
rays, the orientation of the frame is always evaluated
at the epoch associated with the observer, as opposed
to the epoch associated with the light-time corrected
position of the frame center.
Case, leading and trailing blanks are not significant
in the string.
abcorr indicates the aberration corrections to be applied
when computing the ray's direction.
The supported aberration correction options are:
"NONE" No correction.
"S" Stellar aberration correction,
reception case.
"XS" Stellar aberration correction,
transmission case.
For detailed information, see the geometry finder
required reading, gf.req.
Case, leading and trailing blanks are not significant
in the string.
observer is the name of the body from which the target
represented by `raydir' is observed. The instrument
designated by `inst' is treated as if it were co-located
with the observer.
Both object names and NAIF IDs are accepted. For
example, both "CASSINI" and "-82" are accepted. Case and
leading or trailing blanks are not significant in the
string.
et is the observation time in seconds past the J2000
epoch.
-Detailed_Output
visible is SPICETRUE if the ray is "visible", or in the
field-of-view, of `inst' at the time `et'. Otherwise,
`visible' is SPICEFALSE.
-Parameters
SPICE_GF_MAXVRT is the maximum number of vertices that may be used
to define the boundary of the specified instrument's
field of view. See SpiceGF.h for more details.
MARGIN is a small positive number used to constrain the
orientation of the boundary vectors of polygonal
FOVs. Such FOVs must satisfy the following constraints:
1) The boundary vectors must be contained within
a right circular cone of angular radius less
than than (pi/2) - MARGIN radians; in
other words, there must be a vector A such that all
boundary vectors have angular separation from
A of less than (pi/2)-MARGIN radians.
2) There must be a pair of boundary vectors U, V
such that all other boundary vectors lie in
the same half space bounded by the plane
containing U and V. Furthermore, all other
boundary vectors must have orthogonal
projections onto a specific plane normal to
this plane (the normal plane contains the angle
bisector defined by U and V) such that the
projections have angular separation of at least
2*MARGIN radians from the plane spanned
by U and V.
MARGIN is currently set to 1.D-6.
-Exceptions
1) If the observer's name cannot be mapped to a NAIF ID code, the
error SPICE(IDCODENOTFOUND) is signaled.
2) If the aberration correction flag calls for light time
correction, the error SPICE(INVALIDOPTION) is signaled.
3) If the ray's direction vector is zero, the error
SPICE(ZEROVECTOR) is signaled.
4) If the instrument name `inst' does not have corresponding NAIF
ID code, the error will be diagnosed by a routine in the call
tree of this routine.
5) If the FOV parameters of the instrument are not present in
the kernel pool, the error will be diagnosed by routines
in the call tree of this routine.
6) If the FOV boundary has more than SPICE_GF_MAXVRT vertices, the error
will be diagnosed by routines in the call tree of this
routine.
7) If the instrument FOV shape is a polygon or rectangle, and
this routine cannot find a ray R emanating from the FOV
vertex such that maximum angular separation of R and any FOV
boundary vector is within the limit (pi/2)-MARGIN radians,
the error will be diagnosed by a routine in the call tree of
this routine. If the FOV is any other shape, the same error
check will be applied with the instrument boresight vector
serving the role of R.
8) If the loaded kernels provide insufficient data to compute a
requested state vector, the error will be diagnosed by a
routine in the call tree of this routine.
9) If an error occurs while reading an SPK or other kernel file,
the error will be diagnosed by a routine in the call tree
of this routine.
10) If any input string argument pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
11) If any input string argument other than `rframe' is empty, the
error SPICE(EMPTYSTRING) will be signaled.
-Files
Appropriate SPICE kernels must be loaded by the calling program
before this routine is called.
The following data are required:
- SPK data: ephemeris data for the observer at the time
`et'. If aberration corrections are used, the state of the
observer relative to the solar system barycenter
must be calculable from the available ephemeris data.
- Data defining the reference frame in which the instrument's
FOV is defined must be available in the kernel pool.
Additionally the name `inst' must be associated with an ID
code.
- IK data: the kernel pool must contain data such that
the CSPICE routine getfov_c may be called to obtain
parameters for `inst'.
The following data may be required:
- CK data: if the frame in which the instrument's FOV is
defined is fixed to a spacecraft, at least one CK file will
be needed to permit transformation of vectors between that
frame and the J2000 frame.
- SCLK data: if a CK file is needed, an associated SCLK
kernel is required to enable conversion between encoded SCLK
(used to time-tag CK data) and barycentric dynamical time
(TDB).
- Since the input ray direction may be expressed in any
frame, additional FKs, CKs, SCLK kernels, PCKs, and SPKs
may be required to map the direction to the J2000 frame.
Kernel data are normally loaded via furnsh_c once per program run,
NOT every time this routine is called.
-Particulars
To treat the target as an ephemeris object rather than a ray, use
the higher-level CSPICE routine fovtrg_c. fovtrg_c may be used to
determine if ephemeris objects such as Saturn are visible in an
instrument's FOV at a given time.
-Examples
1) The Cassini Ultraviolet Imaging Spectrograph (UVIS)
has been used to measure variations in starlight as
rings and moons occult Cassini's view of the stars.
One of these events happened at 2008-054T21:31:55.158 UTC.
Let's verify that Epsilon CMa (Adhara) was in the
Cassini UVIS field-of-view at the observation time.
KPL/MK
File name: fovray_ex.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
--------- --------
naif0010.tls Leapseconds
cpck26Jan2007.tpc Satellite orientation and
radii
cas00145.tsc Cassini SCLK
cas_v40.tf Cassini frames
cas_uvis_v06.ti Cassini UVIS instrument
080428R_SCPSE_08045_08067.bsp Merged spacecraft,
planetary, and satellite
ephemeris
08052_08057ra.bc Orientation for Cassini
\begindata
KERNELS_TO_LOAD = ( 'cpck26Jan2007.tpc'
'naif0010.tls'
'cas00145.tsc'
'cas_v40.tf'
'cas_uvis_v06.ti'
'080428R_SCPSE_08045_08067.bsp'
'08052_08057ra.bc')
\begintext
Example code begins here.
#include <stdio.h>
#include "SpiceUsr.h"
#include "SpiceZmc.h"
int main()
{
/.
Local constants
./
#define META "fovray_ex.tm"
#define BODLEN 32
#define TIMLEN 32
#define FRMLEN 32
/.
Local variables
The variable `time' is the observation time.
./
SpiceChar * time = "2008-054T21:31:55.158";
SpiceChar time_output[TIMLEN];
ConstSpiceChar * time_format =
"YYYY-MON-DD HR:MN:SC.###::TDB (TDB)";
/.
The variables `right_asc' and `dec' are the right ascension
and declination of Epsilon CMa in degrees.
./
SpiceDouble dec = -28.972;
SpiceDouble et;
SpiceDouble raydir [3];
SpiceDouble right_asc = 104.656;
SpiceBoolean visible;
/.
Load kernels.
./
furnsh_c ( META );
/.
Convert the observation time to `et'.
./
str2et_c ( time, &et );
/.
Create a unit direction vector pointing from Cassini
to the specified star. For details on corrections such
as parallax, please see the example in gfrfov_c.
./
radrec_c ( 1.0, right_asc*rpd_c(), dec*rpd_c(), raydir );
/.
Is the star in the field-of-view of Cassini's UVIS?
./
fovray_c ( "CASSINI_UVIS_FUV_OCC", raydir, "J2000",
"S", "Cassini", &et, &visible );
/.
Put the time in a specified format for output and
report the result.
./
timout_c ( et, time_format, TIMLEN, time_output );
if ( visible ) {
printf ( "Epsilon CMa was visible from the Cassini\n" );
printf ( "UVIS instrument at %s\n", time_output );
}
return (0);
}
When this program was executed on a PC/Linux/gcc platform, the
output was:
Epsilon CMa was visible from the Cassini
UVIS instrument at 2008-FEB-23 21:33:00.343 (TDB)
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
S.C. Krening (JPL)
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.0.0, 15-FEB-2012 (SCK) (NJB)
-Index_Entries
Ray in instrument FOV at specified time
Ray in instrument field_of_view at specified time
-&
*/
{ /* Begin fovray_c */
/*
Local variables
*/
SpiceChar * rFrameStr;
/*
Static variables
*/
static const SpiceChar * blankStr = " ";
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "fovray_c" );
/*
Check the input strings to make sure the pointers are non-null
and the string lengths are non-zero.
*/
CHKFSTR ( CHK_STANDARD, "fovray_c", inst );
CHKFSTR ( CHK_STANDARD, "fovray_c", abcorr );
CHKFSTR ( CHK_STANDARD, "fovray_c", observer );
/*
The input frame name is a special case because we allow the caller
to pass in an empty string. If this string is empty,
we pass a null-terminated string containing one blank character to
the underlying f2c'd routine.
First make sure the frame name pointer is non-null.
*/
CHKPTR ( CHK_STANDARD, "fovray_c", rframe );
/*
Use the input frame string if it's non-empty; otherwise
use a blank string for the frame name.
*/
if ( rframe[0] )
{
rFrameStr = (SpiceChar *) rframe;
}
else
{
rFrameStr = (SpiceChar *) blankStr;
}
/*
Call the f2c'd Fortran routine. Use explicit type casts for every
type defined by f2c.
*/
fovray_ ( (char *) inst,
(doublereal *) raydir,
(char *) rFrameStr,
(char *) abcorr,
(char *) observer,
(doublereal *) et,
(logical *) visible,
(ftnlen ) strlen(inst),
(ftnlen ) strlen(rframe),
(ftnlen ) strlen(abcorr),
(ftnlen ) strlen(observer) );
chkout_c ( "fovray_c" );
} /* End fovray_c */
