Voir la source de User Manual 3.4.1 Kinematics

== Introduction ==
=== Scope ===
The purpose is to extend the current Orekit attitude package with classes and methods to compute and process kinematics operations.

=== Javadoc ===
The kinematics objects are available in the package org.orekit.attitudes.kinematics in the Orekit library.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Orekit
|[{{JavaDoc3.4.1}}/org/orekit/attitudes/kinematics/package-summary.html Package org.orekit.attitudes.kinematics]
|}

=== Links ===
{{specialInclusion prefix=$theme_sub section="Links"/}}

=== Useful Documents ===
{{specialInclusion prefix=$theme_sub section="UsefulDocs"/}}

=== Package Overview ===
The following diagram represents the main classes of the <code>org.orekit.attitudes.kinematics</code> package:

[[File:kinematics.png|center]]

== Features Description ==
=== Quaternions differentiation ===
A quaternion can be differentiated using various methods:

* The quaternion differentiation’s formula <math>\dot{Q}_{S/R} = \frac{1}{2}Q_{S/R}\Omega_{S/R}^{[S]}</math>.
This formula connects time derivative of the quaternion q(t) with the vector of angular velocity W(t).

* When the quaternion is represented by a set of differentiable functions (Fourier series or polynomials), a direct analytic computation can be performed to get its derivative;

* Numerical differentiation (using finite difference, Ridders differentiation method, ...)

=== Quaternion integration ===
A rotation can be integrated, knowing its spin time function, using these methods:
* Wilcox method, with available approximations orders 1 to 4
* Edwards method, that corresponds to an order 3 approximation

=== Spin computation ===
The spin can be represented by a vector (instantaneous spin), or by a time-dependent function. 
The computation of the instantanous value of the spin can be made by one of the following methods:

* estimate the spin from two rotations corresponding to two different dates;
* using the kinematics equation when a quaternion and its derivative are known;
* compute the spin from the Euler or Cardan angles and their derivatives;
* using a direct analytic computation (when the function representing its variation over time is available).

=== Time-dependent orientation function===
The interface <code>OrientationFunction</code> and the abstract class <code>AbstractOrientationFunction</code> have been added to the kinematics package in order to represent a time-dependent orientation function.

These classes provide the following functionalities:

* return the orientation at a date, by the <code>getOrientation(AbsoluteDate)</code> method; it is an abstract method because it is specific to the orientation (or attitude) law the user wants to implement;

* return the function representing the derivative of the quaternion components, by the <code>derivative()</code> method. A numerical differentiation method is used to compute the derivatives, nevertheless the classes inheriting the <code>AbstractOrientationFunction</code> can override this method and return the analytical function representing the derivatives, when possible.

* compute the function representing the spin using the <math>\Omega_{S/R}^{[S]} = 2Q_{S/R}\dot{Q}_{S/R}</math> formula, by the <code>computeSpinFunction()</code> method. The derivatives of the quaternion are computed thanks to the <code>derivative()</code> method.

* estimate the function representing the spin using two rotations corresponding to two different dates (the velocity is supposed to be constant during the time interval between the two rotations), by the <code>estimateRateFunction(dt)</code> method.

* return the spin at a date, by the <code>computeSpin(AbsoluteDate)</code>, or <code>estimateRate(AbsoluteDate, dt)</code> methods (they call the <code>computeSpinFunction()</code> and <code>estimateRateFunction(dt)</code> methods)

=== Time-dependent spin function===
The interface <code>Vector3DFunction</code> and the abstract class <code>AbstractVector3DFunction</code> have been added to the kinematics package in order to represent a time-dependent vector 3D function; a vector 3D function is used to represent the spin, or the n-th derivative of the spin.

These classes provide the following functionalities:

* return the vector at a date, by the <code>getVector3D(AbsoluteDate)</code> method; it is an abstract method because it is specific to the spin (or derivative of the spin) the user wants to implement;

* return the function representing the n-th derivative of the vector, by the <code>nthDerivative(order)</code> method. A numerical differentiation method is used to compute the derivatives, nevertheless the classes inheriting the <code>AbstractVector3DFunction</code> can override this method and return the analytical function representing the derivatives, when possible. 
This method uses the Commons Math classes contained in the differentiation package, in particular the <code>DerivativeStructure</code> class, which allows to compute the n-th derivatives of a function at a point;

* return the integral of the function by the <code>integral(x0, xf)</code> method. A numerical integration method is used to compute the integral, nevertheless the classes inheriting the <code>AbstractVector3DFunction</code> can override this method and return the analytical function representing the integral, when possible.

The <code>DynamicsElements</code> object is created from a spin function and it gathers the n-th derivatives of spin at a given date; an attribute of this class is contained in the <code>Attitude</code> class.

=== Differentiate a quaternion ===
As a time-dependent quaternion can be represented by the <code>OrientationFunction</code> interface, the derivative of the quaternion can be computed using the <code>derivative()</code> method. As this method is implemented by the user, he can choose to use a numerical differentiation method or to compute the exact derivative, when possible. 

The derivative of a quaternion can be also computed using the kinematics equation: <math>\dot{Q}_{S/R} = \frac{1}{2}Q_{S/R}\Omega_{S/R}^{[S]}</math>.
This equation is implemented by the following method in the kinematics toolkit:

<syntaxhighlight lang="java">public static Quaternion differentiateQuaternion(final Quaternion q, final Vector3D spin)</syntaxhighlight>

=== Integrate a quaternion ===
The rotation integration is to be made by the following methods of the <code>KinematicsToolkit</code> class :

* Wilcox method : 

<syntaxhighlight lang="java">
Rotation finalRot = KinematicsToolkit.integrate(IntegrationType.WILCOX_1, 
initOrientation, initDate, finalDate, spin, dt);
</syntaxhighlight>

The order integer is the approximation order : the ones available are 1 to 4.

* Edwards method : 

<syntaxhighlight lang="java">
Rotation finalRot = KinematicsToolkit.integrate(IntegrationType.EDWARDS, 
initOrientation, initDate, finalDate, spin, dt);
</syntaxhighlight>

=== Differentiate and integrate a vector ===
In a similar way to the orientation function, a new class has been added in order to represent a time-dependent 3-D vector function. This class implements the <code>Vector3DFunction</code> interface, and it contains the methods to compute the derivative of the vector or its integral over a time period. The computation can be done using a numerical method or it can be analytical, when possible.

=== Compute the spin ===
The Kinematics package contains some methods aiming to compute the instantaneous spin. These methods are listed hereafter:

* Estimation: two rotations corresponding to two different dates are used to compute the spin (the velocity is supposed to be constant during the time interval between the two rotations).
This function is implemented by the following method in the kinematics toolkit:

<syntaxhighlight lang="java">public static Vector3D estimateSpin(final Rotation start, final Rotation end, final double dt)</syntaxhighlight>.

* <math>\Omega_{S/R}^{[S]} = 2Q_{S/R}\dot{Q}_{S/R}</math>, when knowing the derivative of the quaternion.
This equation is implemented by the following kinematics toolkit method:

<syntaxhighlight lang="java">public static Vector3D computeSpin(final Quaternion q, final Quaternion qd)</syntaxhighlight>.

* Using the derivative of the Euler or Cardan angles:
** Euler (not to be used when the angles are small):  
<math>\Omega_{S/R}^{[S]} = \left[ \begin{array}{c} \dot{\psi}\sin(\theta)\sin(\phi) + \dot{\theta}\cos(\phi) \\ \dot{\psi}\sin(\theta)\cos(\phi)- \dot{\theta}\sin(\phi) \\ \dot{\psi}\cos(\theta) + \dot{\phi} \end{array} \right]</math>
** Cardan (only to be used when the angles are small):
<math>\Omega_{S/R}^{[S]} = \left[ \begin{array}{c}-\dot{\psi}\sin(\theta)+\dot{\phi} \\ \dot{\psi}\cos(\theta)\sin(\phi) + \dot{\theta}\cos(\phi) \\ \dot{\psi}\cos(\theta)\cos(\phi) - \dot{\theta}\sin(\phi) \end{array} \right]</math>

These formula are implemented by the following kinematics toolkit method:

<syntaxhighlight lang="java">public static Vector3D computeSpin(final double[] ang, final double[] angd, final RotationOrder order)</syntaxhighlight>.

* Analytic computation: if the spin is represented by a function, its instantaneous value must be obtained by direct analytic computation (the <code>IVector3DFunction</code> classes have been created for this purpose)

== Getting Started ==
TBD

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''OrientationFunction'''
|This interface represents a generic univariate orientation function.
|[{{JavaDoc3.4.1}}/org/orekit/attitudes/kinematics/OrientationFunction.html ...]
|-
|'''Vector3DFunction'''
|This interface represents a generic univariate 3-D vector function.
|[{{JavaDoc3.4.1}}/org/orekit/attitudes/kinematics/Vector3DFunction.html ...]
|}


=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AbstractOrientationFunction'''
|This class represents an orientation function.
|[{{JavaDoc3.4.1}}/org/orekit/attitudes/kinematics/AbstractOrientationFunction.html ...]
|-
|'''AbstractVector3DFunction'''
|This class represents a spin function, or a spin n-th derivative function.
|[{{JavaDoc3.4.1}}/org/orekit/attitudes/kinematics/AbstractVector3DFunction.html ...]
|}

[[Category:User_Manual_3.4.1_Attitude]]