Interface MathTransformFactory

 All Superinterfaces:
Factory
@UML(identifier="CT_MathTransformFactory", specification=OGC_01009) public interface MathTransformFactory extends Factory
Low level factory for creatingMathTransform
instances. Many high level GIS applications will never need to use this factory directly; they can use a coordinate operation factory instead. However, theMathTransformFactory
interface can be used directly by applications that wish to transform other types of coordinates (e.g. color coordinates, or image pixel coordinates).A
MathTransform
is an object that actually does the work of applyingFormula
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 implementingMathTransformFactory
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 metres into millimetres, or it could be converting kilometres into metres.
Because
MathTransform
s 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 implementMathTransformFactory
. The low semantic content ofMathTransform
s 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
MathTransform
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. Since:
 1.0
 See Also:
 Projection transform list on RemoteSensing.org


Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method 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 WellKnown Text.MathTransform
createFromXML(String xml)
Deprecated.This method was defined in OGC 01009 in anticipation for future normative specification, but no XML format for math transforms have been defined.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 coordinate operations of the given type.ParameterValueGroup
getDefaultParameters(String method)
Returns the default parameter values for a math transform using the given operation method.OperationMethod
getLastMethodUsed()
Returns the operation method used by the latest call to acreate(\u2026)
constructor, ornull
if not applicable.



Method Detail

getAvailableMethods
Set<OperationMethod> getAvailableMethods(Class<? extends SingleOperation> type)
Returns a set of available methods for coordinate operations of the given type. For each element in this set, the operation method name must be a valid argument forgetDefaultParameters(String)
.The
type
argument can be used for filtering the kind of operations described by the returnedOperationMethod
s. The argument is usually (but not restricted to) one of the following types:Transformation
for coordinate operations described by empirically derived parameters.Conversion
for coordinate operations described by definitions.Projection
for conversions from geodetic latitudes and longitudes to plane (map) coordinates.SingleOperation
for all coordinate operations, regardless of their type.
OperationMethod
elements than requested if thisMathTransformFactory
does not support filtering by the given type. Parameters:
type
SingleOperation.class
for fetching all operation methods,Projection.class
for fetching only map projection methods, etc. Returns:
 methods available in this factory for coordinate operations of the given type.
 See Also:
getDefaultParameters(String)
,createParameterizedTransform(ParameterValueGroup)
,CoordinateOperationFactory.getOperationMethod(String)
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.

getLastMethodUsed
OperationMethod getLastMethodUsed()
Returns the operation method used by the latest call to acreate(\u2026)
constructor, ornull
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 sincegetLastMethodUsed()
is optional.Invoking
getLastMethodUsed()
can be useful after a call tocreateParameterizedTransform(…)
, or after a call to another constructor that delegates its work tocreateParameterizedTransform(\u2026)
, for examplecreateBaseToDerived(…)
. Returns:
 the last method used by a
create(\u2026)
constructor, ornull
if unknown of unsupported.  Since:
 2.1
 See Also:
createParameterizedTransform(ParameterValueGroup)
Departure from OGC/ISO specification:
This method is not part of the OGC specification. It has been added because this information appears to be important in some situations. We did not defined a {MathTransform
,OperationMethod
} tuple in order to keepcreate(…)
simpler in the common case where the operation method is not needed, and for historical reasons (conformance to OGC 01009).

getDefaultParameters
ParameterValueGroup getDefaultParameters(String method) throws NoSuchIdentifierException
Returns the default parameter values for a math transform using the given operation method. Themethod
argument is the name of anyOperationMethod
instance returned by
. A typical example is "Transverse Mercator").getAvailableMethods
(SingleOperation.class)The parameter group name shall be a method name or identifier that
createParameterizedTransform(ParameterValueGroup)
can recognize without ambiguity.This function creates new parameter instances at every call. Parameters are intended to be modified by the user before to be given to the abovecited
createParameterizedTransform(\u2026)
constructor. Parameters:
method
 the case insensitive name of the coordinate operation method to search for. Returns:
 a new group of parameter values for the
OperationMethod
identified by the given name.  Throws:
NoSuchIdentifierException
 if there is no method registered for the given name or identifier. See Also:
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.

createBaseToDerived
MathTransform createBaseToDerived(CoordinateReferenceSystem baseCRS, ParameterValueGroup parameters, CoordinateSystem derivedCS) throws NoSuchIdentifierException, FactoryException
Creates a parameterized transform from a base CRS to a derived CS. This convenience constructor concatenates the parameterized transform with any other transform required for performing units changes and ordinates swapping, as described in the note on cartographic projections.In addition, implementations are encouraged to infer the
"semi_major"
and"semi_minor"
parameter values from the ellipsoid associated to thebaseCRS
, if those parameters are not explicitly given and if they are applicable (typically for cartographic projections). This inference is consistent with the EPSG database model. Parameters:
baseCRS
 the source coordinate reference system.parameters
 the parameter values for the transform.derivedCS
 the target coordinate system. Returns:
 the parameterized transform from
baseCRS
toderivedCS
, including unit conversions and axis swapping.  Throws:
NoSuchIdentifierException
 if there is no transform registered for the coordinate operation method.FactoryException
 if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value. Since:
 2.1
Departure from OGC/ISO specification:
This method is part of the GeoAPI mechanism for defining the math transform parameters or deriving other transforms.

createParameterizedTransform
@UML(identifier="createParameterizedTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createParameterizedTransform(ParameterValueGroup parameters) throws NoSuchIdentifierException, FactoryException
Creates a transform from a group of parameters. TheOperationMethod
name is inferred from the parameter group name. Example: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);
Note on cartographic projections: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 constructor will have the following properties: Converts from (longitude,latitude) coordinates to (x,y).
 All angles are assumed to be degrees, and all distances are assumed to be meters.
 The domain shall be a subset of {[180,180)×(90,90)}.
 Axis directions are usually (east, north), but exceptions may exist for some operation methods like "Lambert Conic Conformal (West Orientated)" (EPSG:9826) or "Transverse Mercator (South Orientated)" (EPSG:9808).
When the change of axis directions is part of the map projection definition as in "Transverse Mercator (South Orientated)", there is a conflict with the abovecited (east, north) directions. In such cases the
createParameterizedTransform(\u2026)
behavior is implementation specific, since different libraries may resolve this conflict in different ways. Users can invokecreateBaseToDerived(…)
instead for more determinist results. Parameters:
parameters
 the parameter values. Returns:
 the parameterized transform.
 Throws:
NoSuchIdentifierException
 if there is no transform registered for the coordinate operation method.FactoryException
 if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value. See Also:
getDefaultParameters(String)
,getAvailableMethods(Class)
,getLastMethodUsed()

createAffineTransform
@UML(identifier="createAffineTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createAffineTransform(Matrix matrix) throws FactoryException
Creates an affine transform from a matrix. If the transform's input dimension isM
, and output dimension isN
, 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 thanM
, and 1 for i equalsM
. Parameters:
matrix
 the matrix used to define the affine transform. Returns:
 the affine transform.
 Throws:
FactoryException
 if the object creation failed.

createConcatenatedTransform
@UML(identifier="createConcatenatedTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createConcatenatedTransform(MathTransform transform1, MathTransform transform2) throws FactoryException
Creates a transform by concatenating two existing transforms. A concatenated transform acts in the same way as applying two transforms, one after the other.The dimension of the output space of the first transform must match the dimension of the input space in the second transform. If you wish to concatenate more than two transforms, then you can repeatedly use this constructor.
 Parameters:
transform1
 the first transform to apply to points.transform2
 the second transform to apply to points. Returns:
 the concatenated transform.
 Throws:
FactoryException
 if the object creation failed.

createPassThroughTransform
@UML(identifier="createPassThroughTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createPassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates) throws FactoryException
Creates a transform which passes through a subset of ordinates to another transform. This allows transforms to operate on a subset of ordinates. For example giving (latitude, longitude, height) coordinates, a pass through transform can convert the height values from meters to feet without affecting the (latitude, longitude) values. Parameters:
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 fromfirstAffectedOrdinate
inclusive todimTargetnumTrailingOrdinates
exclusive. Returns:
 a pass through transform with the following dimensions:
Source: firstAffectedOrdinate + subTransform.getDimSource() + numTrailingOrdinates Target: firstAffectedOrdinate + subTransform.getDimTarget() + numTrailingOrdinates
 Throws:
FactoryException
 if the object creation failed.

createFromXML
@Deprecated @UML(identifier="createFromXML", obligation=MANDATORY, specification=OGC_01009) MathTransform createFromXML(String xml) throws FactoryException
Deprecated.This method was defined in OGC 01009 in anticipation for future normative specification, but no XML format for math transforms have been defined.Creates a math transform object from a XML string. Parameters:
xml
 math transform encoded in XML format. Returns:
 the math transform (never
null
).  Throws:
FactoryException
 if the object creation failed.

createFromWKT
@UML(identifier="createFromWKT", obligation=MANDATORY, specification=OGC_01009) MathTransform createFromWKT(String wkt) throws FactoryException
Creates a math transform object from a WellKnown Text. The definition for WKT is shown using Extended Backus Naur Form (EBNF). Parameters:
wkt
 math transform encoded in WellKnown Text format. Returns:
 the math transform (never
null
).  Throws:
FactoryException
 if the WellKnown Text can't be parsed, or if the math transform creation failed from some other reason. See Also:
MathTransform.toWKT()

