User Manual 3.4.1 AngularCoordinates, Attitude and Transform : how to use them

User Manual 3.4.1 AngularCoordinates, Attitude and Transform : how to use them

Angular coordinates

The AngularCoordinates class contains an orientation and its associated rotation rate. Its use is similar to PVCoordinates.

Orientation

The orientation is described by a rotation. This Rotation is the one that transforms the reference frame into the frame of interest. It is expressed in the reference frame.

[math]\vec{X_{int / ref}} = R(\vec{X_{ref / ref}})[/math] [math]\vec{Y_{int / ref}} = R(\vec{Y_{ref / ref}})[/math] [math]\vec{Z_{int / ref}} = R(\vec{Z_{ref / ref}})[/math]

Rotation Rate

The Rotation Rate is a 3D vector expressed in the frame of interest. Its norm is the angular velocity of the frame of interest. Its direction is the instant axis of spin. Here is the case of a spin around the Z axis :

Rotation Acceleration

The Rotation Acceleration is a 3D vector expressed in the frame of interest. Its norm is the angular acceleration of the frame of interest. As the rotation rate, its direction is the instant axis of spin (see image above).

As the classes implementing AttitudeLaw, the computation of this acceleration must be desactived (see Attitude law description) at construction of an instance of the class using the boolean in constructor :

AngularCoordinates(final PVCoordinates u1, final PVCoordinates u2,
                   final PVCoordinates v1, final PVCoordinates v2,
                   final double tolerance, final boolean spinDerivativesComputation)

One can obtain more details about using this constructor reading AngularCoordinates.

Use example : time shifting the orientation

The orientation can be basically shifted in time using the rotation rate. Here is an example of code realizing this computation. It allows some reflexions about the different frames of expression involved.

// getting the content of the angular coordinates
Vector3D rotation_acceleration = angularCoordinates.getRotationAcceleration()
Vector3D rotation_rate = angularCoordinates.getRotationRate();
Rotation orientation = angularCoordinates.getRotation();
 
// To compose two rotations, they must be expressed in the same frame. 
// The orientation is expressed in the reference frame, so the shift (evolution of the rotation) has to be expressed in the reference frame too. 
// To create it, the rotation rate has itself to be expressed in the reference frame. 
// Here is how it shall be obtained :
Vector3D rotation_rate_in_ref_frame = orientation.applyTo(rotation_rate);
 
// the rotation shift can then be created ("dt" is the time duration of the shift) :
Rotation shift = new Rotation(rotation_rate_in_ref_frame, rotation_rate_in_ref_frame.getNorm()* dt);
 
// the new orienation can finally be computed
Rotation finalRotation = shift.applyTo(orientation);

The shifted rotation can be directly retrieved using the method shiftedBy of AngularCoordinates.

AngularCoordinates shifted = angularCoordinates.shiftedBy(dt);
Rotation shiftedRotation = shifted.getRotation();

Attitude

An attitude object contains all the information about the satellite's orientation at a date :

• The time stamped angular coordinates of the frame of interest in the reference frame (wich can be the "satellite frame" or another according to the user's needs)
• The reference Frame

The convention used to describe the orientation of the frame of interest in Attitude is the same as in AngularCoordinates : the rotation returned by Attitude.getRotation() is the one that transforms the reference frame into the frame of interest.

The Attitude class also provides a static method (Attitude.slerp(date, attitude1, attitue2, frame)) to perform interpolation with SLERP method. In term of computational time, it is more performant than Attitude.interpolate(...) but to perform more accurate interpolation, the user should use Attitude.interpolate(...) .

Use example : changing a vector's frame of expression

This convention implies that if one wants to change the frame of expression of a vector from the reference frame to the frame of interest, the computation shall involve the inverse of the orientation :

Vector3D vector_in_ref_frame = new Vector3D(a, b, c);
 
Rotation orientation = myAttitude.getRotation();
 
Vector3D vector_in_sat_frame = orientation.applyInverseTo(vector_in_ref_frame);

Transform

Transform object describes the position, velocity, orientation and rotation rate of a "destination" frame in an "origin" frame.

Transform provides the methods tranformVector(...), tranformPosition(...), tranformVelocity(...), etc... that change the frame of expression of those objects from "origin" to "destination".

The convention used to describe the orientation and rotation rate of the "destination" frame in Transform is the same as in AngularCoordinates : the rotation returned by Transform.getRotation() is the one that transforms the basis vectors of the "origin" frame into the ones of the "destination" frame.

The position and velocity of the "destination" are expressed in the "origin" frame.

Use example : creating a satellite frame

In the following example, the "origin" is a terrestrial frame and the "destination" is a frozen satellite frame : the position and velocity in Transform are the ones of the spacecraft.

// CREATION OF THE TRANSFORM AND SATELLITE FRAME
//-----------------------------------------------
 
 
// satellite pvCoordinates in GCRF
PVCoordinates pvCoordinates = new PVCoordinates(position, velocity);
 
// satellite Angular Coordinates
AngularCoordinates attitudeCoordinates = attitude.getOrientation();
 
// transformation "from GCRF to satellite frame"
Transform gcrf_to_sat = new Transform(date, pvCoordinates, attitudeCoordinates );
 
// satellite frame creation
Frame satFrame = new Frame(FramesFactory.getGCRF(), gcrf_to_sat, "satFrame");
 
// USE OF THE TRANSFORM
//-----------------------------------------------
 
// X vector of the satellite frame
Vector3D x_satFrame = Vector3D.PLUS_I;
 
// the same vector expressed in GCRF
Vector3D x_sat_in_GCRF = gcrf_to_sat.getInverse().transformVector(x_satFrame);

More code examples

Here is an example of code that may help understanding the use of rotations in attitudes and frames transformations.

// GCRF, reference frame
final Frame gcrf = FramesFactory.getGCRF();
 
// Axis of the GCRF frame, expressed in GCRF
final Vector3D xGCRF_inGCRF = Vector3D.PLUS_I;
final Vector3D yGCRF_inGCRF = Vector3D.PLUS_J;
final Vector3D zGCRF_inGCRF = Vector3D.PLUS_K;
 
// Directions associated to those axis
final IDirection xGCRF = new ConstantVectorDirection(xGCRF_inGCRF, gcrf);
final IDirection yGCRF = new ConstantVectorDirection(yGCRF_inGCRF, gcrf);
final IDirection zGCRF = new ConstantVectorDirection(zGCRF_inGCRF, gcrf);
 
// Creation of a "zero" PV provider
final PVCoordinatesProvider pvProv = new PVCoordinatesProvider() {
public PVCoordinates getPVCoordinates(AbsoluteDate date, Frame frame)
throws OrekitException {
return new PVCoordinates(Vector3D.ZERO, Vector3D.ZERO);
}
};
 
// a date...
final AbsoluteDate date = new AbsoluteDate(2014, 10, 2, 11, 46, 00,
TimeScalesFactory.getTAI());
 
// Axis of the satellite frame, expressed in the satellite frame
final Vector3D xSat_inRSat = Vector3D.PLUS_I;
final Vector3D ySat_inRSat = Vector3D.PLUS_J;
final Vector3D zSat_inRSat = Vector3D.PLUS_K;
 
// The attitude law :
//- axe Xsat on Y_GCRF,
//- axe Ysat "as close as possible" to Z_GCRF.
// We are implicitly defining the orientation of the satellite frame.
final AttitudeLaw attLaw = new TwoDirectionsAttitude(yGCRF, zGCRF, xSat_inRSat, ySat_inRSat);
 
// Attitude computation,
// and getting of the associated rotation.
Attitude att = attLaw.getAttitude(pvProv, date, gcrf);
Rotation rot = att.getRotation ();
 
// Computation of the axis of the satellite frame in the GCRF
Vector3D xSat_inGCRF = rot.applyTo(xGCRF_inGCRF);
Vector3D ySat_inGCRF = rot.applyTo(yGCRF_inGCRF);
Vector3D zSat_inGCRF = rot.applyTo(zGCRF_inGCRF);
 
// Print
System.out.println("xSat_inGCRF: " + xSat_inGCRF);
System.out.println("ySat_inGCRF: " + ySat_inGCRF);
System.out.println("zSat_inGCRF: " + zSat_inGCRF);
 
// getting the attitude quaternion
Quaternion q = rot.getQuaternion ();
System.out.println("quaternion: " + q);
 
// Printing the axis and angle of the rotation,
// to visualize its "right" definition.
System.out.println(" axis: " + rot.getAxis());
System.out.println(" angle: " + rot.getAngle());
 
// Creation of the satellite frame
AttitudeFrame attFrame = new AttitudeFrame(pvProv, attLaw, gcrf);
 
// getting the transformation from the satellite frame to the GCRF
Transform transform = attFrame.getTransformTo(gcrf, date);
 
// Changing the expression frame of Xsat from Rsat into GCRF
// to match the previous result :
System.out.println("xSat_inGCRF: " + xSat_inGCRF);
System.out.println("transform.transformVector(xSat_inRSat): " +
transform.transformVector(xSat_inRSat));