Java Doc for AffineTransform.java in  » 6.0-JDK-Core » AWT » java » awt » geom » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.
version:
   1.83, 05/05/07
author:
   Jim Graham
since:
   1.2

 [  x' ]   [  m00  m01 (m02) ] [  x  ]   [ m00x + m01y ]
 [  y' ] = [  m10  m11 (m12) ] [  y  ] = [ m10x + m11y ]
 [ (1) ]   [  (0)  (0) ( 1 ) ] [ (1) ]   [     (1)     ]
 

 [this] = [this] x [Tx]
 

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. a new AffineTransform object representing theinverse transformation.
See Also:   AffineTransform.getDeterminant
exception:
  NoninvertibleTransformException - if the matrix cannot be inverted.
since:
   1.2

 [  x' ]   [  m00  m01 (m02) ] [  x  ]   [ m00x + m01y ]
 [  y' ] = [  m10  m11 (m12) ] [  y  ] = [ m10x + m11y ]
 [ (1) ]   [  (0)  (0) ( 1 ) ] [ (1) ]   [     (1)     ]
 

 [  x' ]   [  m00  m01 (m02) ] [  x  ]   [ m00x + m01y ]
 [  y' ] = [  m10  m11 (m12) ] [  y  ] = [ m10x + m11y ]
 [ (1) ]   [  (0)  (0) ( 1 ) ] [ (1) ]   [     (1)     ]
 

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   |
 

 AffineTransform.getRotateInstance(numquadrants * Math.PI / 2.0);
 

 AffineTransform.getRotateInstance(numquadrants * Math.PI / 2.0,
 anchorx, anchory);
 

 [   cos(theta)    -sin(theta)    0   ]
 [   sin(theta)     cos(theta)    0   ]
 [       0              0         1   ]
 

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 origin
 

 [   cos(theta)    -sin(theta)    x-x*cos+y*sin  ]
 [   sin(theta)     cos(theta)    y-x*sin-y*cos  ]
 [       0              0               1        ]
 

 AffineTransform.getRotateInstance(Math.atan2(vecy, vecx));
 

 AffineTransform.getRotateInstance(Math.atan2(vecy, vecx),
 anchorx, anchory);
 

 [   sx   0    0   ]
 [   0    sy   0   ]
 [   0    0    1   ]
 

 [   1   shx   0   ]
 [  shy   1    0   ]
 [   0    0    1   ]
 

 [   1    0    tx  ]
 [   0    1    ty  ]
 [   0    0    1   ]
 

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.
See Also:   AffineTransform.getDeterminant
exception:
  NoninvertibleTransformException - if the matrix cannot be inverted.
since:
   1.6

 [this] = [Tx] x [this]
 

 rotate(numquadrants * Math.PI / 2.0);
 

 rotate(numquadrants * Math.PI / 2.0, anchorx, anchory);
 

 [   cos(theta)    -sin(theta)    0   ]
 [   sin(theta)     cos(theta)    0   ]
 [       0              0         1   ]
 

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 origin
 

 rotate(Math.atan2(vecy, vecx));
 

 rotate(Math.atan2(vecy, vecx), anchorx, anchory);
 

 [   sx   0    0   ]
 [   0    sy   0   ]
 [   0    0    1   ]
 

 setToRotation(numquadrants * Math.PI / 2.0);
 

 setToRotation(numquadrants * Math.PI / 2.0, anchorx, anchory);
 

 [   cos(theta)    -sin(theta)    0   ]
 [   sin(theta)     cos(theta)    0   ]
 [       0              0         1   ]
 

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 origin
 

 [   cos(theta)    -sin(theta)    x-x*cos+y*sin  ]
 [   sin(theta)     cos(theta)    y-x*sin-y*cos  ]
 [       0              0               1        ]
 

 setToRotation(Math.atan2(vecy, vecx));
 

 setToTranslation(Math.atan2(vecy, vecx), anchorx, anchory);
 

 [   sx   0    0   ]
 [   0    sy   0   ]
 [   0    0    1   ]
 

 [   1   shx   0   ]
 [  shy   1    0   ]
 [   0    0    1   ]
 

 [   1    0    tx  ]
 [   0    1    ty  ]
 [   0    0    1   ]
 

 [   1   shx   0   ]
 [  shy   1    0   ]
 [   0    0    1   ]
 

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
Parameters:
  ptDst - the array into which the transform point objects arereturned
Parameters:
  srcOff - the offset to the first point object to betransformed in the source array
Parameters:
  dstOff - the offset to the location of the firsttransformed point object that is stored in the destination array
Parameters:
  numPts - the number of point objects to be transformed
since:
   1.2

 [   1    0    tx  ]
 [   0    1    ty  ]
 [   0    0    1   ]
 

 SCALE            SHEAR          TRANSLATE
 m00/m11          m01/m10          m02/m12
 IDENTITY             1.0              0.0              0.0
 TRANSLATE (TR)       1.0              0.0          not both 0.0
 SCALE (SC)       not both 1.0         0.0              0.0
 TR | SC          not both 1.0         0.0          not both 0.0
 SHEAR (SH)           0.0          not both 0.0         0.0
 TR | SH              0.0          not both 0.0     not both 0.0
 SC | SH          not both 0.0     not both 0.0         0.0
 TR | SC | SH     not both 0.0     not both 0.0     not both 0.0