Table of contents
CSPICE_FOVRAY determines if a specified ray is within the field-of-view
(FOV) of a specified instrument at a given time.
Given:
inst indicates the name of an instrument, such as a
spacecraft-mounted framing camera.
help, inst
STRING = Scalar
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 `obsrvr' (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)-SPICE_GF_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 Icy routine cspice_getfov 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 the direction vector defining a ray of interest.
help, raydir
DOUBLE = Array[3]
The ray emanates from the location of the ephemeris object
designated by the input argument `obsrvr' and is expressed
relative to the reference frame designated by `rframe' (see
description below).
rframe the name of the reference frame associated with the input ray's
direction vector `raydir'.
help, rframe
STRING = Scalar
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 target's position and orientation.
help, abcorr
STRING = Scalar
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.
obsrvr the name of the body from which the target represented by
`raydir' is observed.
help, obsrvr
STRING = Scalar
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 the observation time in seconds past the J2000 epoch.
help, et
DOUBLE = Scalar or DOUBLE = Array[N]
the call:
cspice_fovray, inst, raydir, rframe, abcorr, obsrvr, et, visibl
returns:
visibl true if the ray is "visible", or in the field-of-view, of `inst'
at the time `et'.
help, visibl
BOOLEAN = Scalar or BOOLEAN = Array[N]
Otherwise, `visibl' is false.
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.
SPICE_GF_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) - SPICE_GF_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)-SPICE_GF_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*SPICE_GF_MARGIN radians from the plane spanned
by U and V.
SPICE_GF_MARGIN is currently set to 1.e-12.
See Icy header file IcyGF.pro for declarations and descriptions of
parameters used throughout the GF system.
Any 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) 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.
Then, check whether Epsilon CMa was in the Cassini UVIS
field-of-view at multiple times.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: fovray_ex1.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 = ( 'naif0010.tls'
'cpck26Jan2007.tpc'
'cas00145.tsc'
'cas_v40.tf'
'cas_uvis_v06.ti'
'080428R_SCPSE_08045_08067.bsp'
'08052_08057ra.bc')
\begintext
End of meta-kernel
Example code begins here.
PRO fovray_ex1
;;
;; Load kernels.
;;
cspice_furnsh, 'fovray_ex1.tm'
;;
;; -------------- Test one time --------------
;;
;; Convert the observation time to `et'.
;;
cspice_str2et, '2008-054T21:31:55.158', et
;;
;; The variables `right_asc' and `dec' are the right ascension
;; and declination of Epsilon CMa in degrees.
;;
right_asc = 104.656
dec = -28.972
;;
;; Create a unit direction vector pointing from Cassini
;; to the specified star. For details on corrections such
;; as parallax, please see the example in cspice_gfrfov.
;;
cspice_radrec, 1, right_asc*cspice_rpd(), dec*cspice_rpd(), raydir
;;
;; Is the star in the field-of-view of Cassini's UVIS?
;;
cspice_fovray, 'CASSINI_UVIS_FUV_OCC', raydir, 'J2000', 's', $
'cassini', et, visible
;;
;; Put the time in a specified format for output and
;; report the result.
;;
cspice_timout, et, 'YYYY-MON-DD HR:MN:SC.###::TDB (TDB)', 32, $
time_output
print, ' ------- Single Time Case ------- '
if ( visible ) then begin
print, 'Epsilon CMa was visible from the Cassini ', $
'UVIS instrument at ', time_output
endif
;;
;; -------------- Test multiple times --------------
;;
;; Now test the visibility of Epsilon CMa for the times below.
;;
times = ['2008-054T20:31:00.000', '2008-054T21:31:55.158', $
'2008-054T21:50:00.000', '2008-054T23:50:00.000']
;;
;; Convert the observation times to `et_vector'.
;;
cspice_str2et, times, et_vector
;;
;; Is the star in the field-of-view of Cassini's UVIS?
;;
cspice_fovray, 'CASSINI_UVIS_FUV_OCC', raydir, 'J2000', 's', $
'cassini', et_vector, visible
;;
;; Report the results.
;;
print, ' ------- Multiple Times Case ------- '
print, 'Epsilon CMa was ____ the FOV of Cassini''s UVIS at ___:'
for i = 0, 3 do begin
if ( visible[i] ) then begin
print, ' within at ', times[i]
endif else begin
print, ' not within at ', times[i]
endelse
endfor
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
------- Single Time Case -------
Epsilon CMa was visible from the Cassini UVIS instrument at
2008-FEB-23 21:33:00.343 (TDB)
------- Multiple Times Case -------
Epsilon CMa was ____ the FOV of Cassini's UVIS at ___:
within at 2008-054T20:31:00.000
within at 2008-054T21:31:55.158
within at 2008-054T21:50:00.000
not within at 2008-054T23:50:00.000
To treat the target as an ephemeris object rather than a ray, use
the higher-level Icy routine cspice_fovtrg. cspice_fovtrg may be used to
determine if ephemeris objects such as Saturn are visible in an
instrument's FOV at a given time.
1) If the observer's name cannot be mapped to a NAIF ID code, the
error SPICE(IDCODENOTFOUND) is signaled by a routine in the
call tree of this routine.
2) If the aberration correction flag calls for light time
correction, the error SPICE(INVALIDOPTION) is signaled by a
routine in the call tree of this routine.
3) If the ray's direction vector is zero, the error
SPICE(ZEROVECTOR) is signaled by a routine in the call tree of
this routine.
4) If the instrument name `inst' does not have corresponding NAIF
ID code, an error is signaled 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, an error is signaled by a routine
in the call tree of this routine.
6) If the FOV boundary has more than SPICE_GF_MAXVRT vertices, an error
is signaled by a routine 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)-SPICE_GF_MARGIN radians, an error
is signaled 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, an error is signaled 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 is signaled by a routine in the call tree
of this routine.
10) If any of the input arguments, `inst', `raydir', `rframe',
`abcorr', `obsrvr' or `et', is undefined, an error is signaled
by the IDL error handling system.
11) If any of the input arguments, `inst', `raydir', `rframe',
`abcorr', `obsrvr' or `et', is not of the expected type, or it
does not have the expected dimensions and size, an error is
signaled by the Icy interface.
12) If the input vectorizable arguments `raydir' and `et' do not
have the same measure of vectorization (N), an error is
signaled by the Icy interface.
13) If the output argument `visibl' is not a named variable, an
error is signaled by the Icy interface.
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 Icy routine cspice_getfov 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 cspice_furnsh once per program run,
NOT every time this routine is called.
None.
CK.REQ
FRAMES.REQ
ICY.REQ
KERNEL.REQ
NAIF_IDS.REQ
PCK.REQ
SPK.REQ
TIME.REQ
None.
J. Diaz del Rio (ODC Space)
S.C. Krening (JPL)
E.D. Wright (JPL)
-Icy Version 1.0.1, 17-JUN-2021 (JDR)
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Edited the header to comply with NAIF standard. Updated list of
Required Reading. Fixed typos in header.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.0, 13-NOV-2013 (SCK) (EDW)
Ray in instrument FOV at specified time
Ray in instrument field_of_view at specified time
|