Module org.apache.sis.referencing
Package org.apache.sis.referencing.operation

Class AbstractCoordinateOperation

Object
FormattableObject
AbstractIdentifiedObject
AbstractCoordinateOperation
All Implemented Interfaces:
Serializable, Formattable, Deprecable, Lenient­Comparable, Identified­Object, Coordinate­Operation
Direct Known Subclasses:
Default­Conversion, Default­Pass­Through­Operation, Default­Transformation
public class AbstractCoordinateOperation extends AbstractIdentifiedObject implements CoordinateOperation
Describes the operation for transforming coordinates in the source CRS to coordinates in the target CRS. Coordinate operations contain a math transform, which does the actual work of transforming coordinates, together with the following information:

Instantiation

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

Immutability and thread safety

This base class is immutable and thus thread-safe if the property values (not necessarily the map itself) given to the constructor are also immutable. Most SIS subclasses and related classes are immutable under similar conditions. This means that unless otherwise noted in the javadoc, Coordinate­Operation instances created using only SIS factories and static constants can be shared by many objects and passed between threads without synchronization.
Since:
0.6
See Also:

  • Constructor Details

  • Method Details

    • castOrCopy

      public static AbstractCoordinateOperation castOrCopy(CoordinateOperation object)
      Returns a SIS coordinate operation implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:
      • If the given object is null, then this method returns null.
      • Otherwise if the given object is an instance of Transformation, Conversion, Projection, Cylindrical­Projection, Conic­Projection, Planar­Projection, Pass­Through­Operation or Concatenated­Operation, then this method delegates to the cast­Or­Copy(…) method of the corresponding SIS subclass. Note that if the given object implements more than one of the above-cited interfaces, then the cast­Or­Copy(…) method to be used is unspecified.
      • Otherwise if the given object is already an instance of Abstract­Coordinate­Operation, then it is returned unchanged.
      • Otherwise a new Abstract­Coordinate­Operation instance is created using the copy constructor and returned. Note that this is a shallow copy operation, because the other properties contained in the given object are not recursively copied.
      Parameters:
      object - the object to get as a SIS implementation, or null if none.
      Returns:
      a SIS implementation containing the values of the given object (may be the given object itself), or null if the argument was null.

    • getInterface

      public Class<? extends CoordinateOperation> getInterface()
      Returns the GeoAPI interface implemented by this class. The default implementation returns Coordinate­Operation​.class. Subclasses implementing a more specific GeoAPI interface shall override this method.
      Overrides:
      get­Interface in class Abstract­Identified­Object
      Returns:
      the coordinate operation interface implemented by this class.

    • isDefiningConversion

      public boolean isDefiningConversion()
      Returns true if this coordinate operation is for the definition of a derived or projected CRS. The standard (ISO 19111) approach constructs defining conversion as an operation of type Conversion with null source and target CRS. But SIS supports also defining conversions with non-null CRS provided that: When this method returns true, the source and target CRS are not marshalled in XML documents.
      Returns:
      true if this coordinate operation is for the definition of a derived or projected CRS.

    • getSourceCRS

      public CoordinateReferenceSystem getSourceCRS()
      Returns the source CRS, or null if unspecified. The source CRS is mandatory for transformations only. This information is optional for conversions according the ISO 19111 standard, but Apache SIS tries to provide that CRS in most cases anyway.
      Specified by:
      get­Source­CRS in interface Coordinate­Operation
      Returns:
      the source CRS, or null if not available.

    • getTargetCRS

      public CoordinateReferenceSystem getTargetCRS()
      Returns the target CRS, or null if unspecified. The target CRS is mandatory for transformations only. This information is optional for conversions according the ISO 19111 standard, but Apache SIS tries to provide that CRS in most cases anyway.
      Specified by:
      get­Target­CRS in interface Coordinate­Operation
      Returns:
      the target CRS, or null if not available.

    • getInterpolationCRS

      public CoordinateReferenceSystem getInterpolationCRS()
      Returns the CRS which is neither the source CRS or target CRS but still required for performing the operation.

      Example

      Some transformations of vertical coordinates (h) require the horizontal coordinates (φ,λ) in order to interpolate in a grid. This method returns the CRS of the grid where such interpolations are performed.
      Returns:
      the CRS (neither source or target CRS) required for interpolating the values, or null if none.

    • getOperationVersion

      public String getOperationVersion()
      Returns the version of the coordinate operation. Different versions of a coordinate transformation may exist because of the stochastic nature of the parameters. In principle this property is irrelevant to coordinate conversions, but Apache SIS accepts it anyway.
      Specified by:
      get­Operation­Version in interface Coordinate­Operation
      Returns:
      the coordinate operation version, or null in none.

    • getCoordinateOperationAccuracy

      public Collection<PositionalAccuracy> getCoordinateOperationAccuracy()
      Returns an estimation of the impact of this operation on point accuracy. The positional accuracy gives position error estimates for target coordinates of this coordinate operation, assuming no errors in source coordinates.
      Specified by:
      get­Coordinate­Operation­Accuracy in interface Coordinate­Operation
      Returns:
      the position error estimations, or an empty collection if not available.
      See Also:

    • getLinearAccuracy

      public double getLinearAccuracy()
      Returns an estimation of positional accuracy in metres, or Na­N if unknown. The default implementation tries to infer a value from the metadata returned by get­Coordinate­Operation­Accuracy() using SIS-specific heuristics.

      Current implementation

      The current implementation uses the heuristic rules listed below. Note that those rules may change in any future SIS version.
      • If at least one quantitative result is found with a linear unit, then returns the largest result value converted to metres.
      • Otherwise if the operation is a conversion, then returns 0 since a conversion is by definition accurate 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. If a datum shift has been applied, returns 25 meters. If a datum shift should have been applied but has been omitted, returns 3000 meters.
        Note: the 3000 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 operation, returns the sum of the accuracy of all components. This is a conservative scenario where we assume that errors cumulate linearly.
        Note: this is not necessarily the "worst case" scenario since the accuracy could be worst if the math transforms are highly non-linear.
      Returns:
      the accuracy estimation (always in meters), or NaN if unknown.
      See Also:

    • getDomainOfValidity

      @Deprecated(since="1.4") public Extent getDomainOfValidity()
      Deprecated.
      Replaced by Abstract­Identified­Object​.get­Domains() as of ISO 19111:2019.
      Returns the area or region or timeframe in which this coordinate operation is valid.
      Specified by:
      get­Domain­Of­Validity in interface Coordinate­Operation
      Returns:
      the coordinate operation valid domain, or null if not available.

    • getScope

      @Deprecated(since="1.4") public InternationalString getScope()
      Deprecated.
      Replaced by Abstract­Identified­Object​.get­Domains() as of ISO 19111:2019.
      Returns a description of domain of usage, or limitations of usage, for which this operation is valid.
      Specified by:
      get­Scope in interface Coordinate­Operation
      Returns:
      a description of domain of usage, or null if none.

    • getMathTransform

      public MathTransform getMathTransform()
      Returns the object for transforming coordinates in the source CRS to coordinates in the target CRS. The transform may be null if this coordinate operation is a defining conversion.
      Specified by:
      get­Math­Transform in interface Coordinate­Operation
      Returns:
      the transform from source to target CRS, or null if not applicable.

    • getWrapAroundChanges

      public Set<Integer> getWrapAroundChanges()
      Returns the indices of target dimensions where "wrap around" may happen as a result of this coordinate operation. If such change exists, then this is usually the longitude axis when the source CRS uses the [-180 … +180]° range and the target CRS uses the [0 … 360]° range, or the converse. If there is no change, then this is an empty set.

      Inverse relationship

      sometimes the target dimensions returned by this method can be mapped directly to wraparound axes in source CRS, but this is not always the case. For example, consider the following operation chain:
      source projected CRS ⟶ base CRS ⟶ target geographic CRS
      In this example, a wraparound axis in the target CRS (the longitude) can be mapped to a wraparound axis in the base CRS. But there is no corresponding wraparound axis in the source CRS because the easting axis in projected CRS does not have a wraparound range meaning. We could argue that axis directions match, but such matching is not guaranteed to exist since Projected­CRS is a special case of General­Derived­CRS and derived CRS can have rotations.

      Default implementation

      The default implementation infers this set by inspecting the source and target coordinate system axes. It returns the indices of all target axes having Range­Meaning​.WRAPAROUND and for which the following condition holds: a colinear source axis exists with compatible unit of measurement, and the range (taking unit conversions in account) or range meaning of those source and target axes are not the same.
      Returns:
      indices of target dimensions where "wrap around" may happen as a result of this coordinate operation.
      Since:
      0.8

    • equals

      public boolean equals(Object object, ComparisonMode mode)
      Compares this coordinate operation with the specified object for equality. If the mode argument is Comparison­Mode​.STRICT or BY_CONTRACT, then all available properties are compared including the domain of validity and the scope.
      Specified by:
      equals in interface Lenient­Comparable
      Overrides:
      equals in class Abstract­Identified­Object
      Parameters:
      object - the object to compare to this.
      mode - STRICT for performing a strict comparison, or IGNORE_METADATA for ignoring properties that do not make a difference in the numerical results of coordinate operations.
      Returns:
      true if both objects are equal for the given comparison mode.
      See Also:

    • computeHashCode

      protected long computeHashCode()
      Invoked by hash­Code() for computing the hash code when first needed. See Abstract­Identified­Object​.compute­Hash­Code() for more information.
      Overrides:
      compute­Hash­Code in class Abstract­Identified­Object
      Returns:
      the hash code value. This value may change in any future Apache SIS version.

    • formatTo

      protected String formatTo(Formatter formatter)
      Formats this coordinate operation in Well Known Text (WKT) version 2 format.

      ESRI extension

      Coordinate operations cannot be formatted in standard WKT 1 format, but an ESRI variant of WKT 1 allows a subset of coordinate operations with the ESRI-specific GEOGTRAN keyword. To enabled this variant, WKTFormat can be configured as below: 
      format = new WKTFormat(null, null);
format.setConvention(Convention.WKT1_IGNORE_AXES);
format.setNameAuthority(Citations.ESRI);
      Overrides:
      format­To in class Abstract­Identified­Object
      Parameters:
      formatter - the formatter to use.
      Returns:
      "Coordinate­Operation".
      See Also: