Interface MathTransform

 All Known Subinterfaces:
LinearTransform
,MathTransform1D
,MathTransform2D
 All Known Implementing Classes:
AbstractMathTransform
,AbstractMathTransform.Inverse
,AffineTransform2D
,AlbersEqualArea
,AzimuthalEquidistant.Abstract
,AzimuthalEquidistant.Ellipsoidal
,AzimuthalEquidistant.Spherical
,CassiniSoldner
,ConcatenatedTransform
,CylindricalEqualArea
,EarthGravitationalModel
,EckertIV
,EqualArea
,EquatorialOrthographic
,EquatorialStereographic
,EquidistantConic
,EquidistantCylindrical
,ExponentialTransform1D
,GeneralOblique
,GeocentricTransform
,GeocentricTranslation
,GeostationarySatellite
,GeostationarySatellite.Ellipsoidal
,GeostationarySatellite.Spherical
,Gnomonic
,Homolosine
,HotineObliqueMercator
,IdentityTransform
,Krovak
,LambertAzimuthalEqualArea
,LambertConformal
,LambertConformal1SP
,LambertConformal2SP
,LambertConformalBelgium
,LinearTransform1D
,LogarithmicTransform1D
,MapProjection
,MathTransformProvider.Delegate
,MathTransformProxy
,Mercator
,Mercator1SP
,Mercator2SP
,MeteosatSG
,Mollweide
,MolodenskiTransform
,NADCONTransform
,NewZealandMapGrid
,NTv2Transform
,ObliqueMercator
,ObliqueOrthographic
,ObliqueStereographic
,Orthographic
,PassThroughTransform
,PlateCarree
,PolarOrthographic
,PolarStereographic
,Polyconic.Abstract
,Polyconic.Ellipsoidal
,Polyconic.Spherical
,ProjectiveTransform
,Robinson
,RotatedPole
,Sinusoidal
,Stereographic
,TransverseMercator
,VerticalTransform
,WarpTransform2D
,WinkelTripel
,WorldVanDerGrintenI
@UML(identifier="CT_MathTransform", specification=OGC_01009) public interface MathTransform
Transforms multidimensional coordinate points. 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:
 GeoAPI 1.0
 Author:
 Martin Desruisseaux (IRD)
 See Also:
AffineTransform
,PerspectiveTransform
,javax.media.j3d.Transform3D
,MathTransformFactory
,CoordinateOperation.getMathTransform()


Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Matrix
derivative(DirectPosition point)
Gets the derivative of this transform at a point.int
getSourceDimensions()
Gets the dimension of input points.int
getTargetDimensions()
Gets the dimension 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 specifiedptSrc
and stores the result inptDst
.



Method Detail

getSourceDimensions
@UML(identifier="getDimSource", specification=OGC_01009) int getSourceDimensions()
Gets the dimension of input points. Returns:
 The dimension of input points.

getTargetDimensions
@UML(identifier="getDimTarget", specification=OGC_01009) int getTargetDimensions()
Gets the dimension of output points. Returns:
 The dimension of output points.

transform
@UML(identifier="transform", specification=OGC_01009) DirectPosition transform(DirectPosition ptSrc, DirectPosition ptDst) throws MismatchedDimensionException, TransformException
Transforms the specifiedptSrc
and stores the result inptDst
. IfptDst
isnull
, a newDirectPosition
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. IfptSrc
andptDst
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 transformingptSrc
, ornull
. Returns:
 the coordinate point after transforming
ptSrc
and storing the result inptDst
, or a newly created point ifptDst
was null.  Throws:
MismatchedDimensionException
 ifptSrc
orptDst
doesn't have the expected dimension.TransformException
 if the point can't 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_{0},y_{0},z_{0}, x_{1},y_{1},z_{1} ...).
 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 thansrcPts
.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 tothis
.

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_{0},y_{0},z_{0}, x_{1},y_{1},z_{1} ...).
 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 thansrcPts
.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 tothis
.

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_{0},y_{0},z_{0}, x_{1},y_{1},z_{1} ...).
 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 tothis
. Since:
 GeoAPI 2.2

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_{0},y_{0},z_{0}, x_{1},y_{1},z_{1} ...).
 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 tothis
. Since:
 GeoAPI 2.2

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 nontranslating 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 sizeN×M
. The elements of the matrix{e_{n,m} : n=0..(N1)}
form a vector in the output space which is parallel to the displacement caused by a small change in the m'th ordinate in the input space.For example, if the input dimension is 4 and the output dimension is 3, then a small displacement
(x_{0}, x_{1}, x_{2}, x_{3})
in the input space will result in a displacement(y_{0}, y_{1}, y_{2})
in the output space computed as below (e_{n,m}
are the matrix's elements):[ y_{0} ] [ e_{00} e_{01} e_{02} e_{03} ] [ x_{0} ] [ y_{1} ] = [ e_{10} e_{11} e_{12} e_{13} ] [ x_{1} ] [ y_{2} ] [ e_{20} e_{21} e_{22} e_{23} ] [ x_{2} ] _{ } _{ } _{ } _{ } _{ } [ x_{3} ]
 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 nonnull 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 dependents on coordinate andpoint
isnull
.MismatchedDimensionException
 ifpoint
doesn't have the expected dimension.TransformException
 if the derivative can't 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 can't be inversed.

isIdentity
@UML(identifier="isIdentity", specification=OGC_01009) boolean isIdentity()
Tests whether this transform does not move any points. Returns:
true
if thisMathTransform
is an identity transform;false
otherwise.

toWKT
@UML(identifier="getWKT", specification=OGC_01009) String toWKT() throws UnsupportedOperationException
Returns a Well Known Text (WKT) for this object. Well know text are defined in extended Backus Naur form. This operation may fails if an object is too complex for the WKT format capability. Returns:
 The Well Known Text (WKT) for this object.
 Throws:
UnsupportedOperationException
 If this object can't be formatted as WKT.

