Module org.opengis.geoapi

Package org.opengis.referencing.operation

Interface MathTransformFactory

All Superinterfaces:

Factory

@UML(identifier="CT_MathTransformFactory",
     specification=OGC_01009)
public interface MathTransformFactory
extends Factory

Low level factory for creating MathTransform instances. Many high level GIS applications will never need to use this factory directly; they can use a coordinate operation factory instead. However, the 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 MathTransform is an object that actually does the work of applying Formula 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 metres into millimetres, or it could be converting kilometres into metres.

Because MathTransforms 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 MathTransforms 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

Method Summary

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 Well-Known Text.
default MathTransform	createFromXML(String xml)	Deprecated. This method was defined in OGC 01-009 in anticipation for future normative specification, but no XML format for math transforms have been defined.
Matrix	createMatrix(int numRow, int numCol)	Creates a matrix of size numRow × numCol.
MathTransform	createParameterizedTransform(ParameterValueGroup parameters)	Creates a transform from a group of parameters.
MathTransform	createPassThroughTransform(int firstAffectedCoordinate, MathTransform subTransform, int numTrailingCoordinates)	Creates a transform which passes through a subset of coordinates 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 a create(…) constructor, or null if not applicable.

Methods inherited from interface org.opengis.util.Factory

getVendor

Method Details

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 for getDefaultParameters(String).

The type argument can be used for filtering the kind of operations described by the returned OperationMethods. The argument is usually (but not restricted to) one of the following types:

• Conversion for coordinate operations described by definitions (including map projections).
• Transformation for coordinate operations described by empirically derived parameters.
• PointMotionOperation for changes due to the motion of the point between two coordinate epochs.
• SingleOperation for all coordinate operations, regardless of their type.

The returned set may conservatively contain more OperationMethod elements than requested if this MathTransformFactory does not support filtering by the given type.

Parameters:

type - SingleOperation.class for fetching all operation methods, Transformation.class for fetching only transformation methods, etc.

Returns:

methods available in this factory for coordinate operations of the given type.

See Also:

• getDefaultParameters(String)
• createParameterizedTransform(ParameterValueGroup)
• CoordinateOperationFactory.getOperationMethod(String)

Extension to OGC/ISO standard

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 a create(…) constructor, or null if not applicable.

Implementers should document how their implementation behave in a multi-threads environment. For example, some implementations use thread local variables, while other can choose to return null in all cases since getLastMethodUsed() is optional.

Invoking getLastMethodUsed() can be useful after a call to createParameterizedTransform(…), or after a call to another constructor that delegates its work to createParameterizedTransform(…), for example createBaseToDerived(…).

Returns:

the last method used by a create(…) constructor, or null if unknown of unsupported.

See Also:

• createParameterizedTransform(ParameterValueGroup)

Extension to OGC/ISO standard

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 keep create(…) simpler in the common case where the operation method is not needed, and for historical reasons (conformance to OGC 01-009).

getDefaultParameters

ParameterValueGroup getDefaultParameters(String method)
                                  throws NoSuchIdentifierException

Returns the default parameter values for a math transform using the given operation method. The method argument is the name of any OperationMethod instance returned by getAvailableMethods(SingleOperation.class). A typical example is "Transverse Mercator".

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 above-cited createParameterizedTransform(…) 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)

Extension to OGC/ISO standard

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 coordinates 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 the baseCRS, 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 to derivedCS, including unit conversions and axis swapping.

Throws:

NoSuchIdentifierException - if there is no transform registered for the coordinate operation method.

FactoryException - if the transform creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.

Extension to OGC/ISO standard

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. The OperationMethod 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).

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

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 above-cited (east, north) directions. In such cases the createParameterizedTransform(…) behavior is implementation specific, since different libraries may resolve this conflict in different ways. Users can invoke createBaseToDerived(…) 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 transform 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 is 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 coordinate 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.

Parameters:

matrix - the matrix used to define the affine transform.

Returns:

the affine transform.

Throws:

FactoryException - if the transform creation failed.

createMatrix

Matrix createMatrix(int numRow,
 int numCol)
             throws FactoryException

Creates a matrix of size numRow × numCol. Elements on the diagonal (j == i) are set to 1.

Parameters:

numRow - number of rows.

numCol - number of columns.

Returns:

a new matrix of the given size.

Throws:

FactoryException - if the matrix creation failed.

Since:

3.1

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 transform creation failed.

createPassThroughTransform

@UML(identifier="createPassThroughTransform",
     obligation=MANDATORY,
     specification=OGC_01009)
MathTransform createPassThroughTransform(int firstAffectedCoordinate,
 MathTransform subTransform,
 int numTrailingCoordinates)
                                  throws FactoryException

Creates a transform which passes through a subset of coordinates to another transform. This allows transforms to operate on a subset of coordinates. 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:

firstAffectedCoordinate - the lowest index of the affected coordinates.

subTransform - transform to use for affected coordinates.

numTrailingCoordinates - number of trailing coordinates to pass through. Affected coordinates will range from firstAffectedCoordinate inclusive to dimTarget-numTrailingCoordinates exclusive.

Returns:

a pass through transform with the following dimensions:

 Source: firstAffectedCoordinate + subTransform.getDimSource() + numTrailingCoordinates
 Target: firstAffectedCoordinate + subTransform.getDimTarget() + numTrailingCoordinates

Throws:

FactoryException - if the transform creation failed.

createFromXML

@Deprecated
@UML(identifier="createFromXML",
     obligation=MANDATORY,
     specification=OGC_01009)
default MathTransform createFromXML(String xml)
                             throws FactoryException

Deprecated.

This method was defined in OGC 01-009 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 Well-Known Text. The WKT of math transforms is defined in OGC 01-009.

Parameters:

wkt - math transform encoded in Well-Known Text format.

Returns:

the math transform (never null).

Throws:

FactoryException - if the Well-Known Text cannot be parsed, or if the math transform creation failed from some other reason.

See Also:

• MathTransform.toWKT()