Index Page
cspice_fovtrg
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_FOVTRG determines if a specified ephemeris object 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 fovtrg_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-
   
      instrument   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 target is visible with respect to the instrument.
      
                   The position of the instrument 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 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.
      
      target       is the name of the target body. This routine determines
                   if the target body appears in the instrument's field of
                   view.
      
                   Both object names and NAIF IDs are accepted. For
                   example, both 'Moon' and '301' are accepted. Case and
                   leading or trailing blanks are not significant in the
                   string.
      
      target_shape is a string indicating the geometric model used to
                   represent the shape of the 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.
      
                   Case and leading or trailing blanks are not
                   significant in the string.
      
      target_frame is the name of the body-fixed, body-centered reference
                   frame associated with the target body. Examples of
                   such names are 'IAU_SATURN' (for Saturn) and 'ITRF93'
                   (for the Earth).
      
                   If the target body is modeled as a point, 'target_frame'
                   is ignored and should be left blank. (Ex: ' ').
      
                   Case and leading or trailing blanks bracketing a
                   non-blank frame name are not significant in the string.
      
      abcorr       indicates the aberration corrections to be applied
                   when computing the target's position and orientation.
      
                   For remote sensing applications, where the apparent
                   position and orientation of the target seen by the
                   observer are desired, normally either of the
                   corrections:
      
                       'LT+S'
                       'CN+S'
      
                   should be used. These and the other supported options
                   are described below.
      
                   Supported aberration correction options for
                   observation (the case where radiation is received by
                   observer at 'et') are:
      
                       'NONE'         No correction.
                       'LT'           Light time only
                       'LT+S'         Light time and stellar aberration.
                       'CN'           Converged Newtonian (CN) light time.
                       'CN+S'         CN light time and stellar aberration.
      
                   Supported aberration correction options for
                   transmission (the case where radiation is emitted from
                   observer at 'et') are:
      
                       'XLT'          Light time only.
                       'XLT+S'        Light time and stellar aberration.
                       'XCN'          Converged Newtonian (CN) light time.
                       'XCN+S'        CN light time and stellar aberration.
      
                   Case, leading and trailing blanks are not significant
                   in the string.
      
      observer     is the name of the body from which the target is
                   observed. The instrument '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_fovtrg, instrument, target,   target_shape, target_frame, $
                     abcorr,     observer, et,           visibl
                     
   returns:

      visibl       is true if 'target' is fully or partially in the
                   field-of-view of 'instrument' 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):
   
      A spectacular picture was taken by Cassini's
      narrow-angle camera on Oct. 6, 2010 that shows
      six of Saturn's moons. Let's verify that the moons
      in the picture are Epimetheus, Atlas, Daphnis, Pan,
      Janus, and Enceladus.
      
      To see this picture, visit:
      http://photojournal.jpl.nasa.gov/catalog/PIA12741
      or go to the PDS Image Node's Image Atlas at
      http://pds-imaging.jpl.nasa.gov/search/search.html.
      Select Cassini as the mission, ISS as the instrument,
      and enter 1_N1665078907.122 as the Product ID in the
      Product tab. Note: these directions may change as the
      PDS Imaging Node changes.
      
      Use the meta-kernel shown below to load the required SPICE
      kernels. For project meta-kernels similar to the one shown
      below, please see the PDS section of the NAIF FTP server.
      For example, look at the following path for Cassini
      meta-kernels: ftp://naif.jpl.nasa.gov//pub/naif/pds/data/
      co-s_j_e_v-spice-6-v1.0/cosp_1000/extras/mk

         KPL/MK
         
         File name: fovtrg_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
            cpck*.tpc                     Satellite orientation and
                                          radii
            pck00010.tpc                  Planet orientation and
                                          radii
            cas_rocks_v18.tf              FK for small satellites
                                          around Saturn
            cas_v40.tf                    Cassini FK
            cas_iss_v10.ti                Cassini ISS IK
            cas00149.tsc                  Cassini SCLK
            *.bsp                         Ephemeris for Cassini,
                                          planets, and satellites
            10279_10284ra.bc              Orientation for Cassini
         
         \begindata
         
            KERNELS_TO_LOAD = ( 'naif0010.tls'
                                'cpck14Oct2010.tpc'
                                'cpck_rock_21Jan2011_merged.tpc'
                                'pck00010.tpc'
                                'cas_rocks_v18.tf'
                                'cas_v40.tf'
                                'cas_iss_v10.ti'
                                'cas00149.tsc'
                                '110317AP_RE_90165_18018.bsp'
                                '110120BP_IRRE_00256_25017.bsp'
                                '101210R_SCPSE_10256_10302.bsp'
                                '10279_10284ra.bc'              )
         
         \begintext
         
         End of meta-kernel

      Beginning of example program.

         PRO fovtrg_ex
         
            ;;
            ;; Local variables
            ;;
            ;; The meta-kernel to be loaded is the variable 'metakr'.
            ;;
            metakr = 'fovtrg_ex.tm'
            time_format =  'YYYY-MON-DD HR:MN:SC.###::TDB (TDB)'
            TIMLEN = 32
            
            ;;
            ;; Load kernels
            ;;
            cspice_furnsh, metakr
            
            ;;
            ;; Retrieve Cassini's NAIF ID.
            ;;
            cspice_bodn2c, 'cassini', cassini_id, found
            
            if ( not found ) then begin
                print, 'Could not find ID code for Cassini.'
                return
            endif
            
            ;;
            ;; Convert the image tag SCLK to ET.
            ;;
            cspice_scs2e, cassini_id, '1665078907.122', et
            
            ;;
            ;; Convert the ET to a string format for the output.
            ;;
            cspice_timout, et, time_format, TIMLEN, time_output
            
            ;;
            ;; Search through all of Saturn's moons to see if each
            ;; satellite was in the ISS NAC's field-of-view at
            ;; the image time. We're going to take advantage of the
            ;; fact that all Saturn's moons have a NAIF ID of 6xx.
            ;;
            print, 'At time ', time_output, ' the following were ', $
                   'in the field of view of CASSINI_ISS_NAC'
                   
            for body_id = 600, 699 do begin
               ;;
               ;; Check to see if the 'body_id' has a translation.
               ;;
               cspice_bodc2n, body_id, body, found
               
               if ( found ) then begin
                  ;;
                  ;; Check to see if a body-fixed frame for this ID exists.
                  ;; If the frame is not in the kernel pool, we cannot
                  ;; perform the visibility test. The main cause of a
                  ;; failure is a missing kernel.
                  ;;
                  cspice_cidfrm, body_id, frame_code, frame_name, found
                  
                  if ( found ) then begin
                     ;;
                     ;; Is this body in the field-of-view of Cassini's
                     ;; ISS narrow-angle camera?
                     ;;
                     cspice_fovtrg, 'CASSINI_ISS_NAC', body, 'ellipsoid', $
                                    frame_name, 'cn+s', 'cassini', et, visible
                     
                     if ( visible ) then print, '  ', body
         
                  endif
               endif 
            endfor
            ;;
            ;; Clear kernels.
            ;;
            cspice_kclear
         END

   IDL outputs:
   
      At time 2010-OCT-06 17:09:45.346 (TDB) the following were in the
      field of view of CASSINI_ISS_NAC
        ENCELADUS
        JANUS
        EPIMETHEUS
        ATLAS
        PAN
        DAPHNIS
        ANTHE

   Example(2):

      Test whether Pan was in the field of view of the Cassini ISS 
      narrow-angle camera at a series of times.
      
         PRO fovtrg_vec_ex
            
            ;;
            ;; Load kernels
            ;;
            cspice_furnsh, 'fovtrg_ex.tm'
         
            ;;
            ;; Test the visibility of Pan at the following times.
            ;;
            times = ['2010-OCT-06 16:09:45.346 (TDB)', $
                     '2010-OCT-06 16:59:45.346 (TDB)', $
                     '2010-OCT-06 17:09:45.346 (TDB)', $
                     '2010-OCT-06 18:09:45.346 (TDB)']
            ;; 
            ;; Convert the times to ephemeris time ET.
            ;; 
            cspice_str2et, times, et
            
            cspice_fovtrg, 'cassini_iss_nac', 'pan', 'ellipsoid',  $
                           'iau_pan', 'cn+s', 'cassini', et, visible
         
            ;; 
            ;; Report the results.
            ;; 
            print, 'Pan was ____ the FOV of Cassini''s ISS NAC 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:

      Pan was ____ the FOV of Cassini's ISS NAC at ___:
        not within at 2010-OCT-06 16:09:45.346 (TDB)
        within     at 2010-OCT-06 16:59:45.346 (TDB)
        within     at 2010-OCT-06 17:09:45.346 (TDB)
        not within at 2010-OCT-06 18:09:45.346 (TDB)
   

Particulars


   To treat the target as a ray rather than as an ephemeris object,
   use the higher-level Icy routine cspice_fovray. cspice_fovray may be used
   to determine if distant target objects such as stars are visible
   in an instrument's FOV at a given time, as long as the direction
   from the observer to the target can be modeled as a ray.

Required Reading


   ICY.REQ
   

Version


   -Icy Version 1.0.0, 21-FEB-2012, SCK (JPL)

Index_Entries


   Target in instrument FOV at specified time
   Target in instrument field_of_view at specified time
 













Wed Apr  5 17:58:01 2017