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

  Modifier and Type
  Method
  Description
  `MathTransform`
  `createMathTransform(MathTransformFactory factory, ParameterValueGroup parameters)`
  Creates a math transform from the specified group of parameter values.

- ## Method Details

  - ### 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).