@UML(identifier="CT_MathTransformFactory", specification=OGC_01009) public interface MathTransformFactory extends Factory
MathTransformFactory
interface can be used directly
by applications that wish to transform other types of coordinates (e.g. color coordinates,
or image pixel coordinates).
A math transform is an object that actually does
the work of applying formulae to coordinate values. The math transform does
not know or care how the coordinates relate to positions in the real world.
This lack of semantics makes implementing MathTransformFactory
significantly easier than it would be otherwise.
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 meters into millimeters, or it could be converting kilometers into meters.
Because math transforms have low semantic value
(but high mathematical value), programmers who do not have much knowledge
of how GIS applications use coordinate systems, or how those coordinate
systems relate to the real world can implement MathTransformFactory
.
The low semantic content of math transforms also
means that they will be useful 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.
Since a math transform does not know what its source and target coordinate systems mean, it is not necessary or desirable for a math transform object to keep information on its source and target coordinate systems.
Modifier and Type  Method and Description 

MathTransform 
createAffineTransform(Matrix matrix)
Creates an affine transform from a matrix.

MathTransform 
createBaseToDerived(CoordinateReferenceSystem baseCRS,
ParameterValueGroup parameters,
CoordinateSystem derivedCS)
Creates a parameterized transform from a base CRS
to a derived CS.

MathTransform 
createConcatenatedTransform(MathTransform transform1,
MathTransform transform2)
Creates a transform by concatenating two existing transforms.

MathTransform 
createFromWKT(String wkt)
Creates a math transform object from a string.

MathTransform 
createFromXML(String xml)
Creates a math transform object from a XML string.

MathTransform 
createParameterizedTransform(ParameterValueGroup parameters)
Creates a transform from a group of parameters.

MathTransform 
createPassThroughTransform(int firstAffectedOrdinate,
MathTransform subTransform,
int numTrailingOrdinates)
Creates a transform which passes through a subset of ordinates to another transform.

Set<OperationMethod> 
getAvailableMethods(Class<? extends SingleOperation> type)
Returns a set of available methods for math transforms.

ParameterValueGroup 
getDefaultParameters(String method)
Returns the default parameter values for a math transform using the given method.

OperationMethod 
getLastMethodUsed()
Returns the operation method used for the latest call to
createParameterizedTransform ,
or null if not applicable. 
Set<OperationMethod> getAvailableMethods(Class<? extends SingleOperation> type)
getDefaultParameters(String)
method in this factory.
The set of available methods is implementation dependent.type
 SingleOperation.class
for fetching all operation methods,
or Projection.class
for fetching only map projection methods.getDefaultParameters(String)
,
createParameterizedTransform(ParameterValueGroup)
Departure from OGC/ISO specification:
This method is not part of the OGC specification. It has been added as a way to publish the capabilities of a factory.
OperationMethod getLastMethodUsed()
createParameterizedTransform
,
or null
if not applicable.
Implementors should document how their implementation behave in a multithreads environment.
For example some implementations use thread local variables,
while other can choose to returns null
in all cases since this method is optional.
Note that this method may apply as well to convenience methods that delegate their work to
createParameterizedTransform
, like createBaseToDerived
.
null
if unknown of unsupported.Departure from OGC/ISO specification:
This method is not part of the OGC specification. It has been added because this information appears to be needed in practice. A more objectoriented approach would have been to return a {MathTransform
,OperationMethod
} tuple in thecreateParameterizedTransform(&hellip)
method, but we wanted to keep the later unchanged for historical reasons (it is inherited from OGC 01009) and because only a minority of use cases need the operation method.Note that the existence of this method does not break threadsafety if the implementor stores this information in a
ThreadLocal
variable.
ParameterValueGroup getDefaultParameters(String method) throws NoSuchIdentifierException
method
argument is the name of any operation method returned by
getAvailableMethods
(CoordinateOperation.class)
.
A typical example is
"Transverse_Mercator"
).
The parameter group name shall be the
method name, or an alias to be understood by createParameterizedTransform(parameters)
. This method creates new parameter instances
at every call. Parameters are intended to be modified by the user before to be given to the
abovecited createParameterizedTransform
method.
method
 The case insensitive name of the method to search for.NoSuchIdentifierException
 if there is no transform registered for the specified method.getAvailableMethods(Class)
,
createParameterizedTransform(ParameterValueGroup)
Departure from OGC/ISO specification:
This method is part of the GeoAPI mechanism for defining the math transform parameters or deriving other transforms.
MathTransform createBaseToDerived(CoordinateReferenceSystem baseCRS, ParameterValueGroup parameters, CoordinateSystem derivedCS) throws NoSuchIdentifierException, FactoryException
In addition, implementations are encouraged to infer the "semi_major"
and
"semi_minor"
parameter values from the ellipsoid, if
they are not explicitly given.
baseCRS
 The source coordinate reference system.parameters
 The parameter values for the transform.derivedCS
 The target coordinate system.NoSuchIdentifierException
 if there is no transform registered for the method.FactoryException
 if the object creation failed. This exception is thrown
if some required parameter has not been supplied, or has illegal value.Departure from OGC/ISO specification:
This method is part of the GeoAPI mechanism for defining the math transform parameters or deriving other transforms.
@UML(identifier="createParameterizedTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createParameterizedTransform(ParameterValueGroup parameters) throws NoSuchIdentifierException, FactoryException
Note on cartographic projections:ParameterValueGroup p = factory.getDefaultParameters("Transverse_Mercator"); p.parameter("semi_major").setValue(6378137.000); p.parameter("semi_minor").setValue(6356752.314); MathTransform mt = factory.createParameterizedTransform(p);
Cartographic projection transforms are used by projected coordinate reference systems to map geographic coordinates (e.g. longitude and latitude) into (x,y) coordinates. These (x,y) coordinates can be imagined to lie on a plane, such as a paper map or a screen. All cartographic projection transforms created through this method will have the following properties:
Although all cartographic projection transforms must have the properties listed above, many projected coordinate reference systems have different properties. For example, in Europe some projected CRSs use grads instead of degrees, and often the base geographic CRS is (latitude, longitude) instead of (longitude, latitude). This means that the cartographic projected transform is often used as a single step in a series of transforms, where the other steps change units and swap ordinates.
parameters
 The parameter values.NoSuchIdentifierException
 if there is no transform registered for the method.FactoryException
 if the object creation failed. This exception is thrown
if some required parameter has not been supplied, or has illegal value.getDefaultParameters(String)
,
getAvailableMethods(Class)
@UML(identifier="createAffineTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createAffineTransform(Matrix matrix) throws FactoryException
M
, and output dimension
is N
, then the matrix will 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
ordinate of the moved origin. The [i][N]
element of the matrix
will be 0 for i less than M
, and 1 for i
equals M
.matrix
 The matrix used to define the affine transform.FactoryException
 if the object creation failed.@UML(identifier="createConcatenatedTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createConcatenatedTransform(MathTransform transform1, MathTransform transform2) throws FactoryException
transform1
 The first transform to apply to points.transform2
 The second transform to apply to points.FactoryException
 if the object creation failed.@UML(identifier="createPassThroughTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createPassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates) throws FactoryException
firstAffectedOrdinate
 The lowest index of the affected ordinates.subTransform
 Transform to use for affected ordinates.numTrailingOrdinates
 Number of trailing ordinates to pass through.
Affected ordinates will range from firstAffectedOrdinate
inclusive to dimTargetnumTrailingOrdinates
exclusive.Source: firstAffectedOrdinate + subTransform.getDimSource() + numTrailingOrdinates Target: firstAffectedOrdinate + subTransform.getDimTarget() + numTrailingOrdinates
FactoryException
 if the object creation failed.@UML(identifier="createFromXML", obligation=MANDATORY, specification=OGC_01009) MathTransform createFromXML(String xml) throws FactoryException
xml
 Math transform encoded in XML format.null
).FactoryException
 if the object creation failed.@UML(identifier="createFromWKT", obligation=MANDATORY, specification=OGC_01009) MathTransform createFromWKT(String wkt) throws FactoryException
wkt
 Math transform encoded in WellKnown Text format.null
).FactoryException
 if the WellKnown Text can't be parsed,
or if the math transform creation failed from some other reason.Copyright © 1994–2019 Open Geospatial Consortium. All rights reserved.