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

## Interface MathTransformProvider

- Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

      @FunctionalInterface
      public interface MathTransformProvider

  An object capable to create `MathTransform` instances from given parameter values. This interface is the Apache SIS mechanism by which formula are concretized as Java code.

  Implementations of this interface usually extend `DefaultOperationMethod`, but this is not mandatory. This interface can also be used alone since `MathTransform` instances can be created for other purpose than coordinate operations.

  This interface is generally not used directly. The recommended way to get a `MathTransform` is to find the coordinate operation (generally from a pair of source and target CRS), then to invoke `CoordinateOperation​.getMathTransform()`. Alternative, one can also use a math transform factory

  How to add custom coordinate operations to Apache SIS
  `DefaultMathTransformFactory` can discover automatically new coordinate operations (including map projections) by scanning the classpath. To define a custom coordinate operation, one needs to define a thread-safe class implementing both this `MathTransformProvider` interface and the `OperationMethod` one. While not mandatory, we suggest to extend `DefaultOperationMethod`. Example:

  >     public class MyProjectionProvider extends DefaultOperationMethod implements MathTransformProvider {
  >         public MyProjectionProvider() {
  >             super(Collections.singletonMap(NAME_KEY, "My projection"),
  >                     2, // Number of source dimensions
  >                     2, // Number of target dimensions
  >                     parameters);
  >         }

  >         @Override
  >         public MathTransform createMathTransform(MathTransformFactory factory, ParameterValueGroup parameters) {
  >             double semiMajor = values.parameter("semi_major").doubleValue(Units.METRE);
  >             double semiMinor = values.parameter("semi_minor").doubleValue(Units.METRE);
  >             // etc...
  >             return new MyProjection(semiMajor, semiMinor, ...);
  >         }
  >     }

  Then the fully-qualified class name of that implementation should be listed in a file reachable on the classpath with this exact name:

  >     META-INF/services/org.opengis.referencing.operation.OperationMethod

  Since:
    0.6
  See Also:
    `DefaultOperationMethod`, `DefaultMathTransformFactory`, `AbstractMathTransform`

  Defined in the `sis-referencing` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `MathTransform` | `createMathTransform​(MathTransformFactory factory, ParameterValueGroup parameters)` | Creates a math transform from the specified group of parameter values.

- - ### Method Detail

    - #### createMathTransform

          MathTransform createMathTransform​(MathTransformFactory factory,
                                            ParameterValueGroup parameters)
                                     throws InvalidParameterNameException,
                                            ParameterNotFoundException,
                                            InvalidParameterValueException,
                                            FactoryException

      Creates a math transform from the specified group of parameter values.
      Implementation example: The following example shows how parameter values can be extracted before to instantiate the transform:

      >     public MathTransform createMathTransform(MathTransformFactory factory, ParameterValueGroup parameters) {
      >         double semiMajor = values.parameter("semi_major").doubleValue(Units.METRE);
      >         double semiMinor = values.parameter("semi_minor").doubleValue(Units.METRE);
      >         // etc...
      >         return new MyProjection(semiMajor, semiMinor, ...);
      >     }

      Purpose of the factory argument
      Some math transforms may actually be implemented as a chain of operation steps, for example a concatenation of affine transforms with other kind of transforms. In such cases, implementations should use the given factory for creating the steps.
      Parameters:
        `factory` - the factory to use if this constructor needs to create other math transforms.
        `parameters` - the parameter values that define the transform to create.
      Returns:
        the math transform created from the given parameters.
      Throws:
        `InvalidParameterNameException` - if the given parameter group contains an unknown parameter.
        `ParameterNotFoundException` - if a required parameter was not found.
        `InvalidParameterValueException` - if a parameter has an invalid value.
        `FactoryException` - if the math transform can not be created for some other reason (for example a required file was not found).