Index Page
cspice_getfov
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_GETFOV returns the field-of-view parameters for a user
   specified instrument.

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

I/O

   
   Given:
   
      instid   the integer NAIF ID for the instrument of interest
      room     the max number of double precision 'bounds' vectors 
               to return
   
   the call:
   
      cspice_getfov, instid, room, shape, frame, bsight, bounds
   
   returns:
   
      shape    a string describing the FOV shape for instrument 
               'instid'. Possible values:
   
                    "POLYGON"
                    "RECTANGLE"
                    "CIRCLE"
                    "ELLIPSE" 
   
      frame    a string identifying the frame in which the FOV is
               defined
      bsight   a double precision 3-vector pointing in the direction
               of the FOV center (boresight)
      bounds   an array of 3-vectors pointing to the "corners"
               of the instrument FOV
   

Examples


   The example program in this section loads the IK file
   'example.ti' with the following contents defining four FOVs of
   various shapes and sizes:

      KPL/IK
      
      The keywords below define a circular, 10-degree wide FOV with
      the boresight along the +Z axis of the 'SC999_INST001' frame
      for an instrument with ID -999001 using the "angles"-class
      specification.
      
      \begindata
         INS-999001_FOV_CLASS_SPEC       = 'ANGLES'
         INS-999001_FOV_SHAPE            = 'CIRCLE'
         INS-999001_FOV_FRAME            = 'SC999_INST001'
         INS-999001_BORESIGHT            = ( 0.0, 0.0, 1.0 )
         INS-999001_FOV_REF_VECTOR       = ( 1.0, 0.0, 0.0 )
         INS-999001_FOV_REF_ANGLE        = ( 5.0 )
         INS-999001_FOV_ANGLE_UNITS      = ( 'DEGREES' )
      \begintext
      
      The keywords below define an elliptical FOV with 2- and
      4-degree angular extents in the XZ and XY planes and the
      boresight along the +X axis of the 'SC999_INST002' frame for
      an instrument with ID -999002 using the "corners"-class
      specification.
      
      \begindata
         INS-999002_FOV_SHAPE            = 'ELLIPSE'
         INS-999002_FOV_FRAME            = 'SC999_INST002'
         INS-999002_BORESIGHT            = ( 1.0, 0.0, 0.0 )
         INS-999002_FOV_BOUNDARY_CORNERS = ( 1.0, 0.0, 0.01745506,
                                             1.0, 0.03492077, 0.0 )
      \begintext
      
      The keywords below define a rectangular FOV with 1.2- and
      0.2-degree angular extents in the ZX and ZY planes and the
      boresight along the +Z axis of the 'SC999_INST003' frame for
      an instrument with ID -999003 using the "angles"-class
      specification.
      
      \begindata
         INS-999003_FOV_CLASS_SPEC       = 'ANGLES'
         INS-999003_FOV_SHAPE            = 'RECTANGLE'
         INS-999003_FOV_FRAME            = 'SC999_INST003'
         INS-999003_BORESIGHT            = ( 0.0, 0.0, 1.0 )
         INS-999003_FOV_REF_VECTOR       = ( 1.0, 0.0, 0.0 )
         INS-999003_FOV_REF_ANGLE        = ( 0.6 )
         INS-999003_FOV_CROSS_ANGLE      = ( 0.1 )
         INS-999003_FOV_ANGLE_UNITS      = ( 'DEGREES' )
      \begintext
      
      The keywords below define a triangular FOV with the boresight
      along the +Y axis of the 'SC999_INST004' frame for an
      instrument with ID -999004 using the "corners"-class
      specification.
      
      \begindata
         INS-999004_FOV_SHAPE            = 'POLYGON'
         INS-999004_FOV_FRAME            = 'SC999_INST004'
         INS-999004_BORESIGHT            = (  0.0,  1.0,  0.0 )
         INS-999004_FOV_BOUNDARY_CORNERS = (  0.0,  0.8,  0.5,
                                              0.4,  0.8, -0.2,
                                             -0.4,  0.8, -0.2 )
      \begintext

   The program shown below loads the IK, fetches parameters for each
   of the four FOVs and prints these parameters to the screen.

      PRO example

         ;;
         ;; Set maximum number of boundary vectors, number of
         ;; instruments and instrument IDs.
         ;;
         MAXBND = 4
         NUMINS = 4
         insids = [-999001, -999002, -999003, -999004]

         ;;
         ;; Load the IK file.
         ;;
         cspice_furnsh, 'example.ti'

         ;;
         ;; For each instrument ...
         ;;
         print, '--------------------------------------'
         for i = 0, NUMINS-1 do begin

            ;;
            ;; ... fetch FOV parameters and ...
            ;; 
            cspice_getfov, insids[i], MAXBND, $
                           shape, frame, bsight, bounds

            ;;
            ;; ... print them to the screen.
            ;;
            print, 'Instrument ID: ', insids[i]
            print, '    FOV shape: ', shape
            print, '    FOV frame: ', frame
            print, 'FOV boresight: ', $
                      bsight[0], bsight[1], bsight[2]

            print, '  FOV corners: '
            for j = 0, n_elements(bounds)/3-1 do begin
               print, '               ', $
                       bounds[0,j], bounds[1,j], bounds[2,j]
            endfor

            print, '--------------------------------------'

         endfor

      END

   The program produces the following output:

      --------------------------------------
      Instrument ID:      -999001
          FOV shape: CIRCLE
          FOV frame: SC999_INST001
      FOV boresight:        0.0000000       0.0000000       1.0000000
        FOV corners:
                          0.087155743       0.0000000      0.99619470
      --------------------------------------
      Instrument ID:      -999002
          FOV shape: ELLIPSE
          FOV frame: SC999_INST002
      FOV boresight:        1.0000000       0.0000000       0.0000000
        FOV corners:
                            1.0000000       0.0000000     0.017455060
                            1.0000000     0.034920770       0.0000000
      --------------------------------------
      Instrument ID:      -999003
          FOV shape: RECTANGLE
          FOV frame: SC999_INST003
      FOV boresight:        0.0000000       0.0000000       1.0000000
        FOV corners:
                          0.010471768    0.0017452327      0.99994365
                         -0.010471768    0.0017452327      0.99994365
                         -0.010471768   -0.0017452327      0.99994365
                          0.010471768   -0.0017452327      0.99994365
      --------------------------------------
      Instrument ID:      -999004
          FOV shape: POLYGON
          FOV frame: SC999_INST004
      FOV boresight:        0.0000000       1.0000000       0.0000000
        FOV corners:
                            0.0000000      0.80000000      0.50000000
                           0.40000000      0.80000000     -0.20000000
                          -0.40000000      0.80000000     -0.20000000
      --------------------------------------

Particulars


   This routine provides a common interface to retrieving the geometric
   characteristics of an instrument field of view for a wide variety of
   remote sensing instruments across many different space missions.

   Given the NAIF instrument ID, (and having "loaded" the
   instrument field of view description via the routine cspice_furnsh)
   this routine returns the bore-sight of the instrument, the
   "shape" of the field of view, a collection of vectors
   that point along the edges of the field of view, and the
   name of the reference frame in which these vectors are defined.

   Currently this routine supports two classes of specifications
   for FOV definitions: "corners" and "angles".

   The "corners" specification requires the following keywords
   defining the shape, boresight, boundary vectors, and reference
   frame of the FOV be provided in one of the text kernel files
   (normally an IK file) loaded into the kernel pool (in the
   keywords below <INSTID> is replaced with the instrument ID as
   passed into the module):

      INS<INSTID>_FOV_CLASS_SPEC         must be set to 'CORNERS' or
                                         omitted to indicate the
                                         "corners"-class
                                         specification.
                                         

      INS<INSTID>_FOV_SHAPE              must be set to one of these
                                         values:

                                            'CIRCLE'
                                            'ELLIPSE'
                                            'RECTANGLE'
                                            'POLYGON'

      INS<INSTID>_FOV_FRAME              must contain the name of
                                         the frame in which the
                                         boresight and boundary
                                         corner vectors are defined.

      INS<INSTID>_BORESIGHT              must be set to a 3D vector
                                         defining the boresight in
                                         the FOV frame specified in
                                         the FOV_FRAME keyword.

      INS<INSTID>_FOV_BOUNDARY   or      
      INS<INSTID>_FOV_BOUNDARY_CORNERS   must be set to one (for
                                         FOV_SHAPE = 'CIRCLE'), two
                                         (for FOV_SHAPE =
                                         'ELLIPSE'), three (for
                                         FOV_SHAPE = 'RECTANGLE'),
                                         or three or more (for
                                         'POLYGON') 3D vectors
                                         defining the corners of the
                                         FOV in the FOV frame
                                         specified in the FOV_FRAME
                                         keyword.

   The "angles" specification requires the following keywords
   defining the shape, boresight, reference vector, reference and
   cross angular extents of the FOV be provided in one of the text
   kernel files (normally an IK file) loaded into the kernel
   pool (in the keywords below <INSTID> is replaced with the
   instrument ID as passed into the module):

      INS<INSTID>_FOV_CLASS_SPEC         must be set to  'ANGLES' to
                                         indicate the "angles"-class
                                         specification.

      INS<INSTID>_FOV_SHAPE              must be set to one of these
                                         values:

                                            'CIRCLE'
                                            'ELLIPSE'
                                            'RECTANGLE'

      INS<INSTID>_FOV_FRAME              must contain the name of
                                         the frame in which the 
                                         boresight and the computed
                                         boundary corner vectors are
                                         defined.

      INS<INSTID>_BORESIGHT              must be set to a 3D vector
                                         defining the boresight in
                                         the FOV frame specified in
                                         the FOV_FRAME keyword.

      INS<INSTID>_FOV_REF_VECTOR         must be set to a 3D vector
                                         that together with the
                                         boresight vector defines
                                         the plane in which the
                                         first angular extent of the
                                         FOV specified in the
                                         FOV_REF_ANGLE keyword is
                                         measured.

      INS<INSTID>_FOV_REF_ANGLE          must be set to the angle
                                         that is 1/2 of the total
                                         FOV angular extent in the 
                                         plane defined by the 
                                         boresight and the vector
                                         specified in the
                                         FOV_REF_VECTOR keyword.

      INS<INSTID>_FOV_CROSS_ANGLE        must be set to the angle
                                         that is 1/2 of the total
                                         FOV angular extent in the
                                         plane containing the
                                         boresight and perpendicular
                                         to the plane defined by the
                                         boresight and the vector
                                         specified in the
                                         FOV_REF_VECTOR keyword.
                                         This keyword is not
                                         required for FOV_SHAPE =
                                         'CIRCLE'.

      INS<INSTID>_FOV_ANGLE_UNITS        must specify units for the
                                         angles given in the
                                         FOV_REF_ANGLE and
                                         FOV_CROSS_ANGLE keywords.
                                         Any angular units
                                         recognized by cspice_convrt
                                         are acceptable.

   This routine is intended to be an intermediate level routine.
   It is expected that users of this routine will be familiar
   with the SPICE frames subsystem and will be comfortable writing
   software to further manipulate the vectors retrieved by this
   routine.

Required Reading


   ICY.REQ

Version


   -Icy Version 1.0.3, 24-APR-2010, EDW (JPL)

      Minor edit to code comments eliminating typo.

   -Icy Version 1.0.2, 05-FEB-2009, BVS (JPL)

      Header update: added information about required IK keywords;
      replaced old example with a new one more focused on getfov_c and
      IK keywords.

   -Icy Version 1.0.1, 07-DEC-2005, EDW (JPL)

      Corrected error describing 'ROOM' in example
      code.

   -Icy Version 1.0.0, 16-JUN-2003, EDW (JPL)

Index_Entries

 
   return instrument's FOV parameters 
 



Wed Apr  5 17:58:01 2017