public class Affine2D extends AffineBase
Affine2D
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 ]
In some variations of the rotate
methods in the
Affine2D
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
.
BaseTransform.Degree
APPLY_2D_DELTA_MASK, APPLY_2D_MASK, APPLY_3D, APPLY_IDENTITY, APPLY_SCALE, APPLY_SHEAR, APPLY_TRANSLATE, HI_3D, HI_IDENTITY, HI_SCALE, HI_SHEAR, HI_SHIFT, HI_TRANSLATE, mxt, mxx, mxy, myt, myx, myy, state, type
IDENTITY_TRANSFORM, TYPE_AFFINE_3D, TYPE_AFFINE2D_MASK, TYPE_FLIP, TYPE_GENERAL_ROTATION, TYPE_GENERAL_SCALE, TYPE_GENERAL_TRANSFORM, TYPE_IDENTITY, TYPE_MASK_ROTATION, TYPE_MASK_SCALE, TYPE_QUADRANT_ROTATION, TYPE_TRANSLATION, TYPE_UNIFORM_SCALE, TYPE_UNKNOWN
Constructor and Description |
---|
Affine2D()
Constructs a new
Affine2D representing the
Identity transformation. |
Affine2D(BaseTransform Tx)
Constructs a new
Affine2D that uses the same transform
as the specified BaseTransform object. |
Affine2D(double mxx,
double myx,
double mxy,
double myy,
double mxt,
double myt)
Constructs a new
Affine2D from 6 double
precision values representing the 6 specifiable entries of the 3x3
transformation matrix. |
Affine2D(float mxx,
float myx,
float mxy,
float myy,
float mxt,
float myt)
Constructs a new
Affine2D from 6 floating point
values representing the 6 specifiable entries of the 3x3
transformation matrix. |
Modifier and Type | Method and Description |
---|---|
BaseTransform |
copy() |
Affine2D |
createInverse()
Returns an
Affine2D object representing the
inverse transformation. |
Point2D |
deltaTransform(Point2D ptSrc,
Point2D ptDst)
Transforms the relative distance vector specified by
ptSrc and stores the result in ptDst . |
BaseTransform |
deriveWithConcatenation(BaseTransform tx) |
BaseTransform |
deriveWithConcatenation(double mxx,
double myx,
double mxy,
double myy,
double mxt,
double myt) |
BaseTransform |
deriveWithConcatenation(double mxx,
double mxy,
double mxz,
double mxt,
double myx,
double myy,
double myz,
double myt,
double mzx,
double mzy,
double mzz,
double mzt) |
BaseTransform |
deriveWithNewTransform(BaseTransform tx) |
BaseTransform |
deriveWithPreConcatenation(BaseTransform tx) |
BaseTransform |
deriveWithPreTranslation(double mxt,
double myt) |
BaseTransform |
deriveWithRotation(double theta,
double axisX,
double axisY,
double axisZ) |
BaseTransform |
deriveWithScale(double mxx,
double myy,
double mzz) |
BaseTransform |
deriveWithTranslation(double mxt,
double myt) |
BaseTransform |
deriveWithTranslation(double mxt,
double myt,
double mzt) |
boolean |
equals(Object obj)
Returns
true if this Affine2D
represents the same coordinate transform as the specified
argument. |
BaseTransform.Degree |
getDegree() |
int |
hashCode()
Returns the hashcode for this transform.
|
boolean |
is2D() |
void |
preConcatenate(BaseTransform Tx)
Concatenates a
BaseTransform Tx to
this Affine2D 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(int numquadrants)
Concatenates this transform with a transform that rotates
coordinates by the specified number of quadrants.
|
void |
quadrantRotate(int numquadrants,
double anchorx,
double anchory)
Concatenates this transform with a transform that rotates
coordinates by the specified number of quadrants around
the specified anchor point.
|
protected void |
reset3Delements()
Resets the 3D (Z) components of the matrix to identity settings
(if they are present).
|
void |
restoreTransform(double mxx,
double myx,
double mxy,
double myy,
double mxt,
double myt)
This function is only guaranteed to succeed if the transform is
of degree AFFINE2D or less and the matrix
parameters specified came from this same instance.
|
void |
restoreTransform(double mxx,
double mxy,
double mxz,
double mxt,
double myx,
double myy,
double myz,
double myt,
double mzx,
double mzy,
double mzz,
double mzt)
This function is only guaranteed to succeed if the matrix
parameters specified came from this same instance.
|
void |
rotate(double vecx,
double vecy)
Concatenates this transform with a transform that rotates
coordinates according to a rotation vector.
|
void |
rotate(double theta,
double anchorx,
double anchory)
Concatenates this transform with a transform that rotates
coordinates around an anchor point.
|
void |
rotate(double vecx,
double vecy,
double anchorx,
double anchory)
Concatenates this transform with a transform that rotates
coordinates around an anchor point according to a rotation
vector.
|
void |
setToQuadrantRotation(int numquadrants)
Sets this transform to a rotation transformation that rotates
coordinates by the specified number of quadrants.
|
void |
setToQuadrantRotation(int numquadrants,
double anchorx,
double anchory)
Sets this transform to a translated rotation transformation
that rotates coordinates by the specified number of quadrants
around the specified anchor point.
|
void |
setToRotation(double theta)
Sets this transform to a rotation transformation.
|
void |
setToRotation(double vecx,
double vecy)
Sets this transform to a rotation transformation that rotates
coordinates according to a rotation vector.
|
void |
setToRotation(double theta,
double anchorx,
double anchory)
Sets this transform to a translated rotation transformation.
|
void |
setToRotation(double vecx,
double vecy,
double anchorx,
double anchory)
Sets this transform to a rotation transformation that rotates
coordinates around an anchor point according to a rotation
vector.
|
void |
setToScale(double sx,
double sy)
Sets this transform to a scaling transformation.
|
void |
setToTranslation(double tx,
double ty)
Sets this transform to a translation transformation.
|
void |
setTransform(BaseTransform Tx)
Sets this transform to a copy of the transform in the specified
BaseTransform object. |
String |
toString()
Returns a
String that represents the value of this
Object . |
void |
transform(Point2D[] ptSrc,
int srcOff,
Point2D[] ptDst,
int dstOff,
int numPts)
Transforms an array of point objects by this transform.
|
calculateType, concatenate, concatenate, createTransformedShape, deltaTransform, deltaTransform, deltaTransform, getDeterminant, getMxt, getMxx, getMxy, getMyt, getMyx, getMyy, getType, inverseDeltaTransform, inverseDeltaTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, invert, isIdentity, isTranslateOrIdentity, rotate, rotate180, rotate270, rotate90, scale, setToIdentity, setToShear, setTransform, shear, stateError, transform, transform, transform, transform, transform, transform, transform, transform, transform, translate, updateState, updateState2D
almostZero, getInstance, getInstance, getInstance, getMxz, getMyz, getMzt, getMzx, getMzy, getMzz, getRotateInstance, getScaleInstance, getTranslateInstance
public Affine2D()
Affine2D
representing the
Identity transformation.public Affine2D(BaseTransform Tx)
Affine2D
that uses the same transform
as the specified BaseTransform
object.Tx
- the BaseTransform
object to copypublic Affine2D(float mxx, float myx, float mxy, float myy, float mxt, float myt)
Affine2D
from 6 floating point
values representing the 6 specifiable entries of the 3x3
transformation matrix.mxx
- the X coordinate scaling element of the 3x3 matrixmyx
- the Y coordinate shearing element of the 3x3 matrixmxy
- the X coordinate shearing element of the 3x3 matrixmyy
- the Y coordinate scaling element of the 3x3 matrixmxt
- the X coordinate translation element of the 3x3 matrixmyt
- the Y coordinate translation element of the 3x3 matrixpublic Affine2D(double mxx, double myx, double mxy, double myy, double mxt, double myt)
Affine2D
from 6 double
precision values representing the 6 specifiable entries of the 3x3
transformation matrix.mxx
- the X coordinate scaling element of the 3x3 matrixmyx
- the Y coordinate shearing element of the 3x3 matrixmxy
- the X coordinate shearing element of the 3x3 matrixmyy
- the Y coordinate scaling element of the 3x3 matrixmxt
- the X coordinate translation element of the 3x3 matrixmyt
- the Y coordinate translation element of the 3x3 matrixpublic BaseTransform.Degree getDegree()
getDegree
in class BaseTransform
protected void reset3Delements()
AffineBase
reset3Delements
in class AffineBase
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.
theta
- the angle of rotation measured in radiansanchorx
- the X coordinate of the rotation anchor pointanchory
- the Y coordinate of the rotation anchor pointpublic 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));
vecx
- the X coordinate of the rotation vectorvecy
- the Y coordinate of the rotation vectorpublic 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);
vecx
- the X coordinate of the rotation vectorvecy
- the Y coordinate of the rotation vectoranchorx
- the X coordinate of the rotation anchor pointanchory
- the Y coordinate of the rotation anchor pointpublic 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.
numquadrants
- the number of 90 degree arcs to rotate bypublic 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.
numquadrants
- the number of 90 degree arcs to rotate byanchorx
- the X coordinate of the rotation anchor pointanchory
- the Y coordinate of the rotation anchor pointpublic void setToTranslation(double tx, double ty)
[ 1 0 tx ] [ 0 1 ty ] [ 0 0 1 ]
tx
- the distance by which coordinates are translated in the
X axis directionty
- the distance by which coordinates are translated in the
Y axis directionpublic 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.
theta
- the angle of rotation measured in radianspublic 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.
theta
- the angle of rotation measured in radiansanchorx
- the X coordinate of the rotation anchor pointanchory
- the Y coordinate of the rotation anchor pointpublic 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));
vecx
- the X coordinate of the rotation vectorvecy
- the Y coordinate of the rotation vectorpublic 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);
vecx
- the X coordinate of the rotation vectorvecy
- the Y coordinate of the rotation vectoranchorx
- the X coordinate of the rotation anchor pointanchory
- the Y coordinate of the rotation anchor pointpublic 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.
numquadrants
- the number of 90 degree arcs to rotate bypublic 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.
numquadrants
- the number of 90 degree arcs to rotate byanchorx
- the X coordinate of the rotation anchor pointanchory
- the Y coordinate of the rotation anchor pointpublic void setToScale(double sx, double sy)
[ sx 0 0 ] [ 0 sy 0 ] [ 0 0 1 ]
sx
- the factor by which coordinates are scaled along the
X axis directionsy
- the factor by which coordinates are scaled along the
Y axis directionpublic void setTransform(BaseTransform Tx)
BaseTransform
object.setTransform
in class BaseTransform
Tx
- the BaseTransform
object from which to
copy the transformpublic void preConcatenate(BaseTransform Tx)
BaseTransform
Tx
to
this Affine2D
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]
Tx
- the BaseTransform
object to be
concatenated with this Affine2D
object.AffineBase.concatenate(com.sun.javafx.geom.transform.BaseTransform)
public Affine2D createInverse() throws NoninvertibleTransformException
Affine2D
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.
createInverse
in class BaseTransform
Affine2D
object representing the
inverse transformation.NoninvertibleTransformException
- if the matrix cannot be inverted.AffineBase.getDeterminant()
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.
ptSrc
- the array containing the source point objectsptDst
- the array into which the transform point objects are
returnedsrcOff
- the offset to the first point object to be
transformed in the source arraydstOff
- the offset to the location of the first
transformed point object that is stored in the destination arraynumPts
- the number of point objects to be transformedpublic 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.ptSrc
- the distance vector to be delta transformedptDst
- the resulting transformed distance vectorptDst
, which contains the result of the
transformation.public String toString()
String
that represents the value of this
Object
.toString
in class BaseTransform
String
representing the value of this
Object
.public boolean is2D()
is2D
in class AffineBase
public void restoreTransform(double mxx, double myx, double mxy, double myy, double mxt, double myt)
BaseTransform
restoreTransform
in class BaseTransform
public void restoreTransform(double mxx, double mxy, double mxz, double mxt, double myx, double myy, double myz, double myt, double mzx, double mzy, double mzz, double mzt)
BaseTransform
restoreTransform
in class BaseTransform
public BaseTransform deriveWithTranslation(double mxt, double myt)
deriveWithTranslation
in class BaseTransform
public BaseTransform deriveWithTranslation(double mxt, double myt, double mzt)
deriveWithTranslation
in class BaseTransform
public BaseTransform deriveWithScale(double mxx, double myy, double mzz)
deriveWithScale
in class BaseTransform
public BaseTransform deriveWithRotation(double theta, double axisX, double axisY, double axisZ)
deriveWithRotation
in class BaseTransform
public BaseTransform deriveWithPreTranslation(double mxt, double myt)
deriveWithPreTranslation
in class BaseTransform
public BaseTransform deriveWithConcatenation(double mxx, double myx, double mxy, double myy, double mxt, double myt)
deriveWithConcatenation
in class BaseTransform
public BaseTransform deriveWithConcatenation(double mxx, double mxy, double mxz, double mxt, double myx, double myy, double myz, double myt, double mzx, double mzy, double mzz, double mzt)
deriveWithConcatenation
in class BaseTransform
public BaseTransform deriveWithConcatenation(BaseTransform tx)
deriveWithConcatenation
in class BaseTransform
public BaseTransform deriveWithPreConcatenation(BaseTransform tx)
deriveWithPreConcatenation
in class BaseTransform
public BaseTransform deriveWithNewTransform(BaseTransform tx)
deriveWithNewTransform
in class BaseTransform
public BaseTransform copy()
copy
in class BaseTransform
public int hashCode()
BaseTransform
class. This implementation is just a
faster way of computing the same value knowing which elements of
the transform matrix are populated.hashCode
in class BaseTransform
public boolean equals(Object obj)
true
if this Affine2D
represents the same coordinate transform as the specified
argument.equals
in class BaseTransform
obj
- the Object
to test for equality with this
Affine2D
true
if obj
equals this
Affine2D
object; false
otherwise.Copyright © 2020. All rights reserved.