org.geotoolkit.referencing.operation.transform
Class AbstractMathTransform

Object
  FormattableObject
      AbstractMathTransform

All Implemented Interfaces:

Formattable, Parameterized, LenientComparable, MathTransform

Direct Known Subclasses:

AbstractMathTransform.Inverse, AbstractMathTransform1D, AbstractMathTransform2D, ConcatenatedTransform, GeocentricTransform, GridTransform, IdentityTransform, MolodenskyTransform, PassThroughTransform, ProjectiveTransform

@ThreadSafe
public abstract class AbstractMathTransform
extends FormattableObject
implements MathTransform, Parameterized, LenientComparable

Provides a default implementation for most methods required by the MathTransform interface. AbstractMathTransform provides a convenient base class from which other transform classes can be easily derived. In addition, AbstractMathTransform implements methods required by the MathTransform2D interface, but does not implements MathTransform2D. Subclasses must declare implements MathTransform2D themselves if they know to map two-dimensional coordinate systems.

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

• getSourceDimensions()
• getTargetDimensions()
• transform(double[],int,double[],int)

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

Since:

1.2

Version:

3.18

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

referencing/geotk-referencing (download)

View source code for this class

Nested Class Summary

protected class

AbstractMathTransform.Inverse Default implementation for inverse math transform.

Field Summary

Fields inherited from class FormattableObject

EPSG, GEOTIFF, INTERNAL, OGC, SINGLE_LINE

Constructor Summary

protected

AbstractMathTransform() Constructs a math transform.

Method Summary

protected int	computeHashCode() Computes a hash value for this transform.
Shape	createTransformedShape(Shape shape) Transform the specified shape.
Matrix	derivative(DirectPosition point) Gets the derivative of this transform at a point.
Matrix	derivative(Point2D point) Gets the derivative of this transform at a point.
protected static void	ensureNonNull(String name, Object object) Makes sure that an argument is non-null.
boolean	equals(Object object) Compares the specified object with this math transform for strict equality.
boolean	equals(Object object, ComparisonMode mode) Compares the specified object with this math transform for equality.
String	formatWKT(Formatter formatter) Formats the inner part of a Well Known Text (WKT) element.
String	getName() Returns a name for this math transform (never null).
ParameterDescriptorGroup	getParameterDescriptors() Returns the parameter descriptors for this math transform, or null if unknown.
ParameterValueGroup	getParameterValues() Returns a copy of the parameter values for this math transform, or null if unknown.
abstract int	getSourceDimensions() Gets the dimension of input points.
abstract int	getTargetDimensions() Gets the dimension of output points.
int	hashCode() Returns a hash value for this transform.
MathTransform	inverse() Returns the inverse transform of this object.
boolean	isIdentity() Tests whether this transform does not move any points.
protected static double	rollLongitude(double x, double bound) Ensures that the specified longitude stay within the [-bound … bound] range.
DirectPosition	transform(DirectPosition ptSrc, DirectPosition ptDst) Transforms the specified ptSrc and stores the result in ptDst.
protected abstract void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff) Transforms a single coordinate point in an array.
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.
Point2D	transform(Point2D ptSrc, Point2D ptDst) Transforms the specified ptSrc and stores the result in ptDst.

Methods inherited from class FormattableObject

getDefaultIndentation, print, setDefaultIndentation, toString, toWKT, toWKT, toWKT

Methods inherited from class Object

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

Methods inherited from interface MathTransform

toWKT

Constructor Detail

AbstractMathTransform

protected AbstractMathTransform()

Constructs a math transform.

Method Detail

getName

public String getName()

Returns a name for this math transform (never null). This convenience methods returns the name of the parameter descriptors if any, or the short class name otherwise.

Returns:

A name for this math transform (never null).

Since:

2.5

getSourceDimensions

public abstract int getSourceDimensions()

Gets the dimension of input points.

Specified by:

getSourceDimensions in interface MathTransform

getTargetDimensions

public abstract int getTargetDimensions()

Gets the dimension of output points.

Specified by:

getTargetDimensions in interface MathTransform

getParameterDescriptors

public ParameterDescriptorGroup getParameterDescriptors()

Returns the parameter descriptors for this math transform, or null if unknown. This method is similar to OperationMethod.getParameters(), except that typical MathTransform implementations return parameters in standard units (usually metres or decimal degrees).

Specified by:

getParameterDescriptors in interface Parameterized

Returns:

The parameter descriptors for this math transform, or null.

See Also:

OperationMethod.getParameters()

getParameterValues

public ParameterValueGroup getParameterValues()

Returns a copy of the parameter values for this math transform, or null if unknown. This method is similar to SingleOperation.getParameterValues(), except that typical MathTransform implementations return parameters in standard units (usually metres or decimal degrees).

Specified by:

getParameterValues in interface Parameterized

Returns:

A copy of the parameter values for this math transform, or null. Since this method returns a copy of the parameter values, any change to a value will have no effect on this math transform.

See Also:

SingleOperation.getParameterValues()

isIdentity

public boolean isIdentity()

Tests whether this transform does not move any points. The default implementation always returns false.

Specified by:

isIdentity in interface MathTransform

transform

public Point2D transform(Point2D ptSrc,
                         Point2D ptDst)
                  throws TransformException

Transforms the specified ptSrc and stores the result in ptDst. The default implementation invokes transform(double[],int,double[],int) using a temporary array of doubles.

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 should 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:

MismatchedDimensionException - If this transform doesn't map two-dimensional coordinate systems.

TransformException - If the point can't be transformed.

See Also:

MathTransform2D.transform(Point2D,Point2D)

transform

public DirectPosition transform(DirectPosition ptSrc,
                                DirectPosition ptDst)
                         throws TransformException

Transforms the specified ptSrc and stores the result in ptDst. The default implementation delegates to transform(double[],int,double[],int).

Specified by:

transform in interface MathTransform

Parameters:

ptSrc - the coordinate point to be transformed.

ptDst - the 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 can't be transformed.

transform

protected abstract void transform(double[] srcPts,
                                  int srcOff,
                                  double[] dstPts,
                                  int dstOff)
                           throws TransformException

Transforms a single coordinate point in an array. Invoking this method is conceptually equivalent to invoking the following:

transform(srcPts, srcOff, dstPts, dstOff, 1)

However this method is easier to implement for AbstractMathTransform subclasses. The default transform(double[],int,double[],int,int) method implementation will invoke this method in a loop, taking care of the iteration strategy depending on the argument value.

The source and destination may overlap. Consequently, implementors must read all source ordinate values before to start writing the transformed ordinates in the destination array.

Note: This method has protected access rather than public in the hope to encourage users to invoke the bulk methods with a number of points greater than 1, which is usually faster than invoking repeatidly this method. In addition this method may skip some verifications that are performed by the public methods. This is the case of Geotk implementation of map projections.

Parameters:

srcPts - The array containing the source point coordinates.

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

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

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

Throws:

TransformException - If the point can't be transformed.

Since:

3.00

transform

public 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₁ ...).

The default implementation invokes transform(double[],int,double[],int) in a loop, using an iteration strategy determined from the arguments for iterating over the points.

Specified by:

transform in interface MathTransform

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 can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.

transform

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

Transforms a list of coordinate point ordinal values. The default implementation delegates to transform(double[],int,double[],int,int) using a temporary array of doubles.

Specified by:

transform in interface MathTransform

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 can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.

transform

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

Transforms a list of coordinate point ordinal values. The default implementation delegates to transform(double[],int,double[],int,int) using a temporary array of doubles.

Specified by:

transform in interface MathTransform

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 can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.

Since:

2.5

transform

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

Transforms a list of coordinate point ordinal values. The default implementation delegates to transform(double[],int,double[],int,int) using a temporary array of doubles if necessary.

Specified by:

transform in interface MathTransform

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 can't be transformed. Some implementations will stop at the first failure, wile some other implementations will fill the untransformable points with NaN values, continue and throw the exception only at end. Implementations that fall in the later case should set the last completed transform to this.

Since:

2.5

createTransformedShape

public Shape createTransformedShape(Shape shape)
                             throws TransformException

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

Parameters:

shape - Shape to transform.

Returns:

Transformed shape, or shape if this transform is the identity transform.

Throws:

IllegalStateException - if this transform doesn't map 2D coordinate systems.

TransformException - if a transform failed.

See Also:

MathTransform2D.createTransformedShape(Shape)

derivative

public Matrix derivative(Point2D point)
                  throws TransformException

Gets the derivative of this transform at a point. The default implementation always throw an exception. Subclasses that implement the MathTransform2D interface should override this method. Other subclasses should override derivative(DirectPosition) instead.

Parameters:

point - The coordinate point where to evaluate the derivative.

Returns:

The derivative at the specified point as a 2×2 matrix.

Throws:

MismatchedDimensionException - if the input dimension is not 2.

TransformException - if the derivative can't be evaluated at the specified point.

See Also:

MathTransform2D.derivative(Point2D)

derivative

public Matrix derivative(DirectPosition point)
                  throws TransformException

Gets the derivative of this transform at a point. The default implementation ensures that point has a valid dimension. Next, if the input dimension is 2, then this method delegates the work to derivative(Point2D). Otherwise a TransformException is thrown.

Specified by:

derivative in interface MathTransform

Parameters:

point - The coordinate point where to evaluate the derivative.

Returns:

The derivative at the specified point (never null).

Throws:

NullPointerException - if the derivative dependents on coordinate and point is null.

MismatchedDimensionException - if point doesn't have the expected dimension.

TransformException - if the derivative can't be evaluated at the specified point.

inverse

public MathTransform inverse()
                      throws NoninvertibleTransformException

Returns the inverse transform of this object. The default implementation returns this if this transform is an identity transform, and throws a NoninvertibleTransformException otherwise. Subclasses should override this method.

Specified by:

inverse in interface MathTransform

Throws:

NoninvertibleTransformException

hashCode

public final int hashCode()

Returns a hash value for this transform. This method invokes computeHashCode() when first needed and caches the value for future invocations. Subclasses should override computeHashCode() instead than this method.

Overrides:

hashCode in class Object

Returns:

The hash code value. This value may change between different execution of the Geotk library.

computeHashCode

protected int computeHashCode()

Computes a hash value for this transform. This method is invoked by hashCode() when first needed.

Returns:

The hash code value. This value may change between different execution of the Geotk library.

Since:

3.18

equals

public final boolean equals(Object object)

Compares the specified object with this math transform for strict equality. This method is implemented as below (omitting assertions):

return equals(other, ComparisonMode.STRICT);

Specified by:

equals in interface LenientComparable

Overrides:

equals in class Object

Parameters:

object - The object to compare with this transform.

Returns:

true if the given object is a transform of the same class and using the same parameter values.

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compares the specified object with this math transform for equality. The default implementation returns true if the following conditions are meet:

• object is an instance of the same class than this. We require the same class because there is no interface for the various kinds of transform.
• The parameter descriptors are equal according the given comparison mode.

The parameter values are not compared because subclasses can typically compare those values more efficiently by accessing to their member fields.

Specified by:

equals in interface LenientComparable

Parameters:

object - The object to compare with this transform.

mode - The strictness level of the comparison. Default to STRICT.

Returns:

true if the given object is a transform of the same class and if, given identical source position, the transformed position would be the equals.

Since:

3.18

formatWKT

public String formatWKT(Formatter formatter)

Formats the inner part of a Well Known Text (WKT) element. The default implementation formats all parameter values returned by getParameterValues(). The parameter group name is used as the math transform name.

Specified by:

formatWKT in interface Formattable

Overrides:

formatWKT in class FormattableObject

Parameters:

formatter - The formatter to use.

Returns:

The WKT element name, which is "PARAM_MT" in the default implementation.

See Also:

FormattableObject.toWKT(), FormattableObject.toString()

ensureNonNull

protected static void ensureNonNull(String name,
                                    Object object)
                             throws InvalidParameterValueException

Makes sure that an argument is non-null. This is a convenience method for subclass constructors.

Parameters:

name - Argument name.

object - User argument.

Throws:

InvalidParameterValueException - if object is null.

rollLongitude

protected static double rollLongitude(double x,
                                      double bound)

Ensures that the specified longitude stay within the [-bound … bound] range. This method is typically invoked before to project geographic coordinates. It may add or subtract some amount of 2×bound from x.

The bound value is typically 180 if the longitude is express in degrees, or Math.PI it the longitude is express in radians. But it can also be some other value if the longitude has already been multiplied by a scale factor before this method is invoked.

Parameters:

x - The longitude.

bound - The absolute value of the minimal and maximal allowed value, or Double.POSITIVE_INFINITY if no rolling should be applied.

Returns:

The longitude between ±bound.