Voir la source de User Manual 4.13 Fields of view

__NOTOC__
== Introduction ==
=== Scope ===
The fields of view are used to describe the instruments and sensors of a spacecraft : each of them has several fields of view and inhibition (the inhibition fields are also created as "fields of view" : they provide the same services).
All the available fields are described thereafter.

=== Javadoc ===
All the fields of view and the associated interface are available in the package <code>fr.cnes.sirius.patrius.fieldsofview</code>

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Basis
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/package-summary.html Package fr.cnes.sirius.patrius.fieldsofview]
|}

=== Package Overview ===
All fields implement the IFieldOfView interface.

== Features Description ==
=== Omnidirectional field ===
This field is all the 3D space : any direction vector belongs to it.
The angular distance to a vector has no sense here : this method always return 1 (the convention for a vector in the field being to return a positive value).

=== Circular field ===
This field is a right circular infinite cone defined by an angular aperture from a given direction.


=== Elliptic field ===
This field is an infinite elliptic cone defined by two an angular aperture from a given origin. (Cf [[User Manual 4.13 Fields of view#Classes|EllipticField]]).

'''Nota :''' Angular distances are approximation. Moreover, if the user point is outside the cone and the closest point on the cone is its apex, then the angular distance return is <math>{-\pi \over 2}</math>).

=== Rectangle field ===
This field is a rectangle infinite cone defined the same way as the identical object of the geometry section : a main direction vector, abn approximative U vector (to define the local frame) and two aperture angles (see the Infinite rectangle cone chapter for more details).

=== Pyramidal field ===
This field describes any pyramidal field defined by an array of directions.
The field must be created with the directions (vectors) in the right order : the inside of the field is on the side of the positive cross vector of two consecutive vetcors i and i+1 of the list (and the last to the first).
This field proposes additional methods for field manipulation:
* <code>getIntersectionWith</code>: computes intersection with another PyramidalField. Be careful, this method may return an exception in case of strongly degenerated cases (multiple intersections, etc.)
* <code>getUnionWith</code>: computes union with another PyramidalField. Be careful, this method may return an exception in case of strongly degenerated cases (multiple unions, etc.)
* <code>getComplementaryFieldOfView</code>: returns the complementary field of view
* <code>isConvex</code>: says if the field is convex

=== Boolean field ===
This field is a boolean combination ("AND" or "OR") of two previously created fields.<br>
A direction is in an "OR" field if it is at least in one of the two fields defining it.<br>
A direction is in an "AND" field if it is in both of the two fields defining it.<br>
Beware : the angular distance computed is approximative in some cases (for a direction in the field in an "OR" case, for a direction out of the field in an "AND" case), but the sign is always the right one, and the function is continuous around its zero (direction on the border of the field), so that it can be used fo events detection.

=== Invert field ===
The invert field is created from an existing one : and represent a field with a same border but an inverse definition of "in" and "out". The angular distance is so the opposite of the one of the original field.

=== Sector field ===
This field is a min/max longitude and min/max latitude aperture on the unit sphere.<br>
It is defined by three vectors : the local "north pole" vector for this sphere, the min latitude- min longitude point vector (V1) and the max latitude - max longitude point vector (V2).<br>
The angle from the pole vector to V1 must be greater than the angle from the pole vector to V2 (greater latitude). None of them can be aligned with or opposite to the "pole" vector (the field is undefined if V1 or V2 is on a pole).


[[File:sectorField.PNG|center]]

=== Azimuth-Elevation Field ===
This field is defined by an azimuth/elevation array. The border is then described by linear segments between these points. The inside of the field is the sector of the unitary sphere with greaters elevation than the border.<br>
The angular distance to the field limit is not the exact shortest distance: it is the exact angular distance on the local meridian (difference of elevation of the target and the linear interpolated local elevation). Concerning the field of view, the limit between two consecutive points is NOT a great circle (i.e. planar) limit: it is linear in azimuth-elevation. The fields with planar limits are the Rectangle or Pyramidal fields.

Azimuth and elevation follow the following convention:

[[File:Azimuth.png|center]]

For a given point P, defined by cartesian coordinates in frame (XYZ):
* This frame is such that x and y axis are in the same plane as reference azimut AzimutRef and such that the angle between reference azimut and x axis is defined by alpha angle in counter-clockwise (trigonometric) direction.
* If alpha = 0, x is along reference azimut (in the case of TopoCentricFrame points along North in general), y is along West direction
* On the above scheme, alpha = -30°, the x axis is along North-East and y axis along North-West
* Azimut of point P is equal to beta angle, counted in clockwise direction, starting from reference azimut. It is equal to 324° on the above scheme.

== Getting Started ==
{{specialInclusion prefix=$theme_sub section="GettingStarted"/}}

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IFieldOfView'''
|Interface for all fields of view.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/IFieldOfView.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''OmnidirectionalField'''
|Field incuding all the 3D space.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/OmnidirectionalField.html ...]
|-
|'''CircularField'''
|Field described by a circular cone.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/CircularField.html ...]
|-
|'''RectangleField'''
|Field described by a direction and two angles.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/RectangleField.html ...]
|-
|'''PyramidalField'''
|Field described by an ordered array of directions.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/PyramidalField.html ...]
|-
|'''BooleanField'''
|Field defined by a boolean combination of two existing fields.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/BooleanField.html ...]
|-
|'''InvertField'''
|Field inverting an existing one.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/InvertField.html ...]
|-
|'''EllipticField'''
|This class describes an elliptic field of view.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/EllipticField.html ...]
|-
|'''SectorField'''
|This class describes a "sector" field of view.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/SectorField.html ...]
|-
|'''AzimuthElevationField'''
|This class describes a field of view defined by an azimuth/elevation array.
|[{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/AzimuthElevationField.html ...]
|}

=== Methods ===
All [[User Manual 4.13 Fields of view#Classes|fields]] implement the IFieldOfView interface (see [{{JavaDoc4.13}}/fr/cnes/sirius/patrius/fieldsofview/IFieldOfView.html javadoc]).

All fields can :

* return a boolean set to true if a user point (<code>direction</code>) is in the field,
* compute the minimal angular distance between a user point (<code>direction</code>) to their border,
* provide their name.

The associated methods are :

;'''getAngularDistance( Vector3D ) : double'''
: The convention is : the returned double is positive if the direction vector is in the field, negative otherwise, so it can be used directely by the event detector computations (the zero of the g function occurs when the direction comes in are goes out of the field).

<syntaxhighlight lang="java">
// creation of a circular field of view
Vector3D axisVector = new Vector3D(2.0, 1.0, 3.0);
double apertureAngle = 1.2;
IFieldOfView field = new CircularFieldOfView(axisVector, apertureAngle);

// the direction
Vector3D direction = new Vector3D(1.0, 0.5, 2.0);

// angular distance to the direction
double angularDistance = field.getAngularDistance(direction);
</syntaxhighlight>

;'''isInTheField( Vector3D ) : boolean'''
: Returns true if the direction vector is in the field, false otherwise.

<syntaxhighlight lang="java">
// angular distance to the direction
boolean direction in field = field.isInTheField(direction);
</syntaxhighlight>

;'''getName( ) : String'''
: Returns the String name of the field.

== Tutorials ==
=== Tutorial 1 ===
{{specialInclusion prefix=$theme_sub section="Tuto1"/}}

== [[File:lightBulb.png]] Tips & Tricks ==
{{specialInclusion prefix=$theme_sub section="Tips"/}}

[[Category:User_Manual_4.13_Spacecraft]]