Class AffineTransformMatrix2D

  • All Implemented Interfaces:
    java.util.function.Function<Vector2D,​Vector2D>, java.util.function.UnaryOperator<Vector2D>, Transform<Vector2D>, EuclideanTransform<Vector2D>

    public final class AffineTransformMatrix2D
    extends AbstractAffineTransformMatrix<Vector2D,​AffineTransformMatrix2D>
    Class using a matrix to represent affine transformations in 2 dimensional Euclidean space.

    Instances of this class use a 3x3 matrix for all transform operations. The last row of this matrix is always set to the values [0 0 1] and so is not stored. Hence, the methods in this class that accept or return arrays always use arrays containing 6 elements, instead of 9.

    • Field Detail

      • NUM_ELEMENTS

        private static final int NUM_ELEMENTS
        The number of internal matrix elements.
        See Also:
        Constant Field Values
      • MATRIX_START

        private static final java.lang.String MATRIX_START
        String used to start the transform matrix string representation.
        See Also:
        Constant Field Values
      • MATRIX_END

        private static final java.lang.String MATRIX_END
        String used to end the transform matrix string representation.
        See Also:
        Constant Field Values
      • ELEMENT_SEPARATOR

        private static final java.lang.String ELEMENT_SEPARATOR
        String used to separate elements in the matrix string representation.
        See Also:
        Constant Field Values
      • ROW_SEPARATOR

        private static final java.lang.String ROW_SEPARATOR
        String used to separate rows in the matrix string representation.
        See Also:
        Constant Field Values
      • IDENTITY_INSTANCE

        private static final AffineTransformMatrix2D IDENTITY_INSTANCE
        Shared transform set to the identity matrix.
      • m00

        private final double m00
        Transform matrix entry m0,0.
      • m01

        private final double m01
        Transform matrix entry m0,1.
      • m02

        private final double m02
        Transform matrix entry m0,2.
      • m10

        private final double m10
        Transform matrix entry m1,0.
      • m11

        private final double m11
        Transform matrix entry m1,1.
      • m12

        private final double m12
        Transform matrix entry m1,2.
    • Constructor Detail

      • AffineTransformMatrix2D

        private AffineTransformMatrix2D​(double m00,
                                        double m01,
                                        double m02,
                                        double m10,
                                        double m11,
                                        double m12)
        Simple constructor; sets all internal matrix elements.
        Parameters:
        m00 - matrix entry m0,0
        m01 - matrix entry m0,1
        m02 - matrix entry m0,2
        m10 - matrix entry m1,0
        m11 - matrix entry m1,1
        m12 - matrix entry m1,2
    • Method Detail

      • toArray

        public double[] toArray()
        Return a 6 element array containing the variable elements from the internal transformation matrix. The elements are in row-major order. The array indices map to the internal matrix as follows:
              [
                  arr[0],   arr[1],   arr[2],
                  arr[3],   arr[4],   arr[5],
                  0         0         1
              ]
         
        Returns:
        6 element array containing the variable elements from the internal transformation matrix
      • apply

        public Vector2D apply​(Vector2D pt)
        Apply this transform to the given point, returning the result as a new instance.

        The transformed point is computed by creating a 3-element column vector from the coordinates in the input and setting the last element to 1. This is then multiplied with the 3x3 transform matrix to produce the transformed point. The 1 in the last position is ignored.

              [ m00  m01  m02 ]     [ x ]     [ x']
              [ m10  m11  m12 ]  *  [ y ]  =  [ y']
              [ 0    0    1   ]     [ 1 ]     [ 1 ]
         
      • applyX

        public double applyX​(double x,
                             double y)
        Apply this transform to the given point coordinates and return the transformed x value. The return value is equal to (x * m00) + (y * m01) + m02.
        Parameters:
        x - x coordinate value
        y - y coordinate value
        Returns:
        transformed x coordinate value
        See Also:
        apply(Vector2D)
      • applyY

        public double applyY​(double x,
                             double y)
        Apply this transform to the given point coordinates and return the transformed y value. The return value is equal to (x * m10) + (y * m11) + m12.
        Parameters:
        x - x coordinate value
        y - y coordinate value
        Returns:
        transformed y coordinate value
        See Also:
        apply(Vector2D)
      • applyVector

        public Vector2D applyVector​(Vector2D vec)
        Apply this transform to the given vector, ignoring translations.

        This method can be used to transform vector instances representing displacements between points. For example, if v represents the difference between points p1 and p2, then transform.applyVector(v) will represent the difference between p1 and p2 after transform is applied.

        The transformed vector is computed by creating a 3-element column vector from the coordinates in the input and setting the last element to 0. This is then multiplied with the 3x3 transform matrix to produce the transformed vector. The 0 in the last position is ignored.

              [ m00  m01  m02 ]     [ x ]     [ x']
              [ m10  m11  m12 ]  *  [ y ]  =  [ y']
              [ 0    0    1   ]     [ 0 ]     [ 0 ]
         
        Parameters:
        vec - the vector to transform
        Returns:
        the new, transformed vector
        See Also:
        applyDirection(Vector2D)
      • applyVectorX

        public double applyVectorX​(double x,
                                   double y)
        Apply this transform to the given vector coordinates, ignoring translations, and return the transformed x value. The return value is equal to (x * m00) + (y * m01).
        Parameters:
        x - x coordinate value
        y - y coordinate value
        Returns:
        transformed x coordinate value
        See Also:
        applyVector(Vector2D)
      • applyVectorY

        public double applyVectorY​(double x,
                                   double y)
        Apply this transform to the given vector coordinates, ignoring translations, and return the transformed y value. The return value is equal to (x * m10) + (y * m11).
        Parameters:
        x - x coordinate value
        y - y coordinate value
        Returns:
        transformed y coordinate value
        See Also:
        applyVector(Vector2D)
      • linear

        public AffineTransformMatrix2D linear()
        Return a matrix containing only the linear portion of this transform. The returned instance contains the same matrix elements as this instance but with the translation component set to zero.

        Example

              [ a, b, c ]   [ a, b, 0 ]
              [ d, e, f ] → [ d, e, 0 ]
              [ 0, 0, 1 ]   [ 0, 0, 1 ]
         
        Specified by:
        linear in class AbstractAffineTransformMatrix<Vector2D,​AffineTransformMatrix2D>
        Returns:
        a matrix containing only the linear portion of this transform
      • linearTranspose

        public AffineTransformMatrix2D linearTranspose()
        Return a matrix containing the transpose of the linear portion of this transform. The returned instance is linear, meaning it has a translation component of zero.

        Example

              [ a, b, c ]   [ a, d, 0 ]
              [ d, e, f ] → [ b, e, 0 ]
              [ 0, 0, 1 ]   [ 0, 0, 1 ]
         
        Specified by:
        linearTranspose in class AbstractAffineTransformMatrix<Vector2D,​AffineTransformMatrix2D>
        Returns:
        a matrix containing the transpose of the linear portion of this transform
      • translate

        public AffineTransformMatrix2D translate​(Vector2D translation)
        Apply a translation to the current instance, returning the result as a new transform.
        Parameters:
        translation - vector containing the translation values for each axis
        Returns:
        a new transform containing the result of applying a translation to the current instance
      • translate

        public AffineTransformMatrix2D translate​(double x,
                                                 double y)
        Apply a translation to the current instance, returning the result as a new transform.
        Parameters:
        x - translation in the x direction
        y - translation in the y direction
        Returns:
        a new transform containing the result of applying a translation to the current instance
      • scale

        public AffineTransformMatrix2D scale​(double factor)
        Apply a scale operation to the current instance, returning the result as a new transform.
        Parameters:
        factor - the scale factor to apply to all axes
        Returns:
        a new transform containing the result of applying a scale operation to the current instance
      • scale

        public AffineTransformMatrix2D scale​(Vector2D scaleFactors)
        Apply a scale operation to the current instance, returning the result as a new transform.
        Parameters:
        scaleFactors - vector containing scale factors for each axis
        Returns:
        a new transform containing the result of applying a scale operation to the current instance
      • scale

        public AffineTransformMatrix2D scale​(double x,
                                             double y)
        Apply a scale operation to the current instance, returning the result as a new transform.
        Parameters:
        x - scale factor for the x axis
        y - scale factor for the y axis
        Returns:
        a new transform containing the result of applying a scale operation to the current instance
      • rotate

        public AffineTransformMatrix2D rotate​(double angle)
        Apply a counterclockwise rotation to the current instance, returning the result as a new transform.
        Parameters:
        angle - the angle of counterclockwise rotation in radians
        Returns:
        a new transform containing the result of applying a rotation to the current instance
        See Also:
        Rotation2D.of(double)
      • rotate

        public AffineTransformMatrix2D rotate​(Rotation2D rotation)
        Apply a counterclockwise rotation to the current instance, returning the result as a new transform.
        Parameters:
        rotation - the rotation to apply
        Returns:
        a new transform containing the result of applying the rotation to the current instance
      • rotate

        public AffineTransformMatrix2D rotate​(Vector2D center,
                                              double angle)
        Apply a counterclockwise rotation about the given center point to the current instance, returning the result as a new transform. This is accomplished by translating the center to the origin, applying the rotation, and then translating back.
        Parameters:
        center - the center of rotation
        angle - the angle of counterclockwise rotation in radians
        Returns:
        a new transform containing the result of applying a rotation about the given center point to the current instance
      • rotate

        public AffineTransformMatrix2D rotate​(Vector2D center,
                                              Rotation2D rotation)
        Apply a counterclockwise rotation about the given center point to the current instance, returning the result as a new transform. This is accomplished by translating the center to the origin, applying the rotation, and then translating back.
        Parameters:
        center - the center of rotation
        rotation - the rotation to apply
        Returns:
        a new transform containing the result of applying a rotation about the given center point to the current instance
      • shear

        public AffineTransformMatrix2D shear​(double shx,
                                             double shy)
        Apply a shear to the current instance, returning the result as a new transform.
        Parameters:
        shx - multiplier by which coordinates are shifted along the positive x-axis as a factor of their y coordinate; a value of 0 indicates no shift along the x-axis
        shy - multiplier by which coordinates are shifted along the positive y-axis as a factor of their x coordinate; a value of 0 indicates no shift along the y-axis
        Returns:
        a new transform containing the result of applying a shear to the current instance
      • multiply

        public AffineTransformMatrix2D multiply​(AffineTransformMatrix2D m)
        Get a new transform created by multiplying this instance by the argument. This is equivalent to the expression A * M where A is the current transform matrix and M is the given transform matrix. In terms of transformations, applying the returned matrix is equivalent to applying M and then applying A. In other words, the rightmost transform is applied first.
        Parameters:
        m - the transform to multiply with
        Returns:
        the result of multiplying the current instance by the given transform matrix
      • premultiply

        public AffineTransformMatrix2D premultiply​(AffineTransformMatrix2D m)
        Get a new transform created by multiplying the argument by this instance. This is equivalent to the expression M * A where A is the current transform matrix and M is the given transform matrix. In terms of transformations, applying the returned matrix is equivalent to applying A and then applying M. In other words, the rightmost transform is applied first.
        Parameters:
        m - the transform to multiply with
        Returns:
        the result of multiplying the given transform matrix by the current instance
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Return true if the given object is an instance of AffineTransformMatrix2D and all matrix element values are exactly equal.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - object to test for equality with the current instance
        Returns:
        true if all transform matrix elements are exactly equal; otherwise false
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • applyVector

        private <T> T applyVector​(Vector2D vec,
                                  DoubleFunction2N<T> factory)
        Multiplies the given vector by the 2x2 linear transformation matrix contained in the upper-right corner of the affine transformation matrix. This applies all transformation operations except for translations. The computed coordinates are passed to the given factory function.
        Type Parameters:
        T - factory output type
        Parameters:
        vec - the vector to transform
        factory - the factory instance that will be passed the transformed coordinates
        Returns:
        the factory return value
      • of

        public static AffineTransformMatrix2D of​(double... arr)
        Get a new transform with the given matrix elements. The array must contain 6 elements.
        Parameters:
        arr - 6-element array containing values for the variable entries in the transform matrix
        Returns:
        a new transform initialized with the given matrix values
        Throws:
        java.lang.IllegalArgumentException - if the array does not have 6 elements
      • from

        public static AffineTransformMatrix2D from​(java.util.function.UnaryOperator<Vector2D> fn)
        Construct a new transform representing the given function. The function is sampled at the origin and along each axis and a matrix is created to perform the transformation.
        Parameters:
        fn - function to create a transform matrix from
        Returns:
        a transform matrix representing the given function
        Throws:
        java.lang.IllegalArgumentException - if the given function does not represent a valid affine transform
      • fromColumnVectors

        public static AffineTransformMatrix2D fromColumnVectors​(Vector2D u,
                                                                Vector2D v)
        Get a new transform create from the given column vectors. The returned transform does not include any translation component.
        Parameters:
        u - first column vector; this corresponds to the first basis vector in the coordinate frame
        v - second column vector; this corresponds to the second basis vector in the coordinate frame
        Returns:
        a new transform with the given column vectors
      • fromColumnVectors

        public static AffineTransformMatrix2D fromColumnVectors​(Vector2D u,
                                                                Vector2D v,
                                                                Vector2D t)
        Get a new transform created from the given column vectors.
        Parameters:
        u - first column vector; this corresponds to the first basis vector in the coordinate frame
        v - second column vector; this corresponds to the second basis vector in the coordinate frame
        t - third column vector; this corresponds to the translation of the transform
        Returns:
        a new transform with the given column vectors
      • identity

        public static AffineTransformMatrix2D identity()
        Get the transform representing the identity matrix. This transform does not modify point or vector values when applied.
        Returns:
        transform representing the identity matrix
      • createTranslation

        public static AffineTransformMatrix2D createTranslation​(Vector2D translation)
        Create a transform representing the given translation.
        Parameters:
        translation - vector containing translation values for each axis
        Returns:
        a new transform representing the given translation
      • createTranslation

        public static AffineTransformMatrix2D createTranslation​(double x,
                                                                double y)
        Create a transform representing the given translation.
        Parameters:
        x - translation in the x direction
        y - translation in the y direction
        Returns:
        a new transform representing the given translation
      • createScale

        public static AffineTransformMatrix2D createScale​(double factor)
        Create a transform representing a scale operation with the given scale factor applied to all axes.
        Parameters:
        factor - scale factor to apply to all axes
        Returns:
        a new transform representing a uniform scaling in all axes
      • createScale

        public static AffineTransformMatrix2D createScale​(Vector2D factors)
        Create a transform representing a scale operation.
        Parameters:
        factors - vector containing scale factors for each axis
        Returns:
        a new transform representing a scale operation
      • createScale

        public static AffineTransformMatrix2D createScale​(double x,
                                                          double y)
        Create a transform representing a scale operation.
        Parameters:
        x - scale factor for the x axis
        y - scale factor for the y axis
        Returns:
        a new transform representing a scale operation
      • createRotation

        public static AffineTransformMatrix2D createRotation​(double angle)
        Create a transform representing a counterclockwise rotation of angle radians around the origin.
        Parameters:
        angle - the angle of rotation in radians
        Returns:
        a new transform representing the rotation
        See Also:
        Rotation2D.toMatrix()
      • createRotation

        public static AffineTransformMatrix2D createRotation​(Vector2D center,
                                                             double angle)
        Create a transform representing a counterclockwise rotation of angle radians around the given center point. This is accomplished by translating the center point to the origin, applying the rotation, and then translating back.
        Parameters:
        center - the center of rotation
        angle - the angle of rotation in radians
        Returns:
        a new transform representing the rotation about the given center
      • createRotation

        public static AffineTransformMatrix2D createRotation​(Vector2D center,
                                                             Rotation2D rotation)
        Create a transform representing a counterclockwise rotation around the given center point. This is accomplished by translating the center point to the origin, applying the rotation, and then translating back.
        Parameters:
        center - the center of rotation
        rotation - the rotation to apply
        Returns:
        a new transform representing the rotation about the given center
      • createShear

        public static AffineTransformMatrix2D createShear​(double shx,
                                                          double shy)
        Create a transform representing a shear operation. The returned instance contains the matrix values
              [ 1,    shx,  0 ]
              [ shy,  1,    0 ]
              [ 0,    0,    0 ]
         
        Parameters:
        shx - multiplier by which coordinates are shifted along the positive x-axis as a factor of their y coordinate; a value of 0 indicates no shift along the x-axis
        shy - multiplier by which coordinates are shifted along the positive y-axis as a factor of their x coordinate; a value of 0 indicates no shift along the y-axis
        Returns:
        a new transform representing the shear operation