Module org.opengis.geoapi

Package org.opengis.referencing.operation

Interface CoordinateOperationFactory

All Superinterfaces:

Factory, ObjectFactory

@UML(identifier="CT_CoordinateTransformationFactory",
     specification=OGC_01009)
public interface CoordinateOperationFactory
extends ObjectFactory

Creates coordinate operations from parameter values, or infers operations from source and target CRS. This factory provides two groups of methods:

• Finding instances provided by the implementation:
  • getOperationMethod(String)
  • createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem)
  • createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, OperationMethod)
• Creating new instances from user supplied parameters:
  • createOperationMethod(Map, ParameterDescriptorGroup)
  • createDefiningConversion(Map, OperationMethod, ParameterValueGroup)
  • createConcatenatedOperation(Map, CoordinateOperation[])

Since:

1.0

Method Summary

Modifier and Type	Method	Description
CoordinateOperation	createConcatenatedOperation(Map<String,?> properties, CoordinateOperation... operations)	Creates a concatenated operation from a sequence of operations.
Conversion	createDefiningConversion(Map<String,?> properties, OperationMethod method, ParameterValueGroup parameters)	Creates a defining conversion from a set of properties.
CoordinateOperation	createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS)	Returns an operation for conversion or transformation between two coordinate reference systems.
CoordinateOperation	createOperation(CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, OperationMethod method)	Returns an operation using a particular method for conversion or transformation between two coordinate reference systems.
OperationMethod	createOperationMethod(Map<String,?> properties, ParameterDescriptorGroup parameters)	Creates an operation method from a set of properties and a descriptor group.
OperationMethod	getOperationMethod(String name)	Returns the build-in operation method of the given name.

Methods inherited from interface org.opengis.util.Factory

getVendor

Method Details

createOperation

@UML(identifier="createFromCoordinateSystems",
     specification=OGC_01009)
CoordinateOperation createOperation(CoordinateReferenceSystem sourceCRS,
 CoordinateReferenceSystem targetCRS)
                             throws FactoryException

Returns an operation for conversion or transformation between two coordinate reference systems.

• If an operation exists, it is returned.
• If more than one operation exists, the default is returned.
• If no operation exists, then the exception is thrown.

Implementations may try to query an authority factory first, and compute the operation next if no operation from source to target code was explicitly defined by the authority.

Parameters:

sourceCRS - input coordinate reference system.

targetCRS - output coordinate reference system.

Returns:

a coordinate operation from sourceCRS to targetCRS.

Throws:

OperationNotFoundException - if no operation path was found from sourceCRS to targetCRS.

FactoryException - if the operation creation failed for some other reason.

createOperation

CoordinateOperation createOperation(CoordinateReferenceSystem sourceCRS,
 CoordinateReferenceSystem targetCRS,
 OperationMethod method)
                             throws FactoryException

Returns an operation using a particular method for conversion or transformation between two coordinate reference systems.

• If the operation exists on the implementation, then it is returned.
• If the operation does not exist on the implementation, then the implementation has the option of inferring the operation from the argument objects.
• If for whatever reason the specified operation will not be returned, then the exception is thrown.

Example: A transformation between two geographic CRS using different datum requires a datum shift. Many methods exist for this purpose, including interpolations in a grid, a scale/rotation/translation in geocentric coordinates or the Molodenski approximation. When invoking createOperation(…) without operation method, this factory may select by default the transformation specified by the authority. When invoking createOperation(…) with an operation method, user can force usage of Molodenski approximation for instance.

Parameters:

sourceCRS - input coordinate reference system.

targetCRS - output coordinate reference system.

method - the algorithmic method for conversion or transformation.

Returns:

a coordinate operation from sourceCRS to targetCRS.

Throws:

OperationNotFoundException - if no operation path was found from sourceCRS to targetCRS.

FactoryException - if the operation creation failed for some other reason.

Extension to OGC/ISO standard

This method has been added at user request, in order to specify the desired transformation path when many are available.

createConcatenatedOperation

CoordinateOperation createConcatenatedOperation(Map<String,?> properties,
 CoordinateOperation... operations)
                                         throws FactoryException

Creates a concatenated operation from a sequence of operations. The source coordinate reference system of the first step and the target coordinate reference system of the last step are the source and target coordinate reference system associated with the concatenated operation.

Parameters:

properties - name and other properties to give to the new object. Available properties are listed there.

operations - the sequence of operations.

Returns:

the concatenated operation.

Throws:

FactoryException - if the object creation failed.

Extension to OGC/ISO standard

This method has been added because OGC 01-009 does not define a factory method for creating such object.

createDefiningConversion

Conversion createDefiningConversion(Map<String,?> properties,
 OperationMethod method,
 ParameterValueGroup parameters)
                             throws FactoryException

Creates a defining conversion from a set of properties. Defining conversions have no source and target CRS, and do not need to have a math transform. Their sole purpose is to be given as an argument to derived CRS and projected CRS constructors.

Some available properties are listed there.

Parameters:

properties - set of properties. Shall contain at least "name".

method - the operation method. A value can be obtained by getOperationMethod(String).

parameters - the parameter values. A default set of parameters can be obtained by method.getParameters().createValue() and modified before to be given to this constructor.

Returns:

the defining conversion.

Throws:

FactoryException - if the object creation failed.

See Also:

• CRSFactory.createProjectedCRS(Map, GeographicCRS, Conversion, CartesianCS)
• CRSFactory.createDerivedCRS(Map, CoordinateReferenceSystem, Conversion, CoordinateSystem)

Extension to OGC/ISO standard

The defining conversion concept appears in ISO 19111 specification without formalization in UML diagrams. This concept has been formalized in GeoAPI in order to allow the creation of ProjectedCRS instances.

createOperationMethod

OperationMethod createOperationMethod(Map<String,?> properties,
 ParameterDescriptorGroup parameters)
                               throws FactoryException

Creates an operation method from a set of properties and a descriptor group. This factory method allows the creation of arbitrary OperationMethod instances. Some available properties are listed there. Additionally, the following properties should be accepted by this constructor:

Keys for additional standard properties

Property name	Value type	Returned by
"formula"	Formula	OperationMethod.getFormula()

Note that implementations may have a build-in list of predefined operation methods. For obtaining a build-in instance, see getOperationMethod(String) instead.

Parameters:

properties - set of properties. Shall contain at least "name".

parameters - a description of the parameters for the operation method.

Returns:

the operation method.

Throws:

FactoryException - if the object creation failed.

Since:

3.1

Extension to OGC/ISO standard

This method has been added because OGC 01-009 does not define a factory method for creating such object.

getOperationMethod

OperationMethod getOperationMethod(String name)
                            throws FactoryException

Returns the build-in operation method of the given name. This is a helper method for usage of the following methods:

• createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem, OperationMethod)
• createDefiningConversion(Map, OperationMethod, ParameterValueGroup)

Examples of typical operation method names are:

Example of operation method names

OGC name	EPSG name
Mercator_1SP	Mercator (variant A)
Mercator_2SP	Mercator (variant B)
Transverse_Mercator	Transverse Mercator
Lambert_Conformal_Conic_1SP	Lambert Conic Conformal (1SP)
Lambert_Conformal_Conic_2SP	Lambert Conic Conformal (2SP)
Lambert_Azimuthal_Equal_Area	Lambert Azimuthal Equal Area
Albers_Conic_Equal_Area	Albers Equal Area
Cassini_Soldner	Cassini-Soldner
Orthographic	Orthographic

Implementations may delegate to their MathTransformFactory, or delegate to their CoordinateOperationAuthorityFactory, or get the operation method in some other way at implementer choice.

Parameters:

name - the name of the operation method to fetch.

Returns:

the operation method of the given name.

Throws:

NoSuchIdentifierException - if no operation method of the given name is known to this factory.

FactoryException - if the method failed for some other reason.

Since:

3.1

See Also:

• MathTransformFactory.getAvailableMethods(Class)
• CoordinateOperationAuthorityFactory.createOperationMethod(String)

Convenience extension to OGC/ISO standard

This method has been added in order to free the user from choosing whether he should get the operation method from CoordinateOperationAuthorityFactory, or from MathTransformFactory, or creating it himself.