org.apache.sis.referencing.operation.transform

Class MathTransforms

Object

Static

MathTransforms

public final class MathTransforms
extends Static

Utility methods creating or working on Math­Transform instances. This class centralizes in one place some of the most commonly used functions this package. The Math­Transforms class provides the following services:

• Create various SIS implementations of Math­Transform.
• Perform non-standard operations on arbitrary instances.

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

Since:

0.5

See Also:

Math­Transform­Factory

Defined in the sis-referencing module

Method Summary

Methods

Modifier and Type	Method and Description
static MathTransform	compound(MathTransform... transforms) Puts together a list of independent math transforms, each of them operating on a subset of ordinate values.
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 Matrix	getMatrix(MathTransform transform) If the given transform is linear, returns its coefficients as a matrix.
static List<MathTransform>	getSteps(MathTransform transform) Returns all single components of the given (potentially concatenated) transform.
static LinearTransform	identity(int dimension) Returns an identity transform of the specified dimension.
static MathTransform1D	interpolate(double[] preimage, double[] values) Creates a transform for the y=f(x) function where y are computed by a linear interpolation.
static LinearTransform	linear(double scale, double offset) Creates a one-dimensional affine transform for the given coefficients.
static LinearTransform	linear(Matrix matrix) Creates an arbitrary linear transform from the specified matrix.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Method Detail

identity

public static LinearTransform identity(int dimension)

Returns an identity transform of the specified dimension.

Special cases:

• If dimension == 1, then the returned transform implements Math­Transform1D.
• If dimension == 2, then the returned transform implements Math­Transform2D.

Parameters:

dimension - the dimension of the transform to be returned.

Returns:

an identity transform of the specified dimension.

linear

public static LinearTransform linear(double scale,
                     double offset)

Creates a one-dimensional affine transform for the given coefficients. Input values x will be converted into output values y using the following equation:

y = x ⋅ scale + offset

Parameters:

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. Usually the matrix is affine, but this is not mandatory. Non-affine matrix will define a projective transform.

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.

Parameters:

matrix - the matrix used to define the linear transform.

Returns:

the linear (usually affine) transform.

See Also:

get­Matrix(Math­Transform), Default­Math­Transform­Factory.create­Affine­Transform(Matrix)

interpolate

public static MathTransform1D interpolate(double[] preimage,
                          double[] values)

Creates a transform for the y=f(x) function where y are computed by a linear interpolation. Both preimage (the x) and values (the y) arguments can be null:

• If both preimage and values arrays are non-null, then the must have the same length.
• If both preimage and values arrays are null, then this method returns the identity transform.
• If only preimage is null, then the x values are taken as {0, 1, 2, …, values.length - 1}.
• If only values is null, then the y values are taken as {0, 1, 2, …, preimage.length - 1}.

All preimage elements shall be real numbers (not NaN) sorted in increasing or decreasing order. Elements in the values array do not need to be ordered, but the returned transform will be invertible only if all values are real numbers sorted in increasing or decreasing order. Furthermore the returned transform is affine (i.e. implement the Linear­Transform interface) if the interval between each preimage and values element is constant.

The current implementation uses linear interpolation. This may be changed in a future SIS version.

Parameters:

preimage - the input values (x) in the function domain, or null.

values - the output values (y) in the function range, or null.

Returns:

the y=f(x) function.

Since:

0.7

compound

public static MathTransform compound(MathTransform... transforms)

Puts together a list of independent math transforms, each of them operating on a subset of ordinate values. This method is often used for defining 4-dimensional (x,y,z,t) transform as an aggregation of 3 simpler transforms operating on (x,y), (z) and (t) values respectively.

Invariants:

• The source dimensions of the returned transform is equals to the sum of the source dimensions of all given transforms.
• The target dimensions of the returned transform is equals to the sum of the target dimensions of all given transforms.

Parameters:

transforms - the transforms to aggregate in a single transform, in the given order.

Returns:

the aggregation of all given transforms, or null if the given transforms array was empty.

Since:

0.6

See Also:

Pass­Through­Transform, Default­Compound­CRS

concatenate

public static MathTransform concatenate(MathTransform tr1,
                        MathTransform tr2)
                                 throws MismatchedDimensionException

Concatenates the two given transforms. The returned transform will implement Math­Transform1D or Math­Transform2D 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.

Throws:

Mismatched­Dimension­Exception - if the output dimension of the first transform does not match the input dimension of the second transform.

See Also:

Default­Math­Transform­Factory.create­Concatenated­Transform(Math­Transform, Math­Transform)

concatenate

public static MathTransform1D concatenate(MathTransform1D tr1,
                          MathTransform1D tr2)
                                   throws MismatchedDimensionException

Concatenates the given one-dimensional transforms. This is a convenience methods delegating to concatenate(Math­Transform, Math­Transform) and casting the result to a Math­Transform1D instance.

Parameters:

tr1 - the first math transform.

tr2 - the second math transform.

Returns:

the concatenated transform.

Throws:

Mismatched­Dimension­Exception - if the output dimension of the first transform does not match the input dimension of the second transform.

concatenate

public static MathTransform2D concatenate(MathTransform2D tr1,
                          MathTransform2D tr2)
                                   throws MismatchedDimensionException

Concatenates the given two-dimensional transforms. This is a convenience methods delegating to concatenate(Math­Transform, Math­Transform) and casting the result to a Math­Transform2D instance.

Parameters:

tr1 - the first math transform.

tr2 - the second math transform.

Returns:

the concatenated transform.

Throws:

Mismatched­Dimension­Exception - if the output dimension of the first transform does not match the input dimension of the second transform.

concatenate

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

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.

Throws:

Mismatched­Dimension­Exception - if the output dimension of a transform does not match the input dimension of next transform.

concatenate

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

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

Parameters:

tr1 - the first math transform.

tr2 - the second math transform.

tr3 - the third math transform.

Returns:

the concatenated transform.

Throws:

Mismatched­Dimension­Exception - if the output dimension of a transform does not match the input dimension of next transform.

concatenate

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

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

Parameters:

tr1 - the first math transform.

tr2 - the second math transform.

tr3 - the third math transform.

Returns:

the concatenated transform.

Throws:

Mismatched­Dimension­Exception - if the output dimension of a transform does not match the input dimension of next transform.

getSteps

public static List<MathTransform> getSteps(MathTransform transform)

Returns all single components of the given (potentially concatenated) transform. This method makes the following choice:

• If transform is null, returns an empty list.
• Otherwise if transform is the result of a call to a concatenate(…) method, returns all components. All nested concatenated transforms (if any) will be flattened.
• Otherwise returns the given transform in a list of size 1.

Parameters:

transform - the transform for which to get the components, or null.

Returns:

all single math transforms performed by this concatenated transform.

getMatrix

public static Matrix getMatrix(MathTransform transform)

If the given transform is linear, returns its coefficients as a matrix. More specifically:

• If the given transform is an instance of Linear­Transform, returns Linear­Transform.get­Matrix().
• Otherwise if the given transform is an instance of Affine­Transform, returns its coefficients in a Matrix3 instance.
• Otherwise returns null.

Parameters:

transform - the transform for which to get the matrix, or null.

Returns:

the matrix of the given transform, or null if none.

See Also:

linear(Matrix), Linear­Transform.get­Matrix()

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 Math­Transform implementations:

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

Parameters:

transform - the transform to use.

src­Pts - the array containing the source coordinate.

src­Off - the offset to the point to be transformed in the source array.

dst­Pts - the array into which the transformed coordinate is returned.

dst­Off - 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:

Transform­Exception - if the point can't be transformed or if a problem occurred while calculating the derivative.