Module org.opengis.geoapi

Package org.opengis.referencing.operation

Interface MathTransform

All Known Subinterfaces:

MathTransform1D, MathTransform2D

All Known Implementing Classes:

AffineTransform2D, ProjectiveTransform, SimpleTransform, SimpleTransform2D

@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), MathTransforms 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

See Also:

• AffineTransform
• MathTransformFactory
• Formula
• CoordinateOperation.getMathTransform()

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.
MathTransform	inverse()	Creates the inverse transform of this object.
boolean	isIdentity()	Tests whether this transform does not move any points.
String	toWKT()	Returns a Well-Known Text (WKT) for this object.
void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate point ordinal values.
void	transform(double[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate point ordinal values.
void	transform(float[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate point ordinal values.
void	transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)	Transforms a list of coordinate point ordinal values.
DirectPosition	transform(DirectPosition ptSrc, DirectPosition ptDst)	Transforms the specified ptSrc and stores the result in ptDst.

Method Details

getSourceDimensions

@UML(identifier="getDimSource",
     specification=OGC_01009)
int getSourceDimensions()

Returns the number of dimensions of input points.

Returns:

the number of dimensions of input points.

See Also:

• OperationMethod.getSourceDimensions()

getTargetDimensions

@UML(identifier="getDimTarget",
     specification=OGC_01009)
int getTargetDimensions()

Returns the number of dimensions of output points.

Returns:

the number of dimensions of output points.

See Also:

• OperationMethod.getTargetDimensions()

transform

@UML(identifier="transform",
     specification=OGC_01009)
DirectPosition transform(DirectPosition ptSrc,
 DirectPosition ptDst)
                  throws MismatchedDimensionException,
TransformException

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 a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).

Parameters:

srcPts - the array containing the source point coordinates.

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

dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.

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

numPts - the number of point objects to be transformed.

Throws:

TransformException - if a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will 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.

See Also:

• AffineTransform.transform(double[], int, double[], int, int)

transform

void transform(float[] srcPts,
 int srcOff,
 float[] dstPts,
 int dstOff,
 int numPts)
        throws TransformException

Transforms a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).

Parameters:

srcPts - the array containing the source point coordinates.

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

dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.

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

numPts - the number of point objects to be transformed.

Throws:

TransformException - if a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will 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.

See Also:

• AffineTransform.transform(float[], int, float[], int, int)

transform

void transform(float[] srcPts,
 int srcOff,
 double[] dstPts,
 int dstOff,
 int numPts)
        throws TransformException

Transforms a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).

Parameters:

srcPts - the array containing the source point coordinates.

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

dstPts - the array into which the transformed point coordinates are returned.

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

numPts - the number of point objects to be transformed.

Throws:

TransformException - if a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will 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.

See Also:

• AffineTransform.transform(float[], int, double[], int, int)

transform

void transform(double[] srcPts,
 int srcOff,
 float[] dstPts,
 int dstOff,
 int numPts)
        throws TransformException

Transforms a list of coordinate point ordinal values. This method is provided for efficiently transforming many points. The supplied array of ordinal values will contain packed ordinal values. For example, if the source dimension is 3, then the ordinals will be packed in this order: (x₀,y₀,z₀, x₁,y₁,z₁ …).

Parameters:

srcPts - the array containing the source point coordinates.

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

dstPts - the array into which the transformed point coordinates are returned.

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

numPts - the number of point objects to be transformed.

Throws:

TransformException - if a point cannot be transformed. Some implementations will stop at the first failure, wile some other implementations will 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.

See Also:

• AffineTransform.transform(double[], int, float[], int, int)

derivative

@UML(identifier="derivative",
     specification=OGC_01009)
Matrix derivative(DirectPosition point)
           throws MismatchedDimensionException,
TransformException

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 {e_n,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 (e_n,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

@UML(identifier="inverse",
     specification=OGC_01009)
MathTransform inverse()
               throws NoninvertibleTransformException

Creates 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.

See Also:

• AffineTransform.createInverse()

isIdentity

@UML(identifier="isIdentity",
     specification=OGC_01009)
boolean isIdentity()

Tests whether this transform does not move any points.

Returns:

true if this MathTransform is an identity transform; false otherwise.

See Also:

• AffineTransform.isIdentity()

toWKT

@UML(identifier="getWKT",
     specification=OGC_01009)
String toWKT()

Returns a Well-Known Text (WKT) for this object. Version 1 of Well-Know Text is defined in extended Backus Naur form. This operation may fail if unsupported or if this instance contains elements that do not have WKT representation.

Returns:

the Well-Known Text (WKT) for this object.

Throws:

UnsupportedOperationException - if this object cannot be formatted as WKT.

See Also:

• MathTransformFactory.createFromWKT(String)