Index Page
cspice_fovray
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_FOVRAY determines if a specified ray is within the field-of-view
   (FOV) of a specified instrument at a given time.

   For important details concerning this module's function, please refer to
   the CSPICE routine fovray_c.

I/O


   Given:

   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.

   Arguments-

      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 '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)-MARGIN radians
               (see description above). 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 defining a ray of interest.
               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   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.

      abcorr   indicates the aberration corrections to be applied
               when computing the target's position and orientation.

               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   is the name of the body from which the target
               represented by 'raydir' is observed. The instrument
               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.

   the call:

      cspice_fovray, inst, raydir, rframe, abcorr,  $
                     obsrvr,   et,     visibl

   returns:

      visibl   is true if the ray is "visible", or in the
               field-of-view, of 'inst' at the time 'et'.
               Otherwise, 'visibl' is false.

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.

   Example(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_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 = ( '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

      Beginning of example program.

         PRO fovray_ex

            ;;
            ;; Local variables
            ;;
            cspice_furnsh, 'fovray_ex.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

            ;;
            ;; Clear kernels.
            ;;
            cspice_kclear

         END

   IDL outputs:

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

Particulars


   To treat the target as an ephemeris object rather than a ray, use
   the higher-level Mice 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.

Required Reading


   ICY.REQ

Version


   -Icy Version 1.0.0, 13-NOV-2013, SCK (JPL), EDW (JPL)

Index_Entries


   Ray in instrument FOV at specified time
   Ray in instrument field_of_view at specified time




Wed Apr  5 17:58:01 2017