Class AffineTransformMatrix3D
- java.lang.Object
-
- org.apache.commons.geometry.euclidean.AbstractAffineTransformMatrix<Vector3D,AffineTransformMatrix3D>
-
- org.apache.commons.geometry.euclidean.threed.AffineTransformMatrix3D
-
- All Implemented Interfaces:
java.util.function.Function<Vector3D,Vector3D>
,java.util.function.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 java.lang.String
ELEMENT_SEPARATOR
String used to separate elements in the matrix string representation.private static AffineTransformMatrix3D
IDENTITY_INSTANCE
Shared transform set to the identity matrix.private double
m00
Transform matrix entrym0,0
.private double
m01
Transform matrix entrym0,1
.private double
m02
Transform matrix entrym0,2
.private double
m03
Transform matrix entrym0,3
.private double
m10
Transform matrix entrym1,0
.private double
m11
Transform matrix entrym1,1
.private double
m12
Transform matrix entrym1,2
.private double
m13
Transform matrix entrym1,3
.private double
m20
Transform matrix entrym2,0
.private double
m21
Transform matrix entrym2,1
.private double
m22
Transform matrix entrym2,2
.private double
m23
Transform matrix entrym2,3
.private static java.lang.String
MATRIX_END
String used to end the transform matrix string representation.private static java.lang.String
MATRIX_START
String used to start the transform matrix string representation.private static int
NUM_ELEMENTS
The number of internal matrix elements.private static java.lang.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
All Methods Static Methods Instance Methods Concrete Methods 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(java.lang.Object obj)
Return true if the given object is an instance ofAffineTransformMatrix3D
and all matrix element values are exactly equal.static AffineTransformMatrix3D
from(java.util.function.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.java.lang.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
-
-
-
-
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 AffineTransformMatrix3D IDENTITY_INSTANCE
Shared transform set to the identity matrix.
-
m00
private final double m00
Transform matrix entrym0,0
.
-
m01
private final double m01
Transform matrix entrym0,1
.
-
m02
private final double m02
Transform matrix entrym0,2
.
-
m03
private final double m03
Transform matrix entrym0,3
.
-
m10
private final double m10
Transform matrix entrym1,0
.
-
m11
private final double m11
Transform matrix entrym1,1
.
-
m12
private final double m12
Transform matrix entrym1,2
.
-
m13
private final double m13
Transform matrix entrym1,3
.
-
m20
private final double m20
Transform matrix entrym2,0
.
-
m21
private final double m21
Transform matrix entrym2,1
.
-
m22
private final double m22
Transform matrix entrym2,2
.
-
m23
private final double m23
Transform matrix entrym2,3
.
-
-
Constructor Detail
-
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 Detail
-
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 valuey
- y coordinate valuez
- 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 valuey
- y coordinate valuez
- 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 valuey
- y coordinate valuez
- 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 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:
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 valuey
- y coordinate valuez
- 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 valuey
- y coordinate valuez
- 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 valuey
- y coordinate valuez
- 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 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:
applyVector(Vector3D)
-
determinant
public double determinant()
Get the determinant of the matrix.- Specified by:
determinant
in classAbstractAffineTransformMatrix<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 classAbstractAffineTransformMatrix<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 classAbstractAffineTransformMatrix<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 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
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 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
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 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:
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 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
public AffineTransformMatrix3D premultiply(AffineTransformMatrix3D m)
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
public AffineTransformMatrix3D 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:
java.lang.IllegalStateException
- if the matrix cannot be inverted
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
Return true if the given object is an instance ofAffineTransformMatrix3D
and all matrix element values are exactly equal.- Overrides:
equals
in classjava.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 classjava.lang.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 transformfactory
- 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:
java.lang.IllegalArgumentException
- if the array does not have 12 elements
-
from
public static AffineTransformMatrix3D from(java.util.function.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:
java.lang.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 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
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 directiony
- translation in the y directionz
- 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 axisy
- scale factor for the y axisz
- 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 rotationrotation
- 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 transformb
- second transform- Returns:
- the transform computed as
a x b
-
-