Class XAffineTransform

  • All Implemented Interfaces:
    Serializable, Cloneable
    Direct Known Subclasses:
    AffineTransform2D

    public class XAffineTransform
    extends AffineTransform
    Utility methods for affine transforms. This class provides two kind of services:
    • A set of public static methods working on any AffineTransform.

    • An abstract base class that override all mutable AffineTransform methods in order to check for permission before changing the transform's state. If checkPermission() is defined to always throw an exception, then XAffineTransform is immutable.

    Since:
    2.3
    Author:
    Martin Desruisseaux (IRD), Simone Giannecchini
    See Also:
    Serialized Form
    • Constructor Detail

      • XAffineTransform

        public XAffineTransform​(AffineTransform tr)
        Constructs a new XAffineTransform that is a copy of the specified AffineTransform object.
      • XAffineTransform

        public XAffineTransform​(double m00,
                                double m10,
                                double m01,
                                double m11,
                                double m02,
                                double m12)
        Constructs a new XAffineTransform from 6 values representing the 6 specifiable entries of the 3×3 transformation matrix. Those values are given unchanged to the super class constructor.
        Since:
        2.5
    • Method Detail

      • checkPermission

        protected void checkPermission()
                                throws UnsupportedOperationException
        Checks if the caller is allowed to change this XAffineTransform state. If this method is defined to thrown an exception in all case, then this XAffineTransform is immutable.

        The default implementation throws the exception in all case, thus making this instance immutable.

        Throws:
        UnsupportedOperationException - if this affine transform is immutable.
      • rotate

        public void rotate​(double theta,
                           double x,
                           double y)
        Checks for permission before rotating this transform.
        Overrides:
        rotate in class AffineTransform
      • scale

        public void scale​(double sx,
                          double sy)
        Checks for permission before scaling this transform.
        Overrides:
        scale in class AffineTransform
      • shear

        public void shear​(double shx,
                          double shy)
        Checks for permission before shearing this transform.
        Overrides:
        shear in class AffineTransform
      • setTransform

        public void setTransform​(double m00,
                                 double m10,
                                 double m01,
                                 double m11,
                                 double m02,
                                 double m12)
        Checks for permission before setting this transform.
        Overrides:
        setTransform in class AffineTransform
      • isIdentity

        public boolean isIdentity​(double tolerance)
        Checks whether or not this XAffineTransform is the identity by using the provided tolerance.
        Parameters:
        tolerance - The tolerance to use for this check.
        Returns:
        true if the transform is identity, false otherwise.
        Since:
        2.3.1
      • isIdentity

        public static boolean isIdentity​(AffineTransform tr,
                                         double tolerance)
        Returns true if the specified affine transform is an identity transform up to the specified tolerance. This method is equivalent to computing the difference between this matrix and an identity matrix (as created by new AffineTransform()) and returning true if and only if all differences are smaller than or equal to tolerance.

        This method is used for working around rounding error in affine transforms resulting from a computation, as in the example below:

         [ 1.0000000000000000001  0.0                      0.0 ]
         [ 0.0                    0.999999999999999999999  0.0 ]
         [ 0.0                    0.0                      1.0 ]
         
        Parameters:
        tr - The affine transform to be checked for identity.
        tolerance - The tolerance value to use when checking for identity. return true if this tranformation is close enough to the identity, false otherwise.
        Since:
        2.3.1
      • transform

        public static Shape transform​(AffineTransform transform,
                                      Shape shape,
                                      boolean overwrite)
        Transforms the given shape. This method is similar to createTransformedShape except that:

        • It tries to preserve the shape kind when possible. For example if the given shape is an instance of RectangularShape and the given transform do not involve rotation, then the returned shape may be some instance of the same class.
        • It tries to recycle the given object if overwrite is true.
        Parameters:
        transform - Affine transform to use.
        shape - The shape to transform.
        overwrite - If true, this method is allowed to overwrite shape with the transform result. If false, then shape is never modified.
        Returns:
        The direct transform of the given shape. May or may not be the same instance than the given shape.
        Since:
        2.5
        See Also:
        AffineTransform.createTransformedShape(java.awt.Shape)
      • inverseDeltaTransform

        public static Point2D inverseDeltaTransform​(AffineTransform transform,
                                                    Point2D source,
                                                    Point2D dest)
                                             throws NoninvertibleTransformException
        Calculates the inverse affine transform of a point without without applying the translation components.
        Parameters:
        transform - Affine transform to use.
        source - Point to transform. This rectangle will not be modified.
        dest - Point in which to place the result. If null, a new point will be created.
        Returns:
        The inverse transform of the source point.
        Throws:
        NoninvertibleTransformException - if the affine transform can't be inverted.
      • getSwapXY

        public static int getSwapXY​(AffineTransform tr)
        Returns an estimation about whatever the specified transform swaps x and y axis. This method assumes that the specified affine transform is built from arbitrary translations, scales or rotations, but no shear. It returns +1 if the (x, y) axis order seems to be preserved, -1 if the transform seems to swap axis to the (y, x) axis order, or 0 if this method can not make a decision.
      • getRotation

        public static double getRotation​(AffineTransform tr)
        Returns an estimation of the rotation angle in radians. This method assumes that the specified affine transform is built from arbitrary translations, scales or rotations, but no shear. If a flip has been applied, then this method assumes that the flipped axis is the y one in source CRS space. For a grid to world CRS transform, this is the row number in grid coordinates.
        Parameters:
        tr - The affine transform to inspect.
        Returns:
        An estimation of the rotation angle in radians, or NaN if the angle can not be estimated.
      • getFlip

        public static int getFlip​(AffineTransform tr)
        Returns -1 if one axis has been flipped, +1 if no axis has been flipped, or 0 if unknown. A flipped axis in an axis with direction reversed (typically the y axis). This method assumes that the specified affine transform is built from arbitrary translations, scales or rotations, but no shear. Note that it is not possible to determine which of the x or y axis has been flipped.

        This method can be used in order to set the sign of a scale according the flipping state. The example below choose to apply the sign on the y scale, but this is an arbitrary (while common) choice:

        double scaleX0 = getScaleX0(transform); double scaleY0 = getScaleY0(transform); int flip = getFlip(transform); if (flip != 0) { scaleY0 *= flip; // ... continue the process here. }
        This method is similar to the following code, except that this method distinguish between "unflipped" and "unknow" states.
        boolean flipped = (tr.getType() & AffineTransform.TYPE_FLIP) != 0;
      • getScaleX0

        public static double getScaleX0​(AffineTransform tr)
        Returns the magnitude of scale factor x by cancelling the effect of eventual flip and rotation. This factor is calculated by .
      • getScaleY0

        public static double getScaleY0​(AffineTransform tr)
        Returns the magnitude of scale factor y by cancelling the effect of eventual flip and rotation. This factor is calculated by .
      • getScaleInstance

        public static AffineTransform getScaleInstance​(double sx,
                                                       double sy,
                                                       double x,
                                                       double y)
        Returns an affine transform representing a zoom carried out around a central point (x, y). The transforms will leave the specified (x, y) coordinate unchanged.
        Parameters:
        sx - Scale along x axis.
        sy - Scale along y axis.
        x - x coordinates of the central point.
        y - y coordinates of the central point.
        Returns:
        Affine transform of a zoom which leaves the (x,y) coordinate unchanged.
      • round

        public static void round​(AffineTransform tr,
                                 double tolerance)
        Checks whether the matrix coefficients are close to whole numbers. If this is the case, these coefficients will be rounded up to the nearest whole numbers. This rounding up is useful, for example, for speeding up image displays. Above all, it is efficient when we know that a matrix has a chance of being close to the similarity matrix.
        Parameters:
        tr - The matrix to round. Rounding will be applied in place.
        tolerance - The maximal departure from integers in order to allow rounding. It is typically a small number like 1E-6.
        Since:
        2.3.1