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.

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.

                    [1,a] = size(instrument), char = class(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.

                    [1,b] = size(target), char = class(target)

                    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.

                    [1,c] = size(target_shape), char = class(target_shape)

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

                    [1,d] = size(target_frame), char = class(target_frame)

                    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.

                    [1,e] = size(abcorr), char = class(abcorr)

                    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.

                    [1,f] = size(observer), char = class(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.

                    [1,n] = size(et), double = class(et)

   the call:

       visibl = cspice_fovtrg ( instrument,   target, target_shape, ...
                                target_frame, abcorr, observer, et )

   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.

                    [1,n] = size(visibl), logical = class(visibl)

Examples


   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.


   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

       Example program starts here.

         %
         %   Load the meta kernel.
         %
         cspice_furnsh ( 'fovtrg_ex.tm' );

         %
         %   Retrieve Cassini's NAIF ID.
         %
         [cassini_id, found] = cspice_bodn2c ( 'cassini' );

         if (~found)
             fprintf ( 'Could not find ID code for Cassini.' );
             return
         end

         %
         %   Convert the image tag SCLK to ET.
         %
         et = cspice_scs2e ( cassini_id, '1665078907.122' );

         %
         %   Convert the ET to a string format for the output.
         %
         time_format = 'YYYY-MON-DD HR:MN:SC.###::TDB (TDB)';
         time = cspice_timout ( et, time_format );

         %
         %   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.
         %
         fprintf ( 'At time %s the following were\n', time     );
         fprintf ( 'in the field of view of CASSINI_ISS_NAC\n' );
         for body_id = 600:699
             %
             %   Check to see if the 'body_id' has a translation.
             %
             [body, found] = cspice_bodc2n ( body_id );

             if (found)
                 %
                 %   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.
                 %
                 [frame_code, frame_name, found] = cspice_cidfrm ( body_id );

                 if (found)
                     %
                     %   Is this body in the field-of-view of Cassini's
                     %   ISS narrow-angle camera?
                     %
                     visibl = cspice_fovtrg ( 'cassini_iss_nac', body, ...
                                     'ellipsoid', frame_name, 'cn+s', ...
                                     'cassini', et );
                     if ( visibl )
                         fprintf ( '  %s\n', body);
                     end
                 end
             end
         end
         %
         %   Unload the kernels.
         %
         cspice_kclear

   MATLAB 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

         Note: there were actually 7 of Saturn's satellites in the
         field-of-view of Cassini's narrow-angle camera. However, Anthe
         is very small and was probably obscured by other objects or
         shadow.

Particulars


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


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

   MICE.REQ
   DAF.REQ

Version


   -Mice Version 1.0.1, 13-APR-2015, EDW (JPL)

      Edit to correct typos in "Usage" string.

   -Mice Version 1.0.0, 16-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 18:00:31 2017