agi.foundation.coordinates

(agi.foundation.core-2025r1.jar)

Class AngleAxisRotation

java.lang.Object

agi.foundation.coordinates.AngleAxisRotation

All Implemented Interfaces:

IEquatable<AngleAxisRotation>, ImmutableValueType, ValueType, IEquatableEpsilon<AngleAxisRotation>

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

Represents a rotation as a unit vector indicating the axis of rotation and an angle indicating the amount of rotation about the axis.

See Also:

ElementaryRotation, EulerSequence, Matrix3By3, Quaternion, UnitQuaternion, YawPitchRoll

Constructor Summary

Constructors

Constructor and Description
AngleAxisRotation() Initializes a new instance.
AngleAxisRotation(double[] elements) Initializes a set of AngleAxisRotation coordinates from the first 4 consecutive elements in the provided array.
AngleAxisRotation(double[] elements, int startIndex) Initializes a set of AngleAxisRotation coordinates from the provided array.
AngleAxisRotation(double angle, UnitCartesian axis) Initializes a set of AngleAxisRotation coordinates from the provided values.
AngleAxisRotation(ElementaryRotation rotation) Initializes a set of AngleAxisRotation coordinates from the provided ElementaryRotation.
AngleAxisRotation(EulerSequence sequence) Initializes a set of AngleAxisRotation coordinates from the provided EulerSequence.
AngleAxisRotation(Matrix3By3 matrix) Initializes a set of AngleAxisRotation coordinates from the provided Matrix3By3.
AngleAxisRotation(UnitQuaternion quaternion) Initializes a set of AngleAxisRotation coordinates from the provided UnitQuaternion.
AngleAxisRotation(YawPitchRoll sequence) Initializes a set of AngleAxisRotation coordinates from the provided YawPitchRoll.

Method Summary

Modifier and Type	Method and Description
static boolean	equals(AngleAxisRotation left, AngleAxisRotation 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(AngleAxisRotation 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(AngleAxisRotation other) Indicates whether another instance of this type is exactly equal to this instance.
double	get(int index) Gets the value of the specified element with 0, 1, 2, and 3 corresponding to the elements Angle, Axis.X, Axis.Y, and Axis.Z.
double	getAngle() Gets the angle coordinate.
UnitCartesian	getAxis() Gets the unit vector representation the axis of rotation.
int	getLength() Gets the number of elements.
static AngleAxisRotation	getZero() Gets the set of AngleAxisRotation coordinates representing the zero vector.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
AngleAxisRotation	invert() Returns the inverse of this angle-axis rotation.
static AngleAxisRotation	multiply(AngleAxisRotation rotation, double scalar) Multiplies a specified AngleAxisRotation by a scalar, yielding a new AngleAxisRotation.
AngleAxisRotation	multiply(double scalar) Multiplies this instance by a scalar, yielding a new AngleAxisRotation.
static AngleAxisRotation	multiply(double scalar, AngleAxisRotation rotation) Multiplies a scalar by a specified AngleAxisRotation, yielding a new AngleAxisRotation.
static boolean	notEquals(AngleAxisRotation left, AngleAxisRotation right) Returns true if the two instances are not exactly equal.
String	toString() Returns the value of this set of AngleAxisRotation coordinates in the form "angle, axis"

Methods inherited from class java.lang.Object

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

Constructor Detail

AngleAxisRotation

public AngleAxisRotation()

Initializes a new instance.

AngleAxisRotation

public AngleAxisRotation(double angle,
                         @Nonnull
                         UnitCartesian axis)

Initializes a set of AngleAxisRotation coordinates from the provided values.

Parameters:

angle - The angle of rotation.

axis - The unit Cartesian vector representation the axis of rotation.

AngleAxisRotation

public AngleAxisRotation(@Nonnull
                         EulerSequence sequence)

Initializes a set of AngleAxisRotation coordinates from the provided EulerSequence.

Parameters:

sequence - The Euler sequence of rotations.

AngleAxisRotation

public AngleAxisRotation(@Nonnull
                         YawPitchRoll sequence)

Initializes a set of AngleAxisRotation coordinates from the provided YawPitchRoll.

Parameters:

sequence - The yaw-pitch-roll sequence of rotations.

AngleAxisRotation

public AngleAxisRotation(@Nonnull
                         ElementaryRotation rotation)

Initializes a set of AngleAxisRotation coordinates from the provided ElementaryRotation.

Parameters:

rotation - The elementary rotation.

Throws:

UnsupportedCaseException - Thrown if rotation's Axis (get) property is not an AxisIndicator.FIRST, AxisIndicator.SECOND, or AxisIndicator.THIRD.

AngleAxisRotation

public AngleAxisRotation(@Nonnull
                         UnitQuaternion quaternion)

Initializes a set of AngleAxisRotation coordinates from the provided UnitQuaternion.

If quaternion is Identity (get), the resulting instance will be a 0.0 rotation around the X-axis.

Parameters:

quaternion - The quaternion.

AngleAxisRotation

public AngleAxisRotation(@Nonnull
                         Matrix3By3 matrix)

Initializes a set of AngleAxisRotation coordinates from the provided Matrix3By3.

Parameters:

matrix - The 3-by-3 rotation matrix.

AngleAxisRotation

public AngleAxisRotation(@Nonnull
                         double[] elements)

Initializes a set of AngleAxisRotation coordinates from the first 4 consecutive elements in the provided array.

Parameters:

elements - The array of element values.

Throws:

ArgumentNullException - Thrown when elements is null.

ArgumentOutOfRangeException - Thrown when an object of this type is constructed from an array with less than 4 elements.

AngleAxisRotation

public AngleAxisRotation(@Nonnull
                         double[] elements,
                         int startIndex)

Initializes a set of AngleAxisRotation coordinates from the provided array.

Parameters:

elements - The array of element values.

startIndex - The index of the first element in the array to use.

Throws:

ArgumentNullException - Thrown when elements is null.

ArgumentOutOfRangeException - Thrown when an object of this type is constructed from an array with less than 4 elements.

Method Detail

getZero

@Nonnull
public static AngleAxisRotation getZero()

Gets the set of AngleAxisRotation coordinates representing the zero vector.

Returns:

The set of AngleAxisRotation coordinates representing the zero vector.

getAngle

public final double getAngle()

Gets the angle coordinate.

getAxis

@Nonnull
public final UnitCartesian getAxis()

Gets the unit vector representation the axis of rotation.

invert

@Nonnull
public final AngleAxisRotation invert()

Returns the inverse of this angle-axis rotation.

Returns:

The resulting angle-axis rotation.

multiply

@Nonnull
public final AngleAxisRotation multiply(double scalar)

Multiplies this instance by a scalar, yielding a new AngleAxisRotation.

Parameters:

scalar - The scalar.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static AngleAxisRotation multiply(@Nonnull
                                                   AngleAxisRotation rotation,
                                                   double scalar)

Multiplies a specified AngleAxisRotation by a scalar, yielding a new AngleAxisRotation.

Parameters:

rotation - The rotation.

scalar - The scalar.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static AngleAxisRotation multiply(double scalar,
                                                   @Nonnull
                                                   AngleAxisRotation rotation)

Multiplies a scalar by a specified AngleAxisRotation, yielding a new AngleAxisRotation.

Parameters:

scalar - The scalar.

rotation - The rotation.

Returns:

The result of the multiplication.

getLength

public final int getLength()

Gets the number of elements.

get

public final double get(int index)

Gets the value of the specified element with 0, 1, 2, and 3 corresponding to the elements Angle, Axis.X, Axis.Y, and Axis.Z.

Parameters:

index - The index.

Returns:

The value of the specified element.

Throws:

ArgumentOutOfRangeException - Thrown when index is less than 0 or greater than or equal to Length (get).

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
                                AngleAxisRotation other)

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

Specified by:

equalsType in interface IEquatable<AngleAxisRotation>

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
                                   AngleAxisRotation 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 two items 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<AngleAxisRotation>

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 AngleAxisRotation coordinates in the form "angle, axis"

Overrides:

toString in class Object

Returns:

The string.

equals

public static boolean equals(@Nonnull
                             AngleAxisRotation left,
                             @Nonnull
                             AngleAxisRotation 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
                                AngleAxisRotation left,
                                @Nonnull
                                AngleAxisRotation 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.