Class AffineTransformMatrix3D
- All Implemented Interfaces:
Function<Vector3D,
,Vector3D> UnaryOperator<Vector3D>
,Transform<Vector3D>
,EuclideanTransform<Vector3D>
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
FieldsModifier and TypeFieldDescriptionprivate static final String
String used to separate elements in the matrix string representation.private static final AffineTransformMatrix3D
Shared transform set to the identity matrix.private final double
Transform matrix entrym0,0
.private final double
Transform matrix entrym0,1
.private final double
Transform matrix entrym0,2
.private final double
Transform matrix entrym0,3
.private final double
Transform matrix entrym1,0
.private final double
Transform matrix entrym1,1
.private final double
Transform matrix entrym1,2
.private final double
Transform matrix entrym1,3
.private final double
Transform matrix entrym2,0
.private final double
Transform matrix entrym2,1
.private final double
Transform matrix entrym2,2
.private final double
Transform matrix entrym2,3
.private static final String
String used to end the transform matrix string representation.private static final String
String used to start the transform matrix string representation.private static final int
The number of internal matrix elements.private static final String
String used to separate rows in the matrix string representation. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
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 TypeMethodDescriptionApply this transform to the given point, returning the result as a new instance.applyDirection
(Vector3D vec) Apply this transform to the given vector, ignoring translations and normalizing the result.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
Get the determinant of the matrix.boolean
Return true if the given object is an instance ofAffineTransformMatrix3D
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.inverse()
Get an instance representing the inverse transform.linear()
Return a matrix containing only the linear portion of this transform.Return a matrix containing the transpose of the linear portion of this transform.Get a new transform created by multiplying this instance by the argument.private static AffineTransformMatrix3D
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.Get a new transform created by multiplying the argument by this instance.rotate
(QuaternionRotation rotation) Apply a rotation to the current instance, returning the result as a new transform.rotate
(Vector3D center, QuaternionRotation rotation) Apply a rotation around the given center point to the current instance, returning the result as a new transform.scale
(double factor) Apply a scale operation to the current instance, returning the result as a new transform.scale
(double x, double y, double z) Apply a scale operation to the current instance, returning the result as a new transform.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.toString()
translate
(double x, double y, double z) Apply a translation to the current instance, returning the result as a new transform.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
-
Field Details
-
NUM_ELEMENTS
private static final int NUM_ELEMENTSThe number of internal matrix elements.- See Also:
-
MATRIX_START
String used to start the transform matrix string representation.- See Also:
-
MATRIX_END
String used to end the transform matrix string representation.- See Also:
-
ELEMENT_SEPARATOR
String used to separate elements in the matrix string representation.- See Also:
-
ROW_SEPARATOR
String used to separate rows in the matrix string representation.- See Also:
-
IDENTITY_INSTANCE
Shared transform set to the identity matrix. -
m00
private final double m00Transform matrix entrym0,0
. -
m01
private final double m01Transform matrix entrym0,1
. -
m02
private final double m02Transform matrix entrym0,2
. -
m03
private final double m03Transform matrix entrym0,3
. -
m10
private final double m10Transform matrix entrym1,0
. -
m11
private final double m11Transform matrix entrym1,1
. -
m12
private final double m12Transform matrix entrym1,2
. -
m13
private final double m13Transform matrix entrym1,3
. -
m20
private final double m20Transform matrix entrym2,0
. -
m21
private final double m21Transform matrix entrym2,1
. -
m22
private final double m22Transform matrix entrym2,2
. -
m23
private final double m23Transform matrix entrym2,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 entrym0,0
m01
- matrix entrym0,1
m02
- matrix entrym0,2
m03
- matrix entrym0,3
m10
- matrix entrym1,0
m11
- matrix entrym1,1
m12
- matrix entrym1,2
m13
- matrix entrym1,3
m20
- matrix entrym2,0
m21
- matrix entrym2,1
m22
- matrix entrym2,2
m23
- matrix entrym2,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
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 valuey
- y coordinate valuez
- z coordinate value- Returns:
- transformed x coordinate value
- See Also:
-
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 valuey
- y coordinate valuez
- z coordinate value- Returns:
- transformed y coordinate value
- See Also:
-
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 valuey
- y coordinate valuez
- z coordinate value- Returns:
- transformed z coordinate value
- See Also:
-
applyVector
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 pointsp1
andp2
, thentransform.applyVector(v)
will represent the difference betweenp1
andp2
aftertransform
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:
-
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 valuey
- y coordinate valuez
- z coordinate value- Returns:
- transformed x coordinate value
- See Also:
-
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 valuey
- y coordinate valuez
- z coordinate value- Returns:
- transformed y coordinate value
- See Also:
-
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 valuey
- y coordinate valuez
- z coordinate value- Returns:
- transformed z coordinate value
- See Also:
-
applyDirection
Apply this transform to the given vector, ignoring translations and normalizing the result. This is equivalent totransform.applyVector(vec).normalize()
but without the intermediate vector instance.- Specified by:
applyDirection
in classAbstractAffineTransformMatrix<Vector3D,
AffineTransformMatrix3D> - Parameters:
vec
- the vector to transform- Returns:
- the new, transformed unit vector
- See Also:
-
determinant
public double determinant()Get the determinant of the matrix.- Specified by:
determinant
in classAbstractAffineTransformMatrix<Vector3D,
AffineTransformMatrix3D> - Returns:
- the determinant of the matrix
-
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 classAbstractAffineTransformMatrix<Vector3D,
AffineTransformMatrix3D> - Returns:
- a matrix containing only the linear portion of this transform
-
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 classAbstractAffineTransformMatrix<Vector3D,
AffineTransformMatrix3D> - Returns:
- a matrix containing the transpose of the linear portion of this transform
-
translate
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
Apply a translation to the current instance, returning the result as a new transform.- Parameters:
x
- translation in the x directiony
- translation in the y directionz
- translation in the z direction- Returns:
- a new transform containing the result of applying a translation to the current instance
-
scale
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
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
Apply a scale operation to the current instance, returning the result as a new transform.- Parameters:
x
- scale factor for the x axisy
- scale factor for the y axisz
- scale factor for the z axis- Returns:
- a new transform containing the result of applying a scale operation to the current instance
-
rotate
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:
-
rotate
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 rotationrotation
- 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:
-
multiply
Get a new transform created by multiplying this instance by the argument. This is equivalent to the expressionA * M
whereA
is the current transform matrix andM
is the given transform matrix. In terms of transformations, applying the returned matrix is equivalent to applyingM
and then applyingA
. 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
Get a new transform created by multiplying the argument by this instance. This is equivalent to the expressionM * A
whereA
is the current transform matrix andM
is the given transform matrix. In terms of transformations, applying the returned matrix is equivalent to applyingA
and then applyingM
. 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
Get an instance representing the inverse transform.- Specified by:
inverse
in interfaceTransform<Vector3D>
- Specified by:
inverse
in classAbstractAffineTransformMatrix<Vector3D,
AffineTransformMatrix3D> - Returns:
- an instance representing the inverse transform
- Throws:
IllegalStateException
- if the matrix cannot be inverted
-
hashCode
public int hashCode() -
equals
Return true if the given object is an instance ofAffineTransformMatrix3D
and all matrix element values are exactly equal. -
toString
-
applyVector
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 transformfactory
- the factory instance that will be passed the transformed coordinates- Returns:
- the factory return value
-
of
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
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
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 framev
- second column vector; this corresponds to the second basis vector in the coordinate framew
- 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 framev
- second column vector; this corresponds to the second basis vector in the coordinate framew
- third column vector; this corresponds to the third basis vector in the coordinate framet
- fourth column vector; this corresponds to the translation of the transform- Returns:
- a new transform with the given column vectors
-
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
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
Create a transform representing the given translation.- Parameters:
x
- translation in the x directiony
- translation in the y directionz
- translation in the z direction- Returns:
- a new transform representing the given translation
-
createScale
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
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
Create a transform representing a scale operation.- Parameters:
x
- scale factor for the x axisy
- scale factor for the y axisz
- scale factor for the z axis- Returns:
- a new transform representing a scale operation
-
createRotation
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 rotationrotation
- the rotation to apply- Returns:
- a new transform representing a rotation about the given center point
- See Also:
-
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 transformb
- second transform- Returns:
- the transform computed as
a x b
-