Interface MathTransformFactory
-
- All Superinterfaces:
Factory
- All Known Implementing Classes:
DefaultMathTransformFactory
public interface MathTransformFactory extends Factory
Low level factory for creating math transforms. 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 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.
- Since:
- GeoAPI 1.0
- Author:
- Martin Desruisseaux (IRD)
- See Also:
- Projection transform list on RemoteSensing.org
-
-
Method Summary
All Methods Instance Methods Abstract 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 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 Operation> 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 tocreateParameterizedTransform
, ornull
if not applicable.
-
-
-
Method Detail
-
getAvailableMethods
Set<OperationMethod> getAvailableMethods(Class<? extends Operation> type)
Returns a set of available methods for math transforms. For each element in this set, the operation method name must be known to thegetDefaultParameters(java.lang.String)
method in this factory. The set of available methods is implementation dependent.- Parameters:
type
-Operation.class
for fetching all operation methods, orProjection.class
for fetching only map projection methods.- Returns:
- All math transform methods available in this factory.
- See Also:
getDefaultParameters(java.lang.String)
,createParameterizedTransform(org.geotools.api.parameter.ParameterValueGroup)
-
getLastMethodUsed
OperationMethod getLastMethodUsed()
Returns the operation method used for the latest call tocreateParameterizedTransform
, ornull
if not applicable.Implementors should document how their implementation behave in a multi-threads 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
, likecreateBaseToDerived
.- Returns:
- The last method used, or
null
if unknown of unsupported. - Since:
- GeoAPI 2.1
-
getDefaultParameters
ParameterValueGroup getDefaultParameters(String method) throws NoSuchIdentifierException
Returns the default parameter values for a math transform using the given method. Themethod
argument is the name of any operation method returned bygetAvailableMethods
(Operation.class)"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 intented to be modified by the user before to be given to the above-citedcreateParameterizedTransform
method.- Parameters:
method
- The case insensitive name of the method to search for.- Returns:
- The default parameter values.
- Throws:
NoSuchIdentifierException
- if there is no transform registered for the specified method.- See Also:
getAvailableMethods(java.lang.Class<? extends org.geotools.api.referencing.operation.Operation>)
,createParameterizedTransform(org.geotools.api.parameter.ParameterValueGroup)
-
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 method 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, if they are not explicitly given.- Parameters:
baseCRS
- The source coordinate reference system.parameters
- The parameter values for the transform.derivedCS
- The target coordinate system.- Returns:
- The parameterized transform.
- Throws:
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.- Since:
- GeoAPI 2.1
-
createParameterizedTransform
@UML(identifier="createParameterizedTransform", obligation=MANDATORY, specification=OGC_01009) MathTransform createParameterizedTransform(ParameterValueGroup parameters) throws NoSuchIdentifierException, FactoryException
Creates a transform from a group of parameters. The method 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);
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:
- 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 should be a subset of {[-180,180)×(-90,90)}.
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:
parameters
- The parameter values.- Returns:
- The parameterized transform.
- Throws:
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.- See Also:
getDefaultParameters(java.lang.String)
,getAvailableMethods(java.lang.Class<? extends org.geotools.api.referencing.operation.Operation>)
-
createAffineTransform
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 method.
- 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 todimTarget-numTrailingOrdinates
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
MathTransform createFromXML(String xml) throws FactoryException
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
MathTransform createFromWKT(String wkt) throws FactoryException
Creates a math transform object from a string. The definition for WKT is shown using Extended Backus Naur Form (EBNF).- Parameters:
wkt
- Math transform encoded in Well-Known Text format.- Returns:
- The math transform (never
null
). - Throws:
FactoryException
- if the Well-Known Text can't be parsed, or if the math transform creation failed from some other reason.
-
-