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 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 module path. 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(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.Operation­Method service.

Since:

0.6

See Also:

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

Method Summary

Modifier and Type	Method	Description
Math­Transform	create­Math­Transform(Math­Transform­Factory factory, Parameter­Value­Group 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:

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