Module org.opengis.geoapi

Package org.opengis.referencing.operation

Interface CoordinateOperation

All Superinterfaces:

IdentifiedObject

All Known Subinterfaces:

ConcatenatedOperation, ConicProjection, Conversion, CylindricalProjection, PassThroughOperation, PlanarProjection, PointMotionOperation, Projection, SingleOperation, Transformation

@Classifier(ABSTRACT)
@UML(identifier="CoordinateOperation",
     specification=ISO_19111)
public interface CoordinateOperation
extends IdentifiedObject

A mathematical operation on coordinates that transforms or converts coordinates to another CRS or epoch. The source CRS and target CRS properties indicate the CRS from which coordinates are changed and the CRS to which coordinates are changed respectively. They are mandatory for all subtypes of coordinate operation except Conversion, but GeoAPI recommends to provide a value even in the latter case.

Inverse operation

Many but not all coordinate operations (from coordinate reference system A to coordinate reference system B) also uniquely define the inverse operation (from coordinate reference system B to coordinate reference system 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.

Since:

1.0

See Also:

• CoordinateOperationAuthorityFactory.createCoordinateOperation(String)
• CoordinateOperationAuthorityFactory.createFromCoordinateReferenceSystemCodes(String, String)
• CoordinateOperationFactory.createOperation(CoordinateReferenceSystem, CoordinateReferenceSystem)

Field Summary

Fields

Modifier and Type	Field	Description
static final String	COORDINATE_OPERATION_ACCURACY_KEY	Key for the "coordinateOperationAccuracy" property.
static final String	DOMAIN_OF_VALIDITY_KEY	Deprecated. Moved to ObjectDomain as of ISO 19111:2019.
static final String	OPERATION_VERSION_KEY	Key for the "operationVersion" property.
static final String	SCOPE_KEY	Deprecated. Moved to ObjectDomain as of ISO 19111:2019.

Fields inherited from interface org.opengis.referencing.IdentifiedObject

ALIAS_KEY, DOMAINS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Method Summary

Modifier and Type	Method	Description
default Collection<PositionalAccuracy>	getCoordinateOperationAccuracy()	Returns estimate(s) of the impact of this operation on point accuracy.
default Extent	getDomainOfValidity()	Deprecated. Replaced by IdentifiedObject.getDomains() as of ISO 19111:2019.
default Optional<CoordinateReferenceSystem>	getInterpolationCRS()	Returns the CRS to be used for interpolations in a grid.
MathTransform	getMathTransform()	Returns the mathematical operation which performs the actual work of changing coordinate values.
default String	getOperationVersion()	Returns the version of this coordinate transformation or point motion operation.
default InternationalString	getScope()	Deprecated. Replaced by IdentifiedObject.getDomains() as of ISO 19111:2019.
CoordinateReferenceSystem	getSourceCRS()	Returns the CRS from which coordinates are changed.
default Optional<Temporal>	getSourceEpoch()	Returns the date at which source coordinate tuples are valid.
CoordinateReferenceSystem	getTargetCRS()	Returns the CRS to which coordinates are changed.
default Optional<Temporal>	getTargetEpoch()	Returns the date at which target coordinate tuples are valid.
CoordinateSet	transform(CoordinateSet data)	Changes coordinates from being referenced to the source CRS and/or epoch to being referenced to the target CRS and/or epoch.

Methods inherited from interface org.opengis.referencing.IdentifiedObject

getAlias, getDomains, getIdentifiers, getName, getRemarks, toWKT

Field Details

OPERATION_VERSION_KEY

static final String OPERATION_VERSION_KEY

Key for the "operationVersion" property. This is used for setting the value to be returned by getOperationVersion().

See Also:

• getOperationVersion()
• Constant Field Values

COORDINATE_OPERATION_ACCURACY_KEY

static final String COORDINATE_OPERATION_ACCURACY_KEY

Key for the "coordinateOperationAccuracy" property. This is used for setting the value to be returned by getCoordinateOperationAccuracy().

See Also:

• getCoordinateOperationAccuracy()
• Constant Field Values

DOMAIN_OF_VALIDITY_KEY

@Deprecated(since="3.1")
static final String DOMAIN_OF_VALIDITY_KEY

Deprecated.

Moved to ObjectDomain as of ISO 19111:2019.

Key for the "domainOfValidity" property.

See Also:

• ObjectDomain.getDomainOfValidity()
• Constant Field Values

SCOPE_KEY

@Deprecated(since="3.1")
static final String SCOPE_KEY

Deprecated.

Moved to ObjectDomain as of ISO 19111:2019.

Key for the "scope" property.

See Also:

• ObjectDomain.getScope()
• Constant Field Values

Method Details

getSourceCRS

@UML(identifier="sourceCRS",
     obligation=CONDITIONAL,
     specification=ISO_19111)
CoordinateReferenceSystem getSourceCRS()

Returns the CRS from which coordinates are changed. This property may be null for defining conversions, but otherwise should be specified for other conversions and shall be specified for transformations and point motion operations.

Obligation

ISO 19111 defines this property as optional for Conversion because the source CRS can be specified by the DerivedCRS.getBaseCRS() property instead. However, GeoAPI recommends to provide a value even in the latter case.

Returns:

the CRS from which coordinates are changed, or null for a defining conversion.

See Also:

• getSourceEpoch()

getTargetCRS

@UML(identifier="targetCRS",
     obligation=CONDITIONAL,
     specification=ISO_19111)
CoordinateReferenceSystem getTargetCRS()

Returns the CRS to which coordinates are changed. This property may be null for defining conversions, but otherwise should be specified for other conversions and shall be specified for transformations and point motion operations.

Obligation

ISO 19111 defines this property as optional for Conversion because the target CRS can be specified by the DerivedCRS instance instead. However, GeoAPI recommends to provide a value even in the latter case.

Returns:

the CRS to which coordinates are changed, or null for a defining conversion.

See Also:

• getTargetEpoch()

getInterpolationCRS

@UML(identifier="interpolationCRS",
     obligation=OPTIONAL,
     specification=ISO_19111)
default Optional<CoordinateReferenceSystem> getInterpolationCRS()

Returns the CRS to be used for interpolations in a grid. Some single coordinate operations employ methods which include interpolation within a grid to derive the values of operation parameters. The CRS to be used for the interpolation may be different from either the source CRS or the target CRS.

Example

Vertical offsets between two vertical CRSs interpolated from a grid. The source and target CRSs will both be vertical CRSs, the interpolation CRS is a geographic CRS to which the grid is referenced.

Returns:

the CRS to be used for interpolations in a grid.

Since:

3.1

getSourceEpoch

@UML(identifier="sourceCoordinateEpoch",
     obligation=CONDITIONAL,
     specification=ISO_19111)
default Optional<Temporal> getSourceEpoch()

Returns the date at which source coordinate tuples are valid. This is mandatory if the CRS is dynamic.

Default implementation

The default implementation checks if the datum of the source CRS is a dynamic reference frame. If true, then the frame reference epoch is returned. If false, then an empty value is returned.

Returns:

epoch at which source coordinate tuples are valid.

Since:

3.1

See Also:

• getSourceCRS()
• DynamicReferenceFrame.getFrameReferenceEpoch()

getTargetEpoch

@UML(identifier="targetCoordinateEpoch",
     obligation=CONDITIONAL,
     specification=ISO_19111)
default Optional<Temporal> getTargetEpoch()

Returns the date at which target coordinate tuples are valid. This is mandatory if the CRS is dynamic.

Default implementation

The default implementation checks if the datum of the target CRS is a dynamic reference frame. If true, then the frame reference epoch is returned. If false, then an empty value is returned.

Returns:

epoch at which target coordinate tuples are valid.

Since:

3.1

See Also:

• getTargetCRS()
• DynamicReferenceFrame.getFrameReferenceEpoch()

getOperationVersion

@UML(identifier="operationVersion",
     obligation=CONDITIONAL,
     specification=ISO_19111)
default String getOperationVersion()

Returns the version of this coordinate transformation or point motion operation. The version is an identification of the instantiation due to the stochastic nature of the parameters. It is mandatory when describing a transformation or point motion operation, and should not be supplied for a conversion.

Returns:

version of the coordinate transformation or point motion, or null if none.

getCoordinateOperationAccuracy

@UML(identifier="coordinateOperationAccuracy",
     obligation=OPTIONAL,
     specification=ISO_19111)
default Collection<PositionalAccuracy> getCoordinateOperationAccuracy()

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

Returns:

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

getDomainOfValidity

@Deprecated(since="3.1")
@UML(identifier="domainOfValidity",
     obligation=OPTIONAL,
     specification=ISO_19111,
     version=2007)
default Extent getDomainOfValidity()

Deprecated.

Replaced by IdentifiedObject.getDomains() as of ISO 19111:2019.

Returns the area or region or timeframe in which this coordinate operation is valid.

Returns:

the coordinate operation valid domain, or null if not available.

See Also:

• ReferenceSystem.getDomainOfValidity()

getScope

@Deprecated(since="3.1")
@UML(identifier="scope",
     obligation=OPTIONAL,
     specification=ISO_19111,
     version=2007)
default InternationalString getScope()

Deprecated.

Replaced by IdentifiedObject.getDomains() as of ISO 19111:2019.

Returns a description of domain of usage, or limitations of usage, for which this operation is valid.

Returns:

a description of domain of usage, or null if none.

Departure from OGC/ISO standard for historical reason

This method has been kept conformant with the specification published in 2003. The revision published in 2007 replaced the singleton by a collection and changed the obligation from "optional" to "mandatory", requiring a return value of not known if the scope is unknown. This change is still under review.

getMathTransform

@UML(identifier="CT_CoordinateTransformation.getMathTransform",
     specification=OGC_01009)
MathTransform getMathTransform()

Returns the mathematical operation which performs the actual work of changing coordinate values. The math transform will transform positions in the source CRS into positions in the target CRS. It may be null in the case of defining conversions.

Returns:

the transform from source to target CRS, or null if not applicable.

transform

@UML(identifier="transform",
     specification=ISO_19111)
CoordinateSet transform(CoordinateSet data)
                 throws TransformException

Changes coordinates from being referenced to the source CRS and/or epoch to being referenced to the target CRS and/or epoch. The CRS and epoch (if any) of the given data should (see below) be equivalent to the source CRS and source epoch of this operation. The CRS and epoch (if any) of the returned data shall be equivalent to the target CRS and target epoch of this operation. The order of coordinate tuples shall be preserved.

This method operates on coordinate tuples and does not deal with interpolation of geometry types. When a coordinate set is subjected to a coordinate operation, its geometry might or might not be preserved.

Implementation flexibility

If the CRS and/or epoch of the given data are not equivalent to the source CRS and/or epoch of this coordinate operation, implementations can either throw an exception or automatically prepend an additional operation step.

Implementations are free to compute the coordinate changes immediately or to delay the computation. For example, the coordinate changes may be computed on-the-fly during CoordinateSet.stream() consumption. In the latter case, invalid coordinates may not cause a TransformException to be thrown when this method is invoked, but instead cause an unchecked exception to be thrown later, typically during the stream terminal operation.

Parameters:

data - the coordinates to change.

Returns:

the result of changing coordinates.

Throws:

TransformException - if some coordinates cannot be changed. Note that an absence of exception during this method call is not a guarantee that the coordinate changes succeeded, because implementations may have deferred the actual computation.

Since:

3.1