Class AffineTransform
- All Implemented Interfaces:
-
Serializable
,Cloneable
public class AffineTransform extends Object implements Cloneable, Serializable
AffineTransform
class represents a 2D affine transform that performs a linear mapping from 2D coordinates to other 2D coordinates that preserves the "straightness" and "parallelness" of lines. Affine transformations can be constructed using sequences of translations, scales, flips, rotations, and shears. Such a coordinate transformation can be represented by a 3 row by 3 column matrix with an implied last row of [ 0 0 1 ]. This matrix transforms source coordinates (x,y)
into destination coordinates (x',y')
by considering them to be a column vector and multiplying the coordinate vector by the matrix according to the following process:
[ x'] [ m00 m01 m02 ] [ x ] [ m00x + m01y + m02 ] [ y'] = [ m10 m11 m12 ] [ y ] = [ m10x + m11y + m12 ] [ 1 ] [ 0 0 1 ] [ 1 ] [ 1 ]
Handling 90-Degree Rotations
In some variations of the rotate
methods in the AffineTransform
class, a double-precision argument specifies the angle of rotation in radians. These methods have special handling for rotations of approximately 90 degrees (including multiples such as 180, 270, and 360 degrees), so that the common case of quadrant rotation is handled more efficiently. This special handling can cause angles very close to multiples of 90 degrees to be treated as if they were exact multiples of 90 degrees. For small multiples of 90 degrees the range of angles treated as a quadrant rotation is approximately 0.00000121 degrees wide. This section explains why such special care is needed and how it is implemented.
Since 90 degrees is represented as PI/2
in radians, and since PI is a transcendental (and therefore irrational) number, it is not possible to exactly represent a multiple of 90 degrees as an exact double precision value measured in radians. As a result it is theoretically impossible to describe quadrant rotations (90, 180, 270 or 360 degrees) using these values. Double precision floating point values can get very close to non-zero multiples of PI/2
but never close enough for the sine or cosine to be exactly 0.0, 1.0 or -1.0. The implementations of Math.sin()
and Math.cos()
correspondingly never return 0.0 for any case other than Math.sin(0.0)
. These same implementations do, however, return exactly 1.0 and -1.0 for some range of numbers around each multiple of 90 degrees since the correct answer is so close to 1.0 or -1.0 that the double precision significand cannot represent the difference as accurately as it can for numbers that are near 0.0.
The net result of these issues is that if the Math.sin()
and Math.cos()
methods are used to directly generate the values for the matrix modifications during these radian-based rotation operations then the resulting transform is never strictly classifiable as a quadrant rotation even for a simple case like rotate(Math.PI/2.0)
, due to minor variations in the matrix caused by the non-0.0 values obtained for the sine and cosine. If these transforms are not classified as quadrant rotations then subsequent code which attempts to optimize further operations based upon the type of the transform will be relegated to its most general implementation.
Because quadrant rotations are fairly common, this class should handle these cases reasonably quickly, both in applying the rotations to the transform and in applying the resulting transform to the coordinates. To facilitate this optimal handling, the methods which take an angle of rotation measured in radians attempt to detect angles that are intended to be quadrant rotations and treat them as such. These methods therefore treat an angle theta as a quadrant rotation if either Math.sin(theta)
or Math.cos(theta)
returns exactly 1.0 or -1.0. As a rule of thumb, this property holds true for a range of approximately 0.0000000211 radians (or 0.00000121 degrees) around small multiples of Math.PI/2.0
.
- Since:
- 1.2
- See Also:
Field Summary
Modifier and Type | Field | Description |
---|---|---|
static final int |
TYPE_FLIP |
This flag bit indicates that the transform defined by this object performs a mirror image flip about some axis which changes the normally right handed coordinate system into a left handed system in addition to the conversions indicated by other flag bits. |
static final int |
TYPE_GENERAL_ROTATION |
This flag bit indicates that the transform defined by this object performs a rotation by an arbitrary angle in addition to the conversions indicated by other flag bits. |
static final int |
TYPE_GENERAL_SCALE |
This flag bit indicates that the transform defined by this object performs a general scale in addition to the conversions indicated by other flag bits. |
static final int |
TYPE_GENERAL_TRANSFORM |
This constant indicates that the transform defined by this object performs an arbitrary conversion of the input coordinates. |
static final int |
TYPE_IDENTITY |
This constant indicates that the transform defined by this object is an identity transform. |
static final int |
TYPE_MASK_ROTATION |
This constant is a bit mask for any of the rotation flag bits. |
static final int |
TYPE_MASK_SCALE |
This constant is a bit mask for any of the scale flag bits. |
static final int |
TYPE_QUADRANT_ROTATION |
This flag bit indicates that the transform defined by this object performs a quadrant rotation by some multiple of 90 degrees in addition to the conversions indicated by other flag bits. |
static final int |
TYPE_TRANSLATION |
This flag bit indicates that the transform defined by this object performs a translation in addition to the conversions indicated by other flag bits. |
static final int |
TYPE_UNIFORM_SCALE |
This flag bit indicates that the transform defined by this object performs a uniform scale in addition to the conversions indicated by other flag bits. |
Constructor Summary
Constructor | Description |
---|---|
AffineTransform() |
Constructs a new AffineTransform representing the Identity transformation. |
AffineTransform |
Constructs a new AffineTransform from an array of double precision values representing either the 4 non-translation entries or the 6 specifiable entries of the 3x3 transformation matrix. |
AffineTransform |
Constructs a new AffineTransform from 6 double precision values representing the 6 specifiable entries of the 3x3 transformation matrix. |
AffineTransform |
Constructs a new AffineTransform from an array of floating point values representing either the 4 non-translation entries or the 6 specifiable entries of the 3x3 transformation matrix. |
AffineTransform |
Constructs a new AffineTransform from 6 floating point values representing the 6 specifiable entries of the 3x3 transformation matrix. |
AffineTransform |
Constructs a new AffineTransform that is a copy of the specified AffineTransform object. |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
Object |
clone() |
Returns a copy of this AffineTransform object. |
void |
concatenate |
Concatenates an AffineTransform Tx to this AffineTransform Cx in the most commonly useful way to provide a new user space that is mapped to the former user space by Tx . |
AffineTransform |
createInverse() |
Returns an AffineTransform object representing the inverse transformation. |
Shape |
createTransformedShape |
Returns a new Shape object defined by the geometry of the specified Shape after it has been transformed by this transform. |
void |
deltaTransform |
Transforms an array of relative distance vectors by this transform. |
Point2D |
deltaTransform |
Transforms the relative distance vector specified by ptSrc and stores the result in ptDst . |
boolean |
equals |
Returns true if this AffineTransform represents the same affine coordinate transform as the specified argument. |
double |
getDeterminant() |
Returns the determinant of the matrix representation of the transform. |
void |
getMatrix |
Retrieves the 6 specifiable values in the 3x3 affine transformation matrix and places them into an array of double precisions values. |
static AffineTransform |
getQuadrantRotateInstance |
Returns a transform that rotates coordinates by the specified number of quadrants. |
static AffineTransform |
getQuadrantRotateInstance |
Returns a transform that rotates coordinates by the specified number of quadrants around the specified anchor point. |
static AffineTransform |
getRotateInstance |
Returns a transform representing a rotation transformation. |
static AffineTransform |
getRotateInstance |
Returns a transform that rotates coordinates according to a rotation vector. |
static AffineTransform |
getRotateInstance |
Returns a transform that rotates coordinates around an anchor point. |
static AffineTransform |
getRotateInstance |
Returns a transform that rotates coordinates around an anchor point according to a rotation vector. |
static AffineTransform |
getScaleInstance |
Returns a transform representing a scaling transformation. |
double |
getScaleX() |
Returns the m00 element of the 3x3 affine transformation matrix. |
double |
getScaleY() |
Returns the m11 element of the 3x3 affine transformation matrix. |
static AffineTransform |
getShearInstance |
Returns a transform representing a shearing transformation. |
double |
getShearX() |
Returns the X coordinate shearing element (m01) of the 3x3 affine transformation matrix. |
double |
getShearY() |
Returns the Y coordinate shearing element (m10) of the 3x3 affine transformation matrix. |
static AffineTransform |
getTranslateInstance |
Returns a transform representing a translation transformation. |
double |
getTranslateX() |
Returns the X coordinate of the translation element (m02) of the 3x3 affine transformation matrix. |
double |
getTranslateY() |
Returns the Y coordinate of the translation element (m12) of the 3x3 affine transformation matrix. |
int |
getType() |
Retrieves the flag bits describing the conversion properties of this transform. |
int |
hashCode() |
Returns the hashcode for this transform. |
void |
inverseTransform |
Inverse transforms an array of double precision coordinates by this transform. |
Point2D |
inverseTransform |
Inverse transforms the specified ptSrc and stores the result in ptDst . |
void |
invert() |
Sets this transform to the inverse of itself. |
boolean |
isIdentity() |
Returns true if this AffineTransform is an identity transform. |
void |
preConcatenate |
Concatenates an AffineTransform Tx to this AffineTransform Cx in a less commonly used way such that Tx modifies the coordinate transformation relative to the absolute pixel space rather than relative to the existing user space. |
void |
quadrantRotate |
Concatenates this transform with a transform that rotates coordinates by the specified number of quadrants. |
void |
quadrantRotate |
Concatenates this transform with a transform that rotates coordinates by the specified number of quadrants around the specified anchor point. |
void |
rotate |
Concatenates this transform with a rotation transformation. |
void |
rotate |
Concatenates this transform with a transform that rotates coordinates according to a rotation vector. |
void |
rotate |
Concatenates this transform with a transform that rotates coordinates around an anchor point. |
void |
rotate |
Concatenates this transform with a transform that rotates coordinates around an anchor point according to a rotation vector. |
void |
scale |
Concatenates this transform with a scaling transformation. |
void |
setToIdentity() |
Resets this transform to the Identity transform. |
void |
setToQuadrantRotation |
Sets this transform to a rotation transformation that rotates coordinates by the specified number of quadrants. |
void |
setToQuadrantRotation |
Sets this transform to a translated rotation transformation that rotates coordinates by the specified number of quadrants around the specified anchor point. |
void |
setToRotation |
Sets this transform to a rotation transformation. |
void |
setToRotation |
Sets this transform to a rotation transformation that rotates coordinates according to a rotation vector. |
void |
setToRotation |
Sets this transform to a translated rotation transformation. |
void |
setToRotation |
Sets this transform to a rotation transformation that rotates coordinates around an anchor point according to a rotation vector. |
void |
setToScale |
Sets this transform to a scaling transformation. |
void |
setToShear |
Sets this transform to a shearing transformation. |
void |
setToTranslation |
Sets this transform to a translation transformation. |
void |
setTransform |
Sets this transform to the matrix specified by the 6 double precision values. |
void |
setTransform |
Sets this transform to a copy of the transform in the specified AffineTransform object. |
void |
shear |
Concatenates this transform with a shearing transformation. |
String |
toString() |
Returns a String that represents the value of this Object . |
void |
transform |
Transforms an array of double precision coordinates by this transform. |
void |
transform |
Transforms an array of double precision coordinates by this transform and stores the results into an array of floats. |
void |
transform |
Transforms an array of floating point coordinates by this transform and stores the results into an array of doubles. |
void |
transform |
Transforms an array of floating point coordinates by this transform. |
void |
transform |
Transforms an array of point objects by this transform. |
Point2D |
transform |
Transforms the specified ptSrc and stores the result in ptDst . |
void |
translate |
Concatenates this transform with a translation transformation. |
Field Details
TYPE_IDENTITY
public static final int TYPE_IDENTITY
TYPE_TRANSLATION
public static final int TYPE_TRANSLATION
TYPE_UNIFORM_SCALE
public static final int TYPE_UNIFORM_SCALE
TYPE_GENERAL_SCALE
public static final int TYPE_GENERAL_SCALE
TYPE_MASK_SCALE
public static final int TYPE_MASK_SCALE
- Since:
- 1.2
- See Also:
TYPE_FLIP
public static final int TYPE_FLIP
TYPE_QUADRANT_ROTATION
public static final int TYPE_QUADRANT_ROTATION
TYPE_GENERAL_ROTATION
public static final int TYPE_GENERAL_ROTATION
TYPE_MASK_ROTATION
public static final int TYPE_MASK_ROTATION
- Since:
- 1.2
- See Also:
TYPE_GENERAL_TRANSFORM
public static final int TYPE_GENERAL_TRANSFORM
Constructor Details
AffineTransform
public AffineTransform()
AffineTransform
representing the Identity transformation.- Since:
- 1.2
AffineTransform
public AffineTransform(AffineTransform Tx)
AffineTransform
that is a copy of the specified AffineTransform
object.- Parameters:
-
Tx
- theAffineTransform
object to copy - Since:
- 1.2
AffineTransform
@ConstructorProperties({"scaleX","shearY","shearX","scaleY","translateX","translateY"}) public AffineTransform(float m00, float m10, float m01, float m11, float m02, float m12)
AffineTransform
from 6 floating point values representing the 6 specifiable entries of the 3x3 transformation matrix.- Parameters:
-
m00
- the X coordinate scaling element of the 3x3 matrix -
m10
- the Y coordinate shearing element of the 3x3 matrix -
m01
- the X coordinate shearing element of the 3x3 matrix -
m11
- the Y coordinate scaling element of the 3x3 matrix -
m02
- the X coordinate translation element of the 3x3 matrix -
m12
- the Y coordinate translation element of the 3x3 matrix - Since:
- 1.2
AffineTransform
public AffineTransform(float[] flatmatrix)
AffineTransform
from an array of floating point values representing either the 4 non-translation entries or the 6 specifiable entries of the 3x3 transformation matrix. The values are retrieved from the array as { m00 m10 m01 m11 [m02 m12]}.- Parameters:
-
flatmatrix
- the float array containing the values to be set in the newAffineTransform
object. The length of the array is assumed to be at least 4. If the length of the array is less than 6, only the first 4 values are taken. If the length of the array is greater than 6, the first 6 values are taken. - Since:
- 1.2
AffineTransform
public AffineTransform(double m00, double m10, double m01, double m11, double m02, double m12)
AffineTransform
from 6 double precision values representing the 6 specifiable entries of the 3x3 transformation matrix.- Parameters:
-
m00
- the X coordinate scaling element of the 3x3 matrix -
m10
- the Y coordinate shearing element of the 3x3 matrix -
m01
- the X coordinate shearing element of the 3x3 matrix -
m11
- the Y coordinate scaling element of the 3x3 matrix -
m02
- the X coordinate translation element of the 3x3 matrix -
m12
- the Y coordinate translation element of the 3x3 matrix - Since:
- 1.2
AffineTransform
public AffineTransform(double[] flatmatrix)
AffineTransform
from an array of double precision values representing either the 4 non-translation entries or the 6 specifiable entries of the 3x3 transformation matrix. The values are retrieved from the array as { m00 m10 m01 m11 [m02 m12]}.- Parameters:
-
flatmatrix
- the double array containing the values to be set in the newAffineTransform
object. The length of the array is assumed to be at least 4. If the length of the array is less than 6, only the first 4 values are taken. If the length of the array is greater than 6, the first 6 values are taken. - Since:
- 1.2
Method Details
getTranslateInstance
public static AffineTransform getTranslateInstance(double tx, double ty)
[ 1 0 tx ] [ 0 1 ty ] [ 0 0 1 ]
- Parameters:
-
tx
- the distance by which coordinates are translated in the X axis direction -
ty
- the distance by which coordinates are translated in the Y axis direction - Returns:
- an
AffineTransform
object that represents a translation transformation, created with the specified vector. - Since:
- 1.2
getRotateInstance
public static AffineTransform getRotateInstance(double theta)
[ cos(theta) -sin(theta) 0 ] [ sin(theta) cos(theta) 0 ] [ 0 0 1 ]Rotating by a positive angle theta rotates points on the positive X axis toward the positive Y axis. Note also the discussion of Handling 90-Degree Rotations above.
- Parameters:
-
theta
- the angle of rotation measured in radians - Returns:
- an
AffineTransform
object that is a rotation transformation, created with the specified angle of rotation. - Since:
- 1.2
getRotateInstance
public static AffineTransform getRotateInstance(double theta, double anchorx, double anchory)
This operation is equivalent to the following sequence of calls:
AffineTransform Tx = new AffineTransform(); Tx.translate(anchorx, anchory); // S3: final translation Tx.rotate(theta); // S2: rotate around anchor Tx.translate(-anchorx, -anchory); // S1: translate anchor to originThe matrix representing the returned transform is:
[ cos(theta) -sin(theta) x-x*cos+y*sin ] [ sin(theta) cos(theta) y-x*sin-y*cos ] [ 0 0 1 ]Rotating by a positive angle theta rotates points on the positive X axis toward the positive Y axis. Note also the discussion of Handling 90-Degree Rotations above.
- Parameters:
-
theta
- the angle of rotation measured in radians -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Returns:
- an
AffineTransform
object that rotates coordinates around the specified point by the specified angle of rotation. - Since:
- 1.2
getRotateInstance
public static AffineTransform getRotateInstance(double vecx, double vecy)
vecx
and vecy
are 0.0, an identity transform is returned. This operation is equivalent to calling: AffineTransform.getRotateInstance(Math.atan2(vecy, vecx));
- Parameters:
-
vecx
- the X coordinate of the rotation vector -
vecy
- the Y coordinate of the rotation vector - Returns:
- an
AffineTransform
object that rotates coordinates according to the specified rotation vector. - Since:
- 1.6
getRotateInstance
public static AffineTransform getRotateInstance(double vecx, double vecy, double anchorx, double anchory)
vecx
and vecy
are 0.0, an identity transform is returned. This operation is equivalent to calling: AffineTransform.getRotateInstance(Math.atan2(vecy, vecx), anchorx, anchory);
- Parameters:
-
vecx
- the X coordinate of the rotation vector -
vecy
- the Y coordinate of the rotation vector -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Returns:
- an
AffineTransform
object that rotates coordinates around the specified point according to the specified rotation vector. - Since:
- 1.6
getQuadrantRotateInstance
public static AffineTransform getQuadrantRotateInstance(int numquadrants)
AffineTransform.getRotateInstance(numquadrants * Math.PI / 2.0);Rotating by a positive number of quadrants rotates points on the positive X axis toward the positive Y axis.
- Parameters:
-
numquadrants
- the number of 90 degree arcs to rotate by - Returns:
- an
AffineTransform
object that rotates coordinates by the specified number of quadrants. - Since:
- 1.6
getQuadrantRotateInstance
public static AffineTransform getQuadrantRotateInstance(int numquadrants, double anchorx, double anchory)
AffineTransform.getRotateInstance(numquadrants * Math.PI / 2.0, anchorx, anchory);Rotating by a positive number of quadrants rotates points on the positive X axis toward the positive Y axis.
- Parameters:
-
numquadrants
- the number of 90 degree arcs to rotate by -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Returns:
- an
AffineTransform
object that rotates coordinates by the specified number of quadrants around the specified anchor point. - Since:
- 1.6
getScaleInstance
public static AffineTransform getScaleInstance(double sx, double sy)
[ sx 0 0 ] [ 0 sy 0 ] [ 0 0 1 ]
- Parameters:
-
sx
- the factor by which coordinates are scaled along the X axis direction -
sy
- the factor by which coordinates are scaled along the Y axis direction - Returns:
- an
AffineTransform
object that scales coordinates by the specified factors. - Since:
- 1.2
getShearInstance
public static AffineTransform getShearInstance(double shx, double shy)
[ 1 shx 0 ] [ shy 1 0 ] [ 0 0 1 ]
- Parameters:
-
shx
- the multiplier by which coordinates are shifted in the direction of the positive X axis as a factor of their Y coordinate -
shy
- the multiplier by which coordinates are shifted in the direction of the positive Y axis as a factor of their X coordinate - Returns:
- an
AffineTransform
object that shears coordinates by the specified multipliers. - Since:
- 1.2
getType
public int getType()
- Returns:
- the OR combination of any of the indicated flags that apply to this transform
- Since:
- 1.2
- See Also:
getDeterminant
public double getDeterminant()
If the determinant is non-zero, then this transform is invertible and the various methods that depend on the inverse transform do not need to throw a NoninvertibleTransformException
. If the determinant is zero then this transform can not be inverted since the transform maps all input coordinates onto a line or a point. If the determinant is near enough to zero then inverse transform operations might not carry enough precision to produce meaningful results.
If this transform represents a uniform scale, as indicated by the getType
method then the determinant also represents the square of the uniform scale factor by which all of the points are expanded from or contracted towards the origin. If this transform represents a non-uniform scale or more general transform then the determinant is not likely to represent a value useful for any purpose other than determining if inverse transforms are possible.
Mathematically, the determinant is calculated using the formula:
| m00 m01 m02 | | m10 m11 m12 | = m00 * m11 - m01 * m10 | 0 0 1 |
- Returns:
- the determinant of the matrix used to transform the coordinates.
- Since:
- 1.2
- See Also:
getMatrix
public void getMatrix(double[] flatmatrix)
- Parameters:
-
flatmatrix
- the double array used to store the returned values. - Since:
- 1.2
- See Also:
getScaleX
public double getScaleX()
m00
element of the 3x3 affine transformation matrix. This matrix factor determines how input X coordinates will affect output X coordinates and is one element of the scale of the transform. To measure the full amount by which X coordinates are stretched or contracted by this transform, use the following code: Point2D p = new Point2D.Double(1, 0); p = tx.deltaTransform(p, p); double scaleX = p.distance(0, 0);
- Returns:
- a double value that is
m00
element of the 3x3 affine transformation matrix. - Since:
- 1.2
- See Also:
getScaleY
public double getScaleY()
m11
element of the 3x3 affine transformation matrix. This matrix factor determines how input Y coordinates will affect output Y coordinates and is one element of the scale of the transform. To measure the full amount by which Y coordinates are stretched or contracted by this transform, use the following code: Point2D p = new Point2D.Double(0, 1); p = tx.deltaTransform(p, p); double scaleY = p.distance(0, 0);
- Returns:
- a double value that is
m11
element of the 3x3 affine transformation matrix. - Since:
- 1.2
- See Also:
getShearX
public double getShearX()
- Returns:
- a double value that is the X coordinate of the shearing element of the affine transformation matrix.
- Since:
- 1.2
- See Also:
getShearY
public double getShearY()
- Returns:
- a double value that is the Y coordinate of the shearing element of the affine transformation matrix.
- Since:
- 1.2
- See Also:
getTranslateX
public double getTranslateX()
- Returns:
- a double value that is the X coordinate of the translation element of the affine transformation matrix.
- Since:
- 1.2
- See Also:
getTranslateY
public double getTranslateY()
- Returns:
- a double value that is the Y coordinate of the translation element of the affine transformation matrix.
- Since:
- 1.2
- See Also:
translate
public void translate(double tx, double ty)
AffineTransform
represented by the following matrix: [ 1 0 tx ] [ 0 1 ty ] [ 0 0 1 ]
- Parameters:
-
tx
- the distance by which coordinates are translated in the X axis direction -
ty
- the distance by which coordinates are translated in the Y axis direction - Since:
- 1.2
rotate
public void rotate(double theta)
AffineTransform
represented by the following matrix: [ cos(theta) -sin(theta) 0 ] [ sin(theta) cos(theta) 0 ] [ 0 0 1 ]Rotating by a positive angle theta rotates points on the positive X axis toward the positive Y axis. Note also the discussion of Handling 90-Degree Rotations above.
- Parameters:
-
theta
- the angle of rotation measured in radians - Since:
- 1.2
rotate
public void rotate(double theta, double anchorx, double anchory)
This operation is equivalent to the following sequence of calls:
translate(anchorx, anchory); // S3: final translation rotate(theta); // S2: rotate around anchor translate(-anchorx, -anchory); // S1: translate anchor to originRotating by a positive angle theta rotates points on the positive X axis toward the positive Y axis. Note also the discussion of Handling 90-Degree Rotations above.
- Parameters:
-
theta
- the angle of rotation measured in radians -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Since:
- 1.2
rotate
public void rotate(double vecx, double vecy)
vecx
and vecy
are 0.0, no additional rotation is added to this transform. This operation is equivalent to calling: rotate(Math.atan2(vecy, vecx));
- Parameters:
-
vecx
- the X coordinate of the rotation vector -
vecy
- the Y coordinate of the rotation vector - Since:
- 1.6
rotate
public void rotate(double vecx, double vecy, double anchorx, double anchory)
vecx
and vecy
are 0.0, the transform is not modified in any way. This method is equivalent to calling: rotate(Math.atan2(vecy, vecx), anchorx, anchory);
- Parameters:
-
vecx
- the X coordinate of the rotation vector -
vecy
- the Y coordinate of the rotation vector -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Since:
- 1.6
quadrantRotate
public void quadrantRotate(int numquadrants)
rotate(numquadrants * Math.PI / 2.0);Rotating by a positive number of quadrants rotates points on the positive X axis toward the positive Y axis.
- Parameters:
-
numquadrants
- the number of 90 degree arcs to rotate by - Since:
- 1.6
quadrantRotate
public void quadrantRotate(int numquadrants, double anchorx, double anchory)
rotate(numquadrants * Math.PI / 2.0, anchorx, anchory);Rotating by a positive number of quadrants rotates points on the positive X axis toward the positive Y axis.
- Parameters:
-
numquadrants
- the number of 90 degree arcs to rotate by -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Since:
- 1.6
scale
public void scale(double sx, double sy)
AffineTransform
represented by the following matrix: [ sx 0 0 ] [ 0 sy 0 ] [ 0 0 1 ]
- Parameters:
-
sx
- the factor by which coordinates are scaled along the X axis direction -
sy
- the factor by which coordinates are scaled along the Y axis direction - Since:
- 1.2
shear
public void shear(double shx, double shy)
AffineTransform
represented by the following matrix: [ 1 shx 0 ] [ shy 1 0 ] [ 0 0 1 ]
- Parameters:
-
shx
- the multiplier by which coordinates are shifted in the direction of the positive X axis as a factor of their Y coordinate -
shy
- the multiplier by which coordinates are shifted in the direction of the positive Y axis as a factor of their X coordinate - Since:
- 1.2
setToIdentity
public void setToIdentity()
- Since:
- 1.2
setToTranslation
public void setToTranslation(double tx, double ty)
[ 1 0 tx ] [ 0 1 ty ] [ 0 0 1 ]
- Parameters:
-
tx
- the distance by which coordinates are translated in the X axis direction -
ty
- the distance by which coordinates are translated in the Y axis direction - Since:
- 1.2
setToRotation
public void setToRotation(double theta)
[ cos(theta) -sin(theta) 0 ] [ sin(theta) cos(theta) 0 ] [ 0 0 1 ]Rotating by a positive angle theta rotates points on the positive X axis toward the positive Y axis. Note also the discussion of Handling 90-Degree Rotations above.
- Parameters:
-
theta
- the angle of rotation measured in radians - Since:
- 1.2
setToRotation
public void setToRotation(double theta, double anchorx, double anchory)
This operation is equivalent to the following sequence of calls:
setToTranslation(anchorx, anchory); // S3: final translation rotate(theta); // S2: rotate around anchor translate(-anchorx, -anchory); // S1: translate anchor to originThe matrix representing this transform becomes:
[ cos(theta) -sin(theta) x-x*cos+y*sin ] [ sin(theta) cos(theta) y-x*sin-y*cos ] [ 0 0 1 ]Rotating by a positive angle theta rotates points on the positive X axis toward the positive Y axis. Note also the discussion of Handling 90-Degree Rotations above.
- Parameters:
-
theta
- the angle of rotation measured in radians -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Since:
- 1.2
setToRotation
public void setToRotation(double vecx, double vecy)
vecx
and vecy
are 0.0, the transform is set to an identity transform. This operation is equivalent to calling: setToRotation(Math.atan2(vecy, vecx));
- Parameters:
-
vecx
- the X coordinate of the rotation vector -
vecy
- the Y coordinate of the rotation vector - Since:
- 1.6
setToRotation
public void setToRotation(double vecx, double vecy, double anchorx, double anchory)
vecx
and vecy
are 0.0, the transform is set to an identity transform. This operation is equivalent to calling: setToTranslation(Math.atan2(vecy, vecx), anchorx, anchory);
- Parameters:
-
vecx
- the X coordinate of the rotation vector -
vecy
- the Y coordinate of the rotation vector -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Since:
- 1.6
setToQuadrantRotation
public void setToQuadrantRotation(int numquadrants)
setToRotation(numquadrants * Math.PI / 2.0);Rotating by a positive number of quadrants rotates points on the positive X axis toward the positive Y axis.
- Parameters:
-
numquadrants
- the number of 90 degree arcs to rotate by - Since:
- 1.6
setToQuadrantRotation
public void setToQuadrantRotation(int numquadrants, double anchorx, double anchory)
setToRotation(numquadrants * Math.PI / 2.0, anchorx, anchory);Rotating by a positive number of quadrants rotates points on the positive X axis toward the positive Y axis.
- Parameters:
-
numquadrants
- the number of 90 degree arcs to rotate by -
anchorx
- the X coordinate of the rotation anchor point -
anchory
- the Y coordinate of the rotation anchor point - Since:
- 1.6
setToScale
public void setToScale(double sx, double sy)
[ sx 0 0 ] [ 0 sy 0 ] [ 0 0 1 ]
- Parameters:
-
sx
- the factor by which coordinates are scaled along the X axis direction -
sy
- the factor by which coordinates are scaled along the Y axis direction - Since:
- 1.2
setToShear
public void setToShear(double shx, double shy)
[ 1 shx 0 ] [ shy 1 0 ] [ 0 0 1 ]
- Parameters:
-
shx
- the multiplier by which coordinates are shifted in the direction of the positive X axis as a factor of their Y coordinate -
shy
- the multiplier by which coordinates are shifted in the direction of the positive Y axis as a factor of their X coordinate - Since:
- 1.2
setTransform
public void setTransform(AffineTransform Tx)
AffineTransform
object.- Parameters:
-
Tx
- theAffineTransform
object from which to copy the transform - Since:
- 1.2
setTransform
public void setTransform(double m00, double m10, double m01, double m11, double m02, double m12)
- Parameters:
-
m00
- the X coordinate scaling element of the 3x3 matrix -
m10
- the Y coordinate shearing element of the 3x3 matrix -
m01
- the X coordinate shearing element of the 3x3 matrix -
m11
- the Y coordinate scaling element of the 3x3 matrix -
m02
- the X coordinate translation element of the 3x3 matrix -
m12
- the Y coordinate translation element of the 3x3 matrix - Since:
- 1.2
concatenate
public void concatenate(AffineTransform Tx)
AffineTransform Tx
to this AffineTransform
Cx in the most commonly useful way to provide a new user space that is mapped to the former user space by Tx
. Cx is updated to perform the combined transformation. Transforming a point p by the updated transform Cx' is equivalent to first transforming p by Tx
and then transforming the result by the original transform Cx like this: Cx'(p) = Cx(Tx(p)) In matrix notation, if this transform Cx is represented by the matrix [this] and Tx
is represented by the matrix [Tx] then this method does the following: [this] = [this] x [Tx]
- Parameters:
-
Tx
- theAffineTransform
object to be concatenated with thisAffineTransform
object. - Since:
- 1.2
- See Also:
preConcatenate
public void preConcatenate(AffineTransform Tx)
AffineTransform Tx
to this AffineTransform
Cx in a less commonly used way such that Tx
modifies the coordinate transformation relative to the absolute pixel space rather than relative to the existing user space. Cx is updated to perform the combined transformation. Transforming a point p by the updated transform Cx' is equivalent to first transforming p by the original transform Cx and then transforming the result by Tx
like this: Cx'(p) = Tx(Cx(p)) In matrix notation, if this transform Cx is represented by the matrix [this] and Tx
is represented by the matrix [Tx] then this method does the following: [this] = [Tx] x [this]
- Parameters:
-
Tx
- theAffineTransform
object to be concatenated with thisAffineTransform
object. - Since:
- 1.2
- See Also:
createInverse
public AffineTransform createInverse() throws NoninvertibleTransformException
AffineTransform
object representing the inverse transformation. The inverse transform Tx' of this transform Tx maps coordinates transformed by Tx back to their original coordinates. In other words, Tx'(Tx(p)) = p = Tx(Tx'(p)). If this transform maps all coordinates onto a point or a line then it will not have an inverse, since coordinates that do not lie on the destination point or line will not have an inverse mapping. The getDeterminant
method can be used to determine if this transform has no inverse, in which case an exception will be thrown if the createInverse
method is called.
- Returns:
- a new
AffineTransform
object representing the inverse transformation. - Throws:
-
NoninvertibleTransformException
- if the matrix cannot be inverted. - Since:
- 1.2
- See Also:
invert
public void invert() throws NoninvertibleTransformException
If this transform maps all coordinates onto a point or a line then it will not have an inverse, since coordinates that do not lie on the destination point or line will not have an inverse mapping. The getDeterminant
method can be used to determine if this transform has no inverse, in which case an exception will be thrown if the invert
method is called.
- Throws:
-
NoninvertibleTransformException
- if the matrix cannot be inverted. - Since:
- 1.6
- See Also:
transform
public Point2D transform(Point2D ptSrc, Point2D ptDst)
ptSrc
and stores the result in ptDst
. If ptDst
is null
, a new Point2D
object is allocated and then the result of the transformation is stored in this object. In either case, ptDst
, which contains the transformed point, is returned for convenience. If ptSrc
and ptDst
are the same object, the input point is correctly overwritten with the transformed point.- Parameters:
-
ptSrc
- the specifiedPoint2D
to be transformed -
ptDst
- the specifiedPoint2D
that stores the result of transformingptSrc
- Returns:
- the
ptDst
after transformingptSrc
and storing the result inptDst
. - Since:
- 1.2
transform
public void transform(Point2D[] ptSrc, int srcOff, Point2D[] ptDst, int dstOff, int numPts)
ptDst
array is null
, a new Point2D
object is allocated and stored into that element before storing the results of the transformation. Note that this method does not take any precautions to avoid problems caused by storing results into Point2D
objects that will be used as the source for calculations further down the source array. This method does guarantee that if a specified Point2D
object is both the source and destination for the same single point transform operation then the results will not be stored until the calculations are complete to avoid storing the results on top of the operands. If, however, the destination Point2D
object for one operation is the same object as the source Point2D
object for another operation further down the source array then the original coordinates in that point are overwritten before they can be converted.
- Parameters:
-
ptSrc
- the array containing the source point objects -
ptDst
- the array into which the transform point objects are returned -
srcOff
- the offset to the first point object to be transformed in the source array -
dstOff
- the offset to the location of the first transformed point object that is stored in the destination array -
numPts
- the number of point objects to be transformed - Since:
- 1.2
transform
public void transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
[x0, y0, x1, y1, ..., xn, yn]
.- Parameters:
-
srcPts
- the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates. -
dstPts
- the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates. -
srcOff
- the offset to the first point to be transformed in the source array -
dstOff
- the offset to the location of the first transformed point that is stored in the destination array -
numPts
- the number of points to be transformed - Since:
- 1.2
transform
public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
[x0, y0, x1, y1, ..., xn, yn]
.- Parameters:
-
srcPts
- the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates. -
dstPts
- the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates. -
srcOff
- the offset to the first point to be transformed in the source array -
dstOff
- the offset to the location of the first transformed point that is stored in the destination array -
numPts
- the number of point objects to be transformed - Since:
- 1.2
transform
public void transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
[x0, y0, x1, y1, ..., xn, yn]
.- Parameters:
-
srcPts
- the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates. -
dstPts
- the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates. -
srcOff
- the offset to the first point to be transformed in the source array -
dstOff
- the offset to the location of the first transformed point that is stored in the destination array -
numPts
- the number of points to be transformed - Since:
- 1.2
transform
public void transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)
[x0, y0, x1, y1, ..., xn, yn]
.- Parameters:
-
srcPts
- the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates. -
dstPts
- the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates. -
srcOff
- the offset to the first point to be transformed in the source array -
dstOff
- the offset to the location of the first transformed point that is stored in the destination array -
numPts
- the number of point objects to be transformed - Since:
- 1.2
inverseTransform
public Point2D inverseTransform(Point2D ptSrc, Point2D ptDst) throws NoninvertibleTransformException
ptSrc
and stores the result in ptDst
. If ptDst
is null
, a new Point2D
object is allocated and then the result of the transform is stored in this object. In either case, ptDst
, which contains the transformed point, is returned for convenience. If ptSrc
and ptDst
are the same object, the input point is correctly overwritten with the transformed point.- Parameters:
-
ptSrc
- the point to be inverse transformed -
ptDst
- the resulting transformed point - Returns:
-
ptDst
, which contains the result of the inverse transform. - Throws:
-
NoninvertibleTransformException
- if the matrix cannot be inverted. - Since:
- 1.2
inverseTransform
public void inverseTransform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws NoninvertibleTransformException
[x0, y0, x1, y1, ..., xn, yn]
.- Parameters:
-
srcPts
- the array containing the source point coordinates. Each point is stored as a pair of x, y coordinates. -
dstPts
- the array into which the transformed point coordinates are returned. Each point is stored as a pair of x, y coordinates. -
srcOff
- the offset to the first point to be transformed in the source array -
dstOff
- the offset to the location of the first transformed point that is stored in the destination array -
numPts
- the number of point objects to be transformed - Throws:
-
NoninvertibleTransformException
- if the matrix cannot be inverted. - Since:
- 1.2
deltaTransform
public Point2D deltaTransform(Point2D ptSrc, Point2D ptDst)
ptSrc
and stores the result in ptDst
. A relative distance vector is transformed without applying the translation components of the affine transformation matrix using the following equations: [ x' ] [ m00 m01 (m02) ] [ x ] [ m00x + m01y ] [ y' ] = [ m10 m11 (m12) ] [ y ] = [ m10x + m11y ] [ (1) ] [ (0) (0) ( 1 ) ] [ (1) ] [ (1) ]If
ptDst
is null
, a new Point2D
object is allocated and then the result of the transform is stored in this object. In either case, ptDst
, which contains the transformed point, is returned for convenience. If ptSrc
and ptDst
are the same object, the input point is correctly overwritten with the transformed point.- Parameters:
-
ptSrc
- the distance vector to be delta transformed -
ptDst
- the resulting transformed distance vector - Returns:
-
ptDst
, which contains the result of the transformation. - Since:
- 1.2
deltaTransform
public void deltaTransform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)
[ x' ] [ m00 m01 (m02) ] [ x ] [ m00x + m01y ] [ y' ] = [ m10 m11 (m12) ] [ y ] = [ m10x + m11y ] [ (1) ] [ (0) (0) ( 1 ) ] [ (1) ] [ (1) ]The two coordinate array sections can be exactly the same or can be overlapping sections of the same array without affecting the validity of the results. This method ensures that no source coordinates are overwritten by a previous operation before they can be transformed. The coordinates are stored in the arrays starting at the indicated offset in the order
[x0, y0, x1, y1, ..., xn, yn]
.- Parameters:
-
srcPts
- the array containing the source distance vectors. Each vector is stored as a pair of relative x, y coordinates. -
dstPts
- the array into which the transformed distance vectors are returned. Each vector is stored as a pair of relative x, y coordinates. -
srcOff
- the offset to the first vector to be transformed in the source array -
dstOff
- the offset to the location of the first transformed vector that is stored in the destination array -
numPts
- the number of vector coordinate pairs to be transformed - Since:
- 1.2
createTransformedShape
public Shape createTransformedShape(Shape pSrc)
Shape
object defined by the geometry of the specified Shape
after it has been transformed by this transform.- Parameters:
-
pSrc
- the specifiedShape
object to be transformed by this transform. - Returns:
- a new
Shape
object that defines the geometry of the transformedShape
, or null ifpSrc
is null. - Since:
- 1.2
toString
public String toString()
String
that represents the value of this Object
.isIdentity
public boolean isIdentity()
true
if this AffineTransform
is an identity transform.- Returns:
-
true
if thisAffineTransform
is an identity transform;false
otherwise. - Since:
- 1.2
clone
public Object clone()
AffineTransform
object.hashCode
public int hashCode()
equals
public boolean equals(Object obj)
true
if this AffineTransform
represents the same affine coordinate transform as the specified argument.
© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/java/awt/geom/AffineTransform.html