org.geotoolkit.referencing.operation
Class MathTransforms

Object
  Static
      MathTransforms

public final class MathTransforms
extends Static

Utility methods related to MathTransforms. This class centralizes in one place some of the most commonly used functions from the org.geotoolkit.referencing.operation.transform package, thus reducing the need to explore that low-level package. The MathTransforms class provides the following services:

• Create various Geotk implementations of MathTransform
• Perform non-standard operations on arbitrary instances

The factory static methods are provided as convenient alternatives to the GeoAPI MathTransformFactory interface. However users seeking for more implementation neutrality are encouraged to limit themselves to the GeoAPI factory interfaces instead.

Since:

3.20

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

See Also:

MathTransformFactory

Module:

referencing/geotk-referencing (download)

View source code for this class

Method Summary

static MathTransform1D	concatenate(MathTransform1D tr1, MathTransform1D tr2) Concatenates the given one-dimensional transforms.
static MathTransform1D	concatenate(MathTransform1D tr1, MathTransform1D tr2, MathTransform1D tr3) Concatenates the three given one-dimensional transforms.
static MathTransform2D	concatenate(MathTransform2D tr1, MathTransform2D tr2) Concatenates the given two-dimensional transforms.
static MathTransform2D	concatenate(MathTransform2D tr1, MathTransform2D tr2, MathTransform2D tr3) Concatenates the three given two-dimensional transforms.
static MathTransform	concatenate(MathTransform tr1, MathTransform tr2) Concatenates the two given transforms.
static MathTransform	concatenate(MathTransform tr1, MathTransform tr2, MathTransform tr3) Concatenates the three given transforms.
static Matrix	derivativeAndTransform(MathTransform transform, double[] srcPts, int srcOff, double[] dstPts, int dstOff) A buckle method for calculating derivative and coordinate transformation in a single step.
static LinearTransform	dimensionFilter(int sourceDim, int[] toKeep) Creates an affine transform that keep only a subset of the source ordinate values.
static LinearTransform	identity(int dimension) Returns an identity transform of the specified dimension.
static LinearTransform	linear(AffineTransform matrix) Creates an affine transform from the specified Java2D object.
static LinearTransform	linear(int dimension, double scale, double offset) Creates an affine transform that apply the same linear conversion for all dimensions.
static LinearTransform	linear(Matrix matrix) Creates an arbitrary linear transform from the specified matrix.

Methods inherited from class Object

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

Method Detail

identity

public static LinearTransform identity(int dimension)

Returns an identity transform of the specified dimension. In the special case of dimension 1 and 2, this method returns instances of LinearTransform1D or AffineTransform2D respectively.

Parameters:

dimension - The dimension of the transform to be returned.

Returns:

An identity transform of the specified dimension.

linear

public static LinearTransform linear(int dimension,
                                     double scale,
                                     double offset)

Creates an affine transform that apply the same linear conversion for all dimensions. For each dimension, input values x are converted into output values y using the following equation:

y = x × scale + offset

Parameters:

dimension - The input and output dimensions.

scale - The scale term in the linear equation.

offset - The offset term in the linear equation.

Returns:

The linear transform for the given scale and offset.

linear

public static LinearTransform linear(Matrix matrix)

Creates an arbitrary linear transform from the specified matrix. If the transform input dimension is M, and output dimension is N, then the given matrix shall have size [N+1][M+1]. The +1 in the matrix dimensions allows the matrix to do a shift, as well as a rotation. The [M][j] element of the matrix will be the j'th ordinate of the moved origin.

The matrix is usually square and affine, but this is not mandatory. Non-affine transforms are allowed.

Parameters:

matrix - The matrix used to define the linear transform.

Returns:

The linear transform.

See Also:

MathTransformFactory.createAffineTransform(Matrix)

linear

public static LinearTransform linear(AffineTransform matrix)

Creates an affine transform from the specified Java2D object. The matrix coefficients are used in the same way than linear(Matrix).

Parameters:

matrix - The matrix used to define the affine transform.

Returns:

The affine transform.

dimensionFilter

public static LinearTransform dimensionFilter(int sourceDim,
                                              int[] toKeep)
                                       throws IndexOutOfBoundsException

Creates an affine transform that keep only a subset of the source ordinate values. The dimension of source coordinates is sourceDim and the dimension of target coordinates is toKeep.length.

Parameters:

sourceDim - the dimension of source coordinates.

toKeep - the indices of source ordinate values to keep.

Returns:

The affine transform keeping only the given dimensions, and discarding all others.

Throws:

IndexOutOfBoundsException - if a value of toKeep is lower than 0 or not smaller than sourceDim.

See Also:

Matrices.createDimensionFilter(int, int[])

concatenate

public static MathTransform concatenate(MathTransform tr1,
                                        MathTransform tr2)

Concatenates the two given transforms. The returned transform will implement MathTransform1D or MathTransform2D if the dimensions of the concatenated transform are equal to 1 or 2 respectively.

Parameters:

tr1 - The first math transform.

tr2 - The second math transform.

Returns:

The concatenated transform.

See Also:

MathTransformFactory.createConcatenatedTransform(MathTransform, MathTransform)

concatenate

public static MathTransform2D concatenate(MathTransform2D tr1,
                                          MathTransform2D tr2)

Concatenates the given two-dimensional transforms. This is a convenience methods delegating to concatenate(MathTransform, MathTransform) and casting the result to a MathTransform2D instance.

Parameters:

tr1 - The first math transform.

tr2 - The second math transform.

Returns:

The concatenated transform.

concatenate

public static MathTransform1D concatenate(MathTransform1D tr1,
                                          MathTransform1D tr2)

Concatenates the given one-dimensional transforms. This is a convenience methods delegating to concatenate(MathTransform, MathTransform) and casting the result to a MathTransform1D instance.

Parameters:

tr1 - The first math transform.

tr2 - The second math transform.

Returns:

The concatenated transform.

concatenate

public static MathTransform concatenate(MathTransform tr1,
                                        MathTransform tr2,
                                        MathTransform tr3)

Concatenates the three given transforms. This is a convenience methods doing its job as two consecutive concatenations.

Parameters:

tr1 - The first math transform.

tr2 - The second math transform.

tr3 - The third math transform.

Returns:

The concatenated transform.

concatenate

public static MathTransform2D concatenate(MathTransform2D tr1,
                                          MathTransform2D tr2,
                                          MathTransform2D tr3)

Concatenates the three given two-dimensional transforms. This is a convenience methods delegating to concatenate(MathTransform, MathTransform, MathTransform) and casting the result to a MathTransform2D instance.

Parameters:

tr1 - The first math transform.

tr2 - The second math transform.

tr3 - The third math transform.

Returns:

The concatenated transform.

concatenate

public static MathTransform1D concatenate(MathTransform1D tr1,
                                          MathTransform1D tr2,
                                          MathTransform1D tr3)

Concatenates the three given one-dimensional transforms. This is a convenience methods delegating to concatenate(MathTransform, MathTransform, MathTransform) and casting the result to a MathTransform1D instance.

Parameters:

tr1 - The first math transform.

tr2 - The second math transform.

tr3 - The third math transform.

Returns:

The concatenated transform.

derivativeAndTransform

public static Matrix derivativeAndTransform(MathTransform transform,
                                            double[] srcPts,
                                            int srcOff,
                                            double[] dstPts,
                                            int dstOff)
                                     throws TransformException

A buckle method for calculating derivative and coordinate transformation in a single step. The transform result is stored in the given destination array, and the derivative matrix is returned. Invoking this method is equivalent to the following code, except that it may execute faster with some MathTransform implementations:

DirectPosition ptSrc = ...;
DirectPosition ptDst = ...;
Matrix matrixDst = derivative(ptSrc);
ptDst = transform(ptSrc, ptDst);

Parameters:

transform - The transform to use.

srcPts - The array containing the source coordinate.

srcOff - The offset to the point to be transformed in the source array.

dstPts - the array into which the transformed coordinate is returned.

dstOff - The offset to the location of the transformed point that is stored in the destination array.

Returns:

The matrix of the transform derivative at the given source position.

Throws:

TransformException - If the point can't be transformed or if a problem occurred while calculating the derivative.