Package geomss.geom

Class GTransform

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, javolution.lang.Immutable, javolution.lang.ValueType, javolution.xml.XMLSerializable
    public class GTransform
extends java.lang.Object
implements javolution.lang.ValueType, java.lang.Cloneable, javolution.xml.XMLSerializable
    A general 4x4 transformation matrix that transforms GeomPoint objects.

    Modified by: Joseph A. Huwaldt

    Version:
    February 17, 2025
    Author:
    Joseph A. Huwaldt, Date: April 29, 2009
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static GTransform IDENTITY
      The identity matrix containing ones along the diagonal.
      static GTransform ZERO
      A matrix containing all zero elements.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      GTransform applyRotation​(Matrix<Float64> m1)
      Return a new transformation matrix that is identical to this one, but with the rotational components replaced with those in the specified direction cosine matrix.
      GTransform applyRotationScale​(Matrix<Float64> m1)
      Return a new transformation matrix with the upper-left 3x3 portion of this matrix (rotation and scaling) replaced by the specified values.
      GTransform applyScale​(double scale)
      Return a new transformation matrix that is identical to this one, but with the specified uniform scale factor applied.
      GTransform applyScale​(Float64Vector scale)
      Return a new transformation matrix that is identical to this one, but with the specified set of three scale factors applied in each axis (X,Y,Z).
      GTransform applyTranslation​(Vector<javax.measure.quantity.Length> trans)
      Return a new transformation matrix that is identical to this one, but with the translation components replaced by the specified values.
      GTransform applyTranslation​(Float64Vector trans)
      Return a new transformation matrix that is identical to this one, but with the translation components replaced by the specified values.
      java.lang.Object clone()
      Returns a copy of this GTransform instance allocated by the calling thread (possibly on the stack).
      GTransform copy()
      Returns a copy of this matrix allocated by the calling thread (possibly on the stack).
      Float64 determinant()
      Returns the determinant of this matrix.
      boolean equals​(java.lang.Object obj)
      Compares this GTransform against the specified object for strict equality (same values).
      Float64 get​(int i, int j)
      Returns a single element from this matrix.
      Float64Vector getColumn​(int j)
      Returns the column identified by the specified index in this matrix.
      Float64Vector getDiagonal()
      Returns the diagonal vector.
      Float64Matrix getFloat64Matrix()
      Return the transformation matrix that represents this GTransform object as a Float64Matrix.
      double[][] getMatrix()
      Return the transformation matrix that represents this GTranfrom object as a 2D Java matrix.
      int getNumberOfColumns()
      Returns the number of columns for this matrix.
      int getNumberOfRows()
      Returns the number of rows for this matrix.
      DCMatrix getRotation()
      Returns a direction cosine matrix containing the rotational portion of this transformation matrix.
      Matrix<Float64> getRotationScale()
      Returns the upper 3x3 values of this matrix (which contains combined rotation and scale information) and places them into the output matrix.
      Float64Vector getRow​(int i)
      Returns the row identified by the specified index in this matrix.
      double getScale()
      Returns the uniform scale factor for this matrix.
      Float64Vector getScaleVector()
      Returns a 3 element vector containing the scale factors in each dimension X, Y & Z.
      Vector<javax.measure.quantity.Length> getTranslation()
      Returns the translational components of this transformation matrix.
      double getValue​(int i, int j)
      Returns a single element from this matrix as a double.
      int hashCode()
      Returns the hash code for this GTransform object.
      GTransform inverse()
      Returns the inverse of this matrix.
      static void main​(java.lang.String[] args)
      Tests the methods in this class.
      static GTransform newRotationX​(Parameter<javax.measure.quantity.Angle> angle)
      Return a transformation matrix representing a counter-clockwise or right-handed rotation about the X axis (when looking down the X-axis).
      static GTransform newRotationY​(Parameter<javax.measure.quantity.Angle> angle)
      Return a transformation matrix representing a counter-clockwise or right-handed rotation about the Y axis (when looking down the Y-axis).
      static GTransform newRotationZ​(Parameter<javax.measure.quantity.Angle> angle)
      Return a transformation matrix representing a counter-clockwise or right-handed rotation about the Z axis (when looking down the Z-axis).
      static GTransform newScale​(double scale)
      Returns a transformation matrix representing a scale matrix with a uniform scale factor applied to each dimension.
      static GTransform newTranslation​(double transX, double transY, double transZ)
      Returns a transformation matrix representing a translation matrix.
      static GTransform newTranslation​(GeomVector<javax.measure.quantity.Length> vector)
      Returns a transformation matrix representing a translation matrix.
      static GTransform newTranslation​(Parameter<javax.measure.quantity.Length> transX, Parameter<javax.measure.quantity.Length> transY, Parameter<javax.measure.quantity.Length> transZ)
      Returns a transformation matrix representing a translation matrix.
      static GTransform newTranslation​(Float64Vector trans)
      Returns a transformation matrix representing a translation matrix.
      GTransform times​(GTransform that)
      Returns the product of this matrix with the one specified.
      java.lang.String toString()
      Returns a string representation of this matrix.
      javolution.text.Text toText()
      Returns the text representation of this matrix.
      Point transform​(GeomPoint p)
      Transform the input point by multiplying it times this general transformation matrix.
      GTransform transpose()
      Returns the transpose of this matrix.
      static GTransform valueOf​(double diagX, double diagY, double diagZ, double diagW)
      Returns a transformation matrix holding the specified diagonal vector with zeros placed in all the other elements.
      static GTransform valueOf​(GeomVector srcAxis, GeomVector destAxis)
      Returns a GTransform instance representing the transformation from one axis direction directly to another.
      static GTransform valueOf​(Rotation rotation)
      Returns a GTransform instance containing a copy of the specified rotation transformation.
      static GTransform valueOf​(Rotation rotation, double scale, Vector<javax.measure.quantity.Length> trans)
      Returns a GTransform instance containing the specified rotation transformation, uniform scale factor, and translation vector.
      static GTransform valueOf​(java.util.List<Float64Vector> rows)
      Returns a transformation matrix holding the row vectors from the specified list.
      static GTransform valueOf​(Float64Vector row0, Float64Vector row1, Float64Vector row2, Float64Vector row3)
      Returns a transformation matrix holding the specified row vectors.
      static GTransform valueOf​(Matrix<Float64> matrix)
      Returns a GTransform instance containing a copy of the specified matrix of Float64 values.
      static GTransform valueOf​(Matrix<Float64> dcm, double scale, Vector<javax.measure.quantity.Length> trans)
      Returns a GTransform instance containing the specified direction cosine rotation matrix, uniform scale factor, and translation vector.
      Float64Vector vectorization()
      Returns the vectorization of this matrix.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • ZERO

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

      • IDENTITY

        public static final GTransform IDENTITY
        The identity matrix containing ones along the diagonal.

    • Method Detail

      • valueOf

        public static GTransform valueOf​(Float64Vector row0,
                                 Float64Vector row1,
                                 Float64Vector row2,
                                 Float64Vector row3)
        Returns a transformation matrix holding the specified row vectors. Note: any transformations in the 4th column of the matrix must have units of meters!
        Parameters:
        row0 - the 1st row vector. May not be null.
        row1 - the 2nd row vector. May not be null.
        row2 - the 3rd row vector. May not be null.
        row3 - the 4th row vector. May not be null.
        Returns:
        the transformation matrix having the specified rows.
        Throws:
        DimensionException - if the any of the rows do not have a dimension of 4.

      • valueOf

        public static GTransform valueOf​(java.util.List<Float64Vector> rows)
        Returns a transformation matrix holding the row vectors from the specified list. Note: any transformations in the 4th column of the matrix must have units of meters!
        Parameters:
        rows - The list of 4 row vectors. May not be null.
        Returns:
        the transformation matrix having the specified rows.
        Throws:
        DimensionException - if the rows do not have a dimension of 4.

      • valueOf

        public static GTransform valueOf​(double diagX,
                                 double diagY,
                                 double diagZ,
                                 double diagW)
        Returns a transformation 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.
        diagW - the 4th element of the diagonal vector for the matrix.
        Returns:
        the transformation matrix having the specified diagonal.

      • valueOf

        public static GTransform valueOf​(Matrix<Float64> matrix)
        Returns a GTransform instance containing a copy of the specified matrix of Float64 values. The matrix must have dimensions of either 3x3 for a combined scale and direction cosine matrix or 4x4 for a general transformation matrix. If a 3x3 matrix is input, then the upper-left 3x3 portion of the output matrix will be set to those values and the other elements will be set as if it were an identity matrix (i.e., affine matrix with no translational component). If a 4x4 matrix is input, then the 4th column (the translation) must be in units of meters!
        Parameters:
        matrix - the matrix of Float64 values to convert (must have dimension of 3x3 or 4x4). May not be null.
        Returns:
        the transformation matrix having the specified elements.

      • valueOf

        public static GTransform valueOf​(Matrix<Float64> dcm,
                                 double scale,
                                 Vector<javax.measure.quantity.Length> trans)
        Returns a GTransform instance containing the specified direction cosine rotation matrix, uniform scale factor, and translation vector.
        Parameters:
        dcm - The direction cosine matrix to convert (must have dimension of 3x3). May not be null.
        scale - The uniform scale factor to apply to each axis.
        trans - The amount to translate in each axis X, Y & Z.
        Returns:
        the transformation matrix having the specified elements.

      • valueOf

        public static GTransform valueOf​(Rotation rotation)
        Returns a GTransform instance containing a copy of the specified rotation transformation. The upper-left 3x3 portion of the output matrix will be set to DCM values from the rotation and the other elements will be set as if it were an identity matrix (i.e., affine matrix with no translational component).
        Parameters:
        rotation - the Rotation transformation to convert. May not be null.
        Returns:
        the general transformation matrix having the specified rotational elements.

      • valueOf

        public static GTransform valueOf​(Rotation rotation,
                                 double scale,
                                 Vector<javax.measure.quantity.Length> trans)
        Returns a GTransform instance containing the specified rotation transformation, uniform scale factor, and translation vector.
        Parameters:
        rotation - The rotation transformation to convert. May not be null.
        scale - The uniform scale factor to apply to each axis.
        trans - The amount to translate in each axis X, Y & Z. May not be null.
        Returns:
        the transformation matrix having the specified elements.

      • valueOf

        public static GTransform valueOf​(GeomVector srcAxis,
                                 GeomVector destAxis)
        Returns a GTransform instance representing the transformation from one axis direction directly to another. Input vectors must be 3D.
        Parameters:
        srcAxis - A vector representing the 1st or starting axis. May not be null.
        destAxis - A vector representing the 2nd or ending axis. May not be null.
        Returns:
        The transformation matrix representing the rotation from the 1st (source) axis directly to the 2nd (destination) axis.

      • newScale

        public static GTransform newScale​(double scale)
        Returns a transformation matrix representing a scale matrix with a uniform scale factor applied to each dimension.
        Parameters:
        scale - The scale factor to create a scale matrix for.
        Returns:
        the transformation matrix representing the specified scale.

      • newTranslation

        public static GTransform newTranslation​(double transX,
                                        double transY,
                                        double transZ)
        Returns a transformation matrix representing a translation matrix.
        Parameters:
        transX - The amount to translate, in meters, in the X axis direction.
        transY - The amount to translate, in meters, in the Y axis direction.
        transZ - The amount to translate, in meters, in the Z axis direction.
        Returns:
        the transformation matrix representing the specified translation.
        Throws:
        DimensionException - if the input vector does not have 3 elements.

      • newTranslation

        public static GTransform newTranslation​(Parameter<javax.measure.quantity.Length> transX,
                                        Parameter<javax.measure.quantity.Length> transY,
                                        Parameter<javax.measure.quantity.Length> transZ)
        Returns a transformation matrix representing a translation matrix.
        Parameters:
        transX - The amount to translate in the X axis direction. May not be null.
        transY - The amount to translate in the Y axis direction. May not be null.
        transZ - The amount to translate in the Z axis direction. May not be null.
        Returns:
        the transformation matrix representing the specified translation.
        Throws:
        DimensionException - if the input vector does not have 3 elements.

      • newTranslation

        public static GTransform newTranslation​(GeomVector<javax.measure.quantity.Length> vector)
        Returns a transformation matrix representing a translation matrix.
        Parameters:
        vector - The amount to translate in each axis X, Y & Z. May not be null.
        Returns:
        the transformation matrix representing the specified translation.

      • newTranslation

        public static GTransform newTranslation​(Float64Vector trans)
        Returns a transformation matrix representing a translation matrix.
        Parameters:
        trans - The amount to translate, in meters, in each axis X, Y & Z. May not be null.
        Returns:
        the transformation matrix representing the specified translation.
        Throws:
        DimensionException - if the input vector does not have 3 elements.

      • newRotationX

        public static GTransform newRotationX​(Parameter<javax.measure.quantity.Angle> angle)
        Return a transformation matrix representing a counter-clockwise or right-handed rotation about the X axis (when looking down the X-axis).
        Parameters:
        angle - The angle to rotate about the X axis. May not be null.
        Returns:
        A transformation matrix for a counter-clockwise rotation about the X axis.

      • newRotationY

        public static GTransform newRotationY​(Parameter<javax.measure.quantity.Angle> angle)
        Return a transformation matrix representing a counter-clockwise or right-handed rotation about the Y axis (when looking down the Y-axis).
        Parameters:
        angle - The angle to rotate about the Y axis. May not be null.
        Returns:
        A transformation matrix for a counter-clockwise rotation about the Y axis.

      • newRotationZ

        public static GTransform newRotationZ​(Parameter<javax.measure.quantity.Angle> angle)
        Return a transformation matrix representing a counter-clockwise or right-handed rotation about the Z axis (when looking down the Z-axis).
        Parameters:
        angle - The angle to rotate about the Z axis. May not be null.
        Returns:
        A transformation matrix for a counter-clockwise rotation about the Z axis.

      • getNumberOfRows

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

      • getNumberOfColumns

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

      • 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].

      • getFloat64Matrix

        public Float64Matrix getFloat64Matrix()
        Return the transformation matrix that represents this GTransform object as a Float64Matrix. The translation column values have units of METER.
        Returns:
        The transformation matrix that represents this GTransform object.

      • getMatrix

        public double[][] getMatrix()
        Return the transformation matrix that represents this GTranfrom object as a 2D Java matrix. The translation column values have units of METER.
        Returns:
        The transformation matrix that represents this GTranfrom object.

      • 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 in this matrix as a Float64Vector.

      • 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 in this matrix as a Float64Vector.

      • getDiagonal

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

      • transform

        public Point transform​(GeomPoint p)
        Transform the input point by multiplying it times this general transformation matrix.
        Parameters:
        p - The point to be transformed. May not be null.
        Returns:
        this · p
        Throws:
        DimensionException - if p.getPhyDimension() != 3

      • times

        public GTransform times​(GTransform that)
        Returns the product of this matrix with the one specified.
        Parameters:
        that - the matrix multiplier. May not be null.
        Returns:
        this · that

      • determinant

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

      • 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 GTransform copy()
        Returns a copy of this matrix allocated by the calling thread (possibly on the stack).
        Specified by:
        copy in interface javolution.lang.ValueType
        Returns:
        an identical and independent copy of this matrix.

      • clone

        public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
        Returns a copy of this GTransform instance allocated by the calling thread (possibly on the stack).
        Returns:
        an identical and independent copy of this matrix.
        Throws:
        java.lang.CloneNotSupportedException - Never thrown.

      • toText

        public javolution.text.Text toText()
        Returns the text representation of this matrix.
        Returns:
        the text representation of this matrix.

      • toString

        public java.lang.String toString()
        Returns a string representation of this matrix.
        Overrides:
        toString in class java.lang.Object

      • equals

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

      • hashCode

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

      • getScale

        public double getScale()
        Returns the uniform scale factor for this matrix. If the matrix has non-uniform scale factors, than the maximum of the X, Y & Z scale factor is returned.
        Returns:
        the uniform or maximum scale factor.

      • getScaleVector

        public Float64Vector getScaleVector()
        Returns a 3 element vector containing the scale factors in each dimension X, Y & Z.
        Returns:
        the scale factors of this matrix

      • getRotation

        public DCMatrix getRotation()
        Returns a direction cosine matrix containing the rotational portion of this transformation matrix.
        Returns:
        the direction cosine matrix

      • getRotationScale

        public Matrix<Float64> getRotationScale()
        Returns the upper 3x3 values of this matrix (which contains combined rotation and scale information) and places them into the output matrix.
        Returns:
        A 3x3 matrix representing the combined rotation and scaling of this matrix.

      • getTranslation

        public Vector<javax.measure.quantity.Length> getTranslation()
        Returns the translational components of this transformation matrix.
        Returns:
        The translational components of this transformation matrix.

      • applyScale

        public GTransform applyScale​(double scale)
        Return a new transformation matrix that is identical to this one, but with the specified uniform scale factor applied.
        Parameters:
        scale - The scale factor to apply to this transformation.
        Returns:
        A new GTransform that is identical to this one, but with the specified uniform scale factor applied.

      • applyScale

        public GTransform applyScale​(Float64Vector scale)
        Return a new transformation matrix that is identical to this one, but with the specified set of three scale factors applied in each axis (X,Y,Z).
        Parameters:
        scale - The scale factor in each dimension (X, Y & Z) to apply to this transformation. May not be null.
        Returns:
        A new GTransform that is identical to this one, but with the specified set of three scale factors applied.
        Throws:
        DimensionException - if the input list of scale factors does not have 3 elements.

      • applyRotation

        public GTransform applyRotation​(Matrix<Float64> m1)
        Return a new transformation matrix that is identical to this one, but with the rotational components replaced with those in the specified direction cosine matrix. The effect of scale is factored out, then the new rotation components are placed in the upper-left 3x3 portion of the matrix and then the scale is reapplied.
        Parameters:
        m1 - The direction cosine matrix to apply to this matrix. May not be null.
        Returns:
        A new GTransform that is identical to this one, but with the rotational components replaced with those in the specified direction cosine matrix.
        Throws:
        DimensionException - if matrix is not 3x3

      • applyRotationScale

        public GTransform applyRotationScale​(Matrix<Float64> m1)
        Return a new transformation matrix with the upper-left 3x3 portion of this matrix (rotation and scaling) replaced by the specified values. The remaining elements of the matrix are left unchanged.
        Parameters:
        m1 - The 3x3 matrix that will be the new upper left portion. May not be null.
        Returns:
        A new GTransform with the upper-left 3x3 portion of this matrix replaced by the specified values.
        Throws:
        DimensionException - if m1 is not 3x3

      • applyTranslation

        public GTransform applyTranslation​(Vector<javax.measure.quantity.Length> trans)
        Return a new transformation matrix that is identical to this one, but with the translation components replaced by the specified values. The remaining elements of the matrix are left unchanged.
        Parameters:
        trans - The 3 element translation offsets in (X, Y & Z). May not be null.
        Returns:
        A new GTransform that is identical to this one, but with the translation components replaced by the specified values.

      • applyTranslation

        public GTransform applyTranslation​(Float64Vector trans)
        Return a new transformation matrix that is identical to this one, but with the translation components replaced by the specified values. The remaining elements of the matrix are left unchanged.
        Parameters:
        trans - The 3 element translation offsets in meters (X, Y & Z). May not be null.
        Returns:
        A new GTransform that is identical to this one, but with the translation components replaced by the specified values.
        Throws:
        DimensionException - if input vector does not have exactly 3 elements.

      • main

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