Package org.apache.sis.referencing.operation.matrix

## Class AffineTransforms2D

- Object
- - Static
  - - AffineTransforms2D

-     public final class AffineTransforms2D
      extends Static

  Bridge between `Matrix` and Java2D `AffineTransform` instances. Those `AffineTransform` instances can be viewed as 3×3 matrices.
  Since:
    0.4

  Defined in the `sis-referencing` module

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static AffineTransform` | `castOrCopy​(Matrix matrix)` | Returns the given matrix as a Java2D affine transform.
    `static int` | `getFlip​(AffineTransform transform)` | Returns `-1` if one axis has been flipped, `+1` if no axis has been flipped, or 0 if unknown.
    `static double` | `getRotation​(AffineTransform transform)` | Returns an estimation of the rotation angle in radians.
    `static double` | `getScaleX0​(AffineTransform transform)` | Returns the magnitude of scale factor x by canceling the effect of eventual flip and rotation.
    `static double` | `getScaleY0​(AffineTransform transform)` | Returns the magnitude of scale factor y by canceling the effect of eventual flip and rotation.
    `static int` | `getSwapXY​(AffineTransform transform)` | Returns an estimation about whether the specified transform swaps x and y axes.
    `static Point2D` | `inverseDeltaTransform​(AffineTransform transform, Point2D vector, Point2D dest)` | Calculates the inverse transform of a point without applying the translation components.
    `static Rectangle2D` | `inverseTransform​(AffineTransform transform, Rectangle2D bounds, Rectangle2D dest)` | Calculates a rectangle which entirely contains the inverse transform of `bounds`.
    `static Matrix3` | `toMatrix​(AffineTransform transform)` | Creates a 3×3 matrix from the given affine transform.
    `static Rectangle2D` | `transform​(AffineTransform transform, Rectangle2D bounds, Rectangle2D dest)` | Calculates a rectangle which entirely contains the direct transform of `bounds`.
    `static Shape` | `transform​(AffineTransform transform, Shape shape, boolean allowOverwrite)` | Transforms the given shape.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### castOrCopy

          public static AffineTransform castOrCopy​(Matrix matrix)
                                            throws IllegalArgumentException

      Returns the given matrix as a Java2D affine transform. If the given matrix is already an instance of `AffineTransform`, then it is returned directly. Otherwise the values are copied in a new `AffineTransform` instance.
      Parameters:
        `matrix` - the matrix to returns as an affine transform, or `null`.
      Returns:
        the matrix argument if it can be safely casted (including `null` argument), or a copy of the given matrix otherwise.
      Throws:
        `IllegalArgumentException` - if the given matrix size is not 3×3 or if the matrix is not affine.
      See Also:
        `Matrices​.isAffine(Matrix)`

    - #### toMatrix

          public static Matrix3 toMatrix​(AffineTransform transform)

      Creates a 3×3 matrix from the given affine transform.
      Parameters:
        `transform` - the affine transform to copy as a matrix.
      Returns:
        a matrix containing the same terms than the given affine transform.

    - #### transform

          public static Shape transform​(AffineTransform transform,
                                        Shape shape,
                                        boolean allowOverwrite)

      Transforms the given shape. This method is similar to `AffineTransform​.createTransformedShape(Shape)` 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 does 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` - the affine transform to use.
        `shape` - the shape to transform, or `null`.
        `allowOverwrite` - if `true`, this method is allowed to overwrite `shape` with the transform result. If `false`, then `shape` is never modified.
      Returns:
        the transform of the given shape, or `null` if the given shape was null. May or may not be the same instance than the given shape.
      See Also:
        `AffineTransform​.createTransformedShape(Shape)`

    - #### transform

          public static Rectangle2D transform​(AffineTransform transform,
                                              Rectangle2D bounds,
                                              Rectangle2D dest)

      Calculates a rectangle which entirely contains the direct transform of `bounds`. This operation is equivalent to the following code, except that it can reuse the given `dest` rectangle and is potentially more efficient:

      >     return transform.createTransformedShape(bounds).getBounds2D();

      Note that if the given rectangle is an image bounds, then the given transform shall map the upper-left corner of pixels (as in Java2D usage), not the center of pixels (OGC usage).
      Parameters:
        `transform` - the affine transform to use.
        `bounds` - the rectangle to transform, or `null`. this rectangle will not be modified except if `dest` references the same object.
        `dest` - rectangle in which to place the result. If `null`, a new rectangle will be created.
      Returns:
        the direct transform of the `bounds` rectangle, or `null` if `bounds` was null.
      See Also:
        `Shapes2D​.transform(MathTransform2D, Rectangle2D, Rectangle2D)`

    - #### inverseTransform

          public static Rectangle2D inverseTransform​(AffineTransform transform,
                                                     Rectangle2D bounds,
                                                     Rectangle2D dest)
                                              throws NoninvertibleTransformException

      Calculates a rectangle which entirely contains the inverse transform of `bounds`. This operation is equivalent to the following code, except that it can reuse the given `dest` rectangle and is potentially more efficient:

      >     return createInverse().createTransformedShape(bounds).getBounds2D();

      Parameters:
        `transform` - the affine transform to use.
        `bounds` - the rectangle to transform, or `null`. this rectangle will not be modified except if `dest` references the same object.
        `dest` - rectangle in which to place the result. If `null`, a new rectangle will be created.
      Returns:
        the inverse transform of the `bounds` rectangle, or `null` if `bounds` was null.
      Throws:
        `NoninvertibleTransformException` - if the affine transform can't be inverted.

    - #### inverseDeltaTransform

          public static Point2D inverseDeltaTransform​(AffineTransform transform,
                                                      Point2D vector,
                                                      Point2D dest)
                                               throws NoninvertibleTransformException

      Calculates the inverse transform of a point without applying the translation components. In other words, calculates the inverse transform of a displacement vector.
      Parameters:
        `transform` - the affine transform to use.
        `vector` - the vector to transform stored as a point. this point will not be modified except if `dest` references the same object.
        `dest` - point in which to place the result. If `null`, a new point will be created.
      Returns:
        the inverse transform of the `vector`, or `null` if `source` was null.
      Throws:
        `NoninvertibleTransformException` - if the affine transform can't be inverted.

    - #### getSwapXY

          public static int getSwapXY​(AffineTransform transform)

      Returns an estimation about whether the specified transform swaps x and y axes. 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.
      Parameters:
        `transform` - the affine transform to inspect.
      Returns:
        `true` if the given transform seems to swap axis order.

    - #### getRotation

          public static double getRotation​(AffineTransform transform)

      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:
        `transform` - 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 transform)

      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 distinguishes between "unflipped" and "unknown" states.

      >     boolean flipped = (tr.getType() & TYPE_FLIP) != 0;

      Parameters:
        `transform` - the affine transform to inspect.
      Returns:
        -1 if an axis has been flipped, +1 if no flipping, or 0 if unknown.

    - #### getScaleX0

          public static double getScaleX0​(AffineTransform transform)

      Returns the magnitude of scale factor x by canceling the effect of eventual flip and rotation. This factor is calculated by:

      Parameters:
        `transform` - the affine transform to inspect.
      Returns:
        the magnitude of scale factor x.

    - #### getScaleY0

          public static double getScaleY0​(AffineTransform transform)

      Returns the magnitude of scale factor y by canceling the effect of eventual flip and rotation. This factor is calculated by:

      Parameters:
        `transform` - the affine transform to inspect.
      Returns:
        the magnitude of scale factor y.