agi.foundation.coordinates

(agi.foundation.core-2024r3.jar)

Class EulerSequence

java.lang.Object

agi.foundation.coordinates.EulerSequence

All Implemented Interfaces:

IEquatable<EulerSequence>, ImmutableValueType, ValueType, IEquatableEpsilon<EulerSequence>

public final class EulerSequence
extends Object
implements IEquatable<EulerSequence>, IEquatableEpsilon<EulerSequence>, ImmutableValueType

Represents a rotation as a sequence of three ElementaryRotations about consecutive axes. The first elementary rotation results in an intermediate orientation and associated set of axes from which the second elementary rotation is performed. Likewise, the third elementary rotation is performed from the intermediate orientation and set of axes which result from the second rotation.

A 321 Euler sequence is commonly used to represent yaw about the z-axis, followed by pitch about the resulting y-axis, and then roll about the resulting x-axis when expressing the attitude of a vehicle relative to some reference orientation.

A 321 Euler sequence can be used to express the yaw (heading), pitch (elevation), and roll (bank) orientation of the vehicle body axis relative to the local North-East-Down axes of the vehicle. To obtain these angles, use a 321 EulerSequence as shown below:

Point myVehiclePoint = propagator.createPoint();
EarthCentralBody earth = CentralBodiesFacet.getFromContext().getEarth();
AxesNorthEastDown ned = new AxesNorthEastDown(earth, myVehiclePoint);
Vector surfaceNormal = new VectorEllipsoidSurfaceNormal(earth.getShape(), earth.getFixedFrame(), myVehiclePoint);
AxesAlignedConstrained vehicleBodyAxes = new AxesAlignedConstrained(
        new VectorVelocity(myVehiclePoint, earth.getFixedFrame()), AxisIndicator.FIRST,
        new VectorInverted(surfaceNormal), AxisIndicator.THIRD);

AxesEvaluator rotationEvaluator = GeometryTransformer.getAxesTransformation(ned, vehicleBodyAxes);

UnitQuaternion ned2body = rotationEvaluator.evaluate(propagator.getTimeInterval().getStart());

EulerSequence yawPitchRoll = new EulerSequence(ned2body, EulerSequenceIndicator.EULER321);
double yaw = yawPitchRoll.getFirstRotation().getAngle();
double pitch = yawPitchRoll.getSecondRotation().getAngle();
double roll = yawPitchRoll.getThirdRotation().getAngle();

See Also:

AngleAxisRotation, ElementaryRotation, Matrix3By3, Quaternion, UnitQuaternion, YawPitchRoll

Constructor Summary

Constructors

Constructor and Description
EulerSequence() Initializes a new instance.
EulerSequence(AngleAxisRotation rotation, EulerSequenceIndicator sequence) Initializes an EulerSequence from the provided AngleAxisRotation and sequence.
EulerSequence(double angle1, double angle2, double angle3, EulerSequenceIndicator sequence) Initializes an EulerSequence from the provided angles and sequence.
EulerSequence(ElementaryRotation firstRotation, ElementaryRotation secondRotation, ElementaryRotation thirdRotation) Initializes an EulerSequence from the provided ElementaryRotations.
EulerSequence(Matrix3By3 matrix, EulerSequenceIndicator sequence) Initializes an EulerSequence from the provided Matrix3By3 and sequence.
EulerSequence(UnitQuaternion quaternion, EulerSequenceIndicator sequence) Initializes an EulerSequence from the provided UnitQuaternion and sequence.
EulerSequence(YawPitchRoll sequence) Initializes an EulerSequence from the provided YawPitchRoll sequence.

Method Summary

Modifier and Type	Method and Description
static boolean	equals(EulerSequence left, EulerSequence right) Returns true if the two instances are exactly equal.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
boolean	equalsEpsilon(EulerSequence other, double epsilon) Returns true if all of the elements of this rotation are within epsilon of the same elements of the specified rotation.
boolean	equalsType(EulerSequence other) Indicates whether another instance of this type is exactly equal to this instance.
static AxisIndicator	firstAxis(EulerSequenceIndicator sequence) Determines the first axis indicator from the provided EulerSequenceIndicator.
ElementaryRotation	getFirstRotation() Gets the first rotation.
ElementaryRotation	getSecondRotation() Gets the second rotation.
EulerSequenceIndicator	getSequence() Gets the order of the axes rotations for this instance.
ElementaryRotation	getThirdRotation() Gets the third rotation.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
static EulerSequenceIndicator	indicator(AxisIndicator first, AxisIndicator second, AxisIndicator third) Composes a EulerSequenceIndicator from three individual AxisIndicator items.
EulerSequence	invert() Inverts this instance, yielding a new EulerSequence.
static boolean	notEquals(EulerSequence left, EulerSequence right) Returns true if the two instances are not exactly equal.
static AxisIndicator	secondAxis(EulerSequenceIndicator sequence) Determines the second axis indicator from the provided EulerSequenceIndicator.
static AxisIndicator	thirdAxis(EulerSequenceIndicator sequence) Determines the third axis indicator from the provided EulerSequenceIndicator.
String	toString() Returns the value of this set of EulerSequence coordinates in the form "first rotation, second rotation, third rotation"

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EulerSequence

public EulerSequence()

Initializes a new instance.

EulerSequence

public EulerSequence(double angle1,
                     double angle2,
                     double angle3,
                     @Nonnull
                     EulerSequenceIndicator sequence)

Initializes an EulerSequence from the provided angles and sequence.

Parameters:

angle1 - The first angle.

angle2 - The second angle.

angle3 - The third angle.

sequence - The sequence.

EulerSequence

public EulerSequence(@Nonnull
                     ElementaryRotation firstRotation,
                     @Nonnull
                     ElementaryRotation secondRotation,
                     @Nonnull
                     ElementaryRotation thirdRotation)

Initializes an EulerSequence from the provided ElementaryRotations.

Parameters:

firstRotation - The first rotation.

secondRotation - The second rotation.

thirdRotation - The third rotation.

EulerSequence

public EulerSequence(@Nonnull
                     YawPitchRoll sequence)

Initializes an EulerSequence from the provided YawPitchRoll sequence.

Parameters:

sequence - The sequence.

EulerSequence

public EulerSequence(@Nonnull
                     Matrix3By3 matrix,
                     @Nonnull
                     EulerSequenceIndicator sequence)

Initializes an EulerSequence from the provided Matrix3By3 and sequence.

Note that the matrix must be an orthogonal rotation matrix.

Parameters:

matrix - The orthogonal rotation matrix.

sequence - The sequence.

EulerSequence

public EulerSequence(@Nonnull
                     UnitQuaternion quaternion,
                     @Nonnull
                     EulerSequenceIndicator sequence)

Initializes an EulerSequence from the provided UnitQuaternion and sequence.

Parameters:

quaternion - The unit quaternion.

sequence - The sequence.

EulerSequence

public EulerSequence(@Nonnull
                     AngleAxisRotation rotation,
                     @Nonnull
                     EulerSequenceIndicator sequence)

Initializes an EulerSequence from the provided AngleAxisRotation and sequence.

Parameters:

rotation - The rotation.

sequence - The sequence.

Method Detail

indicator

@Nonnull
public static EulerSequenceIndicator indicator(@Nonnull
                                                         AxisIndicator first,
                                                         @Nonnull
                                                         AxisIndicator second,
                                                         @Nonnull
                                                         AxisIndicator third)

Composes a EulerSequenceIndicator from three individual AxisIndicator items.

Parameters:

first - The first axis of rotation.

second - The second axis of rotation.

third - The third axis of rotation.

Returns:

The indicator.

firstAxis

@Nonnull
public static AxisIndicator firstAxis(@Nonnull
                                                EulerSequenceIndicator sequence)

Determines the first axis indicator from the provided EulerSequenceIndicator.

Parameters:

sequence - The order of the axes of rotation.

Returns:

The first axis indicator.

secondAxis

@Nonnull
public static AxisIndicator secondAxis(@Nonnull
                                                 EulerSequenceIndicator sequence)

Determines the second axis indicator from the provided EulerSequenceIndicator.

Parameters:

sequence - The order of the axes of rotation.

Returns:

The second axis indicator.

thirdAxis

@Nonnull
public static AxisIndicator thirdAxis(@Nonnull
                                                EulerSequenceIndicator sequence)

Determines the third axis indicator from the provided EulerSequenceIndicator.

Parameters:

sequence - The order of the axes of rotation.

Returns:

The third axis indicator.

getFirstRotation

@Nonnull
public final ElementaryRotation getFirstRotation()

Gets the first rotation.

getSecondRotation

@Nonnull
public final ElementaryRotation getSecondRotation()

Gets the second rotation.

getThirdRotation

@Nonnull
public final ElementaryRotation getThirdRotation()

Gets the third rotation.

getSequence

@Nonnull
public final EulerSequenceIndicator getSequence()

Gets the order of the axes rotations for this instance.

invert

@Nonnull
public final EulerSequence invert()

Inverts this instance, yielding a new EulerSequence.

Returns:

The inverted EulerSequence.

equals

public boolean equals(Object obj)

Indicates whether another object is exactly equal to this instance.

Overrides:

equals in class Object

Parameters:

obj - The object to compare to this instance.

Returns:

true if obj is an instance of this type and represents the same value as this instance; otherwise false.

See Also:

Object.hashCode(), HashMap

equalsType

public final boolean equalsType(@Nonnull
                                EulerSequence other)

Indicates whether another instance of this type is exactly equal to this instance.

Specified by:

equalsType in interface IEquatable<EulerSequence>

Parameters:

other - The instance to compare to this instance.

Returns:

true if other represents the same value as this instance; otherwise false.

equalsEpsilon

public final boolean equalsEpsilon(@Nonnull
                                   EulerSequence other,
                                   double epsilon)

Returns true if all of the elements of this rotation are within epsilon of the same elements of the specified rotation. That is, in order for the rotations to be considered equal (and for this function to return true), the absolute value of the difference between each of their elements must be less than or equal to epsilon.

Specified by:

equalsEpsilon in interface IEquatableEpsilon<EulerSequence>

Parameters:

other - The rotation to compare to this rotation.

epsilon - The largest difference between the elements of the rotations for which they will be considered equal.

Returns:

true if the rotations are equal as defined by the epsilon value.

hashCode

public int hashCode()

Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.

Overrides:

hashCode in class Object

Returns:

A hash code for the current object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

public String toString()

Returns the value of this set of EulerSequence coordinates in the form "first rotation, second rotation, third rotation"

Overrides:

toString in class Object

Returns:

The string.

equals

public static boolean equals(@Nonnull
                             EulerSequence left,
                             @Nonnull
                             EulerSequence right)

Returns true if the two instances are exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left represents the same value as right; otherwise false.

notEquals

public static boolean notEquals(@Nonnull
                                EulerSequence left,
                                @Nonnull
                                EulerSequence right)

Returns true if the two instances are not exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left does not represent the same value as right; otherwise false.