Class 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)

    Defined in the sis-referencing module

    • Method Detail

      • 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 can not 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 can not 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 can not 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 can not 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 can not 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 can not 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 can not 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 can not be constructed.