User Manual 3.3 AngularCoordinates, Attitude and Transform : how to use them
Sommaire
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));