Package jahuwaldt.js.param

Class DCMatrix

  • All Implemented Interfaces:
    Rotation<DCMatrix>, java.io.Serializable, javolution.lang.Immutable, javolution.lang.Realtime, javolution.lang.ValueType, javolution.xml.XMLSerializable
    public final class DCMatrix
extends AbstractRotation<DCMatrix>
implements javolution.xml.XMLSerializable

    This class represents a 3x3 transformation or direction cosine matrix that represents a relative orientation (attitude or rotation transformation) between two different reference frames; B wrt A or BA. It can be used to transform coordinates in reference frame A to reference frame B (A2B).

    Assumes matrix is used to multiply column vector on the left: vnew = mat * vold. Works correctly for right-handed coordinate system and right-handed rotations.

    Modified by: Joseph A. Huwaldt

    Version:
    February 23, 2025
    Author:
    Joseph A. Huwaldt, Date: November 26, 2008
    See Also:
    Serialized Form

    • Field Detail

      • ZERO

        public static final DCMatrix ZERO
        A matrix containing all zero elements.

      • IDENT

        public static final DCMatrix IDENT
        A DCM object that represents no relative change in orientation.

    • Method Detail

      • valueOf

        public static DCMatrix valueOf​(double a,
                               double b,
                               double c,
                               double d,
                               double e,
                               double f,
                               double g,
                               double h,
                               double i)

        Returns a 3D direction cosine matrix from a sequence of 9 double values.

        Values are ordered as follows: 

                 | a b c |
         | d e f |
         | g h i |
        Parameters:
        a - matrix element 0,0
        b - matrix element 0,1
        c - matrix element 0,2
        d - matrix element 1,0
        e - matrix element 1,1
        f - matrix element 1,2
        g - matrix element 2,0
        h - matrix element 2,1
        i - matrix element 2,2
        Returns:
        the 3D matrix having the specified elements.

      • valueOf

        public static DCMatrix valueOf​(double[] row0,
                               double[] row1,
                               double[] row2)
        Returns a 3D direction cosine matrix holding the specified row vectors (column vectors if transposed).
        Parameters:
        row0 - the 1st row vector.
        row1 - the 2nd row vector.
        row2 - the 3rd row vector.
        Returns:
        the 3D matrix having the specified rows.

      • valueOf

        public static DCMatrix valueOf​(Float64Vector row0,
                               Float64Vector row1,
                               Float64Vector row2)
        Returns a 3D direction cosine matrix holding the specified row vectors (column vectors if transposed).
        Parameters:
        row0 - the 1st row vector.
        row1 - the 2nd row vector.
        row2 - the 3rd row vector.
        Returns:
        the 3D matrix having the specified rows.

      • valueOf

        public static DCMatrix valueOf​(double diagX,
                               double diagY,
                               double diagZ)
        Returns a 3D direction cosine matrix holding the specified diagonal vector with zeros placed in all the other elements.
        Parameters:
        diagX - the 1st element of the diagonal vector for the matrix.
        diagY - the 2nd element of the diagonal vector for the matrix.
        diagZ - the 3rd element of the diagonal vector for the matrix.
        Returns:
        the 3D matrix having the specified diagonal.

      • valueOf

        public static DCMatrix valueOf​(Float64Vector diag)
        Returns a 3D direction cosine matrix holding the specified diagonal vector with zeros placed in all the other elements.
        Parameters:
        diag - the diagonal vector for the matrix.
        Returns:
        the 3D matrix having the specified diagonal.

      • valueOf

        public static DCMatrix valueOf​(java.util.List<Float64Vector> rows)
        Returns a 3D direction cosine matrix holding the row vectors from the specified collection (column vectors if transposed).
        Parameters:
        rows - The list of row vectors. If there are more than 3 elements, an exception is thrown.
        Returns:
        the 3D matrix having the specified rows.
        Throws:
        DimensionException - if the rows do not have a dimension of 3.

      • valueOf

        public static DCMatrix valueOf​(Matrix<Float64> matrix)
        Returns a DCMatrix instance containing a copy of the specified matrix of Float64 values. The matrix must have dimensions of 3x3.
        Parameters:
        matrix - the matrix of Float64 values to convert (must have dimension of 3x3).
        Returns:
        the matrix having the specified elements.

      • valueOf

        public static DCMatrix valueOf​(Rotation<?> transform)
        Returns a DCMatrix instance equivalent to the specified rotation transform.
        Parameters:
        transform - The Rotation to convert to a direction cosine matrix.
        Returns:
        the direction cosine matrix representing the specified rotation transform.

      • valueOf

        public static DCMatrix valueOf​(Coordinate3D vector1,
                               Coordinate3D vector2,
                               int axis1,
                               int axis2)
        Return a new DCMatrix instance constructed from the specified axis pair.
        Parameters:
        vector1 - The vector defining the 1st axis.
        vector2 - The vector defining the 2nd axis.
        axis1 - Constant from this class designating which axis the 1st axis is (e.g.: X=0, or Z=2).
        axis2 - Constant from this class designating which axis the 2nd axis is (e.g.: Y=1 or X=0).
        Returns:
        A direction cosine matrix representing a rotation from the base axis system to the specified axis orientations.

      • getNumberOfRows

        public int getNumberOfRows()
        Returns the number of rows m for this matrix. This implementation always returns 3.
        Returns:
        The number of rows for this matrix

      • getNumberOfColumns

        public int getNumberOfColumns()
        Returns the number of columns n for this matrix. This implementation always returns 3.
        Returns:
        The number of columns for this matrix

      • get

        public Float64 get​(int i,
                   int j)
        Returns a single element from this matrix.
        Parameters:
        i - the row index (range [0..3[).
        j - the column index (range [0..3[).
        Returns:
        the matrix element at [i,j].

      • getValue

        public double getValue​(int i,
                       int j)

        Returns a single element from this matrix as a double.

        This is a convenience method for: this.get(i,j).doubleValue();

        Parameters:
        i - the row index (range [0..3[).
        j - the column index (range [0..3[).
        Returns:
        the matrix element at [i,j].

      • getRow

        public Float64Vector getRow​(int i)
        Returns the row identified by the specified index in this matrix.
        Parameters:
        i - the row index (range [0..3[).
        Returns:
        The specified row of this matrix.

      • getColumn

        public Float64Vector getColumn​(int j)
        Returns the column identified by the specified index in this matrix.
        Parameters:
        j - the column index (range [0..3[).
        Returns:
        The specified column of this matrix.

      • getDiagonal

        public Float64Vector getDiagonal()
        Returns the diagonal vector.
        Returns:
        the vector holding the diagonal elements.

      • opposite

        public DCMatrix opposite()
        Returns the negation of this matrix.
        Returns:
        -this

      • plus

        public DCMatrix plus​(DCMatrix that)
        Returns the sum of this matrix with the one specified.
        Parameters:
        that - the matrix to be added.
        Returns:
        this + that

      • minus

        public DCMatrix minus​(DCMatrix that)
        Returns the difference between this matrix and the one specified.
        Parameters:
        that - the matrix to be subtracted from this one.
        Returns:
        this - that

      • times

        public DCMatrix times​(Float64 k)
        Returns the product of this matrix by the specified factor.
        Parameters:
        k - the coefficient multiplier
        Returns:
        this · k

      • times

        public Float64Vector times​(Vector<Float64> v)
        Returns the product of this matrix by the specified vector.
        Parameters:
        v - the vector.
        Returns:
        this · v
        Throws:
        DimensionException - - if v.getDimension() != this.getNumberOfColumns()

      • times

        public <Q extends javax.measure.quantity.Quantity> Vector3D<Q> times​(Coordinate3D<Q> v)
        Returns the product of this matrix by the specified vector.
        Type Parameters:
        Q - The Quantity (unit type) of the vector.
        Parameters:
        v - the vector.
        Returns:
        this · v

      • transform

        public <Q extends javax.measure.quantity.Quantity> Vector3D<Q> transform​(Coordinate3D<Q> v)
        Transforms a 3D vector from frame A to B using this rotation transformation.
        Specified by:
        transform in interface Rotation<DCMatrix>
        Type Parameters:
        Q - The Quantity (unit type) of the vector.
        Parameters:
        v - the vector expressed in frame A.
        Returns:
        the vector expressed in frame B.

      • times

        public DCMatrix times​(Rotation<?> that)
        Returns the product of this direction cosine matrix and another rotation transform. If this rotation transform is BA and that is AC then the returned value is: BC = BA · AC (or C2B = A2B · C2A).
        Specified by:
        times in interface Rotation<DCMatrix>
        Parameters:
        that - the rotation transform multiplier.
        Returns:
        this · that

      • inverse

        public DCMatrix inverse()
        Returns the inverse of this matrix. If the matrix is singular, the determinant() will be zero (or nearly zero).
        Returns:
        1 / this

      • determinant

        public Float64 determinant()
        Returns the determinant of this matrix.
        Returns:
        this matrix determinant.

      • transpose

        public DCMatrix transpose()
        Returns the transpose of this matrix. This results in the spatial inverse of this transformation: AB rather than BA.
        Specified by:
        transpose in interface Rotation<DCMatrix>
        Returns:
        this'

      • cofactor

        public Float64 cofactor​(int i,
                        int j)
        Returns the cofactor of an element in this matrix. It is the value obtained by evaluating the determinant formed by the elements not in that particular row or column.
        Parameters:
        i - the row index.
        j - the column index.
        Returns:
        the cofactor of THIS[i,j].

      • adjoint

        public DCMatrix adjoint()
        Returns the adjoint of this matrix. It is obtained by replacing each element in this matrix with its cofactor and applying a + or - sign according to (-1)**(i+j), and then finding the transpose of the resulting matrix.
        Returns:
        the adjoint of this matrix.

      • vectorization

        public Float64Vector vectorization()
        Returns the vectorization of this matrix. The vectorization of a matrix is the column vector obtained by stacking the columns of the matrix on top of one another.
        Returns:
        the vectorization of this matrix.

      • copy

        public DCMatrix copy()
        Returns a copy of this matrix allocated by the calling thread (possibly on the stack).
        Specified by:
        copy in interface Rotation<DCMatrix>
        Specified by:
        copy in interface javolution.lang.ValueType
        Returns:
        an identical and independent copy of this matrix.

      • toFloat64Matrix

        public Float64Matrix toFloat64Matrix()
        Returns the equivalent of this direction cosine matrix as a Float64Matix.
        Returns:
        The equivalent of this direction cosine matrix as a Float64Matix.

      • toMatrix

        public double[][] toMatrix()
        Returns the equivalent of this direction cosine matrix as a Java 2D matrix.
        Returns:
        The equivalent of this direction cosine matrix as a Java 2D matrix.

      • toText

        public javolution.text.Text toText()
        Returns the text representation of this direction cosine matrix.
        Specified by:
        toText in interface javolution.lang.Realtime
        Returns:
        the text representation of this matrix.

      • equals

        public boolean equals​(java.lang.Object obj)
        Compares this DCMatrix against the specified object for strict equality (same rotation type and same values).
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the object to compare with.
        Returns:
        true if this rotation is identical to that rotation; false otherwise.

      • hashCode

        public int hashCode()
        Returns the hash code for this rotation.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code value.

      • main

        public static void main​(java.lang.String[] args)
        Tests the methods in this class.
        Parameters:
        args - Command line arguments (ignored).