| getfvn_c |
|
Table of contents
Procedure
getfvn_c (Get instrument FOV parameters, by instrument name)
void getfvn_c ( ConstSpiceChar * inst,
SpiceInt room,
SpiceInt shalen,
SpiceInt fralen,
SpiceChar * shape,
SpiceChar * frame,
SpiceDouble bsight [3],
SpiceInt * n,
SpiceDouble bounds [][3] )
AbstractReturn the field-of-view (FOV) parameters for a specified instrument. The instrument is specified by name. Required_ReadingNAIF_IDS KeywordsFOV INSTRUMENT Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- inst I Name of an instrument. room I Maximum number of vectors that can be returned. shalen I Maximum length of output string `shape'. fralen I Maximum length of output string `frame'. shape O Instrument FOV shape. frame O Name of the frame in which FOV vectors are defined. bsight O Boresight vector. n O Number of boundary vectors returned. bounds O FOV boundary vectors. Detailed_Input
inst is the name of an instrument, such as a
spacecraft-mounted framing camera, for which the field of
view parameters are to be retrieved from the kernel pool.
`inst' is case-insensitive, and leading and trailing blanks
in `inst' are not significant. Optionally, you may supply
the integer ID for the instrument as an integer string.
For example, both "CASSINI_ISS_NAC" and "-82360" are
legitimate strings that indicate the CASSINI ISS NAC
camera is the instrument of interest.
room is the maximum number of 3-dimensional vectors that can
be returned in `bounds'.
shalen is the maximum allowed length of the output string
`shape'. This length must be large enough to hold the
output string plus the null-terminator character. If the
output string is expected to have X characters, `shalen'
should be at least X+1.
fralen is the maximum allowed length of the output string
`frame'. This length must be large enough to hold the
output string plus the null-terminator character. If the
output string is expected to have X characters, `fralen'
should be at least X+1.
Detailed_Output
shape is a character string that describes the "shape" of
the field of view. 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 is the name of the reference frame in which the field
of view boundary vectors are defined.
bsight is a 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. The length of `bsight'
is not specified other than being non-zero.
n is the number of boundary vectors returned.
bounds is an array of vectors that point to the "corners" of
the instrument field of view. (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. See the header of the routine getfov_c for its
current value.
Exceptions
1) If the name of the instrument cannot be translated to its NAIF
ID code, the error SPICE(IDCODENOTFOUND) is signaled by a
routine in the call tree of this routine.
2) If the frame associated with the instrument can not be found,
an error is signaled by a routine in the call tree of this
routine.
3) If the shape of the instrument field of view can not be found
in the kernel pool, an error is signaled by a routine in the
call tree of this routine.
4) If the FOV_SHAPE specified by the instrument kernel is not
one of the four values: 'CIRCLE', 'POLYGON', 'ELLIPSE', or
'RECTANGLE', an error 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'.
5) If the direction of the boresight cannot be located in the
kernel pool, an error is signaled by a routine in the call
tree of this routine.
6) If the number of components for the boresight vector in the
kernel pool is not 3, or they are not numeric, an error is
signaled by a routine in the call tree of this routine.
7) If the boresight vector is the zero vector, an error is
is signaled by a routine in the call tree of this routine.
8) 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, an error is signaled
by a routine in the call tree of this routine.
9) 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, an error 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 a multiple of 3, an error is signaled by a routine
in the call tree of this routine.
11) 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, an error is signaled by a routine in the call tree of
this routine.
12) If the reference vector for the 'ANGLES' specification can not
be found in the kernel pool, an error is signaled by a routine
in the call tree of this routine.
13) 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, an error is signaled by a routine in the call
tree of this routine.
14) 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, an
error is signaled by a routine in the call tree of this
routine.
15) If the keyword that stores the angular units for the angles
used in the 'ANGLES' specification is absent from the kernel
pool, an error is signaled by a routine in the call tree of
this routine.
16) If the value used for the units in the 'ANGLES' specification
is not one of the supported angular units of convrt_c, an error
is signaled by a routine in the call tree of this routine.
17) If the keyword that stores the cross angle for the 'ANGLES'
specification is needed and is absent from the kernel pool, an
error is signaled by a routine in the call tree of this
routine.
18) If the angles for the 'RECTANGLE'/'ANGLES' specification case
have cosines that are less than those stored in the parameter
MINCOS defined in the getfov_c routine, an error is signaled by
a routine in the call tree of this routine.
19) If the class specification contains something other than
'ANGLES' or 'CORNERS', an error is signaled by a routine in
the call tree of this routine.
20) 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.
21) If the `inst' input string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
22) If the `inst' input string has zero length, the error
SPICE(EMPTYSTRING) is signaled.
23) If any of the `shape' or `frame' output string pointers is
null, the error SPICE(NULLPOINTER) is signaled.
24) If any of the `shape' or `frame' output strings has length
less than two characters, the error SPICE(STRINGTOOSHORT) is
signaled, since the output string is too short to contain one
character of output data plus a null terminator.
FilesAppropriate SPICE kernels must be loaded by the calling program before this routine is called. This routine relies upon having successfully loaded an instrument kernel (IK file) via the routine furnsh_c prior to calling this routine. The name `inst' must be associated with an NAIF ID code, normally through a frames kernel (FK file) or instrument kernel (IK file). Kernel data are normally loaded via furnsh_c once per program run, NOT every time this routine is called. ParticularsThis 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. This routine is identical in function to the routine getfov_c except that it allows you to refer to an instrument by name (via a character string) instead of by its NAIF instrument ID. Given the NAIF instrument name, (and having "loaded" the instrument field of view description and instrument name to NAIF ID mapping) 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 which corresponds to the `inst' name 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 which corresponds to the `inst' name 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 convrt_c 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 ) > 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. Examples
The numerical results shown for this example 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.
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, and the
mapping between their NAMES and NAIF IDs.
KPL/IK
File name: getfvn_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
The keywords below define the INSTRUMENT name to NAIF ID
mappings for this example. For convenience we will keep them
in the example's IK although they could be placed elsewhere
(normally on the mission's frames kernel)
\begindata
NAIF_BODY_NAME += ( 'SC999_INST001' )
NAIF_BODY_CODE += ( -999001 )
NAIF_BODY_NAME += ( 'SC999_INST002' )
NAIF_BODY_CODE += ( -999002 )
NAIF_BODY_NAME += ( 'SC999_INST003' )
NAIF_BODY_CODE += ( -999003 )
NAIF_BODY_NAME += ( 'SC999_INST004' )
NAIF_BODY_CODE += ( -999004 )
\begintext
End of IK
Example code begins here.
/.
Program getfvn_ex1
./
#include <stdio.h>
#include "SpiceUsr.h"
int main( )
{
/.
Local parameters
./
#define MAXBND 4
#define NUMINS 4
#define WDSIZE 33
/.
Local variables
./
SpiceChar frame [WDSIZE];
SpiceChar shape [WDSIZE];
SpiceDouble bounds [MAXBND][3];
SpiceDouble bsight [3];
SpiceInt i;
SpiceInt j;
SpiceInt n;
/.
Define the instrument IDs.
./
SpiceChar instnm [NUMINS][WDSIZE] = { "SC999_INST001",
"SC999_INST002",
"SC999_INST003",
"SC999_INST004" };
/.
Load the IK file.
./
furnsh_c ( "getfvn_ex1.ti" );
/.
For each instrument ...
./
printf( "--------------------------------------\n" );
for ( i = 0; i < NUMINS; i++ )
{
/.
... fetch FOV parameters and ...
./
getfvn_c ( instnm[i], MAXBND, WDSIZE,
WDSIZE, shape, frame,
bsight, &n, bounds );
/.
... print them to the screen.
./
printf( "Instrument NAME: %s\n", instnm[i] );
printf( " FOV shape: %s\n", shape );
printf( " FOV frame: %s\n", frame );
printf( "FOV boresight: %11.8f %11.8f %11.8f\n",
bsight[0], bsight[1], bsight[2] );
printf( " FOV corners:\n" );
for ( j = 0; j < n; j++ )
{
printf( " %11.8f %11.8f %11.8f\n",
bounds[j][0], bounds[j][1], bounds[j][2] );
}
printf( "--------------------------------------\n" );
}
return ( 0 );
}
When this program was executed on a Mac/Intel/cc/64-bit
platform, the output was:
--------------------------------------
Instrument NAME: SC999_INST001
FOV shape: CIRCLE
FOV frame: SC999_INST001
FOV boresight: 0.00000000 0.00000000 1.00000000
FOV corners:
0.08715574 0.00000000 0.99619470
--------------------------------------
Instrument NAME: SC999_INST002
FOV shape: ELLIPSE
FOV frame: SC999_INST002
FOV boresight: 1.00000000 0.00000000 0.00000000
FOV corners:
1.00000000 0.00000000 0.01745506
1.00000000 0.03492077 0.00000000
--------------------------------------
Instrument NAME: SC999_INST003
FOV shape: RECTANGLE
FOV frame: SC999_INST003
FOV boresight: 0.00000000 0.00000000 1.00000000
FOV corners:
0.01047177 0.00174523 0.99994365
-0.01047177 0.00174523 0.99994365
-0.01047177 -0.00174523 0.99994365
0.01047177 -0.00174523 0.99994365
--------------------------------------
Instrument NAME: SC999_INST004
FOV shape: POLYGON
FOV frame: SC999_INST004
FOV boresight: 0.00000000 1.00000000 0.00000000
FOV corners:
0.00000000 0.80000000 0.50000000
0.40000000 0.80000000 -0.20000000
-0.40000000 0.80000000 -0.20000000
--------------------------------------
Restrictions
1) This routine will not operate unless proper mapping between
the instrument name `inst' and a NAIF ID exists, an I-kernel for
that instrument ID has been loaded via a call to furnsh_c prior
to calling this routine and this IK contains the specification
for the instrument field of view consistent with the
expectations of this routine.
Literature_ReferencesNone. Author_and_InstitutionJ. Diaz del Rio (ODC Space) Version-CSPICE Version 1.0.0, 17-DEC-2021 (JDR) Index_Entriesreturn instrument's FOV parameters, using instrument name |
Fri Dec 31 18:41:07 2021