agi.foundation.coordinates

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

Class Matrix3By3

java.lang.Object

agi.foundation.coordinates.Matrix3By3

All Implemented Interfaces:

IEquatable<Matrix3By3>, ImmutableValueType, ValueType, IEquatableEpsilon<Matrix3By3>

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

A 3-by-3 matrix. This type is often used to represent a rotation. This represents an 'alias' rotation which transforms coordinates by modifying the underlying coordinate basis rather than modifying the coordinates themselves.

For more information, see the Coordinates topic.

See Also:

AngleAxisRotation, ElementaryRotation, EulerSequence, Quaternion, UnitQuaternion, YawPitchRoll

Constructor Summary

Constructors

Constructor and Description
Matrix3By3() Initializes a new instance.
Matrix3By3(AngleAxisRotation rotation) Initializes a new instance from an angle axis rotation.
Matrix3By3(double m11, double m12, double m13, double m21, double m22, double m23, double m31, double m32, double m33) Initializes a new instance from elements.
Matrix3By3(EigenDecomposition eigenDecomposition) Initializes a new instance from an EigenDecomposition.
Matrix3By3(ElementaryRotation rotation) Initializes a new instance representing an elementary rotation about one of the original axes.
Matrix3By3(EulerSequence sequence) Initializes a new instance from the provided EulerSequence.
Matrix3By3(Matrix3By3Symmetric matrix) Initializes a new instance from a Matrix3By3Symmetric.
Matrix3By3(UnitQuaternion quaternion) Initializes a new instance from a UnitQuaternion.
Matrix3By3(YawPitchRoll sequence) Initializes a new instance from the provided YawPitchRoll sequence.

Method Summary

Modifier and Type	Method and Description
Matrix3By3	add(Matrix3By3 matrix) Adds a matrix to this matrix.
static Matrix3By3	add(Matrix3By3 left, Matrix3By3 right) Adds a matrix to this matrix.
static Matrix3By3	add(Matrix3By3 left, Matrix3By3Symmetric right) Adds a matrix to this matrix.
Matrix3By3	add(Matrix3By3Symmetric matrix) Adds a matrix to this matrix.
static Matrix3By3	crossProductEquivalentMatrix(Cartesian vector) Forms a Matrix3By3 from the input vector such that the result of the cross product of the input vector with another vector is equivalent to premultiplying the other vector by the returned matrix.
static Matrix3By3	crossProductEquivalentMatrix(UnitCartesian vector) Forms a Matrix3By3 from the input vector such that the result of the cross product of the input unit vector with another vector is equivalent to premultiplying the other vector by the returned matrix.
double	determinant() Calculates the determinant of the matrix.
static Matrix3By3	diagonalMatrix(Cartesian vector) Forms a diagonal matrix from the input vector.
static Matrix3By3	diagonalMatrix(double m11, double m22, double m33) Forms a diagonal matrix from the input elements.
static Matrix3By3	diagonalMatrix(UnitCartesian vector) Forms a diagonal matrix from the input unit vector.
static boolean	equals(Matrix3By3 left, Matrix3By3 right) Returns true if the two instances are exactly equal.
boolean	equals(Matrix3By3Symmetric other) Indicates whether another instance of this type is exactly equal to this instance.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
boolean	equalsEpsilon(Matrix3By3 other, double epsilon) Returns true if all of the elements of this matrix are within epsilon of the same elements of the specified matrix.
boolean	equalsType(Matrix3By3 other) Indicates whether another instance of this type is exactly equal to this instance.
double	frobeniusNorm() Computes the Frobenius norm of the matrix.
double	frobeniusNormSquared() Computes the square of the Frobenius norm of the matrix.
double	get(int row, int column) Accesses the matrix elements using zero-based indexing.
static Matrix3By3	getIdentity() Gets a Matrix3By3 representing an identity transformation.
boolean	getIsUndefined() Gets a value indicating whether any of the matrix values are Double.NaN.
double	getM11() Gets the element in the first row, first column.
double	getM12() Gets the element in the first row, second column.
double	getM13() Gets the element in the first row, third column.
double	getM21() Gets the element in the second row, first column.
double	getM22() Gets the element in the second row, second column.
double	getM23() Gets the element in the second row, third column.
double	getM31() Gets the element in the third row, first column.
double	getM32() Gets the element in the third row, second column.
double	getM33() Gets the element in the third row, third column.
static Matrix3By3	getUndefined() Gets a Matrix3By3 with elements of Double.NaN.
static Matrix3By3	getZero() Gets a Matrix3By3 representing the zero matrix.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
Matrix3By3	invert() Inverts the matrix.
Cartesian	multiply(Cartesian vector) Forms a new Cartesian vector as the product of this 3-by-3 matrix and the provided Cartesian vector.
Matrix3By3	multiply(double scalar) Multiplies this matrix by a scalar.
static Matrix3By3	multiply(double scalar, Matrix3By3 matrix) Multiplies a scalar by a matrix.
Matrix3By3	multiply(ElementaryRotation rotation) Forms a new 3-by-3 matrix as the product of this 3-by-3 matrix and the provided elementary rotation.
Matrix3By3	multiply(Matrix3By3 matrix) Multiplies this matrix by a matrix.
static Cartesian	multiply(Matrix3By3 matrix, Cartesian vector) Multiplies the 3-by-3 matrix by the Cartesian vector.
static Matrix3By3	multiply(Matrix3By3 matrix, double scalar) Multiplies a matrix by a scalar.
static Matrix3By3	multiply(Matrix3By3 matrix, ElementaryRotation rotation) Multiplies a 3-by-3 matrix by an ElementaryRotation.
static Matrix3By3	multiply(Matrix3By3 left, Matrix3By3 right) Multiplies the left matrix by the right matrix.
static Matrix3By3	multiply(Matrix3By3 left, Matrix3By3Symmetric right) Multiplies the left matrix by the right matrix.
Matrix3By3	multiply(Matrix3By3Symmetric matrix) Multiplies this matrix by a matrix.
static boolean	notEquals(Matrix3By3 left, Matrix3By3 right) Returns true if the two instances are not exactly equal.
Matrix3By3	subtract(Matrix3By3 matrix) Subtracts a matrix from this matrix.
static Matrix3By3	subtract(Matrix3By3 left, Matrix3By3 right) Subtracts the second matrix from the first.
static Matrix3By3	subtract(Matrix3By3 left, Matrix3By3Symmetric right) Subtracts the second matrix from the first.
Matrix3By3	subtract(Matrix3By3Symmetric matrix) Subtracts a matrix from this matrix.
Matrix3By3	transpose() Transposes the matrix.

Methods inherited from class java.lang.Object

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

Constructor Detail

Matrix3By3

public Matrix3By3()

Initializes a new instance.

Matrix3By3

public Matrix3By3(@Nonnull
                  EulerSequence sequence)

Initializes a new instance from the provided EulerSequence.

Parameters:

sequence - The Euler sequence of rotations.

Matrix3By3

public Matrix3By3(@Nonnull
                  YawPitchRoll sequence)

Initializes a new instance from the provided YawPitchRoll sequence.

Parameters:

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

Matrix3By3

public Matrix3By3(@Nonnull
                  ElementaryRotation rotation)

Initializes a new instance representing an elementary rotation about one of the original axes.

Parameters:

rotation - The elementary rotation.

Throws:

UnsupportedCaseException - Thrown if the Axis (get) property of rotation is not AxisIndicator.FIRST, AxisIndicator.SECOND, or AxisIndicator.THIRD.

Matrix3By3

public Matrix3By3(@Nonnull
                  AngleAxisRotation rotation)

Initializes a new instance from an angle axis rotation.

Parameters:

rotation - The angle axis rotation.

Matrix3By3

public Matrix3By3(@Nonnull
                  UnitQuaternion quaternion)

Initializes a new instance from a UnitQuaternion.

Parameters:

quaternion - The quaternion.

Matrix3By3

public Matrix3By3(double m11,
                  double m12,
                  double m13,
                  double m21,
                  double m22,
                  double m23,
                  double m31,
                  double m32,
                  double m33)

Initializes a new instance from elements.

Parameters:

m11 - 1,1

m12 - 1,2

m13 - 1,3

m21 - 2,1

m22 - 2,2

m23 - 2,3

m31 - 3,1

m32 - 3,2

m33 - 3,3

Matrix3By3

public Matrix3By3(@Nonnull
                  Matrix3By3Symmetric matrix)

Initializes a new instance from a Matrix3By3Symmetric.

Parameters:

matrix - The symmetric matrix.

Matrix3By3

public Matrix3By3(@Nonnull
                  EigenDecomposition eigenDecomposition)

Initializes a new instance from an EigenDecomposition.

Parameters:

eigenDecomposition - The eigenvectors and eigenvalues of the matrix.

Method Detail

getIdentity

@Nonnull
public static Matrix3By3 getIdentity()

Gets a Matrix3By3 representing an identity transformation.

Returns:

The 3-by-3 identity matrix.

getUndefined

@Nonnull
public static Matrix3By3 getUndefined()

Gets a Matrix3By3 with elements of Double.NaN.

Use IsUndefined (get) to test whether a Matrix3By3 instance is undefined since it will return true if any of the element values are Double.NaN.

getZero

@Nonnull
public static Matrix3By3 getZero()

Gets a Matrix3By3 representing the zero matrix.

Returns:

The 3-by-3 zero matrix.

crossProductEquivalentMatrix

@Nonnull
public static Matrix3By3 crossProductEquivalentMatrix(@Nonnull
                                                                Cartesian vector)

Forms a Matrix3By3 from the input vector such that the result of the cross product of the input vector with another vector is equivalent to premultiplying the other vector by the returned matrix.

Parameters:

vector - The vector for which the cross product equivalent matrix is desired.

Returns:

The cross product equivalent matrix.

crossProductEquivalentMatrix

@Nonnull
public static Matrix3By3 crossProductEquivalentMatrix(@Nonnull
                                                                UnitCartesian vector)

Forms a Matrix3By3 from the input vector such that the result of the cross product of the input unit vector with another vector is equivalent to premultiplying the other vector by the returned matrix.

Parameters:

vector - The unit vector for which the cross product equivalent matrix is desired.

Returns:

The cross product equivalent matrix.

diagonalMatrix

@Nonnull
public static Matrix3By3 diagonalMatrix(double m11,
                                                  double m22,
                                                  double m33)

Forms a diagonal matrix from the input elements.

Parameters:

m11 - 1,1

m22 - 2,2

m33 - 3,3

Returns:

The diagonal matrix.

diagonalMatrix

@Nonnull
public static Matrix3By3 diagonalMatrix(@Nonnull
                                                  Cartesian vector)

Forms a diagonal matrix from the input vector.

Parameters:

vector - The vector.

Returns:

The diagonal matrix

diagonalMatrix

@Nonnull
public static Matrix3By3 diagonalMatrix(@Nonnull
                                                  UnitCartesian vector)

Forms a diagonal matrix from the input unit vector.

Parameters:

vector - The vector.

Returns:

The diagonal matrix.

get

public final double get(int row,
                        int column)

Accesses the matrix elements using zero-based indexing.

Parameters:

row - The row index.

column - The column index.

Returns:

The value corresponding to the indicated element of the matrix.

Throws:

ArgumentOutOfRangeException - Thrown when either row or column is less than 0 or greater than 2.

getM11

public final double getM11()

Gets the element in the first row, first column.

getM12

public final double getM12()

Gets the element in the first row, second column.

getM13

public final double getM13()

Gets the element in the first row, third column.

getM21

public final double getM21()

Gets the element in the second row, first column.

getM22

public final double getM22()

Gets the element in the second row, second column.

getM23

public final double getM23()

Gets the element in the second row, third column.

getM31

public final double getM31()

Gets the element in the third row, first column.

getM32

public final double getM32()

Gets the element in the third row, second column.

getM33

public final double getM33()

Gets the element in the third row, third column.

transpose

@Nonnull
public final Matrix3By3 transpose()

Transposes the matrix.

Returns:

The transposed matrix.

determinant

public final double determinant()

Calculates the determinant of the matrix.

Returns:

The determinant of the matrix.

invert

@Nonnull
public final Matrix3By3 invert()

Inverts the matrix.

Returns:

The inverted matrix.

Throws:

ArithmeticException - Thrown when the absolute value of the Matrix3By3.determinant() is less than Constants.Epsilon15.

getIsUndefined

public final boolean getIsUndefined()

Gets a value indicating whether any of the matrix values are Double.NaN.

frobeniusNormSquared

public final double frobeniusNormSquared()

Computes the square of the Frobenius norm of the matrix.

Returns:

The square of the Frobenius norm.

frobeniusNorm

public final double frobeniusNorm()

Computes the Frobenius norm of the matrix.

Returns:

The Frobenius norm.

add

@Nonnull
public final Matrix3By3 add(@Nonnull
                                      Matrix3By3 matrix)

Adds a matrix to this matrix.

Parameters:

matrix - The matrix.

Returns:

The sum of the matrices.

add

@Nonnull
public final Matrix3By3 add(@Nonnull
                                      Matrix3By3Symmetric matrix)

Adds a matrix to this matrix.

Parameters:

matrix - The matrix.

Returns:

The sum of the matrices.

subtract

@Nonnull
public final Matrix3By3 subtract(@Nonnull
                                           Matrix3By3 matrix)

Subtracts a matrix from this matrix.

Parameters:

matrix - The matrix to subtract.

Returns:

The result of the subtraction.

subtract

@Nonnull
public final Matrix3By3 subtract(@Nonnull
                                           Matrix3By3Symmetric matrix)

Subtracts a matrix from this matrix.

Parameters:

matrix - The matrix to subtract.

Returns:

The result of the subtraction.

multiply

@Nonnull
public final Matrix3By3 multiply(double scalar)

Multiplies this matrix by a scalar.

Parameters:

scalar - The scalar to multiply by.

Returns:

The result of the multiplication.

multiply

@Nonnull
public final Matrix3By3 multiply(@Nonnull
                                           ElementaryRotation rotation)

Forms a new 3-by-3 matrix as the product of this 3-by-3 matrix and the provided elementary rotation.

Parameters:

rotation - The elementary rotation.

Returns:

The resulting 3-by-3 matrix.

Throws:

UnsupportedCaseException - Thrown if the Axis (get) property of rotation is not AxisIndicator.FIRST, AxisIndicator.SECOND, or AxisIndicator.THIRD.

multiply

@Nonnull
public final Matrix3By3 multiply(@Nonnull
                                           Matrix3By3 matrix)

Multiplies this matrix by a matrix.

Parameters:

matrix - The matrix to multiply by.

Returns:

The result of the multiplication.

multiply

@Nonnull
public final Matrix3By3 multiply(@Nonnull
                                           Matrix3By3Symmetric matrix)

Multiplies this matrix by a matrix.

Parameters:

matrix - The matrix to multiply by.

Returns:

The result of the multiplication.

multiply

@Nonnull
public final Cartesian multiply(@Nonnull
                                          Cartesian vector)

Forms a new Cartesian vector as the product of this 3-by-3 matrix and the provided Cartesian vector.

Parameters:

vector - The vector.

Returns:

The resulting Cartesian vector.

multiply

@Nonnull
public static Matrix3By3 multiply(@Nonnull
                                            Matrix3By3 matrix,
                                            double scalar)

Multiplies a matrix by a scalar.

Parameters:

matrix - The matrix.

scalar - The scalar.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static Matrix3By3 multiply(double scalar,
                                            @Nonnull
                                            Matrix3By3 matrix)

Multiplies a scalar by a matrix.

Parameters:

scalar - The scalar.

matrix - The matrix.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static Matrix3By3 multiply(@Nonnull
                                            Matrix3By3 matrix,
                                            @Nonnull
                                            ElementaryRotation rotation)

Multiplies a 3-by-3 matrix by an ElementaryRotation.

Parameters:

matrix - The matrix.

rotation - The elementary rotation.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static Matrix3By3 multiply(@Nonnull
                                            Matrix3By3 left,
                                            @Nonnull
                                            Matrix3By3 right)

Multiplies the left matrix by the right matrix.

Parameters:

left - The matrix on the left.

right - The matrix on the right.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static Matrix3By3 multiply(@Nonnull
                                            Matrix3By3 left,
                                            @Nonnull
                                            Matrix3By3Symmetric right)

Multiplies the left matrix by the right matrix.

Parameters:

left - The matrix on the left.

right - The matrix on the right.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static Cartesian multiply(@Nonnull
                                           Matrix3By3 matrix,
                                           @Nonnull
                                           Cartesian vector)

Multiplies the 3-by-3 matrix by the Cartesian vector.

Parameters:

matrix - The matrix.

vector - The vector.

Returns:

The result of the multiplication.

add

@Nonnull
public static Matrix3By3 add(@Nonnull
                                       Matrix3By3 left,
                                       @Nonnull
                                       Matrix3By3 right)

Adds a matrix to this matrix.

Parameters:

left - The left matrix.

right - The right matrix.

Returns:

The sum of the matrices.

add

@Nonnull
public static Matrix3By3 add(@Nonnull
                                       Matrix3By3 left,
                                       @Nonnull
                                       Matrix3By3Symmetric right)

Adds a matrix to this matrix.

Parameters:

left - The left matrix.

right - The right matrix.

Returns:

The sum of the matrices.

subtract

@Nonnull
public static Matrix3By3 subtract(@Nonnull
                                            Matrix3By3 left,
                                            @Nonnull
                                            Matrix3By3 right)

Subtracts the second matrix from the first.

Parameters:

left - The left matrix.

right - The right matrix.

Returns:

The result of subtracting the second matrix from the first.

subtract

@Nonnull
public static Matrix3By3 subtract(@Nonnull
                                            Matrix3By3 left,
                                            @Nonnull
                                            Matrix3By3Symmetric right)

Subtracts the second matrix from the first.

Parameters:

left - The left matrix.

right - The right matrix.

Returns:

The result of subtracting the second matrix from the first.

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

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

Specified by:

equalsType in interface IEquatable<Matrix3By3>

Parameters:

other - The instance to compare to this instance.

Returns:

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

equals

public final boolean equals(@Nonnull
                            Matrix3By3Symmetric other)

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

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
                                   Matrix3By3 other,
                                   double epsilon)

Returns true if all of the elements of this matrix are within epsilon of the same elements of the specified matrix. That is, in order for the matrices 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<Matrix3By3>

Parameters:

other - The Matrix3By3 to compare to this matrix.

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

Returns:

true if the matrices 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)

equals

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