Module org.apache.sis.referencing
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 module path. 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(Map.of(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 class name of that implementation shall be declared in `module-info​.java` as a provider of the `org​.opengis​.referencing​.operation​.OperationMethod` service.

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

- ## 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 cannot be created for some other reason (for example a required file was not found).