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

Class DefaultConversion

Object
FormattableObject
AbstractIdentifiedObject
AbstractCoordinateOperation
DefaultConversion
All Implemented Interfaces:
Serializable, Formattable, Parameterized, Deprecable, Lenient­Comparable, Identified­Object, Conversion, Coordinate­Operation, Single­Operation
public class DefaultConversion extends AbstractCoordinateOperation implements 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

Operation­Method 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 (Conic­Projection, Cylindrical­Projection or Planar­Projection) 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
See Also:

  • Constructor Details

    • DefaultConversion

      public DefaultConversion(Map<String,?> properties, CoordinateReferenceSystem sourceCRS, CoordinateReferenceSystem targetCRS, CoordinateReferenceSystem interpolationCRS, OperationMethod method, 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 source­CRS and target­CRS 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.

      Note that while Apache SIS accepts to construct Default­Conversion instances with different source and target datum, it does not accept to use such instances for derived CRS construction.

      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.
      Parameters:
      properties - the properties to be given to the identified object.
      source­CRS - the source CRS.
      target­CRS - the target CRS, which shall use a datum equals (ignoring metadata) to the source CRS datum.
      interpolation­CRS - 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, OperationMethod method, MathTransform transform, 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 Axes­Convention for more information about what Apache SIS means by "normalized".

      If the caller cannot yet supply a Math­Transform, 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 Single­Operation​.get­Parameter­Values() 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

      protected DefaultConversion(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:

  • Method Details