Instrument functions

The instrument functions provide access to the description and the properties of instruments defined in the ephemeris files.

calceph_getfov

int calceph_getfov(t_calcephbin *eph, int instrumentid, int *shape, t_calcephcharvalue frame, double vector[3], double *arraybounds, int nbounds)

Parameters:

eph -- ephemeris descriptor
instrumentid -- Instrument identifier
shape -- FOV shape
frame -- Reference frame name
vector -- Boresight vector
arraybounds --

Array of boundary vectors

The length of the array has to be greater than 3*nbounds. (because each vector has 3 components)

can be NULL to query nbounds necessary
nbounds -- Maximum number of boundary vectors

Returns:

0 if an error occurs, otherwise the number of boundary vectors

This function retrieves the instrument Field Of View (FOV) description from an instrument kernel (IK) of the ephemeris file associated to eph, and computes the boundary vectors expressed in the instrument frame.

Depending on the FOV specification found in the IK, the function reads a subset of the following keywords (example names use the NAIF convention INS<id>_...):

INS#_FOV_SHAPE — shape: CIRCLE, ELLIPSE, RECTANGLE, POLYGON.
INS#_FOV_FRAME — name of the reference frame used for the boresight and boundary vectors.
INS#_BORESIGHT — the boresight vector (3 components).
INS#_FOV_CLASS_SPEC — either ANGLES or CORNERS.

If FOV_CLASS_SPEC = ANGLES additional keywords are expected:

INS#_FOV_REF_VECTOR — reference vector defining the reference axis in the boresight plane.
INS#_FOV_REF_ANGLE — half angular extent along the reference axis.
INS#_FOV_CROSS_ANGLE — half angular extent along the axis orthogonal to the reference axis.
INS#_FOV_ANGLE_UNITS — angle units (DEGREES, RADIANS).

If FOV_CLASS_SPEC = CORNERS the IK must provide explicit boundary corner vectors:

INS#_FOV_BOUNDARY_CORNERS — array of 3-component vectors giving the boundary corners.

Difference between ANGLES and CORNERS:

ANGLES: The IK describes the FOV by angular half-extents and a reference vector. Boundary vectors are computed from these values. Returned vectors share the same magnitude as the boresight.
CORNERS: The IK provides explicit boundary vectors, which are returned exactly as given. Magnitudes are preserved.

Coordinate conventions and units:

All vectors are expressed in the frame INS#_FOV_FRAME.
Angles may be in DEGREES or RADIANS; converted internally to radians.
For ANGLES, the boundary vectors preserve boresight magnitude. For CORNERS, the magnitudes are taken as-is.

For the ANGLES specification, the following formula is used internally to compute FOV boundary vectors. It describes how to rotate a vector $u$ inside the plane defined by two vectors $u$ and $v$ , starting from $u$ and turning it by a given angle $\theta$ :

$\mathbf{u}' = \|\mathbf{u}\| \left( \cos\theta \, \frac{\mathbf{u}}{\|\mathbf{u}\|} + \sin\theta \, \mathbf{Z} \right)$

where $\mathbf{Z}$ is the normalized projection of $v$ onto the plane orthogonal to $u$ .

$\mathbf{Z} = \frac{\mathbf{v} - \dfrac{(\mathbf{v}\cdot\mathbf{u})}{\|\mathbf{u}\|^2}\,\mathbf{u}}{\left\|\mathbf{v} - \dfrac{(\mathbf{v}\cdot\mathbf{u})}{\|\mathbf{u}\|^2}\,\mathbf{u} \right\|}$

This rotation is the core operation used when computing the boundary vectors of a FOV.

For the CORNERS specification, vectors are returned as given in the IK.

The possible values for shape are :

value	meaning
1	Polygon
2	Rectangle
3	Circle
4	Ellipse

If the argument arraybounds is NULL, the function does not write any boundary vector. Instead, it returns the number of boundary vectors required for the given instrument and FOV definition.

This allows the caller to query the required size first, allocate the appropriate array, and then call the function again to retrieve the actual boundary vectors.

The following example prints the shape, the frame, and the boundary vector for a circular FOV

t_calcephbin *peph;
int instrumentid = -42550;
int shape;
t_calcephcharvalue frame;
double vector[3];
double boundary[3];

/* open the kernel file */
peph = calceph_open("example_ik.ti");

if (peph != NULL)
{
    /* get the field of view */
    if (calceph_getfov(peph, instrumentid, &shape, &frame, vector, boundary, 3) != 0)
    {
        printf("Instrument %d\n", instrumentid);
        printf("Shape=%d Frame=%s\n", shape, frame);
        printf("Boresight vector : %f %f %f\n", vector[0], vector[1], vector[2]);
        printf("Boundary vector : %f %f %f\n", boundary[0], boundary[1], boundary[2]);
    }

    /* close the file */
    calceph_close(peph);
}