Package org.apache.sis.referencing.operation.transform

# Class AbstractMathTransform2D

Object
FormattableObject
AbstractMathTransform
AbstractMathTransform2D

All Implemented Interfaces:
  `Parameterized`, `LenientComparable`, `MathTransform`, `MathTransform2D`

Direct Known Subclasses:
  `NormalizedProjection`, `ZonedGridSystem`

public abstract class AbstractMathTransform2D extends AbstractMathTransform implements MathTransform2D
Base class for math transforms that are known to be two-dimensional in all cases. Two-dimensional math transforms are not required to extend this class, however doing so may simplify their implementation.

The simplest way to implement this abstract class is to provide an implementation for the following methods only:

- `AbstractMathTransform​.transform(double[], int, double[], int, boolean)`

However more performance may be gained by overriding the other `transform` methods as well.

## Immutability and thread safety

All Apache SIS implementations of `MathTransform2D` are immutable and thread-safe. It is highly recommended that third-party implementations be immutable and thread-safe too. This means that unless otherwise noted in the javadoc, `MathTransform2D` instances can be shared by many objects and passed between threads without synchronization.

## Serialization

`MathTransform2D` may or may not be serializable, at implementation choices. Most Apache SIS implementations are serializable, but the serialized objects are not guaranteed to be compatible with future SIS versions. Serialization should be used only for short term storage or RMI between applications running the same SIS version.

Since:
  0.5

Defined in the `sis-referencing` module

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `AbstractMathTransform2D​.Inverse`
  Base class for implementation of inverse math transforms.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractMathTransform2D()`
  Constructor for subclasses.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Shape`
  `createTransformedShape(Shape shape)`
  Transforms the specified shape.
  `Matrix`
  `derivative(Point2D point)`
  Gets the derivative of this transform at a point.
  `final int`
  `getSourceDimensions()`
  Returns the dimension of input points, which is always 2.
  `final int`
  `getTargetDimensions()`
  Returns the dimension of output points, which is always 2.
  `MathTransform2D`
  `inverse()`
  Returns the inverse transform of this object.
  `Point2D`
  `transform(Point2D ptSrc, Point2D ptDst)`
  Transforms the specified `ptSrc` and stores the result in `ptDst`.

  ### Methods inherited from class AbstractMathTransform

  `computeHashCode, derivative, equals, equals, formatTo, getContextualParameters, getParameterDescriptors, getParameterValues, hashCode, isIdentity, transform, transform, transform, transform, transform, transform, tryConcatenate`

  ### Methods inherited from class FormattableObject

  `print, toString, toString, toWKT`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface MathTransform

  `derivative, isIdentity, toWKT, transform, transform, transform, transform, transform`

- ## Constructor Details

  - ### AbstractMathTransform2D

    protected AbstractMathTransform2D()
    Constructor for subclasses.

- ## Method Details

  - ### getSourceDimensions

    public final int getSourceDimensions()
    Returns the dimension of input points, which is always 2.
    Specified by:
      `getSourceDimensions` in interface `MathTransform`
    Specified by:
      `getSourceDimensions` in class `AbstractMathTransform`
    Returns:
      the dimension of input points.
    See Also:
      - `DefaultOperationMethod​.getSourceDimensions()`

  - ### getTargetDimensions

    public final int getTargetDimensions()
    Returns the dimension of output points, which is always 2.
    Specified by:
      `getTargetDimensions` in interface `MathTransform`
    Specified by:
      `getTargetDimensions` in class `AbstractMathTransform`
    Returns:
      the dimension of output points.
    See Also:
      - `DefaultOperationMethod​.getTargetDimensions()`

  - ### transform

    public Point2D transform(Point2D ptSrc, Point2D ptDst) throws TransformException
    Transforms the specified `ptSrc` and stores the result in `ptDst`. The default implementation invokes `AbstractMathTransform​.transform(double[], int, double[], int, boolean)` using a temporary array of doubles.
    Specified by:
      `transform` in interface `MathTransform2D`
    Parameters:
      `ptSrc` - the coordinate point to be transformed.
      `ptDst` - the coordinate point that stores the result of transforming `ptSrc`, or `null` if a new point shall be created.
    Returns:
      the coordinate point after transforming `ptSrc` and storing the result in `ptDst`, or in a new point if `ptDst` was null.
    Throws:
      `TransformException` - if the point can not be transformed.
    See Also:
      - `MathTransform2D​.transform(Point2D, Point2D)`

  - ### createTransformedShape

    public Shape createTransformedShape(Shape shape) throws TransformException
    Transforms the specified shape. The default implementation computes quadratic curves using three points for each line segment in the shape. The returned object is often a `Path2D`, but may also be a `Line2D` or a `QuadCurve2D` if such simplification is possible.
    Specified by:
      `createTransformedShape` in interface `MathTransform2D`
    Parameters:
      `shape` - shape to transform.
    Returns:
      transformed shape, or `shape` if this transform is the identity transform.
    Throws:
      `TransformException` - if a transform failed.

  - ### derivative

    public Matrix derivative(Point2D point) throws TransformException
    Gets the derivative of this transform at a point. The default implementation performs the following steps:
    - Copy the coordinate in a temporary array and pass that array to the `AbstractMathTransform​.transform(double[], int, double[], int, boolean)` method, with the `derivate` boolean argument set to `true`.
    - If the later method returned a non-null matrix, returns that matrix. Otherwise throws `TransformException`.
    Specified by:
      `derivative` in interface `MathTransform2D`
    Parameters:
      `point` - the coordinate point where to evaluate the derivative.
    Returns:
      the derivative at the specified point as a 2×2 matrix.
    Throws:
      `TransformException` - if the derivative can not be evaluated at the specified point.

  - ### inverse

    public MathTransform2D inverse() throws NoninvertibleTransformException
    Returns the inverse transform of this object. The default implementation returns `this` if this transform is an identity transform, or throws an exception otherwise. Subclasses should override this method.
    Specified by:
      `inverse` in interface `MathTransform`
    Specified by:
      `inverse` in interface `MathTransform2D`
    Overrides:
      `inverse` in class `AbstractMathTransform`
    Throws:
      `NoninvertibleTransformException`