Package org.locationtech.jts.geom.util
Class AffineTransformation
java.lang.Object
org.locationtech.jts.geom.util.AffineTransformation
- All Implemented Interfaces:
Cloneable
,CoordinateSequenceFilter
Represents an affine transformation on the 2D Cartesian plane.
It can be used to transform a
Coordinate
or Geometry
.
An affine transformation is a mapping of the 2D plane into itself
via a series of transformations of the following basic types:
- reflection (through a line)
- rotation (around the origin)
- scaling (relative to the origin)
- shearing (in both the X and Y directions)
- translation
An affine transformation can be represented by a 3x3 matrix in the following form:
A coordinate P = (x, y) can be transformed to a new coordinate P' = (x', y') by representing it as a 3x1 matrix and using matrix multiplication to compute:T = | m00 m01 m02 | | m10 m11 m12 | | 0 0 1 |
| x' | = T x | x | | y' | | y | | 1 | | 1 |
Transformation Composition
Affine transformations can be composed using thecompose(org.locationtech.jts.geom.util.AffineTransformation)
method.
Composition is computed via multiplication of the
transformation matrices, and is defined as:
A.compose(B) = TB x TA
This produces a transformation whose effect is that of A followed by B.
The methods reflect(double, double, double, double)
, rotate(double)
,
scale(double, double)
, shear(double, double)
, and translate(double, double)
have the effect of composing a transformation of that type with
the transformation they are invoked on.
The composition of transformations is in general not commutative.
Transformation Inversion
Affine transformations may be invertible or non-invertible. If a transformation is invertible, then there exists an inverse transformation which when composed produces the identity transformation. ThegetInverse()
method
computes the inverse of a transformation, if one exists.- Author:
- Martin Davis
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs a new identity transformationAffineTransformation
(double[] matrix) Constructs a new transformation whose matrix has the specified values.AffineTransformation
(double m00, double m01, double m02, double m10, double m11, double m12) Constructs a new transformation whose matrix has the specified values.AffineTransformation
(Coordinate src0, Coordinate src1, Coordinate src2, Coordinate dest0, Coordinate dest1, Coordinate dest2) Deprecated.use AffineTransformationFactoryConstructs a transformation which is a copy of the given one. -
Method Summary
Modifier and TypeMethodDescriptionclone()
Clones this transformationcompose
(AffineTransformation trans) Updates this transformation to be the composition of this transformation with the givenAffineTransformation
.Updates this transformation to be the composition of a givenAffineTransformation
with this transformation.boolean
Tests if an object is an AffineTransformation and has the same matrix as this transformation.void
filter
(CoordinateSequence seq, int i) Transforms the i'th coordinate in the input sequencedouble
Computes the determinant of the transformation matrix.Computes the inverse of this transformation, if one exists.double[]
Gets an array containing the entries of the transformation matrix.int
hashCode()
boolean
isDone()
Reports that this filter should continue to be executed until all coordinates have been transformed.boolean
Reports whether the execution of this filter has modified the coordinates of the geometry.boolean
Tests if this transformation is the identity transformation.reflect
(double x, double y) Updates the value of this transformation to that of a reflection transformation composed with the current value.reflect
(double x0, double y0, double x1, double y1) Updates the value of this transformation to that of a reflection transformation composed with the current value.static AffineTransformation
reflectionInstance
(double x, double y) Creates a transformation for a reflection about the line (0,0) - (x,y).static AffineTransformation
reflectionInstance
(double x0, double y0, double x1, double y1) Creates a transformation for a reflection about the line (x0,y0) - (x1,y1).rotate
(double theta) Updates the value of this transformation to that of a rotation transformation composed with the current value.rotate
(double sinTheta, double cosTheta) Updates the value of this transformation to that of a rotation around the origin composed with the current value, with the sin and cos of the rotation angle specified directly.rotate
(double theta, double x, double y) Updates the value of this transformation to that of a rotation around a given point composed with the current value.rotate
(double sinTheta, double cosTheta, double x, double y) Updates the value of this transformation to that of a rotation around a given point composed with the current value, with the sin and cos of the rotation angle specified directly.static AffineTransformation
rotationInstance
(double theta) Creates a transformation for a rotation about the origin by an angle theta.static AffineTransformation
rotationInstance
(double sinTheta, double cosTheta) Creates a transformation for a rotation by an angle theta, specified by the sine and cosine of the angle.static AffineTransformation
rotationInstance
(double theta, double x, double y) Creates a transformation for a rotation about the point (x,y) by an angle theta.static AffineTransformation
rotationInstance
(double sinTheta, double cosTheta, double x, double y) Creates a transformation for a rotation about the point (x,y) by an angle theta, specified by the sine and cosine of the angle.scale
(double xScale, double yScale) Updates the value of this transformation to that of a scale transformation composed with the current value.static AffineTransformation
scaleInstance
(double xScale, double yScale) Creates a transformation for a scaling relative to the origin.static AffineTransformation
scaleInstance
(double xScale, double yScale, double x, double y) Creates a transformation for a scaling relative to the point (x,y).Sets this transformation to be the identity transformation.setToReflection
(double x, double y) Sets this transformation to be a reflection about the line defined by vector (x,y).setToReflection
(double x0, double y0, double x1, double y1) Sets this transformation to be a reflection about the line defined by a line (x0,y0) - (x1,y1).setToReflectionBasic
(double x0, double y0, double x1, double y1) Explicitly computes the math for a reflection.setToRotation
(double theta) Sets this transformation to be a rotation around the origin.setToRotation
(double sinTheta, double cosTheta) Sets this transformation to be a rotation around the origin by specifying the sin and cos of the rotation angle directly.setToRotation
(double theta, double x, double y) Sets this transformation to be a rotation around a given point (x,y).setToRotation
(double sinTheta, double cosTheta, double x, double y) Sets this transformation to be a rotation around a given point (x,y) by specifying the sin and cos of the rotation angle directly.setToScale
(double xScale, double yScale) Sets this transformation to be a scaling.setToShear
(double xShear, double yShear) Sets this transformation to be a shear.setToTranslation
(double dx, double dy) Sets this transformation to be a translation.setTransformation
(double m00, double m01, double m02, double m10, double m11, double m12) Sets this transformation's matrix to have the given values.Sets this transformation to be a copy of the given oneshear
(double xShear, double yShear) Updates the value of this transformation to that of a shear transformation composed with the current value.static AffineTransformation
shearInstance
(double xShear, double yShear) Creates a transformation for a shear.toString()
Gets a text representation of this transformation.transform
(Coordinate src, Coordinate dest) Applies this transformation to the src coordinate and places the results in the dest coordinate (which may be the same as the source).void
transform
(CoordinateSequence seq, int i) Applies this transformation to the i'th coordinate in the given CoordinateSequence.Creates a newGeometry
which is the result of this transformation applied to the input Geometry.translate
(double x, double y) Updates the value of this transformation to that of a translation transformation composed with the current value.static AffineTransformation
translationInstance
(double x, double y) Creates a transformation for a translation.
-
Constructor Details
-
AffineTransformation
public AffineTransformation()Constructs a new identity transformation -
AffineTransformation
public AffineTransformation(double[] matrix) Constructs a new transformation whose matrix has the specified values.- Parameters:
matrix
- an array containing the 6 values { m00, m01, m02, m10, m11, m12 }- Throws:
NullPointerException
- if matrix is nullArrayIndexOutOfBoundsException
- if matrix is too small
-
AffineTransformation
public AffineTransformation(double m00, double m01, double m02, double m10, double m11, double m12) Constructs a new transformation whose matrix has the specified values.- Parameters:
m00
- the entry for the [0, 0] element in the transformation matrixm01
- the entry for the [0, 1] element in the transformation matrixm02
- the entry for the [0, 2] element in the transformation matrixm10
- the entry for the [1, 0] element in the transformation matrixm11
- the entry for the [1, 1] element in the transformation matrixm12
- the entry for the [1, 2] element in the transformation matrix
-
AffineTransformation
Constructs a transformation which is a copy of the given one.- Parameters:
trans
- the transformation to copy
-
AffineTransformation
public AffineTransformation(Coordinate src0, Coordinate src1, Coordinate src2, Coordinate dest0, Coordinate dest1, Coordinate dest2) Deprecated.use AffineTransformationFactoryConstructs a transformation which maps the given source points into the given destination points.- Parameters:
src0
- source point 0src1
- source point 1src2
- source point 2dest0
- the mapped point for source point 0dest1
- the mapped point for source point 1dest2
- the mapped point for source point 2
-
-
Method Details
-
reflectionInstance
Creates a transformation for a reflection about the line (x0,y0) - (x1,y1).- Parameters:
x0
- the x-ordinate of a point on the reflection liney0
- the y-ordinate of a point on the reflection linex1
- the x-ordinate of a another point on the reflection liney1
- the y-ordinate of a another point on the reflection line- Returns:
- a transformation for the reflection
-
reflectionInstance
Creates a transformation for a reflection about the line (0,0) - (x,y).- Parameters:
x
- the x-ordinate of a point on the reflection liney
- the y-ordinate of a point on the reflection line- Returns:
- a transformation for the reflection
-
rotationInstance
Creates a transformation for a rotation about the origin by an angle theta. Positive angles correspond to a rotation in the counter-clockwise direction.- Parameters:
theta
- the rotation angle, in radians- Returns:
- a transformation for the rotation
-
rotationInstance
Creates a transformation for a rotation by an angle theta, specified by the sine and cosine of the angle. This allows providing exact values for sin(theta) and cos(theta) for the common case of rotations of multiples of quarter-circles.- Parameters:
sinTheta
- the sine of the rotation anglecosTheta
- the cosine of the rotation angle- Returns:
- a transformation for the rotation
-
rotationInstance
Creates a transformation for a rotation about the point (x,y) by an angle theta. Positive angles correspond to a rotation in the counter-clockwise direction.- Parameters:
theta
- the rotation angle, in radiansx
- the x-ordinate of the rotation pointy
- the y-ordinate of the rotation point- Returns:
- a transformation for the rotation
-
rotationInstance
public static AffineTransformation rotationInstance(double sinTheta, double cosTheta, double x, double y) Creates a transformation for a rotation about the point (x,y) by an angle theta, specified by the sine and cosine of the angle. This allows providing exact values for sin(theta) and cos(theta) for the common case of rotations of multiples of quarter-circles.- Parameters:
sinTheta
- the sine of the rotation anglecosTheta
- the cosine of the rotation anglex
- the x-ordinate of the rotation pointy
- the y-ordinate of the rotation point- Returns:
- a transformation for the rotation
-
scaleInstance
Creates a transformation for a scaling relative to the origin.- Parameters:
xScale
- the value to scale by in the x directionyScale
- the value to scale by in the y direction- Returns:
- a transformation for the scaling
-
scaleInstance
Creates a transformation for a scaling relative to the point (x,y).- Parameters:
xScale
- the value to scale by in the x directionyScale
- the value to scale by in the y directionx
- the x-ordinate of the point to scale aroundy
- the y-ordinate of the point to scale around- Returns:
- a transformation for the scaling
-
shearInstance
Creates a transformation for a shear.- Parameters:
xShear
- the value to shear by in the x directionyShear
- the value to shear by in the y direction- Returns:
- a transformation for the shear
-
translationInstance
Creates a transformation for a translation.- Parameters:
x
- the value to translate by in the x directiony
- the value to translate by in the y direction- Returns:
- a transformation for the translation
-
setToIdentity
Sets this transformation to be the identity transformation. The identity transformation has the matrix:| 1 0 0 | | 0 1 0 | | 0 0 1 |
- Returns:
- this transformation, with an updated matrix
-
setTransformation
public AffineTransformation setTransformation(double m00, double m01, double m02, double m10, double m11, double m12) Sets this transformation's matrix to have the given values.- Parameters:
m00
- the entry for the [0, 0] element in the transformation matrixm01
- the entry for the [0, 1] element in the transformation matrixm02
- the entry for the [0, 2] element in the transformation matrixm10
- the entry for the [1, 0] element in the transformation matrixm11
- the entry for the [1, 1] element in the transformation matrixm12
- the entry for the [1, 2] element in the transformation matrix- Returns:
- this transformation, with an updated matrix
-
setTransformation
Sets this transformation to be a copy of the given one- Parameters:
trans
- a transformation to copy- Returns:
- this transformation, with an updated matrix
-
getMatrixEntries
public double[] getMatrixEntries()Gets an array containing the entries of the transformation matrix. Only the 6 non-trivial entries are returned, in the sequence:m00, m01, m02, m10, m11, m12
- Returns:
- an array of length 6
-
getDeterminant
public double getDeterminant()Computes the determinant of the transformation matrix. The determinant is computed as:
If the determinant is zero, the transform is singular (not invertible), and operations which attempt to compute an inverse will throw a NoninvertibleTransformException.| m00 m01 m02 | | m10 m11 m12 | = m00 * m11 - m01 * m10 | 0 0 1 |
- Returns:
- the determinant of the transformation
- See Also:
-
getInverse
Computes the inverse of this transformation, if one exists. The inverse is the transformation which when composed with this one produces the identity transformation. A transformation has an inverse if and only if it is not singular (i.e. its determinant is non-zero). Geometrically, an transformation is non-invertible if it maps the plane to a line or a point. If no inverse exists this method will throw a NoninvertibleTransformationException.The matrix of the inverse is equal to the inverse of the matrix for the transformation. It is computed as follows:
1 inverse(A) = --- x adjoint(A) det = 1 | m11 -m01 m01*m12-m02*m11 | --- x | -m10 m00 -m00*m12+m10*m02 | det | 0 0 m00*m11-m10*m01 | = | m11/det -m01/det m01*m12-m02*m11/det | | -m10/det m00/det -m00*m12+m10*m02/det | | 0 0 1 |
- Returns:
- a new inverse transformation
- Throws:
NoninvertibleTransformationException
- See Also:
-
setToReflectionBasic
Explicitly computes the math for a reflection. May not work.- Parameters:
x0
- the X ordinate of one point on the reflection liney0
- the Y ordinate of one point on the reflection linex1
- the X ordinate of another point on the reflection liney1
- the Y ordinate of another point on the reflection line- Returns:
- this transformation, with an updated matrix
-
setToReflection
Sets this transformation to be a reflection about the line defined by a line (x0,y0) - (x1,y1).- Parameters:
x0
- the X ordinate of one point on the reflection liney0
- the Y ordinate of one point on the reflection linex1
- the X ordinate of another point on the reflection liney1
- the Y ordinate of another point on the reflection line- Returns:
- this transformation, with an updated matrix
-
setToReflection
Sets this transformation to be a reflection about the line defined by vector (x,y). The transformation for a reflection is computed by:d = sqrt(x2 + y2)
sin = y / d;
cos = x / d;
Tref = Trot(sin, cos) x Tscale(1, -1) x Trot(-sin, cos)
- Parameters:
x
- the x-component of the reflection line vectory
- the y-component of the reflection line vector- Returns:
- this transformation, with an updated matrix
-
setToRotation
Sets this transformation to be a rotation around the origin. A positive rotation angle corresponds to a counter-clockwise rotation. The transformation matrix for a rotation by an angle theta has the value:| cos(theta) -sin(theta) 0 | | sin(theta) cos(theta) 0 | | 0 0 1 |
- Parameters:
theta
- the rotation angle, in radians- Returns:
- this transformation, with an updated matrix
-
setToRotation
Sets this transformation to be a rotation around the origin by specifying the sin and cos of the rotation angle directly. The transformation matrix for the rotation has the value:| cosTheta -sinTheta 0 | | sinTheta cosTheta 0 | | 0 0 1 |
- Parameters:
sinTheta
- the sine of the rotation anglecosTheta
- the cosine of the rotation angle- Returns:
- this transformation, with an updated matrix
-
setToRotation
Sets this transformation to be a rotation around a given point (x,y). A positive rotation angle corresponds to a counter-clockwise rotation. The transformation matrix for a rotation by an angle theta has the value:| cosTheta -sinTheta x-x*cos+y*sin | | sinTheta cosTheta y-x*sin-y*cos | | 0 0 1 |
- Parameters:
theta
- the rotation angle, in radiansx
- the x-ordinate of the rotation pointy
- the y-ordinate of the rotation point- Returns:
- this transformation, with an updated matrix
-
setToRotation
Sets this transformation to be a rotation around a given point (x,y) by specifying the sin and cos of the rotation angle directly. The transformation matrix for the rotation has the value:| cosTheta -sinTheta x-x*cos+y*sin | | sinTheta cosTheta y-x*sin-y*cos | | 0 0 1 |
- Parameters:
sinTheta
- the sine of the rotation anglecosTheta
- the cosine of the rotation anglex
- the x-ordinate of the rotation pointy
- the y-ordinate of the rotation point- Returns:
- this transformation, with an updated matrix
-
setToScale
Sets this transformation to be a scaling. The transformation matrix for a scale has the value:| xScale 0 dx | | 0 yScale dy | | 0 0 1 |
- Parameters:
xScale
- the amount to scale x-ordinates byyScale
- the amount to scale y-ordinates by- Returns:
- this transformation, with an updated matrix
-
setToShear
Sets this transformation to be a shear. The transformation matrix for a shear has the value:
Note that a shear of (1, 1) is not equal to shear(1, 0) composed with shear(0, 1). Instead, shear(1, 1) corresponds to a mapping onto the line x = y.| 1 xShear 0 | | yShear 1 0 | | 0 0 1 |
- Parameters:
xShear
- the x component to shear byyShear
- the y component to shear by- Returns:
- this transformation, with an updated matrix
-
setToTranslation
Sets this transformation to be a translation. For a translation by the vector (x, y) the transformation matrix has the value:| 1 0 dx | | 1 0 dy | | 0 0 1 |
- Parameters:
dx
- the x component to translate bydy
- the y component to translate by- Returns:
- this transformation, with an updated matrix
-
reflect
Updates the value of this transformation to that of a reflection transformation composed with the current value.- Parameters:
x0
- the x-ordinate of a point on the line to reflect aroundy0
- the y-ordinate of a point on the line to reflect aroundx1
- the x-ordinate of a point on the line to reflect aroundy1
- the y-ordinate of a point on the line to reflect around- Returns:
- this transformation, with an updated matrix
-
reflect
Updates the value of this transformation to that of a reflection transformation composed with the current value.- Parameters:
x
- the x-ordinate of the line to reflect aroundy
- the y-ordinate of the line to reflect around- Returns:
- this transformation, with an updated matrix
-
rotate
Updates the value of this transformation to that of a rotation transformation composed with the current value. Positive angles correspond to a rotation in the counter-clockwise direction.- Parameters:
theta
- the angle to rotate by, in radians- Returns:
- this transformation, with an updated matrix
-
rotate
Updates the value of this transformation to that of a rotation around the origin composed with the current value, with the sin and cos of the rotation angle specified directly.- Parameters:
sinTheta
- the sine of the angle to rotate bycosTheta
- the cosine of the angle to rotate by- Returns:
- this transformation, with an updated matrix
-
rotate
Updates the value of this transformation to that of a rotation around a given point composed with the current value. Positive angles correspond to a rotation in the counter-clockwise direction.- Parameters:
theta
- the angle to rotate by, in radiansx
- the x-ordinate of the rotation pointy
- the y-ordinate of the rotation point- Returns:
- this transformation, with an updated matrix
-
rotate
Updates the value of this transformation to that of a rotation around a given point composed with the current value, with the sin and cos of the rotation angle specified directly.- Parameters:
sinTheta
- the sine of the angle to rotate bycosTheta
- the cosine of the angle to rotate byx
- the x-ordinate of the rotation pointy
- the y-ordinate of the rotation point- Returns:
- this transformation, with an updated matrix
-
scale
Updates the value of this transformation to that of a scale transformation composed with the current value.- Parameters:
xScale
- the value to scale by in the x directionyScale
- the value to scale by in the y direction- Returns:
- this transformation, with an updated matrix
-
shear
Updates the value of this transformation to that of a shear transformation composed with the current value.- Parameters:
xShear
- the value to shear by in the x directionyShear
- the value to shear by in the y direction- Returns:
- this transformation, with an updated matrix
-
translate
Updates the value of this transformation to that of a translation transformation composed with the current value.- Parameters:
x
- the value to translate by in the x directiony
- the value to translate by in the y direction- Returns:
- this transformation, with an updated matrix
-
compose
Updates this transformation to be the composition of this transformation with the givenAffineTransformation
. This produces a transformation whose effect is equal to applying this transformation followed by the argument transformation. Mathematically,A.compose(B) = TB x TA
- Parameters:
trans
- an affine transformation- Returns:
- this transformation, with an updated matrix
-
composeBefore
Updates this transformation to be the composition of a givenAffineTransformation
with this transformation. This produces a transformation whose effect is equal to applying the argument transformation followed by this transformation. Mathematically,A.composeBefore(B) = TA x TB
- Parameters:
trans
- an affine transformation- Returns:
- this transformation, with an updated matrix
-
transform
Applies this transformation to the src coordinate and places the results in the dest coordinate (which may be the same as the source).- Parameters:
src
- the coordinate to transformdest
- the coordinate to accept the results- Returns:
- the dest coordinate
-
transform
Creates a newGeometry
which is the result of this transformation applied to the input Geometry.- Parameters:
g
- aGeometry
- Returns:
- a transformed Geometry
-
transform
Applies this transformation to the i'th coordinate in the given CoordinateSequence.- Parameters:
seq
- aCoordinateSequence
i
- the index of the coordinate to transform
-
filter
Transforms the i'th coordinate in the input sequence- Specified by:
filter
in interfaceCoordinateSequenceFilter
- Parameters:
seq
- aCoordinateSequence
i
- the index of the coordinate to transform
-
isGeometryChanged
public boolean isGeometryChanged()Description copied from interface:CoordinateSequenceFilter
Reports whether the execution of this filter has modified the coordinates of the geometry. If so,Geometry.geometryChanged()
will be executed after this filter has finished being executed.Most filters can simply return a constant value reflecting whether they are able to change the coordinates.
- Specified by:
isGeometryChanged
in interfaceCoordinateSequenceFilter
- Returns:
- true if this filter has changed the coordinates of the geometry
-
isDone
public boolean isDone()Reports that this filter should continue to be executed until all coordinates have been transformed.- Specified by:
isDone
in interfaceCoordinateSequenceFilter
- Returns:
- false
-
isIdentity
public boolean isIdentity()Tests if this transformation is the identity transformation.- Returns:
- true if this is the identity transformation
-
equals
Tests if an object is an AffineTransformation and has the same matrix as this transformation. -
hashCode
public int hashCode() -
toString
Gets a text representation of this transformation. The string is of the form:AffineTransformation[[m00, m01, m02], [m10, m11, m12]]
-
clone
Clones this transformation- Returns:
- a copy of this transformation
-