org.apache.sis.referencing.operation.transform

## Interface MathTransformProvider

-     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 and 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, implementors 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).

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.