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

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_GETFOV returns the field-of-view (FOV) parameters for a specified
   instrument. The instrument is specified by its NAIF ID code.

I/O


   Given:

      instid   the NAIF ID of an instrument.

               help, instid
                  LONG = Scalar

      room     the maximum number of 3-dimensional vectors that can be returned
               in `bounds'.

               help, room
                  LONG = Scalar

   the call:

      cspice_getfov, instid, room, shape, frame, bsight, bounds

   returns:

      shape    a character string that describes the "shape" of the field of
               view.

               help, shape
                  STRING = Scalar

               Possible values returned are:

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

               If the value of `shape' is 'POLYGON' the field of view
               of the instrument is a pyramidal polyhedron. The
               vertex of the pyramid is at the instrument focal
               point. The rays along the edges of the pyramid are
               parallel to the vectors returned in `bounds'.

               If the value of `shape' is 'RECTANGLE' the field of view
               of the instrument is a rectangular pyramid. The vertex
               of the pyramid is at the instrument focal point. The
               rays along the edges of the pyramid are parallel to
               the vectors returned in `bounds'. Moreover, in this
               case, the boresight points along the axis of symmetry
               of the rectangular pyramid.

               If the value of `shape' is 'CIRCLE' the field of view of
               the instrument is a circular cone centered on the
               boresight vector. The vertex of the cone is at the
               instrument focal point. A single vector will be
               returned in `bounds'. This vector will be parallel to a
               ray that lies in the cone that makes up the boundary
               of the field of view.

               If the value of `shape' is 'ELLIPSE' the field of view
               of the instrument is an elliptical cone with the
               boresight vector as the axis of the cone. In this
               case two vectors are returned in `bounds'. One of the
               vectors returned in `bounds' points to the end of the
               semi-major axis of a perpendicular cross section of
               the elliptic cone. The other vector points to the end
               of the semi-minor axis of a perpendicular cross
               section of the cone.

      frame    the name of the reference frame in which the field of view
               boundary vectors are defined.

               help, frame
                  STRING = Scalar

      bsight   a double precision 3-vector representing the principal
               instrument view direction that can be

                  -  the central pixel view direction,
                  -  the optical axis direction,
                  -  the FOV geometric center view direction,
                  -  an axis of the FOV frame,

               or any other vector specified for this purpose
               in the IK FOV definition.

               help, bsight
                  DOUBLE = Array[3]

               The length of `bsight' is not specified other than being
               non-zero.

      bounds   an array of 3-dimensional double precision vectors that point to
               the "corners" of the instrument field of view.

               help, bounds
                  DOUBLE = Array[3,N]

               (See the discussion accompanying `shape' for an expansion of
               the term "corner of the field of view.") Note that the vectors
               returned in `bounds' are not necessarily unit vectors. Their
               magnitudes will be as set in the IK (for 'CORNERS'-style FOV
               specifications) or the same as the magnitude of the boresight
               (for 'ANGLES'-style FOV specifications.)

Parameters


   MINCOS      is the lower limit on the value of the cosine of the
               cross or reference angles in the 'ANGLES' specification
               cases. The current value for MINCOS is 1.0d-15.

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.

   1) Load an IK, fetch the parameters for each of the FOVs defined
      within and print these parameters to the screen.

      Use the kernel shown below, an IK defining four FOVs of
      various shapes and sizes, to load the FOV definitions.


         KPL/IK

         File name: getfov_ex1.ti

         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

         End of IK


      Example code begins here.


      PRO getfov_ex1

         ;;
         ;; 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, 'getfov_ex1.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


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      --------------------------------------
      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 for retrieving from the
   kernel pool 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 boresight 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 that 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'), four (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 vectors should
                                         be listed in either
                                         clockwise or
                                         counterclockwise order.
                                         This is required by some
                                         SPICE routines that make
                                         use of FOV specifications.

   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. The
                                         the FOV angular half-extents
                                         are measured from the
                                         boresight vector.

      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. The
                                         the FOV angular half-extents
                                         are measured from the
                                         boresight vector. 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.

   The INS<INSTID>_FOV_REF_ANGLE and INS<INSTID>_FOV_CROSS_ANGLE
   keywords can have any values for the 'CIRCLE' and 'ELLIPSE'
   FOV shapes but must satisfy the condition cos( angle  - 1) > 0 for
   the 'RECTANGLE' shape.

   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.

Exceptions


   1)  If the frame associated with the instrument can not be found,
       the error SPICE(FRAMEMISSING) is signaled by a routine in the
       call tree of this routine.

   2)  If the shape of the instrument field of view can not be found
       in the kernel pool, the error SPICE(SHAPEMISSING) is signaled
       by a routine in the call tree of this routine signaled.

   3)  If the FOV_SHAPE specified by the instrument kernel is not one
       of the four values: 'CIRCLE', 'POLYGON', 'ELLIPSE', or
       'RECTANGLE', the error SPICE(SHAPENOTSUPPORTED) is signaled by
       a routine in the call tree of this routine. If the 'ANGLES'
       specification is used, FOV_SHAPE must be one of the three
       values: 'CIRCLE', 'ELLIPSE', or 'RECTANGLE'.

   4)  If the direction of the boresight cannot be located in the
       kernel pool, the error SPICE(BORESIGHTMISSING) is signaled by
       a routine in the call tree of this routine.

   5)  If the number of components for the boresight vector in the
       kernel pool is not 3, or they are not numeric, the error
       SPICE(BADBORESIGHTSPEC) is signaled by a routine in the call
       tree of this routine.

   6)  If the boresight vector is the zero vector, the error 
       SPICE(ZEROBORESIGHT) is signaled by a routine in the call
       tree of this routine.

   7)  If the 'ANGLES' specification is not present in the kernel
       pool and the boundary vectors for the edge of the field of
       view cannot be found in the kernel pool, the error
       SPICE(BOUNDARYMISSING) is signaled by a routine in the call
       tree of this routine.

   8)  If there is insufficient room (as specified by the argument
       `room') to return all of the vectors associated with the
       boundary of the field of view, the error SPICE(BOUNDARYTOOBIG)
       is signaled by a routine in the call tree of this routine.

   9)  If the number of components of vectors making up the field of
       view is not a multiple of 3, the error SPICE(BADBOUNDARY) is
       signaled by a routine in the call tree of this routine.

   10) If the number of components of vectors making up the field of
       view is not compatible with the shape specified for the field
       of view, the error SPICE(BADBOUNDARY) is signaled by a routine
       in the call tree of this routine.

   11) If the reference vector for the 'ANGLES' specification can not
       be found in the kernel pool, the error SPICE(REFVECTORMISSING)
       is signaled by a routine in the call tree of this routine.

   12) If the reference vector stored in the kernel pool to support
       the 'ANGLES' specification contains an incorrect number of
       components, contains 3 character components, or is parallel to
       the boresight, the error SPICE(BADREFVECTORSPEC) is signaled
       by a routine in the call tree of this routine.

   13) If the 'ANGLES' specification is present in the kernel pool
       and the reference angle stored in the kernel pool to support
       the 'ANGLES' specification is absent from the kernel pool, the
       error SPICE(REFANGLEMISSING) is signaled by a routine in the
       call tree of this routine.

   14) If the keyword that stores the angular units for the angles
       used in the 'ANGLES' specification is absent from the kernel
       pool, the error SPICE(UNITSMISSING) is signaled by a routine
       in the call tree of this routine.

   15) If the value used for the units in the 'ANGLES' specification
       is not one of the supported angular units of cspice_convrt, an error
       is signaled by a routine in the call tree of this routine.

   16) If the keyword that stores the cross angle for the 'ANGLES'
       specification is needed and is absent from the kernel pool,
       the error SPICE(CROSSANGLEMISSING) is signaled by a routine in
       the call tree of this routine.

   17) If the angles for the 'RECTANGLE'/'ANGLES' specification case
       have cosines that are less than those stored in the parameter
       MINCOS, the error SPICE(BADBOUNDARY) is signaled by a routine
       in the call tree of this routine.

   18) If the class specification contains something other than
       'ANGLES' or 'CORNERS', the error SPICE(UNSUPPORTEDSPEC) is
       signaled by a routine in the call tree of this routine.

   19) In the event that the CLASS_SPEC keyword is absent from the
       kernel pool for the instrument whose FOV is sought, this
       module assumes the 'CORNERS' specification is to be utilized.

   20) If any of the input arguments, `instid' or `room', is
       undefined, an error is signaled by the IDL error handling
       system.

   21) If any of the input arguments, `instid' or `room', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy interface.

   22) If any of the output arguments, `shape', `frame', `bsight' or
       `bounds', is not a named variable, an error is signaled by the
       Icy interface.

Files


   This routine relies upon having successfully loaded an instrument
   kernel (IK file) via the routine cspice_furnsh prior to calling this
   routine.

Restrictions


   1)  This routine will not operate unless an I-kernel for the
       instrument with the NAIF ID specified in `instid' have been
       loaded via a call to cspice_furnsh prior to calling this routine and
       this IK contains the specification for the instrument field of
       view consistent with the expectations of this routine.

Required_Reading


   ICY.REQ
   NAIF_IDS.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   B.V. Semenov        (JPL)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.0.4, 17-DEC-2021 (JDR)

       Bug fix: added missing exception for the boresight vector
       being the zero vector.

       Extended description of "bsight" output argument.

       Edited the header to comply with NAIF standard. Updated all sections to
       improve the interface's documentation.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       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.3, 24-APR-2010 (EDW)

       Minor edit to code comments eliminating typo.

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

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

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

       Corrected error describing 'ROOM' in example
       code.

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

Index_Entries


   return instrument's FOV parameters



Fri Dec 31 18:43:04 2021