Class MathTransforms

public final class MathTransforms extends Static
Utility methods creating or working onMathTransform
instances. This class centralizes in one place some of the most commonly used functions this package. TheMathTransforms
class provides the following services: Create various SIS implementations of
MathTransform
.  Perform nonstandard operations on arbitrary instances.
MathTransformFactory
interface. However users seeking for more implementation neutrality are encouraged to limit themselves to the GeoAPI factory interfaces instead. Since:
 0.5
 See Also:
MathTransformFactory
Defined in the
sisreferencing
module  Create various SIS implementations of


Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static MathTransform
compound(MathTransform... components)
Puts together a list of independent math transforms, each of them operating on a subset of coordinate values.static MathTransform1D
concatenate(MathTransform1D tr1, MathTransform1D tr2)
Concatenates the given onedimensional transforms.static MathTransform1D
concatenate(MathTransform1D tr1, MathTransform1D tr2, MathTransform1D tr3)
Concatenates the three given onedimensional transforms.static MathTransform2D
concatenate(MathTransform2D tr1, MathTransform2D tr2)
Concatenates the given twodimensional transforms.static MathTransform2D
concatenate(MathTransform2D tr1, MathTransform2D tr2, MathTransform2D tr3)
Concatenates the three given twodimensional 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 Matrix
getMatrix(MathTransform transform, DirectPosition position)
Returns the coefficients of an affine transform in the vicinity of the given position.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 onedimensional affine transform for the given coefficients.static LinearTransform
linear(MathTransform transform, DirectPosition position)
Returns a linear (usually affine) transform which approximates the given transform in the vicinity of the given position.static LinearTransform
linear(Matrix matrix)
Creates an arbitrary linear transform from the specified matrix.static MathTransform
passThrough(int firstAffectedCoordinate, MathTransform subTransform, int numTrailingCoordinates)
Creates a transform which passes through a subset of coordinates to another transform.static LinearTransform
scale(double... factors)
Creates an affine transform which applies the given scale.static MathTransform
specialize(MathTransform global, Map<Envelope,MathTransform> specializations)
Creates a transform defined as one transform applied globally except in subareas where more accurate transforms are available.static LinearTransform
translation(double... vector)
Creates an affine transform which applies the given translation.static LinearTransform
uniformTranslation(int dimension, double offset)
Creates an affine transform which applies the same translation for all dimensions.



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 implementsMathTransform1D
.  If
dimension == 2
, then the returned transform implementsMathTransform2D
.
 Parameters:
dimension
 number of dimensions of the transform to be returned. Returns:
 an identity transform of the specified dimension.
 If

uniformTranslation
public static LinearTransform uniformTranslation(int dimension, double offset)
Creates an affine transform which applies the same translation for all dimensions. For each dimension, input values x are converted into output values y using the following equation:y = x +
offset
 Parameters:
dimension
 number of input and output dimensions.offset
 theoffset
term in the linear equation. Returns:
 an affine transform applying the specified translation.
 Since:
 1.0

translation
public static LinearTransform translation(double... vector)
Creates an affine transform which applies the given translation. The source and target dimensions of the transform are the length of the given vector. Parameters:
vector
 the translation vector. Returns:
 an affine transform applying the specified translation.
 Since:
 1.0

scale
public static LinearTransform scale(double... factors)
Creates an affine transform which applies the given scale. The source and target dimensions of the transform are the length of the given vector. Parameters:
factors
 the scale factors. Returns:
 an affine transform applying the specified scales.
 Since:
 1.0

linear
public static LinearTransform linear(double scale, double offset)
Creates a onedimensional 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
 thescale
term in the linear equation.offset
 theoffset
term in the linear equation. Returns:
 the linear transform for the given scale and offset.
 See Also:
Units.converter(Number, Number)

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. Nonaffine matrix will define a projective transform.If the transform input dimension is
M
, and output dimension isN
, 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 coordinate of the moved origin. Parameters:
matrix
 the matrix used to define the linear transform. Returns:
 the linear (usually affine) transform.
 See Also:
getMatrix(MathTransform)
,DefaultMathTransformFactory.createAffineTransform(Matrix)

linear
public static LinearTransform linear(MathTransform transform, DirectPosition position) throws TransformException
Returns a linear (usually affine) transform which approximates the given transform in the vicinity of the given position. If the given transform is already an instance ofLinearTransform
, then it is returned asis. Otherwise an approximation for the given position is created using the transform derivative at that position.Invariant: transforming the given
position
using the giventransform
produces the same result (ignoring rounding error) than transforming the sameposition
using the returned transform. This invariant holds only for that particular position; the transformation of any other positions may produce different results. Parameters:
transform
 the transform to approximate by an affine transform.position
 position in source CRS around which to get the an affine transform approximation. Returns:
 a transform approximating the given transform around the given position.
 Throws:
TransformException
 if an error occurred while transforming the given position or computing the derivative at that position. Since:
 1.0
 See Also:
getMatrix(MathTransform, DirectPosition)

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. Bothpreimage
(the x) andvalues
(the y) arguments can be null: If both
preimage
andvalues
arrays are nonnull, then they must have the same length.  If both
preimage
andvalues
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}.
preimage
elements shall be real numbers (not NaN) sorted in increasing or decreasing order. Elements in thevalues
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 theLinearTransform
interface) if the interval between eachpreimage
andvalues
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, ornull
.values
 the output values (y) in the function range, ornull
. Returns:
 the y=f(x) function.
 Since:
 0.7
 If both

specialize
public static MathTransform specialize(MathTransform global, Map<Envelope,MathTransform> specializations)
Creates a transform defined as one transform applied globally except in subareas where more accurate transforms are available. Such constructs appear in some datum shift files. The result of transforming a point by the returnedMathTransform
is as if iterating over all givenEnvelope
s in no particular order, find the smallest one containing the point to transform (envelope border considered inclusive), then use the associatedMathTransform
for transforming the point. If the point is not found in any envelope, then the global transform is applied.The following constraints apply:
 The global transform must be a reasonable approximation of the specialized transforms (this is required for calculating the inverse transform).
 All transforms in the
specializations
map must have the same number of source and target dimensions than theglobal
transform.  All envelopes in the
specializations
map must have the same number of dimensions than the global transform source dimensions.  In current implementation, each envelope must either be fully included in another envelope, or not overlap any other envelope.
 Parameters:
global
 the transform to use globally where there is no suitable specialization.specializations
 more accurate transforms available in some subareas. Returns:
 a transform applying the given global transform except in subareas where specializations are available.
 Throws:
IllegalArgumentException
 if a constraint is not met. Since:
 1.0

passThrough
public static MathTransform passThrough(int firstAffectedCoordinate, MathTransform subTransform, int numTrailingCoordinates)
Creates a transform which passes through a subset of coordinates to another transform. This method returns a transform having the following dimensions:
Affected coordinates will range fromSource: firstAffectedCoordinate + subTransform.getSourceDimensions() + numTrailingCoordinates Target: firstAffectedCoordinate + subTransform.getTargetDimensions() + numTrailingCoordinates
firstAffectedCoordinate
inclusive todimTarget  numTrailingCoordinates
exclusive. Parameters:
firstAffectedCoordinate
 index of the first affected coordinate.subTransform
 the subtransform to apply on modified coordinates.numTrailingCoordinates
 number of trailing coordinates to pass through. Returns:
 a passthrough transform, potentially as a
PassThroughTransform
instance but not necessarily.  Since:
 1.0

compound
public static MathTransform compound(MathTransform... components)
Puts together a list of independent math transforms, each of them operating on a subset of coordinate values. This method is often used for defining 4dimensional (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:
components
 the transforms to aggregate in a single transform, in the given order. Returns:
 the aggregation of all given transforms, or
null
if the givencomponents
array was empty.  Since:
 0.6
 See Also:
PassThroughTransform
,CRS.compound(CoordinateReferenceSystem...)
,Envelopes.compound(Envelope...)

concatenate
public static MathTransform concatenate(MathTransform tr1, MathTransform tr2) throws MismatchedDimensionException
Concatenates the two given transforms. The returned transform will implementMathTransform1D
orMathTransform2D
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:
MismatchedDimensionException
 if the output dimension of the first transform does not match the input dimension of the second transform. See Also:
DefaultMathTransformFactory.createConcatenatedTransform(MathTransform, MathTransform)

concatenate
public static MathTransform1D concatenate(MathTransform1D tr1, MathTransform1D tr2) throws MismatchedDimensionException
Concatenates the given onedimensional transforms. This is a convenience methods delegating toconcatenate(MathTransform, MathTransform)
and casting the result to aMathTransform1D
instance. Parameters:
tr1
 the first math transform.tr2
 the second math transform. Returns:
 the concatenated transform.
 Throws:
MismatchedDimensionException
 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 twodimensional transforms. This is a convenience methods delegating toconcatenate(MathTransform, MathTransform)
and casting the result to aMathTransform2D
instance. Parameters:
tr1
 the first math transform.tr2
 the second math transform. Returns:
 the concatenated transform.
 Throws:
MismatchedDimensionException
 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:
MismatchedDimensionException
 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 onedimensional transforms. This is a convenience methods delegating toconcatenate(MathTransform, MathTransform, MathTransform)
and casting the result to aMathTransform1D
instance. Parameters:
tr1
 the first math transform.tr2
 the second math transform.tr3
 the third math transform. Returns:
 the concatenated transform.
 Throws:
MismatchedDimensionException
 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 twodimensional transforms. This is a convenience methods delegating toconcatenate(MathTransform, MathTransform, MathTransform)
and casting the result to aMathTransform2D
instance. Parameters:
tr1
 the first math transform.tr2
 the second math transform.tr3
 the third math transform. Returns:
 the concatenated transform.
 Throws:
MismatchedDimensionException
 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
isnull
, returns an empty list.  Otherwise if
transform
is the result of a call to aconcatenate(…)
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, ornull
. Returns:
 all single math transforms performed by this concatenated transform.
 If

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
LinearTransform
, returnsLinearTransform.getMatrix()
.  Otherwise if the given transform is an instance of
AffineTransform
, returns its coefficients in aMatrix3
instance.  Otherwise returns
null
.
 Parameters:
transform
 the transform for which to get the matrix, ornull
. Returns:
 the matrix of the given transform, or
null
if none.  See Also:
linear(Matrix)
,LinearTransform.getMatrix()
 If the given transform is an instance of

getMatrix
public static Matrix getMatrix(MathTransform transform, DirectPosition position) throws TransformException
Returns the coefficients of an affine transform in the vicinity of the given position. If the given transform is linear, then this method produces a result identical togetMatrix(MathTransform)
. Otherwise the returned matrix can be used for building a linear transform which can be used as an approximation of the given transform for short distances around the given position. Parameters:
transform
 the transform to approximate by an affine transform.position
 position in source CRS around which to get the coefficients of an affine transform approximation. Returns:
 the matrix of the given transform around the given position.
 Throws:
TransformException
 if an error occurred while transforming the given position or computing the derivative at that position. Since:
 1.0
 See Also:
linear(MathTransform, DirectPosition)

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

