Class DefaultConversion

All Implemented Interfaces:
Serializable, Formattable, Parameterized, Deprecable, LenientComparable, org.opengis.referencing.IdentifiedObject, org.opengis.referencing.operation.Conversion, org.opengis.referencing.operation.CoordinateOperation, org.opengis.referencing.operation.SingleOperation
Direct Known Subclasses:
DefaultProjection

public class DefaultConversion extends AbstractSingleOperation implements org.opengis.referencing.operation.Conversion
A parameterized mathematical operation that converts coordinates to another CRS without any change of datum. The best-known example of a coordinate conversion is a map projection. The parameters describing coordinate conversions are defined rather than empirically derived.

This coordinate operation contains an operation method, usually with associated parameter values. In the SIS implementation, the parameter values can be either inferred from the math transform or explicitly provided at construction time in a defining conversion (see below).

Defining conversions

OperationMethod instances are generally created for a pair of existing source and target CRS. But Conversion instances without those information may exist temporarily while creating a derived or projected CRS. Those defining conversions have no source and target CRS since those elements are provided by the derived or projected CRS themselves. This class provides a constructor for such defining conversions.

After the source and target CRS become known, we can invoke the specialize(…) method for creating a math transform from the parameters, instantiate a new Conversion of a more specific type (ConicProjection, CylindricalProjection or PlanarProjection) if possible, and assign the source and target CRS to it.

Immutability and thread safety

This class is immutable and thus thread-safe if the property values (not necessarily the map itself) given to the constructor are also immutable. This means that unless otherwise noted in the javadoc, Conversion instances created using only SIS factories and static constants can be shared by many objects and passed between threads without synchronization.
Since:
0.6
Version:
1.3
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final long
    Serial number for inter-operability with different versions.

    Fields inherited from class org.apache.sis.referencing.operation.AbstractSingleOperation

    parameters

    Fields inherited from class org.apache.sis.referencing.operation.AbstractCoordinateOperation

    coordinateOperationAccuracy, domainOfValidity, sourceCRS, targetCRS, transform

    Fields inherited from class org.apache.sis.referencing.AbstractIdentifiedObject

    DEPRECATED_KEY, LOCALE_KEY

    Fields inherited from interface org.opengis.referencing.operation.CoordinateOperation

    COORDINATE_OPERATION_ACCURACY_KEY, DOMAIN_OF_VALIDITY_KEY, OPERATION_VERSION_KEY, SCOPE_KEY

    Fields inherited from interface org.opengis.referencing.IdentifiedObject

    ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Constructs a new object in which every attributes are set to a null value.
     
    DefaultConversion(Map<String,?> properties, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.crs.CoordinateReferenceSystem interpolationCRS, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform)
    Creates a coordinate conversion from the given properties.
     
    DefaultConversion(Map<String,?> properties, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform, org.opengis.parameter.ParameterValueGroup parameters)
    Creates a defining conversion from the given transform and/or parameters.
    protected
    DefaultConversion(org.opengis.referencing.operation.Conversion operation)
    Creates a new coordinate operation with the same values than the specified one.
    (package private)
    DefaultConversion(org.opengis.referencing.operation.Conversion definition, org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target, org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.operation.OperationMethod[] actual)
    Constructs a new conversion with the same values than the specified one, together with the specified source and target CRS.
  • Method Summary

    Modifier and Type
    Method
    Description
    castOrCopy(org.opengis.referencing.operation.Conversion object)
    Returns a SIS coordinate operation implementation with the values of the given arbitrary implementation.
    private static void
    ensureCompatibleDatum(String param, org.opengis.referencing.crs.CoordinateReferenceSystem expected, org.opengis.referencing.crs.CoordinateReferenceSystem actual)
    Ensures that the actual CRS uses a datum which is equal, ignoring metadata, to the datum of the expected CRS.
    Class<? extends org.opengis.referencing.operation.Conversion>
    Returns the GeoAPI interface implemented by this class.
    <T extends org.opengis.referencing.operation.Conversion>
    T
    specialize(Class<T> baseType, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.MathTransformFactory factory)
    Returns a specialization of this conversion with a more specific type, source and target CRS.
    private static org.opengis.referencing.operation.MathTransform
    swapAndScaleAxes(org.opengis.referencing.operation.MathTransform transform, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, int interpDim, boolean isSource, org.opengis.referencing.operation.MathTransformFactory factory)
    Concatenates to the given transform the operation needed for swapping and scaling the axes.

    Methods inherited from class org.apache.sis.referencing.operation.AbstractSingleOperation

    afterUnmarshal, equals, getMethod, getParameterDescriptors, getParameterValues, setParameterValues

    Methods inherited from class org.apache.sis.io.wkt.FormattableObject

    print, toString, toString, toWKT

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.opengis.referencing.operation.Conversion

    getOperationVersion, getSourceCRS, getTargetCRS

    Methods inherited from interface org.opengis.referencing.operation.CoordinateOperation

    getCoordinateOperationAccuracy, getDomainOfValidity, getMathTransform, getScope

    Methods inherited from interface org.opengis.referencing.IdentifiedObject

    getAlias, getIdentifiers, getName, getRemarks, toWKT

    Methods inherited from interface org.opengis.referencing.operation.SingleOperation

    getMethod, getParameterValues
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:
  • Constructor Details

    • DefaultConversion

      public DefaultConversion(Map<String,?> properties, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.crs.CoordinateReferenceSystem interpolationCRS, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform)
      Creates a coordinate conversion from the given properties. The properties given in argument follow the same rules than for the super-class constructor. The following table is a reminder of main (not all) properties:
      Recognized properties (non exhaustive list)
      Property name Value type Returned by
      "name" Identifier or String AbstractIdentifiedObject.getName()
      "identifiers" Identifier (optionally as array) AbstractIdentifiedObject.getIdentifiers()
      "domainOfValidity" Extent AbstractCoordinateOperation.getDomainOfValidity()

      Relationship between datum

      By definition, coordinate conversions do not change the datum. Consequently, the given sourceCRS and targetCRS should use the same datum. If the datum is not the same, then the coordinate operation should probably be a transformation instead. However, Apache SIS does not enforce that condition, but we encourage users to follow it. The reason why SIS is tolerant is because some gray areas may exist about whether an operation should be considered as a conversion or a transformation.
      Example: converting time instants from a temporal CRS using the January 1st, 1950 epoch to another temporal CRS using the January 1st, 1970 epoch is a datum change, since the epoch is part of temporal datum definition. However, such operation does not have all the accuracy issues of transformations between geodetic datum (empirically determined, over-determined systems, stochastic nature of the parameters). Consequently, some users may consider sufficient to represent temporal epoch changes as conversions instead than transformations.
      Note that while Apache SIS accepts to construct DefaultConversion instances with different source and target datum, it does not accept to use such instances for derived CRS construction.
      Parameters:
      properties - the properties to be given to the identified object.
      sourceCRS - the source CRS.
      targetCRS - the target CRS, which shall use a datum equals (ignoring metadata) to the source CRS datum.
      interpolationCRS - the CRS of additional coordinates needed for the operation, or null if none.
      method - the coordinate operation method (mandatory in all cases).
      transform - transform from positions in the source CRS to positions in the target CRS.
    • DefaultConversion

      public DefaultConversion(Map<String,?> properties, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform, org.opengis.parameter.ParameterValueGroup parameters)
      Creates a defining conversion from the given transform and/or parameters. This conversion has no source and target CRS since those elements are usually unknown at defining conversion construction time. The source and target CRS will become known later, at the Derived CRS or Projected CRS construction time.

      The properties map given in argument follows the same rules than for the above constructor.

      Transform and parameters arguments

      At least one of the transform or parameters argument must be non-null. If the caller supplies a transform argument, then it shall be a transform expecting normalized input coordinates and producing normalized output coordinates. See AxesConvention for more information about what Apache SIS means by "normalized".

      If the caller cannot yet supply a MathTransform, then (s)he shall supply the parameter values needed for creating that transform, with the possible omission of "semi_major" and "semi_minor" values. The semi-major and semi-minor parameter values will be set automatically when the specialize(…) method will be invoked.

      If both the transform and parameters arguments are non-null, then the latter should describe the parameters used for creating the transform. Those parameters will be stored for information purpose and can be given back by the AbstractSingleOperation.getParameterValues() method.

      Parameters:
      properties - the properties to be given to the identified object.
      method - the operation method.
      transform - transform from positions in the source CRS to positions in the target CRS, or null.
      parameters - the transform parameter values, or null.
      See Also:
    • DefaultConversion

      DefaultConversion(org.opengis.referencing.operation.Conversion definition, org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target, org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.operation.OperationMethod[] actual) throws org.opengis.util.FactoryException
      Constructs a new conversion with the same values than the specified one, together with the specified source and target CRS. While the source conversion can be an arbitrary one, it is typically a defining conversion.
      Parameters:
      definition - the defining conversion.
      source - the new source CRS.
      target - the new target CRS.
      factory - the factory to use for creating a transform from the parameters or for performing axis changes.
      actual - an array of length 1 where to store the actual operation method used by the math transform factory.
      Throws:
      org.opengis.util.FactoryException
    • DefaultConversion

      protected DefaultConversion(org.opengis.referencing.operation.Conversion operation)
      Creates a new coordinate operation with the same values than the specified one. This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.

      This constructor performs a shallow copy, i.e. the properties are not cloned.

      Parameters:
      operation - the coordinate operation to copy.
      See Also:
    • DefaultConversion

      private DefaultConversion()
      Constructs a new object in which every attributes are set to a null value. This is not a valid object. This constructor is strictly reserved to JAXB, which will assign values to the fields using reflection.
  • Method Details

    • castOrCopy

      public static DefaultConversion castOrCopy(org.opengis.referencing.operation.Conversion 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 Conversion, Projection, CylindricalProjection, ConicProjection or PlanarProjection, then this method delegates to the castOrCopy(…) method of the corresponding SIS subclass. Note that if the given object implements more than one of the above-cited interfaces, then the castOrCopy(…) method to be used is unspecified.
      • Otherwise if the given object is already an instance of DefaultConversion, then it is returned unchanged.
      • Otherwise a new DefaultConversion 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 org.opengis.referencing.operation.Conversion> getInterface()
      Returns the GeoAPI interface implemented by this class. The default implementation returns Conversion.class. Subclasses implementing a more specific GeoAPI interface shall override this method.
      Overrides:
      getInterface in class AbstractCoordinateOperation
      Returns:
      the conversion interface implemented by this class.
    • specialize

      public <T extends org.opengis.referencing.operation.Conversion> T specialize(Class<T> baseType, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.MathTransformFactory factory) throws org.opengis.util.FactoryException
      Returns a specialization of this conversion with a more specific type, source and target CRS. This specialize(…) method is typically invoked on defining conversion instances, when more information become available about the conversion to create.

      The given baseType argument can be one of the following values:

      • Conversion.class
      • Projection.class
      • CylindricalProjection.class
      • ConicProjection.class
      • PlanarProjection.class
      This specialize(…) method returns a conversion which implement at least the given baseType interface, but may also implement a more specific GeoAPI interface if specialize(…) has been able to infer the type from the operation method.
      Type Parameters:
      T - compile-time type of the baseType argument.
      Parameters:
      baseType - the base GeoAPI interface to be implemented by the conversion to return.
      sourceCRS - the source CRS.
      targetCRS - the target CRS.
      factory - the factory to use for creating a transform from the parameters or for performing axis changes, or null for the default factory.
      Returns:
      the conversion of the given type between the given CRS.
      Throws:
      ClassCastException - if a contradiction is found between the given baseType, the defining conversion type and the method operation type.
      MismatchedDatumException - if the given CRS do not use the same datum than the source and target CRS of this conversion.
      org.opengis.util.FactoryException - if the creation of a MathTransform from the parameter values, or a change of axis order or units failed.
      See Also:
    • ensureCompatibleDatum

      private static void ensureCompatibleDatum(String param, org.opengis.referencing.crs.CoordinateReferenceSystem expected, org.opengis.referencing.crs.CoordinateReferenceSystem actual)
      Ensures that the actual CRS uses a datum which is equal, ignoring metadata, to the datum of the expected CRS.
      Parameters:
      param - the parameter name, used only in case of error.
      expected - the CRS containing the expected datum, or null.
      actual - the CRS for which to check the datum, or null.
      Throws:
      MismatchedDatumException - if the two CRS use different datum.
    • swapAndScaleAxes

      private static org.opengis.referencing.operation.MathTransform swapAndScaleAxes(org.opengis.referencing.operation.MathTransform transform, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, int interpDim, boolean isSource, org.opengis.referencing.operation.MathTransformFactory factory) throws org.opengis.util.FactoryException
      Concatenates to the given transform the operation needed for swapping and scaling the axes. The two coordinate systems must implement the same GeoAPI coordinate system interface. For example if sourceCRS uses a CartesianCS, then targetCRS must use a CartesianCS too.
      Parameters:
      transform - the transform to which to concatenate axis changes.
      sourceCRS - the first CRS of the pair for which to check for axes changes.
      targetCRS - the second CRS of the pair for which to check for axes changes.
      interpDim - the number of dimensions of the interpolation CRS, or 0 if none.
      isSource - true for pre-concatenating the changes, or false for post-concatenating.
      factory - the factory to use for performing axis changes.
      Throws:
      org.opengis.util.FactoryException