org.geotoolkit.referencing.operation
Class AbstractCoordinateOperation

Object
  FormattableObject
      AbstractIdentifiedObject
          AbstractCoordinateOperation

All Implemented Interfaces:

Serializable, Formattable, LenientComparable, IdentifiedObject, CoordinateOperation

Direct Known Subclasses:

DefaultConcatenatedOperation, DefaultSingleOperation

@Immutable
public class AbstractCoordinateOperation
extends AbstractIdentifiedObject
implements CoordinateOperation

Establishes an association between a source and a target coordinate reference system, and provides a transform for transforming coordinates in the source CRS to coordinates in the target CRS. Many but not all coordinate operations (from CRS A to CRS B) also uniquely define the inverse operation (from CRS B to CRS A). In some cases, the operation method algorithm for the inverse operation is the same as for the forward algorithm, but the signs of some operation parameter values must be reversed. In other cases, different algorithms are required for the forward and inverse operations, but the same operation parameter values are used. If (some) entirely different parameter values are needed, a different coordinate operation shall be defined.

This class is conceptually abstract, even if it is technically possible to instantiate it. Typical applications should create instances of the most specific subclass with Default prefix instead. An exception to this rule may occurs when it is not possible to identify the exact type.

Since:

1.2

Version:

3.18

Author:

Martin Desruisseaux (IRD, Geomatys)

See Also:

Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Field Summary

protected Extent	domainOfValidity Area in which this operation is valid, or null if not available.
static PositionalAccuracy[]	EMPTY_ACCURACY_ARRAY An empty array of positional accuracy.
protected CoordinateReferenceSystem	sourceCRS The source CRS, or null if not available.
protected CoordinateReferenceSystem	targetCRS The target CRS, or null if not available.
protected MathTransform	transform Transform from positions in the source coordinate reference system to positions in the target coordinate reference system.

Fields inherited from class AbstractIdentifiedObject

EMPTY_ALIAS_ARRAY, EMPTY_IDENTIFIER_ARRAY, IDENTIFIER_COMPARATOR, NAME_COMPARATOR, REMARKS_COMPARATOR

Fields inherited from class FormattableObject

EPSG, GEOTIFF, INTERNAL, OGC, SINGLE_LINE

Fields inherited from interface CoordinateOperation

COORDINATE_OPERATION_ACCURACY_KEY, DOMAIN_OF_VALIDITY_KEY, OPERATION_VERSION_KEY, SCOPE_KEY

Fields inherited from interface IdentifiedObject

ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Constructor Summary

AbstractCoordinateOperation(Map<String,?> properties, CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, MathTransform transform)
Constructs a coordinate operation from a set of properties.

Method Summary

protected int	computeHashCode() Computes a hash value for this identified object.
boolean	equals(Object object, ComparisonMode mode) Compares this coordinate operation with the specified object for equality.
String	formatWKT(Formatter formatter) Formats this operation as a pseudo-WKT format.
double	getAccuracy() Convenience method returning the accuracy in meters.
static double	getAccuracy(CoordinateOperation operation) Convenience method returning the accuracy in meters for the specified operation.
Collection<PositionalAccuracy>	getCoordinateOperationAccuracy() Estimate(s) of the impact of this operation on point accuracy.
Extent	getDomainOfValidity() Area or region or timeframe in which this coordinate operation is valid.
MathTransform	getMathTransform() Gets the math transform.
String	getOperationVersion() Version of the coordinate transformation (i.e., instantiation due to the stochastic nature of the parameters).
InternationalString	getScope() Description of domain of usage, or limitations of usage, for which this operation is valid.
CoordinateReferenceSystem	getSourceCRS() Returns the source CRS.
CoordinateReferenceSystem	getTargetCRS() Returns the target CRS.
static Class<? extends CoordinateOperation>	getType(CoordinateOperation operation) Returns the most specific CoordinateOperation interface implemented by the specified operation.

Methods inherited from class AbstractIdentifiedObject

equals, equals, equals, equals, getAlias, getIdentifier, getIdentifier, getIdentifiers, getName, getName, getName, getProperties, getProperties, getRemarks, hashCode, nameMatches, nameMatches, nameMatches

Methods inherited from class FormattableObject

getDefaultIndentation, print, setDefaultIndentation, toString, toWKT, toWKT, toWKT

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface IdentifiedObject

getAlias, getIdentifiers, getName, getRemarks, toWKT

Field Detail

EMPTY_ACCURACY_ARRAY

public static final PositionalAccuracy[] EMPTY_ACCURACY_ARRAY

An empty array of positional accuracy. This is useful for fetching accuracies as an array, using the following idiom:

getCoordinateOperationAccuracy().toArray(EMPTY_ACCURACY_ARRAY);

See Also:

getCoordinateOperationAccuracy()

sourceCRS

protected final CoordinateReferenceSystem sourceCRS

The source CRS, or null if not available.

targetCRS

protected final CoordinateReferenceSystem targetCRS

The target CRS, or null if not available.

domainOfValidity

protected final Extent domainOfValidity

Area in which this operation is valid, or null if not available.

transform

protected final MathTransform transform

Transform from positions in the source coordinate reference system to positions in the target coordinate reference system.

Constructor Detail

AbstractCoordinateOperation

public AbstractCoordinateOperation(Map<String,?> properties,
                                   CoordinateReferenceSystem sourceCRS,
                                   CoordinateReferenceSystem targetCRS,
                                   MathTransform transform)

Constructs a coordinate operation from a set of properties. The properties given in argument follow the same rules than for the super-class constructor. Additionally, the following properties are understood by this construtor:

Property name	Value type	Value given to
"operationVersion"	String	getOperationVersion()
"coordinateOperationAccuracy"	PositionalAccuracy (singleton or array)	getCoordinateOperationAccuracy()
"domainOfValidity"	Extent	getDomainOfValidity()
"scope"	String or InternationalString	getScope()

Parameters:

properties - Set of properties. Should contains at least "name".

sourceCRS - The source CRS.

targetCRS - The target CRS.

transform - Transform from positions in the source CRS to positions in the target CRS.

Method Detail

getSourceCRS

public CoordinateReferenceSystem getSourceCRS()

Returns the source CRS.

Specified by:

getSourceCRS in interface CoordinateOperation

getTargetCRS

public CoordinateReferenceSystem getTargetCRS()

Returns the target CRS.

Specified by:

getTargetCRS in interface CoordinateOperation

getOperationVersion

public String getOperationVersion()

Version of the coordinate transformation (i.e., instantiation due to the stochastic nature of the parameters). Mandatory when describing a transformation, and should not be supplied for a conversion.

Specified by:

getOperationVersion in interface CoordinateOperation

Returns:

The coordinate operation version, or null in none.

getCoordinateOperationAccuracy

public Collection<PositionalAccuracy> getCoordinateOperationAccuracy()

Estimate(s) of the impact of this operation on point accuracy. Gives position error estimates for target coordinates of this coordinate operation, assuming no errors in source coordinates.

Specified by:

getCoordinateOperationAccuracy in interface CoordinateOperation

Returns:

The position error estimates, or an empty collection if not available.

Since:

2.4

See Also:

getAccuracy()

getAccuracy

public double getAccuracy()

Convenience method returning the accuracy in meters. The default implementation delegates to getAccuracy(this). Subclasses should override this method if they can provide a more accurate algorithm.

Returns:

The accuracy in meters, or NaN if unknown.

Since:

2.2

getAccuracy

public static double getAccuracy(CoordinateOperation operation)

Convenience method returning the accuracy in meters for the specified operation. This method try each of the following procedures and returns the first successful one:

• If a quantitative positional accuracy is found with a linear unit, then this accuracy estimate is converted to metres and returned.
• Otherwise, if the operation is a conversion, then returns 0 since a conversion is by definition accurates up to rounding errors.
• Otherwise, if the operation is a transformation, then checks if the datum shift were applied with the help of Bursa-Wolf parameters. This procedure looks for Geotk-specific DATUM_SHIFT_APPLIED and DATUM_SHIFT_OMITTED metadata. If a datum shift has been applied, returns 25 meters. If a datum shift should have been applied but has been omitted, returns 1000 meters. The 1000 meters value is higher than the highest value (999 meters) found in the EPSG database version 6.7. The 25 meters value is the next highest value found in the EPSG database for a significant number of transformations.
• Otherwise, if the operation is a concatenated one, returns the sum of the accuracy of all components. This is a conservative scenario where we assume that errors cumulate linearly. Note that this is not necessarily the "worst case" scenario since the accuracy could be worst if the math transforms are highly non-linear.

Parameters:

operation - The operation to inspect for accuracy.

Returns:

The accuracy estimate (always in meters), or NaN if unknown.

Since:

2.2

getDomainOfValidity

public Extent getDomainOfValidity()

Area or region or timeframe in which this coordinate operation is valid. Returns null if not available.

Specified by:

getDomainOfValidity in interface CoordinateOperation

Since:

2.4

getScope

public InternationalString getScope()

Description of domain of usage, or limitations of usage, for which this operation is valid.

Specified by:

getScope in interface CoordinateOperation

getMathTransform

public MathTransform getMathTransform()

Gets the math transform. The math transform will transform positions in the source coordinate reference system into positions in the target coordinate reference system.

Specified by:

getMathTransform in interface CoordinateOperation

getType

public static Class<? extends CoordinateOperation> getType(CoordinateOperation operation)

Returns the most specific CoordinateOperation interface implemented by the specified operation. Special cases:

• If the operation implements the Transformation interface, then this method returns Transformation.class. Transformation has precedence over any other interface implemented by the operation.
• Otherwise if the operation implements the Conversion interface, then this method returns the most specific Conversion sub-interface.
• Otherwise if the operation implements the SingleOperation interface, then this method returns SingleOperation.class.
• Otherwise if the operation implements the ConcatenatedOperation interface, then this method returns ConcatenatedOperation.class.
• Otherwise this method returns CoordinateOperation.class.

Parameters:

operation - A coordinate operation.

Returns:

The most specific GeoAPI interface implemented by the given operation.

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compares this coordinate operation with the specified object for equality. If the mode argument value is STRICT or BY_CONTRACT, then all available properties are compared including the domain of validity and the scope.

Specified by:

equals in interface LenientComparable

Overrides:

equals in class AbstractIdentifiedObject

Parameters:

object - The object to compare to this.

mode - STRICT for performing a strict comparison, or IGNORE_METADATA for comparing only properties relevant to transformations.

Returns:

true if both objects are equal.

computeHashCode

protected int computeHashCode()

Computes a hash value for this identified object. This method is invoked by AbstractIdentifiedObject.hashCode() when first needed.

Implementation specific feature
In the Geotk implementation, the name, identifiers and remarks are not used for hash code computation. Consequently two identified objects will return the same hash value if they are equal in the sense of equals(…, ComparisonMode.IGNORE_METADATA). This feature allows users to implement metadata-insensitive HashMap.

Overrides:

computeHashCode in class AbstractIdentifiedObject

Returns:

The hash code value. This value may change between different execution of the Geotk library.

formatWKT

public String formatWKT(Formatter formatter)

Formats this operation as a pseudo-WKT format. No WKT format were defined for coordinate operation at the time this method was written. This method may change in any future version until a standard format is found.

Specified by:

formatWKT in interface Formattable

Overrides:

formatWKT in class FormattableObject

Parameters:

formatter - The formatter to use.

Returns:

The WKT element name.

See Also:

FormattableObject.toWKT(), FormattableObject.toString()