Package org.apache.sis.referencing.operation.transform

## Class DefaultMathTransformFactory.Context

- Object
- - Context

- All Implemented Interfaces:
    `Serializable`
  Enclosing class:
    DefaultMathTransformFactory

      public static class DefaultMathTransformFactory.Context
      extends Object
      implements Serializable

  Source and target coordinate systems for which a new parameterized transform is going to be used. `DefaultMathTransformFactory` uses this information for:
  - Completing some parameters if they were not provided. In particular, the source ellipsoid can be used for providing values for the `"semi_major"` and `"semi_minor"` parameters in map projections.
  - Swapping and scaling axes if the source or the target coordinate systems are not normalized.
  By default this class does not handle change of prime meridian or anything else related to datum. Datum changes have dedicated `OperationMethod`, for example "Longitude rotation" (EPSG:9601) for changing the prime meridian.
  Since:
    0.7
  See Also:
    Serialized Form

  Defined in the `sis-referencing` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Context()` | Creates a new context with all properties initialized to `null`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ParameterValueGroup` | `getCompletedParameters()` | Returns the parameter values used for the math transform creation, including the parameters completed by the factory.
    `Matrix` | `getMatrix​(ContextualParameters.MatrixRole role)` | Returns the matrix that represent the affine transform to concatenate before or after the parameterized transform.
    `CoordinateSystem` | `getSourceCS()` | Returns the source coordinate system, or `null` if unspecified.
    `Ellipsoid` | `getSourceEllipsoid()` | Returns the ellipsoid of the source ellipsoidal coordinate system, or `null` if it does not apply.
    `CoordinateSystem` | `getTargetCS()` | Returns the target coordinate system, or `null` if unspecified.
    `Ellipsoid` | `getTargetEllipsoid()` | Returns the ellipsoid of the target ellipsoidal coordinate system, or `null` if it does not apply.
    `void` | `setSource​(CoordinateSystem cs)` | Sets the source coordinate system to the given value.
    `void` | `setSource​(EllipsoidalCS cs, Ellipsoid ellipsoid)` | Sets the source coordinate system and its associated ellipsoid to the given value.
    `void` | `setTarget​(CoordinateSystem cs)` | Sets the target coordinate system to the given value.
    `void` | `setTarget​(EllipsoidalCS cs, Ellipsoid ellipsoid)` | Sets the target coordinate system and its associated ellipsoid to the given value.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Context

          public Context()

      Creates a new context with all properties initialized to `null`.

  - ### Method Detail

    - #### setSource

          public void setSource​(CoordinateSystem cs)

      Sets the source coordinate system to the given value. The source ellipsoid is unconditionally set to `null`.
      Parameters:
        `cs` - the coordinate system to set as the source (can be `null`).

    - #### setSource

          public void setSource​(EllipsoidalCS cs,
                                Ellipsoid ellipsoid)

      Sets the source coordinate system and its associated ellipsoid to the given value.
      Design note: ellipsoidal coordinate systems and ellipsoids are associated indirectly, through a geodetic CRS. However this method expects those two components to be given explicitly instead than inferring them from a `CoordinateReferenceSystem` for making clear that `MathTransformFactory` does not perform any geodetic datum analysis. For coordinate operations that take datum changes in account (including change of prime meridian), see `DefaultCoordinateOperationFactory`. This policy helps to enforce a separation of concerns.
      Parameters:
        `cs` - the coordinate system to set as the source, or `null`.
        `ellipsoid` - the ellipsoid associated to the given coordinate system, or `null`.

    - #### setTarget

          public void setTarget​(CoordinateSystem cs)

      Sets the target coordinate system to the given value. The target ellipsoid is unconditionally set to `null`.
      Parameters:
        `cs` - the coordinate system to set as the target (can be `null`).

    - #### setTarget

          public void setTarget​(EllipsoidalCS cs,
                                Ellipsoid ellipsoid)

      Sets the target coordinate system and its associated ellipsoid to the given value.
      Design note: see `setSource(EllipsoidalCS, Ellipsoid)`.
      Parameters:
        `cs` - the coordinate system to set as the source, or `null`.
        `ellipsoid` - the ellipsoid associated to the given coordinate system, or `null`.

    - #### getSourceCS

          public CoordinateSystem getSourceCS()

      Returns the source coordinate system, or `null` if unspecified.
      Returns:
        the source coordinate system, or `null`.

    - #### getSourceEllipsoid

          public Ellipsoid getSourceEllipsoid()

      Returns the ellipsoid of the source ellipsoidal coordinate system, or `null` if it does not apply. This information is valid only if `getSourceCS()` returns an instance of `EllipsoidalCS`.
      Returns:
        the ellipsoid of the source ellipsoidal coordinate system, or `null` if it does not apply.

    - #### getTargetCS

          public CoordinateSystem getTargetCS()

      Returns the target coordinate system, or `null` if unspecified.
      Returns:
        the target coordinate system, or `null`.

    - #### getTargetEllipsoid

          public Ellipsoid getTargetEllipsoid()

      Returns the ellipsoid of the target ellipsoidal coordinate system, or `null` if it does not apply. This information is valid only if `getTargetCS()` returns an instance of `EllipsoidalCS`.
      Returns:
        the ellipsoid of the target ellipsoidal coordinate system, or `null` if it does not apply.

    - #### getMatrix

          public Matrix getMatrix​(ContextualParameters.MatrixRole role)
                           throws FactoryException

      Returns the matrix that represent the affine transform to concatenate before or after the parameterized transform. The `role` argument specifies which matrix is desired:
      - `NORMALIZATION` for the conversion from the source coordinate system to a normalized coordinate system, usually with (longitude, latitude) axis order in degrees or (easting, northing) in metres. This normalization needs to be applied before the parameterized transform.
      - `DENORMALIZATION` for the conversion from a normalized coordinate system to the target coordinate system, for example with (latitude, longitude) axis order. This denormalization needs to be applied after the parameterized transform.
      - `INVERSE_NORMALIZATION` and `INVERSE_DENORMALIZATION` are also supported but rarely used.
      This method is invoked by `DefaultMathTransformFactory​.swapAndScaleAxes(MathTransform, Context)`. Users an override this method if they need to customize the normalization process.
      Parameters:
        `role` - whether the normalization or denormalization matrix is desired.
      Returns:
        the requested matrix, or `null` if this `Context` has no information about the coordinate system.
      Throws:
        `FactoryException` - if an error occurred while computing the matrix.
      See Also:
        `DefaultMathTransformFactory​.createAffineTransform(Matrix)`, `DefaultMathTransformFactory​.createParameterizedTransform(ParameterValueGroup, Context)`

    - #### getCompletedParameters

          public ParameterValueGroup getCompletedParameters()

      Returns the parameter values used for the math transform creation, including the parameters completed by the factory.
      Returns:
        the parameter values used by the factory.
      Throws:
        `IllegalStateException` - if `DefaultMathTransformFactory​.createParameterizedTransform(ParameterValueGroup, Context)` has not yet been invoked.