# Interface MathTransform

All Known Subinterfaces:
`MathTransform1D`, `MathTransform2D`

@UML(identifier="CT_MathTransform", specification=OGC_01009) public interface MathTransform
Transforms multi-dimensional coordinate points. A `MathTransform` is an object that actually does the work of applying a formula to coordinate values. The math transform does not know or care how the coordinates relate to positions in the real world. For example, the affine transform applies a matrix to the coordinates without knowing how what it is doing relates to the real world. So if the matrix scales z values by a factor of 1000, then it could be converting metres into millimetres, or it could be converting kilometres into metres.

Because they have low semantic value (but high mathematical value), `MathTransform`s can be used in applications that have nothing to do with GIS coordinates. For example, a math transform could be used to map color coordinates between different color spaces, such as converting (red, green, blue) colors into (hue, light, saturation) colors.

## Application to coordinate operations

When used for coordinate operations, this interface transforms coordinate value for a point given in the source coordinate reference system to coordinate value for the same point in the target coordinate reference system.
• In a conversion, the transformation is accurate to within the limitations of the computer making the calculations.
• In a transformation, where some of the operational parameters are derived from observations, the transformation is accurate to within the limitations of those observations.
If a client application wishes to query the source and target coordinate reference systems of an operation, then it should keep hold of the `CoordinateOperation` interface, and use the contained math transform object whenever it wishes to perform a transform.
Since:
1.0
• ## Method Summary

Modifier and Type
Method
Description
`Matrix`
`derivative(DirectPosition point)`
Gets the derivative of this transform at a point.
`int`
`getSourceDimensions()`
Returns the number of dimensions of input points.
`int`
`getTargetDimensions()`
Returns the number of dimensions of output points.
`default MathTransform`
`inverse()`
Returns the inverse transform of this object.
`boolean`
`isIdentity()`
Tests whether this transform does not move any points.
`default String`
`toWKT()`
Returns a Well-Known Text (WKT) for this object.
`void`
```transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)```
Transforms an array of double-precision coordinate tuples.
`void`
```transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)```
Transforms an array of double-precision coordinate tuples, then converts to single-precision.
`void`
```transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)```
Converts an array of single-precision coordinate tuples to double precision, then transform.
`void`
```transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)```
Transforms an array of single-precision coordinate tuples.
`default int`
```transform(DoubleBuffer srcPts, DoubleBuffer dstPts)```
Transforms a buffer of double-precision coordinate tuples.
`default int`
```transform(DoubleBuffer srcPts, FloatBuffer dstPts)```
Transforms coordinate tuples and converts the result to single-precision.
`default int`
```transform(FloatBuffer srcPts, DoubleBuffer dstPts)```
Converts simple-precision coordinate tuples to double-precision and transform them.
`default int`
```transform(FloatBuffer srcPts, FloatBuffer dstPts)```
Transforms a buffer of single-precision coordinate tuples.
`DirectPosition`
```transform(DirectPosition ptSrc, DirectPosition ptDst)```
Transforms the specified `ptSrc` and stores the result in `ptDst`.
• ## Method Details

• ### getSourceDimensions

Returns the number of dimensions of input points.
Returns:
the number of dimensions of input points.
• ### getTargetDimensions

Returns the number of dimensions of output points.
Returns:
the number of dimensions of output points.
• ### transform

Transforms the specified `ptSrc` and stores the result in `ptDst`. If `ptDst` is `null`, a new `DirectPosition` object is allocated and then the result of the transformation is stored in this object. In either case, `ptDst`, which contains the transformed point, is returned for convenience. If `ptSrc` and `ptDst` are the same object, the input point is correctly overwritten with the transformed point.
Parameters:
`ptSrc` - the specified coordinate point to be transformed.
`ptDst` - the specified coordinate point that stores the result of transforming `ptSrc`, or `null`.
Returns:
the coordinate point after transforming `ptSrc` and storing the result in `ptDst`, or a newly created point if `ptDst` was null.
Throws:
`MismatchedDimensionException` - if `ptSrc` or `ptDst` doesn't have the expected dimension.
`TransformException` - if the point cannot be transformed.
• ### transform

@UML(identifier="transformList", specification=OGC_01009) void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
Transforms an array of double-precision coordinate tuples. This method is provided for efficiently transforming many points. The supplied array will contain packed coordinate tuples. For example, if the source dimension is 3, then the coordinates will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).
Parameters:
`srcPts` - the array containing the source coordinate tuples.
`srcOff` - the offset to the first tuple to be transformed in the source array.
`dstPts` - the array into which the transformed coordinate tuples are stored. May be the same array as `srcPts`.
`dstOff` - the offset to the first transformed coordinate that is stored in the destination array.
`numPts` - the number of coordinate tuples to be transformed.
Throws:
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
• ### transform

void transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws TransformException
Transforms an array of single-precision coordinate tuples. This method is provided for efficiently transforming many points. The supplied array will contain packed coordinate tuples. For example, if the source dimension is 3, then the coordinates will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).

Note: while the source and destination arrays use single-precision floating point numbers, implementation should perform intermediate calculations in double-precision.

Parameters:
`srcPts` - the array containing the source coordinate tuples.
`srcOff` - the offset to the first tuple to be transformed in the source array.
`dstPts` - the array into which the transformed coordinate tuples are stored. May be the same array as `srcPts`.
`dstOff` - the offset to the first transformed coordinate that is stored in the destination array.
`numPts` - the number of coordinate tuples to be transformed.
Throws:
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
• ### transform

void transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
Converts an array of single-precision coordinate tuples to double precision, then transform. This method is provided for efficiently transforming many points. The supplied array will contain packed coordinate tuples. For example, if the source dimension is 3, then the coordinates will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).
Parameters:
`srcPts` - the array containing the source coordinate tuples.
`srcOff` - the offset to the first tuple to be transformed in the source array.
`dstPts` - the array into which the transformed coordinate tuples are stored. May be the same array as `srcPts`.
`dstOff` - the offset to the first transformed coordinate that is stored in the destination array.
`numPts` - the number of coordinate tuples to be transformed.
Throws:
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
• ### transform

void transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws TransformException
Transforms an array of double-precision coordinate tuples, then converts to single-precision. This method is provided for efficiently transforming many points. The supplied array will contain packed coordinate tuples. For example, if the source dimension is 3, then the coordinates will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).
Parameters:
`srcPts` - the array containing the source coordinate tuples.
`srcOff` - the offset to the first tuple to be transformed in the source array.
`dstPts` - the array into which the transformed coordinate tuples are stored. May be the same array as `srcPts`.
`dstOff` - the offset to the first transformed coordinate that is stored in the destination array.
`numPts` - the number of coordinate tuples to be transformed.
Throws:
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
• ### transform

default int transform(DoubleBuffer srcPts, DoubleBuffer dstPts) throws TransformException
Transforms a buffer of double-precision coordinate tuples. This method is provided for efficiently transforming many points, either in Java heap or in the memory of native applications (e.g. C/C++). The supplied buffer will contain packed coordinate tuples. For example, if the source dimension is 3, then the coordinates will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).

The first coordinate to transform is read at index `srcPts.position()` and the first transformed coordinate will be stored at index `dstPts.position()`. The maximal number of coordinate tuples to transform is:

``````int numPts = Math.min(srcPts.remaining() / getSourceDimensions(),
dstPts.remaining() / getTargetDimensions());
``````

If above maximum is zero, then this method returns 0. Otherwise, this method shall transform at least one coordinate tuple. It may transform any number of coordinate tuples between 1 and the above-cited maximum, at implementation choice. On success, the position of the source and destination buffer will be set to the index after the last coordinate read and stored respectively. If an exception has been thrown, then the buffer positions are undetermined.

#### Default implementation

The default implementation delegates to `transform(double[], int, double[], int, int)`. Therefore, the default implementation supports only buffers on Java heap. Implementations should override this method if they want to support native heaps.
Parameters:
`srcPts` - the buffer containing the source coordinate tuples.
`dstPts` - the buffer into which the transformed coordinate tuples are stored. May be the same buffer as `srcPts`.
Returns:
number of coordinate tuples actually transformed.
Throws:
`UnsupportedOperationException` - if this implementation supports only buffers backed by accessible Java arrays, and at least one buffer is backed by native memory.
`ReadOnlyBufferException` - if the destination buffer is read-only.
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
Since:
3.1
• ### transform

default int transform(FloatBuffer srcPts, FloatBuffer dstPts) throws TransformException
Transforms a buffer of single-precision coordinate tuples. This method follows the same contract as `transform(DoubleBuffer, DoubleBuffer)`, except that the floating-point precision of source and destination buffers are different. See the double-precision variant of this method for details.

#### Default implementation

The default implementation delegates to `transform(float[], int, float[], int, int)`. Therefore, the default implementation supports only buffers on Java heap. Implementations should override this method if they want to support native heaps.
Parameters:
`srcPts` - the buffer containing the source coordinate tuples.
`dstPts` - the buffer into which the transformed coordinate tuples are stored. May be the same buffer as `srcPts`.
Returns:
number of coordinate tuples actually transformed.
Throws:
`UnsupportedOperationException` - if this implementation supports only buffers backed by accessible Java arrays, and at least one buffer is backed by native memory.
`ReadOnlyBufferException` - if the destination buffer is read-only.
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Float.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
Since:
3.1
• ### transform

default int transform(FloatBuffer srcPts, DoubleBuffer dstPts) throws TransformException
Converts simple-precision coordinate tuples to double-precision and transform them. This method follows the same contract as `transform(DoubleBuffer, DoubleBuffer)`, except that the floating-point precision of the source buffer is different. See the double-precision variant of this method for details.

#### Default implementation

The default implementation delegates to `transform(float[], int, double[], int, int)`. Therefore, the default implementation supports only buffers on Java heap. Implementations should override this method if they want to support native heaps.
Parameters:
`srcPts` - the buffer containing the source coordinate tuples.
`dstPts` - the buffer into which the transformed coordinate tuples are stored. May be the same buffer as `srcPts`.
Returns:
number of coordinate tuples actually transformed.
Throws:
`UnsupportedOperationException` - if this implementation supports only buffers backed by accessible Java arrays, and at least one buffer is backed by native memory.
`ReadOnlyBufferException` - if the destination buffer is read-only.
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Double.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
Since:
3.1
• ### transform

default int transform(DoubleBuffer srcPts, FloatBuffer dstPts) throws TransformException
Transforms coordinate tuples and converts the result to single-precision. This method follows the same contract as `transform(DoubleBuffer, DoubleBuffer)`, except that the floating-point precision of the destination buffer is different. See the double-precision variant of this method for details.

#### Default implementation

The default implementation delegates to `transform(double[], int, float[], int, int)`. Therefore, the default implementation supports only buffers on Java heap. Implementations should override this method if they want to support native heaps.
Parameters:
`srcPts` - the buffer containing the source coordinate tuples.
`dstPts` - the buffer into which the transformed coordinate tuples are stored. May be the same buffer as `srcPts`.
Returns:
number of coordinate tuples actually transformed.
Throws:
`UnsupportedOperationException` - if this implementation supports only buffers backed by accessible Java arrays, and at least one buffer is backed by native memory.
`ReadOnlyBufferException` - if the destination buffer is read-only.
`TransformException` - if a point cannot be transformed. Some implementations may stop at the first failure, while some other implementations may fill the untransformable points with Float.NaN values, continue and throw the exception only at end. Implementations that fall in the latter case should set the last completed transform to `this`.
Since:
3.1
• ### derivative

Gets the derivative of this transform at a point. The derivative is the matrix of the non-translating portion of the approximate affine map at the point. The matrix will have dimensions corresponding to the source and target coordinate systems. If the input dimension is M, and the output dimension is N, then the matrix will have size N×M. The elements of the matrix {en,m : n=0 … (N-1)} form a vector in the output space which is parallel to the displacement caused by a small change in the m'th coordinate in the input space.

For example, if the input dimension is 4 and the output dimension is 3, then a small displacement (x₀, x₁, x₂, x₃) in the input space will result in a displacement (y₀, y₁, y₂) in the output space computed as below (en,m are the matrix elements):

```┌    ┐     ┌                    ┐ ┌    ┐
│ y₀ │     │ e₀₀  e₀₁  e₀₂  e₀₃ │ │ x₀ │
│ y₁ │  =  │ e₁₀  e₁₁  e₁₂  e₁₃ │ │ x₁ │
│ y₂ │     │ e₂₀  e₂₁  e₂₂  e₂₃ │ │ x₂ │
└    ┘     └                    ┘ │ x₃ │
└    ┘```
Parameters:
`point` - the coordinate point where to evaluate the derivative. Null value is accepted only if the derivative is the same everywhere. For example, affine transform accept null value since they produces identical derivative no matter the coordinate value. But most map projection will requires a non-null value.
Returns:
the derivative at the specified point (never `null`). This method never returns an internal object: changing the matrix will not change the state of this math transform.
Throws:
`NullPointerException` - if the derivative depends on coordinate and `point` is `null`.
`MismatchedDimensionException` - if `point` does not have the expected dimension.
`TransformException` - if the derivative cannot be evaluated at the specified point.
• ### inverse

Returns the inverse transform of this object. The target of the inverse transform is the source of the original. The source of the inverse transform is the target of the original. Using the original transform followed by the inverse's transform will result in an identity map on the source coordinate space, when allowances for error are made. This method may fail if the transform is not one to one. However, all cartographic projections should succeed.
Returns:
the inverse transform.
Throws:
`NoninvertibleTransformException` - if the transform cannot be inverted.
• ### isIdentity

Tests whether this transform does not move any points.
Returns:
`true` if this `MathTransform` is an identity transform; `false` otherwise.
`UnsupportedOperationException` - if this object cannot be formatted as WKT.