# Interface MathTransformProvider.Context

Enclosing interface:
  `MathTransformProvider`

public static interface MathTransformProvider.Context
The parameter values that define the transform to create, together with its context. The context includes the desired number of source and target dimensions, and the factory to use if the provider needs to create math transform steps. The context intentionally (by design) excludes the following information:

- Details about coordinate systems (only their types is provided), because axis order and unit conversions are handled separately.
- Datum, because inferring datum shifts is the task of other classes, generally requiring a connection to a geodetic registry.

## Purpose of the dimension properties

If the operation method accepts different number of dimensions (for example, operations that can optionally use or compute an ellipsoidal height as the third dimension), then the provider can use the desired number of dimensions for selecting which variant (2D versus 3D) of the operation method to use.

## Purpose of the factory property

Some math transforms may actually be implemented as a chain of operation steps, for example a concatenation of affine transforms with other kinds of transforms. In such cases, providers can use the given factory for creating and concatenating the affine steps.

Since:
  1.5

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ParameterValueGroup`
  `getCompletedParameters()`
  Returns the parameter values that fully define the transform to create.
  `default Map<String,Boolean>`
  `getContextualParameters()`
  Returns the names of parameters that have been inferred from the context.
  `default MathTransformFactory`
  `getFactory()`
  The factory to use if the provider needs to create other math transforms as operation steps.
  `default Class<? extends CoordinateSystem>`
  `getSourceCSType()`
  Returns the type of the source coordinate system.
  `default OptionalInt`
  `getSourceDimensions()`
  Returns the desired number of source dimensions.
  `default Optional<Ellipsoid>`
  `getSourceEllipsoid()`
  Returns the ellipsoid which is used together with the source coordinate system.
  `default Class<? extends CoordinateSystem>`
  `getTargetCSType()`
  Returns the type of the target coordinate system.
  `default OptionalInt`
  `getTargetDimensions()`
  Returns the desired number of target dimensions.
  `default Optional<Ellipsoid>`
  `getTargetEllipsoid()`
  Returns the ellipsoid which is used together with the target coordinate system.

- ## Method Details

  - ### getFactory

    default MathTransformFactory getFactory()
    The factory to use if the provider needs to create other math transforms as operation steps. This is often the factory which is invoking the `MathTransformProvider​.createMathTransform(Context)` method, but not necessarily.

    The default implementation returns the `DefaultMathTransformFactory`.

    Returns:
      the factory to use if the provider needs to create other math transforms.

  - ### getSourceDimensions

    default OptionalInt getSourceDimensions()
    Returns the desired number of source dimensions. This value can be the determined from the source coordinate reference system, but not necessarily. It can also be the number of target dimensions of the previous step in a concatenated transform.

    The number of source dimensions may be unknown (absent). In such case, the default number of dimensions is method-specific. Some operation methods may search for a `ParameterValue` named `"dim"`. Other operation methods will fallback on a hard-coded number of dimensions, typically 2 or 3.

    Returns:
      desired number of source dimensions.
    See Also:
      - `MathTransform​.getSourceDimensions()`

  - ### getTargetDimensions

    default OptionalInt getTargetDimensions()
    Returns the desired number of target dimensions. This value can be the determined from the target coordinate reference system, but not necessarily. It can also be the number of source dimensions of the next step in a concatenated transform.

    The number of target dimensions may be unknown (absent). In such case, the default number of dimensions is method-specific. Some operation methods may search for a `ParameterValue` named `"dim"`. Other operation methods will fallback on a hard-coded number of dimensions, typically 2 or 3.

    Returns:
      desired number of target dimensions.
    See Also:
      - `MathTransform​.getTargetDimensions()`

  - ### getSourceCSType

    default Class<? extends CoordinateSystem> getSourceCSType()
    Returns the type of the source coordinate system. The returned value may be an interface or an implementation class. If the coordinate system type is unknown, then this method returns `CoordinateSystem​.class`.
    Returns:
      the type of the source coordinate system, or `CoordinateSystem​.class` if unknown.

  - ### getTargetCSType

    default Class<? extends CoordinateSystem> getTargetCSType()
    Returns the type of the target coordinate system. The returned value may be an interface or an implementation class. If the coordinate system type is unknown, then this method returns `CoordinateSystem​.class`.
    Returns:
      the type of the target coordinate system, or `CoordinateSystem​.class` if unknown.

  - ### getSourceEllipsoid

    default Optional<Ellipsoid> getSourceEllipsoid()
    Returns the ellipsoid which is used together with the source coordinate system.
    Returns:
      the ellipsoid which is used together with the source coordinate system, or empty if none.
    Since:
      1.6

  - ### getTargetEllipsoid

    default Optional<Ellipsoid> getTargetEllipsoid()
    Returns the ellipsoid which is used together with the target coordinate system.
    Returns:
      the ellipsoid which is used together with the target coordinate system, or empty if none.
    Since:
      1.6

  - ### getContextualParameters

    default Map<String,Boolean> getContextualParameters()
    Returns the names of parameters that have been inferred from the context. The set of keys can contain any of `"dim"`, `"semi_major"`, `"semi_minor"`, `"src_semi_major"`, `"src_semi_minor"`, `"tgt_semi_major"`, `"tgt_semi_minor"` and/or `"inverse_flattening"`, depending on the operation method used. The parameters named in that set are included in the parameters returned by `getCompletedParameters()`.

    #### Associated Boolean values

    The associated Boolean in the map tells whether the named parameter value is really contextual. The Boolean is `TRUE` if the value was inferred from the context, or was explicitly set by the user to the same value as what would have been inferred from the context. OTherwise (i.e., if there is a mismatch between inferred and user-defined value), the Boolean is `FALSE`, a warning should be logged by the implementation, and the user-supplied value should have precedence in the parameters returned by `getCompletedParameters()`.
    Returns:
      names of parameters inferred from context.

  - ### getCompletedParameters

    ParameterValueGroup getCompletedParameters()
    Returns the parameter values that fully define the transform to create. The parameters returned by this method shall include parameters that are usually inferred from the context (source and target CRS) rather that explicitly provided by the users. Examples of inferred parameters are `"dim"`, `"semi_major"`, `"semi_minor"`, `"src_semi_major"`, `"src_semi_minor"`, `"tgt_semi_major"`, `"tgt_semi_minor"` and/or `"inverse_flattening"`, depending on the operation method.

    An exception to above rule is the source and target number of dimensions, which can be specified either by the `"dim"` parameter or by the `getSourceDimensions()` and `getTargetDimensions()` methods. The reason for this departure is that the number of dimensions is often not a formal parameter of an operation method, but can nevertheless be used for inferring variants. For example the Geographic3D offsets (EPSG:9660) method does not have a "dimension" argument because, as its name implies, that operation method is intended for the three-dimensional case only. However, if the number of dimensions is nevertheless 2, the provider may be able to opportunistically redirect to the Geographic2D offsets (EPSG:9619) operation method, because those two methods are actually implemented by the same code (an affine transform) in Apache SIS.

    Returns:
      the parameter values that fully define the transform to create.