Module org.apache.sis.referencing

Package org.apache.sis.referencing.operation

Class CoordinateOperationFinder

Object

CoordinateOperationFinder

public class CoordinateOperationFinder
extends Object

Finds a conversion or transformation path from a source CRS to a target CRS. This class implements two strategies for searching the coordinate operation:

1. When create­Operation(source­CRS, target­CRS) is invoked, this class first tries to find the authority codes for the given source and target CRS. If such codes are found, they are submitted to a registry of coordinate operations. If an operation is found, it will be returned.
   Note: the above is known as the late-binding approach. The late-binding approach allows the authority to define better suited operations than what we would get if we were transforming everything from and to a pivot system (e.g. WGS84). In addition, this approach provides useful information like the coordinate operation scope and domain of validity, accuracy.
2. If the above authority factory does not know about the specified CRS, then this class tries to infer the coordinate operation by itself. The CRS type is examined and the work is dispatched to one or many of the create­Operation­Step(…) protected methods defined in this class. Those methods use properties associated to the CRS, including BOUNDCRS or TOWGS84 elements found in Well Known Text (WKT).
   Note: the use of elements like TOWGS84 is known as the early-binding approach. The operation found by this approach may be sub-optimal. The early-binding approach is used only as a fallback when the late-binding approach gave no result.

Customization

Instances of this class are created by Default­Coordinate­Operation­Factory. The only public method is create­Operation(Coordinate­Reference­System, Coordinate­Reference­System), which dispatches its work to the create­Operation­Step(…) protected methods. Developers can override those protected methods if they want to alter the way some operations are created.

Limitations

• Each instance of this class shall be used only once.
• This class is not thread-safe. A new instance shall be created for each coordinate operation to infer.

Since:

0.7

See Also:

• Default­Coordinate­Operation­Factory.create­Operation(Coordinate­Reference­System, Coordinate­Reference­System, Coordinate­Operation­Context)

Field Summary

Fields

Modifier and Type	Field	Description
protected Extent	area­Of­Interest	The spatiotemporal area of interest, or null if none.
protected double	desired­Accuracy	The desired accuracy in metres, or 0 for the best accuracy available.
protected final Coordinate­Operation­Factory	factory	The factory to use for creating coordinate operations not found in the registry.
protected final Coordinate­Operation­Authority­Factory	registry	The factory to use for creating operations as defined by authority, or null if none.

Constructor Summary

Constructors

Constructor	Description
Coordinate­Operation­Finder(Coordinate­Operation­Authority­Factory registry, Coordinate­Operation­Factory factory, Coordinate­Operation­Context context)	Creates a new instance for the given factory and context.

Method Summary

Modifier and Type	Method	Description
Coordinate­Operation	create­Operation(Coordinate­Reference­System source­CRS, Coordinate­Reference­System target­CRS)	Infers an operation for conversion or transformation between two coordinate reference systems.
List<Coordinate­Operation>	create­Operations(Coordinate­Reference­System source­CRS, Coordinate­Reference­System target­CRS)	Infers operations for conversions or transformations between two coordinate reference systems.
protected List<Coordinate­Operation>	create­Operation­Step(Coordinate­Reference­System source­CRS, List<? extends Single­CRS> source­Components, Coordinate­Reference­System target­CRS, List<? extends Single­CRS> target­Components)	Creates an operation between at least one Compound­CRS (usually the source) and an arbitrary CRS.
protected List<Coordinate­Operation>	create­Operation­Step(General­Derived­CRS source­CRS, General­Derived­CRS target­CRS)	Creates an operation between two derived coordinate reference systems.
protected List<Coordinate­Operation>	create­Operation­Step(General­Derived­CRS source­CRS, Single­CRS target­CRS)	Creates an operation from a derived CRS to an arbitrary single coordinate reference system.
protected List<Coordinate­Operation>	create­Operation­Step(Geodetic­CRS source­CRS, Geodetic­CRS target­CRS)	Creates an operation between two geodetic (geographic or geocentric) coordinate reference systems.
protected List<Coordinate­Operation>	create­Operation­Step(Geodetic­CRS source­CRS, Vertical­CRS target­CRS)	Creates an operation between a geodetic and a vertical coordinate reference systems.
protected List<Coordinate­Operation>	create­Operation­Step(Single­CRS source­CRS, General­Derived­CRS target­CRS)	Creates operations from an arbitrary single CRS to a derived coordinate reference system.
protected List<Coordinate­Operation>	create­Operation­Step(Temporal­CRS source­CRS, Temporal­CRS target­CRS)	Creates an operation between two temporal coordinate reference systems.
protected List<Coordinate­Operation>	create­Operation­Step(Vertical­CRS source­CRS, Vertical­CRS target­CRS)	Creates an operation between two vertical coordinate reference systems.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Field Details

registry

protected final CoordinateOperationAuthorityFactory registry

The factory to use for creating operations as defined by authority, or null if none. This is the factory used by the late-binding approach.

factory

protected final CoordinateOperationFactory factory

The factory to use for creating coordinate operations not found in the registry. This is the factory used by the early-binding approach.

areaOfInterest

protected Extent areaOfInterest

The spatiotemporal area of interest, or null if none. When a new Coordinate­Operation­Finder instance is created with a non-null Coordinate­Operation­Context, the context is used for initializing this value. After initialization, this field may be updated as Coordinate­Operation­Finder progresses in its search for a coordinate operation.

See Also:

• Coordinate­Operation­Context.get­Area­Of­Interest()

desiredAccuracy

protected double desiredAccuracy

The desired accuracy in metres, or 0 for the best accuracy available.

See Also:

• Coordinate­Operation­Context.get­Desired­Accuracy()

Constructor Details

CoordinateOperationFinder

public CoordinateOperationFinder(CoordinateOperationAuthorityFactory registry,
 CoordinateOperationFactory factory,
 CoordinateOperationContext context)
                          throws FactoryException

Creates a new instance for the given factory and context.

Parameters:

registry - the factory to use for creating operations as defined by authority, or null if none.

factory - the factory to use for creating operations not found in the registry.

context - the area of interest and desired accuracy, or null if none.

Throws:

Factory­Exception - if an error occurred while initializing this Coordinate­Operation­Finder.

See Also:

• Default­Coordinate­Operation­Factory.create­Operation­Finder(Coordinate­Operation­Authority­Factory, Coordinate­Operation­Context)

Method Details

createOperation

public CoordinateOperation createOperation(CoordinateReferenceSystem sourceCRS,
 CoordinateReferenceSystem targetCRS)
                                    throws OperationNotFoundException,
FactoryException

Infers an operation for conversion or transformation between two coordinate reference systems. If a non-null authority factory – the registry – has been specified at construction time, then this method will first query that factory (late-binding approach – see class javadoc). If no operation has been found in the registry or if no registry has been specified to the constructor, this method inspects the given CRS and delegates the work to one or many create­Operation­Step(…) methods (early-binding approach).

The default implementation invokes create­Operations(source­CRS, target­CRS), then returns the first operation in the returned list or throws an exception if the list is empty.

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Operation­Not­Found­Exception - if no operation path was found from source­CRS to target­CRS.

Factory­Exception - if the operation creation failed for some other reason.

createOperations

public List<CoordinateOperation> createOperations(CoordinateReferenceSystem sourceCRS,
 CoordinateReferenceSystem targetCRS)
                                           throws FactoryException

Infers operations for conversions or transformations between two coordinate reference systems. If a non-null authority factory – the registry – has been specified at construction time, then this method will first query that factory (late-binding approach – see class javadoc). If no operation has been found in the registry or if no registry has been specified to the constructor, this method inspects the given CRS and delegates the work to one or many create­Operation­Step(…) methods (early-binding approach).

At first, this method is invoked with the source­CRS and target­CRS arguments given to the Coordinate­Operation­Factory.create­Operation(…) method. But then, this method may be invoked recursively by some create­Operation­Step(…) methods with different source or target CRS, for example in order to process the base geographic CRS of a projected CRS.

Coordinate operations are returned in preference order: best operations for the area of interest should be first. The returned list is modifiable: callers can add, remove or set elements without impact on this Coordinate­Operation­Finder instance.

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

coordinate operations from source­CRS to target­CRS.

Throws:

Operation­Not­Found­Exception - if no operation path was found from source­CRS to target­CRS.

Factory­Exception - if the operation creation failed for some other reason.

Since:

1.0

createOperationStep

protected List<CoordinateOperation> createOperationStep(SingleCRS sourceCRS,
 GeneralDerivedCRS targetCRS)
                                                 throws FactoryException

Creates operations from an arbitrary single CRS to a derived coordinate reference system. Conversions from Geographic­CRS to Projected­CRS are also handled by this method, since projected CRS are a special kind of General­Derived­CRS.

The default implementation constructs the following operation chain:

source­CRS → base­CRS → target­CRS

where the conversion from base­CRS to target­CRS is obtained from target­CRS.get­Conversion­From­Base().

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

coordinate operations from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.

createOperationStep

protected List<CoordinateOperation> createOperationStep(GeneralDerivedCRS sourceCRS,
 SingleCRS targetCRS)
                                                 throws FactoryException

Creates an operation from a derived CRS to an arbitrary single coordinate reference system. Conversions from Projected­CRS to Geographic­CRS are also handled by this method, since projected CRS are a special kind of General­Derived­CRS.

The default implementation constructs the following operation chain:

source­CRS → base­CRS → target­CRS

where the conversion from source­CRS to base­CRS is obtained from the inverse of source­CRS.get­Conversion­From­Base().

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.

createOperationStep

protected List<CoordinateOperation> createOperationStep(GeneralDerivedCRS sourceCRS,
 GeneralDerivedCRS targetCRS)
                                                 throws FactoryException

Creates an operation between two derived coordinate reference systems. The default implementation performs three steps:

1. Convert from source­CRS to its base CRS.
2. Convert the source base CRS to target base CRS.
3. Convert from the target base CRS to the target­CRS.

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.

createOperationStep

protected List<CoordinateOperation> createOperationStep(GeodeticCRS sourceCRS,
 GeodeticCRS targetCRS)
                                                 throws FactoryException

Creates an operation between two geodetic (geographic or geocentric) coordinate reference systems. The default implementation can:

• adjust axis order and orientation, for example converting from (North, West) axes to (East, North) axes,
• apply units conversion if needed,
• perform longitude rotation if needed,
• perform datum shift if Bursa-Wolf parameters are available for the area of interest.

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.

createOperationStep

protected List<CoordinateOperation> createOperationStep(GeodeticCRS sourceCRS,
 VerticalCRS targetCRS)
                                                 throws FactoryException

Creates an operation between a geodetic and a vertical coordinate reference systems. The height returned by this method will usually be part of a pass-through operation.

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.

createOperationStep

protected List<CoordinateOperation> createOperationStep(VerticalCRS sourceCRS,
 VerticalCRS targetCRS)
                                                 throws FactoryException

Creates an operation between two vertical coordinate reference systems. The default implementation checks if both CRS use the same datum, then adjusts for axis direction and units.

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.

"TODO:"

Needs to implement vertical datum shift.

createOperationStep

protected List<CoordinateOperation> createOperationStep(TemporalCRS sourceCRS,
 TemporalCRS targetCRS)
                                                 throws FactoryException

Creates an operation between two temporal coordinate reference systems. The default implementation checks if both CRS use the same datum, then adjusts for axis direction, units and epoch.

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

target­CRS - output coordinate reference system.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.

createOperationStep

protected List<CoordinateOperation> createOperationStep(CoordinateReferenceSystem sourceCRS,
 List<? extends SingleCRS> sourceComponents,
 CoordinateReferenceSystem targetCRS,
 List<? extends SingleCRS> targetComponents)
                                                 throws FactoryException

Creates an operation between at least one Compound­CRS (usually the source) and an arbitrary CRS. The default implementation tries to invoke the create­Operation(…) method with various combinations of source and target components. A preference is given for components of the same type (e.g. source Geodetic­CRS with target Geodetic­CRS, etc.).

This method returns only one step for a chain of concatenated operations (to be built by the caller). But a list is returned because the same step may be implemented by different operation methods. Only one element in the returned list should be selected (usually the first one).

Parameters:

source­CRS - input coordinate reference system.

source­Components - components of the source CRS.

target­CRS - output coordinate reference system.

target­Components - components of the target CRS.

Returns:

a coordinate operation from source­CRS to target­CRS.

Throws:

Factory­Exception - if the operation cannot be constructed.