Package org.apache.commons.geometry.euclidean.threed

Class AffineTransformMatrix3D

java.lang.Object

org.apache.commons.geometry.euclidean.AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>

org.apache.commons.geometry.euclidean.threed.AffineTransformMatrix3D

All Implemented Interfaces:

Function<Vector3D,Vector3D>, UnaryOperator<Vector3D>, Transform<Vector3D>, EuclideanTransform<Vector3D>

public final class AffineTransformMatrix3D
extends AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>

Class using a matrix to represent affine transformations in 3 dimensional Euclidean space.

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

Field Summary

Fields

Modifier and Type	Field	Description
private static final String	ELEMENT_SEPARATOR	String used to separate elements in the matrix string representation.
private static final AffineTransformMatrix3D	IDENTITY_INSTANCE	Shared transform set to the identity matrix.
private final double	m00	Transform matrix entry m0,0.
private final double	m01	Transform matrix entry m0,1.
private final double	m02	Transform matrix entry m0,2.
private final double	m03	Transform matrix entry m0,3.
private final double	m10	Transform matrix entry m1,0.
private final double	m11	Transform matrix entry m1,1.
private final double	m12	Transform matrix entry m1,2.
private final double	m13	Transform matrix entry m1,3.
private final double	m20	Transform matrix entry m2,0.
private final double	m21	Transform matrix entry m2,1.
private final double	m22	Transform matrix entry m2,2.
private final double	m23	Transform matrix entry m2,3.
private static final String	MATRIX_END	String used to end the transform matrix string representation.
private static final String	MATRIX_START	String used to start the transform matrix string representation.
private static final int	NUM_ELEMENTS	The number of internal matrix elements.
private static final String	ROW_SEPARATOR	String used to separate rows in the matrix string representation.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	AffineTransformMatrix3D(double m00, double m01, double m02, double m03, double m10, double m11, double m12, double m13, double m20, double m21, double m22, double m23)	Package-private constructor; sets all internal matrix elements.

Method Summary

Modifier and Type	Method	Description
Vector3D	apply(Vector3D pt)	Apply this transform to the given point, returning the result as a new instance.
Vector3D.Unit	applyDirection(Vector3D vec)	Apply this transform to the given vector, ignoring translations and normalizing the result.
Vector3D	applyVector(Vector3D vec)	Apply this transform to the given vector, ignoring translations.
private <T> T	applyVector(Vector3D vec, DoubleFunction3N<T> factory)	Multiplies the given vector by the 3x3 linear transformation matrix contained in the upper-right corner of the affine transformation matrix.
double	applyVectorX(double x, double y, double z)	Apply this transform to the given vector coordinates, ignoring translations, and return the transformed x value.
double	applyVectorY(double x, double y, double z)	Apply this transform to the given vector coordinates, ignoring translations, and return the transformed y value.
double	applyVectorZ(double x, double y, double z)	Apply this transform to the given vector coordinates, ignoring translations, and return the transformed z value.
double	applyX(double x, double y, double z)	Apply this transform to the given point coordinates and return the transformed x value.
double	applyY(double x, double y, double z)	Apply this transform to the given point coordinates and return the transformed y value.
double	applyZ(double x, double y, double z)	Apply this transform to the given point coordinates and return the transformed z value.
static AffineTransformMatrix3D	createRotation(Vector3D center, QuaternionRotation rotation)	Create a transform representing a rotation about the given center point.
static AffineTransformMatrix3D	createScale(double factor)	Create a transform representing a scale operation with the given scale factor applied to all axes.
static AffineTransformMatrix3D	createScale(double x, double y, double z)	Create a transform representing a scale operation.
static AffineTransformMatrix3D	createScale(Vector3D factors)	Create a transform representing a scale operation.
static AffineTransformMatrix3D	createTranslation(double x, double y, double z)	Create a transform representing the given translation.
static AffineTransformMatrix3D	createTranslation(Vector3D translation)	Create a transform representing the given translation.
double	determinant()	Get the determinant of the matrix.
boolean	equals(Object obj)	Return true if the given object is an instance of AffineTransformMatrix3D and all matrix element values are exactly equal.
static AffineTransformMatrix3D	from(UnaryOperator<Vector3D> fn)	Construct a new transform representing the given function.
static AffineTransformMatrix3D	fromColumnVectors(Vector3D u, Vector3D v, Vector3D w)	Get a new transform create from the given column vectors.
static AffineTransformMatrix3D	fromColumnVectors(Vector3D u, Vector3D v, Vector3D w, Vector3D t)	Get a new transform created from the given column vectors.
int	hashCode()
static AffineTransformMatrix3D	identity()	Get the transform representing the identity matrix.
AffineTransformMatrix3D	inverse()	Get an instance representing the inverse transform.
AffineTransformMatrix3D	linear()	Return a matrix containing only the linear portion of this transform.
AffineTransformMatrix3D	linearTranspose()	Return a matrix containing the transpose of the linear portion of this transform.
AffineTransformMatrix3D	multiply(AffineTransformMatrix3D m)	Get a new transform created by multiplying this instance by the argument.
private static AffineTransformMatrix3D	multiply(AffineTransformMatrix3D a, AffineTransformMatrix3D b)	Multiply two transform matrices together and return the result as a new transform instance.
static AffineTransformMatrix3D	of(double... arr)	Get a new transform with the given matrix elements.
AffineTransformMatrix3D	premultiply(AffineTransformMatrix3D m)	Get a new transform created by multiplying the argument by this instance.
AffineTransformMatrix3D	rotate(QuaternionRotation rotation)	Apply a rotation to the current instance, returning the result as a new transform.
AffineTransformMatrix3D	rotate(Vector3D center, QuaternionRotation rotation)	Apply a rotation around the given center point to the current instance, returning the result as a new transform.
AffineTransformMatrix3D	scale(double factor)	Apply a scale operation to the current instance, returning the result as a new transform.
AffineTransformMatrix3D	scale(double x, double y, double z)	Apply a scale operation to the current instance, returning the result as a new transform.
AffineTransformMatrix3D	scale(Vector3D scaleFactors)	Apply a scale operation to the current instance, returning the result as a new transform.
double[]	toArray()	Return a 12 element array containing the variable elements from the internal transformation matrix.
String	toString()
AffineTransformMatrix3D	translate(double x, double y, double z)	Apply a translation to the current instance, returning the result as a new transform.
AffineTransformMatrix3D	translate(Vector3D translation)	Apply a translation to the current instance, returning the result as a new transform.

Methods inherited from class org.apache.commons.geometry.euclidean.AbstractAffineTransformMatrix

normalTransform, preservesOrientation

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.function.Function

andThen, compose

Field Details

NUM_ELEMENTS

private static final int NUM_ELEMENTS

The number of internal matrix elements.

See Also:

• Constant Field Values

MATRIX_START

private static final String MATRIX_START

String used to start the transform matrix string representation.

See Also:

• Constant Field Values

MATRIX_END

private static final String MATRIX_END

String used to end the transform matrix string representation.

See Also:

• Constant Field Values

ELEMENT_SEPARATOR

private static final String ELEMENT_SEPARATOR

String used to separate elements in the matrix string representation.

See Also:

• Constant Field Values

ROW_SEPARATOR

private static final String ROW_SEPARATOR

String used to separate rows in the matrix string representation.

See Also:

• Constant Field Values

IDENTITY_INSTANCE

private static final AffineTransformMatrix3D 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.

m03

private final double m03

Transform matrix entry m0,3.

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.

m13

private final double m13

Transform matrix entry m1,3.

m20

private final double m20

Transform matrix entry m2,0.

m21

private final double m21

Transform matrix entry m2,1.

m22

private final double m22

Transform matrix entry m2,2.

m23

private final double m23

Transform matrix entry m2,3.

Constructor Details

AffineTransformMatrix3D

private AffineTransformMatrix3D(double m00,
 double m01,
 double m02,
 double m03,
 double m10,
 double m11,
 double m12,
 double m13,
 double m20,
 double m21,
 double m22,
 double m23)

Package-private constructor; sets all internal matrix elements.

Parameters:

m00 - matrix entry m0,0

m01 - matrix entry m0,1

m02 - matrix entry m0,2

m03 - matrix entry m0,3

m10 - matrix entry m1,0

m11 - matrix entry m1,1

m12 - matrix entry m1,2

m13 - matrix entry m1,3

m20 - matrix entry m2,0

m21 - matrix entry m2,1

m22 - matrix entry m2,2

m23 - matrix entry m2,3

Method Details

toArray

public double[] toArray()

Return a 12 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],   arr[6],   arr[7],
          arr[8],   arr[9],   arr[10],  arr[11],
          0         0         0         1
      ]
 

Returns:

12 element array containing the variable elements from the internal transformation matrix

apply

public Vector3D apply(Vector3D pt)

Apply this transform to the given point, returning the result as a new instance.

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

      [ m00  m01  m02  m03 ]     [ x ]     [ x']
      [ m10  m11  m12  m13 ]  *  [ y ]  =  [ y']
      [ m20  m21  m22  m23 ]     [ z ]     [ z']
      [ 0    0    0    1   ]     [ 1 ]     [ 1 ]
 

applyX

public double applyX(double x,
 double y,
 double z)

Apply this transform to the given point coordinates and return the transformed x value. The return value is equal to (x * m00) + (y * m01) + (z * m02) + m03.

Parameters:

x - x coordinate value

y - y coordinate value

z - z coordinate value

Returns:

transformed x coordinate value

See Also:

• apply(Vector3D)

applyY

public double applyY(double x,
 double y,
 double z)

Apply this transform to the given point coordinates and return the transformed y value. The return value is equal to (x * m10) + (y * m11) + (z * m12) + m13.

Parameters:

x - x coordinate value

y - y coordinate value

z - z coordinate value

Returns:

transformed y coordinate value

See Also:

• apply(Vector3D)

applyZ

public double applyZ(double x,
 double y,
 double z)

Apply this transform to the given point coordinates and return the transformed z value. The return value is equal to (x * m20) + (y * m21) + (z * m22) + m23.

Parameters:

x - x coordinate value

y - y coordinate value

z - z coordinate value

Returns:

transformed z coordinate value

See Also:

• apply(Vector3D)

applyVector

public Vector3D applyVector(Vector3D 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 4-element column vector from the coordinates in the input and setting the last element to 0. This is then multiplied with the 4x4 transform matrix to produce the transformed vector. The 0 in the last position is ignored.

      [ m00  m01  m02  m03 ]     [ x ]     [ x']
      [ m10  m11  m12  m13 ]  *  [ y ]  =  [ y']
      [ m20  m21  m22  m23 ]     [ z ]     [ z']
      [ 0    0    0    1   ]     [ 0 ]     [ 0 ]
 

Parameters:

vec - the vector to transform

Returns:

the new, transformed vector

See Also:

• applyDirection(Vector3D)

applyVectorX

public double applyVectorX(double x,
 double y,
 double z)

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) + (z * m02).

Parameters:

x - x coordinate value

y - y coordinate value

z - z coordinate value

Returns:

transformed x coordinate value

See Also:

• applyVector(Vector3D)

applyVectorY

public double applyVectorY(double x,
 double y,
 double z)

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) + (z * m12).

Parameters:

x - x coordinate value

y - y coordinate value

z - z coordinate value

Returns:

transformed y coordinate value

See Also:

• applyVector(Vector3D)

applyVectorZ

public double applyVectorZ(double x,
 double y,
 double z)

Apply this transform to the given vector coordinates, ignoring translations, and return the transformed z value. The return value is equal to (x * m20) + (y * m21) + (z * m22).

Parameters:

x - x coordinate value

y - y coordinate value

z - z coordinate value

Returns:

transformed z coordinate value

See Also:

• applyVector(Vector3D)

applyDirection

public Vector3D.Unit applyDirection(Vector3D vec)

Apply this transform to the given vector, ignoring translations and normalizing the result. This is equivalent to transform.applyVector(vec).normalize() but without the intermediate vector instance.

Specified by:

applyDirection in class AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>

Parameters:

vec - the vector to transform

Returns:

the new, transformed unit vector

See Also:

• applyVector(Vector3D)

determinant

public double determinant()

Get the determinant of the matrix.

Specified by:

determinant in class AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>

Returns:

the determinant of the matrix

linear

public AffineTransformMatrix3D 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, d ]   [ a, b, c, 0 ]
      [ e, f, g, h ]   [ e, f, g, 0 ]
      [ i, j, k, l ] → [ i, j, k, 0 ]
      [ 0, 0, 0, 1 ]   [ 0, 0, 0, 1 ]
 

Specified by:

linear in class AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>

Returns:

a matrix containing only the linear portion of this transform

linearTranspose

public AffineTransformMatrix3D 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, d ]   [ a, e, i, 0 ]
      [ e, f, g, h ]   [ b, f, j, 0 ]
      [ i, j, k, l ] → [ c, g, k, 0 ]
      [ 0, 0, 0, 1 ]   [ 0, 0, 0, 1 ]
 

Specified by:

linearTranspose in class AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>

Returns:

a matrix containing the transpose of the linear portion of this transform

translate

public AffineTransformMatrix3D translate(Vector3D 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 AffineTransformMatrix3D translate(double x,
 double y,
 double z)

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

z - translation in the z direction

Returns:

a new transform containing the result of applying a translation to the current instance

scale

public AffineTransformMatrix3D 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 AffineTransformMatrix3D scale(Vector3D 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 AffineTransformMatrix3D scale(double x,
 double y,
 double z)

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

z - scale factor for the z axis

Returns:

a new transform containing the result of applying a scale operation to the current instance

rotate

public AffineTransformMatrix3D rotate(QuaternionRotation rotation)

Apply a 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 a rotation to the current instance

See Also:

• QuaternionRotation.toMatrix()

rotate

public AffineTransformMatrix3D rotate(Vector3D center,
 QuaternionRotation rotation)

Apply a rotation around the given center point to the current instance, returning the result as a new transform. This is achieved 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 containing the result of applying a rotation about the given center point to the current instance

See Also:

• QuaternionRotation.toMatrix()

multiply

public AffineTransformMatrix3D multiply(AffineTransformMatrix3D 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 AffineTransformMatrix3D premultiply(AffineTransformMatrix3D 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

inverse

public AffineTransformMatrix3D inverse()

Get an instance representing the inverse transform.

Specified by:

inverse in interface Transform<Vector3D>

Specified by:

inverse in class AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>

Returns:

an instance representing the inverse transform

Throws:

IllegalStateException - if the matrix cannot be inverted

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Return true if the given object is an instance of AffineTransformMatrix3D and all matrix element values are exactly equal.

Overrides:

equals in class 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 String toString()

Overrides:

toString in class Object

applyVector

private <T> T applyVector(Vector3D vec,
 DoubleFunction3N<T> factory)

Multiplies the given vector by the 3x3 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 AffineTransformMatrix3D of(double... arr)

Get a new transform with the given matrix elements. The array must contain 12 elements.

Parameters:

arr - 12-element array containing values for the variable entries in the transform matrix

Returns:

a new transform initialized with the given matrix values

Throws:

IllegalArgumentException - if the array does not have 12 elements

from

public static AffineTransformMatrix3D from(UnaryOperator<Vector3D> 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:

IllegalArgumentException - if the given function does not represent a valid affine transform

fromColumnVectors

public static AffineTransformMatrix3D fromColumnVectors(Vector3D u,
 Vector3D v,
 Vector3D w)

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

w - third column vector; this corresponds to the third basis vector in the coordinate frame

Returns:

a new transform with the given column vectors

fromColumnVectors

public static AffineTransformMatrix3D fromColumnVectors(Vector3D u,
 Vector3D v,
 Vector3D w,
 Vector3D 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

w - third column vector; this corresponds to the third basis vector in the coordinate frame

t - fourth column vector; this corresponds to the translation of the transform

Returns:

a new transform with the given column vectors

identity

public static AffineTransformMatrix3D 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 AffineTransformMatrix3D createTranslation(Vector3D 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 AffineTransformMatrix3D createTranslation(double x,
 double y,
 double z)

Create a transform representing the given translation.

Parameters:

x - translation in the x direction

y - translation in the y direction

z - translation in the z direction

Returns:

a new transform representing the given translation

createScale

public static AffineTransformMatrix3D 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 AffineTransformMatrix3D createScale(Vector3D 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 AffineTransformMatrix3D createScale(double x,
 double y,
 double z)

Create a transform representing a scale operation.

Parameters:

x - scale factor for the x axis

y - scale factor for the y axis

z - scale factor for the z axis

Returns:

a new transform representing a scale operation

createRotation

public static AffineTransformMatrix3D createRotation(Vector3D center,
 QuaternionRotation rotation)

Create a transform representing a rotation about the given center point. This is achieved 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 representing a rotation about the given center point

See Also:

• QuaternionRotation.toMatrix()

multiply

private static AffineTransformMatrix3D multiply(AffineTransformMatrix3D a,
 AffineTransformMatrix3D b)

Multiply two transform matrices together and return the result as a new transform instance.

Parameters:

a - first transform

b - second transform

Returns:

the transform computed as a x b