org.apache.sis.referencing.operation.transform

Interface MathTransformProvider

public interface MathTransformProvider

An object capable to create Math­Transform 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 Default­Operation­Method, but this is not mandatory. This interface can also be used alone since Math­Transform instances can be created for other purpose than coordinate operations.

This interface is generally not used directly. The recommended way to get a Math­Transform is to find the coordinate operation (generally from a pair of source and target CRS), then to invoke Coordinate­Operation.get­Math­Transform(). Alternative, one can also use a math transform factory

How to add custom coordinate operations to Apache SIS

Default­Math­Transform­Factory 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 Math­Transform­Provider interface and the Operation­Method one. While not mandatory, we suggest to extend Default­Operation­Method. 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:

Default­Operation­Method, Default­Math­Transform­Factory, Abstract­Math­Transform

Defined in the sis-referencing module

Method Summary

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:

Invalid­Parameter­Name­Exception - if the given parameter group contains an unknown parameter.

Parameter­Not­Found­Exception - if a required parameter was not found.

Invalid­Parameter­Value­Exception - if a parameter has an invalid value.

Factory­Exception - if the math transform can not be created for some other reason (for example a required file was not found).