Package com.luciad.cartesian

Class Matrix4x4

java.lang.Object
com.luciad.cartesian.Matrix4x4
All Implemented Interfaces:
AutoCloseable
public final class Matrix4x4 extends Object implements AutoCloseable
A general-purpose 4x4 matrix, defined in a right-handed coordinate system.

A common use case for this class is to represent affine 3D transformations, such as translations, scalings, and rotations.

Since:
2026.1

  • Constructor Details

    • Matrix4x4

      public Matrix4x4()
      Default constructor.

      Constructs the identity matrix.

  • Method Details

    • finalize

      protected void finalize()
      Overrides:
      finalize in class Object

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • identity

      @NotNull public static Matrix4x4 identity()
      Creates a new identity matrix. 

       [ 1 0 0 0 ]
   [ 0 1 0 0 ]
   [ 0 0 1 0 ]
   [ 0 0 0 1 ]
      Returns:
      a new identity matrix.

    • translate

      @NotNull public static Matrix4x4 translate(double x, double y, double z)
      Creates a new translation matrix.
      Parameters:
      x - the translation on the x-axis.
      y - the translation on the y-axis.
      z - the translation on the z-axis.
      Returns:
      a new translation matrix.

    • translate

      @NotNull public static Matrix4x4 translate(@NotNull Coordinate translation)
      Creates a new translation matrix.
      Parameters:
      translation - the translation.
      Returns:
      a new translation matrix.

    • scale

      @NotNull public static Matrix4x4 scale(double scalar)
      Creates a new scaling matrix in all 3 dimensions.
      Parameters:
      scalar - the amount to scale.
      Returns:
      a new scaling matrix.

    • scale

      @NotNull public static Matrix4x4 scale(double x, double y, double z)
      Creates a new scaling matrix.
      Parameters:
      x - the amount to scale on the x-axis.
      y - the amount to scale on the y-axis.
      z - the amount to scale on the z-axis.
      Returns:
      a new scaling matrix.

    • rotateX

      @NotNull public static Matrix4x4 rotateX(@NotNull Angle angle)
      Creates a new rotation matrix around the x-axis.

      Note: the rotation happens counterclockwise. Looking towards negative infinity on the x-axis makes the rotation appear counterclockwise.

      Parameters:
      angle - the amount to rotate.
      Returns:
      a new rotation matrix around the x-axis.

    • rotateY

      @NotNull public static Matrix4x4 rotateY(@NotNull Angle angle)
      Creates a new rotation matrix around the y-axis.

      Note: the rotation happens counterclockwise. Looking towards negative infinity on the y-axis makes the rotation appear counterclockwise.

      Parameters:
      angle - the amount to rotate.
      Returns:
      a new rotation matrix around the y-axis.

    • rotateZ

      @NotNull public static Matrix4x4 rotateZ(@NotNull Angle angle)
      Creates a new rotation matrix around the z-axis.

      Note: the rotation happens counterclockwise. Looking towards negative infinity on the z-axis makes the rotation appear counterclockwise.

      Parameters:
      angle - the amount to rotate.
      Returns:
      a new rotation matrix around the z-axis.

    • rotate

      @NotNull public static Matrix4x4 rotate(@NotNull Coordinate axis, @NotNull Angle angle)
      Creates a new rotation matrix around a given vector.

      Note: the rotation happens counterclockwise. When imagining the vector as an arrow, looking at the arrowhead coming towards you makes the rotation appear counterclockwise.

      Parameters:
      axis - the vector to rotate around.
      angle - the amount to rotate.
      Returns:
      a new rotation matrix around the given vector.

    • create

      @NotNull public static Matrix4x4 create(@NotNull List<Double> values) throws IllegalArgumentException
      Creates a new 4x4 matrix with the given values.

      The values are expected in column-major order. For example, a list like [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] will become the following matrix: 

       [ 0   4   8  12 ]
   [ 1   5   9  13 ]
   [ 2   6  10  14 ]
   [ 3   7  11  15 ]
      Parameters:
      values - a list of 16 values, in column-major order.
      Returns:
      a new 4x4 matrix with the given values.
      Throws:
      IllegalArgumentException - when the list does not contain exactly 16 values.

    • add

      @NotNull public Matrix4x4 add(@NotNull Matrix4x4 other)
      Returns the sum of two matrices.
      Parameters:
      other - the other matrix.
      Returns:
      the sum of the two matrices.

    • subtract

      @NotNull public Matrix4x4 subtract(@NotNull Matrix4x4 other)
      Returns the difference of two matrices.
      Parameters:
      other - the other matrix.
      Returns:
      the difference of the two matrices.

    • multiply

      @NotNull public Matrix4x4 multiply(@NotNull Matrix4x4 other)
      Returns the product of two matrices.
      Parameters:
      other - the other matrix.
      Returns:
      the product of the two matrices.

    • multiply

      @NotNull public Matrix4x4 multiply(double scalar)
      Returns the element-wise product between this matrix and a scalar.
      Parameters:
      scalar - the scalar.
      Returns:
      the element-wise product between this matrix and the scalar.

    • multiply

      @NotNull public Coordinate multiply(@NotNull Coordinate point)
      Applies this matrix as an affine transformation to a point.

      This method does the same as transformPoint.

      Parameters:
      point - the point.
      Returns:
      the transformed point.

    • inverse

      @Nullable public Matrix4x4 inverse()
      Returns the inverse of this matrix, or null if this matrix is not invertible.
      Returns:
      the inverse of this matrix, or null if this matrix is not invertible.

    • transpose

      @NotNull public Matrix4x4 transpose()
      Returns the transpose of this matrix.
      Returns:
      the transpose of this matrix.

    • getValue

      public double getValue(long column, long row)
      Returns the value from the given column and row.
      Parameters:
      column - the column.
      row - the row.
      Returns:
      the value from the given column and row.

    • setValue

      public void setValue(long column, long row, double value)
      Sets the value at the given column and row.
      Parameters:
      column - the column.
      row - the row.
      value - the value.

    • transformPoint

      @NotNull public Coordinate transformPoint(@NotNull Coordinate point)
      Applies this matrix as an affine transformation to a point.

      This method does the same as the multiply operator.

      Parameters:
      point - the point.
      Returns:
      the transformed point.

    • transformVector

      @NotNull public Coordinate transformVector(@NotNull Coordinate vector)
      Applies this matrix as an affine transformation to a vector.

      Note: the main difference between transformVector and transformPoint is that transformVector does NOT apply translations, whereas transformPoint does.

      Parameters:
      vector - the vector.
      Returns:
      the transformed vector.

    • isAffineTransformation

      public boolean isAffineTransformation()
      Returns whether this arbitrary matrix represents a valid 3D affine transformation.

      This is equivalent to checking whether the matrix has the following form: 

       [ . . . . ]
   [ . . . . ]
   [ . . . . ]
   [ 0 0 0 1 ]
      Returns:
      whether this matrix is an affine transformation.

    • toString

      @NotNull public String toString()
      Overrides:
      toString in class Object

    • hashCode

      public int hashCode()
      Returns the hash of this matrix.
      Overrides:
      hashCode in class Object
      Returns:
      the hash of this matrix.

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object