# Class MathTransformBuilder

Object
MathTransformBuilder

public abstract class MathTransformBuilder extends Object
Builder of a parameterized math transform using a method identified by a name or code. A builder instance is created by a call to `DefaultMathTransformFactory​.builder(String)`. The parameters are set to default values and should be modified in-place by the caller. If the transform requires semi-major and semi-minor axis lengths, those parameters can be set directly or indirectly. Then, the transform is created by a call to `create()`.

Since:
  1.5

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final MathTransformFactory`
  `factory`
  The factory to use for building the transform.
  `protected OperationMethod`
  `provider`
  The provider that created the parameterized `MathTransform` instance, or `null` if this information does not apply.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `MathTransformBuilder(MathTransformFactory factory)`
  Creates a new builder.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract MathTransform`
  `create()`
  Creates the parameterized transform.
  `final Optional<OperationMethod>`
  `getMethod()`
  Returns the operation method used for creating the math transform from the parameter values.
  `abstract ParameterValueGroup`
  `parameters()`
  Returns the parameter values of the transform to create.
  `void`
  `setSourceAxes(CoordinateSystem cs, Ellipsoid ellipsoid)`
  Gives hints about axis lengths and their orientations in input coordinates.
  `void`
  `setTargetAxes(CoordinateSystem cs, Ellipsoid ellipsoid)`
  Gives hints about axis lengths and their orientations in output coordinates.
  `String`
  `toString()`
  Returns a string representation of this builder for debugging purposes.
  `protected MathTransform`
  `unique(MathTransform result)`
  Eventually replaces the given transform by a unique instance.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### factory

    protected final MathTransformFactory factory
    The factory to use for building the transform.

  - ### provider

    protected OperationMethod provider
    The provider that created the parameterized `MathTransform` instance, or `null` if this information does not apply. This is initially set to the operation method specified in the call to
    invalid reference

        #builder(String)

    , but may be modified by `create()`.

    This operation method is usually an instance of `MathTransformProvider`, but not necessarily.

    See Also:
      - `getMethod()`

- ## Constructor Details

  - ### MathTransformBuilder

    protected MathTransformBuilder(MathTransformFactory factory)
    Creates a new builder.
    Parameters:
      `factory` - factory to use for building the transform.

- ## Method Details

  - ### getMethod

    public final Optional<OperationMethod> getMethod()
    Returns the operation method used for creating the math transform from the parameter values. This is initially the operation method specified in the call to
    invalid reference

        #builder(String)

    , but may change after the call to `create()` if the method has been adjusted because of the parameter values.
    Returns:
      the operation method used for creating the math transform from the parameter values.

  - ### parameters

    public abstract ParameterValueGroup parameters()
    Returns the parameter values of the transform to create. Those parameters are initialized to default values, which may be implementation or method depend. User-supplied values should be set directly in the returned instance with codes like `parameter(`name`).setValue(`value`)`.
    Returns:
      the parameter values of the transform to create. Values should be set in-place.

  - ### setSourceAxes

    public void setSourceAxes(CoordinateSystem cs, Ellipsoid ellipsoid)
    Gives hints about axis lengths and their orientations in input coordinates. The action performed by this call depends on the operation method. For map projections, the action may include something equivalent to the following code:

        parameters().parameter("semi_major").setValue(ellipsoid.getSemiMajorAxis(), ellipsoid.getAxisUnit());
        parameters().parameter("semi_minor").setValue(ellipsoid.getSemiMinorAxis(), ellipsoid.getAxisUnit());

    For geodetic datum shifts, the action may be similar to above code but with different parameter names: `"src_semi_major"` and `"src_semi_minor"`. Other operation methods may ignore the arguments.

    #### Axis order, units and direction

    By default, the source axes of a parameterized transform are normalized to east, north, up (if applicable) directions with units in degrees and meters. If this requirement is ambiguous, for example because the operation method uses incompatible axis directions or units, then the `cs` argument should be non-null for allowing the implementation to resolve that ambiguity.
    Parameters:
      `cs` - the coordinate system defining source axis order and units, or `null` if none.
      `ellipsoid` - the ellipsoid providing source semi-axis lengths, or `null` if none.

  - ### setTargetAxes

    public void setTargetAxes(CoordinateSystem cs, Ellipsoid ellipsoid)
    Gives hints about axis lengths and their orientations in output coordinates. The action performed by this call depends on the operation method. For datum shifts, the action may include something equivalent to the following code:

        parameters().parameter("tgt_semi_major").setValue(ellipsoid.getSemiMajorAxis(), ellipsoid.getAxisUnit());
        parameters().parameter("tgt_semi_minor").setValue(ellipsoid.getSemiMinorAxis(), ellipsoid.getAxisUnit());

    #### Axis order, units and direction

    By default, the target axes of a parameterized transform are normalized to east, north, up (if applicable) directions with units in degrees and meters. If this requirement is ambiguous, for example because the operation method uses incompatible axis directions or units, then the `cs` argument should be non-null for allowing the implementation to resolve that ambiguity.
    Parameters:
      `cs` - the coordinate system defining target axis order and units, or `null` if none.
      `ellipsoid` - the ellipsoid providing target semi-axis lengths, or `null` if none.

  - ### create

    public abstract MathTransform create() throws FactoryException
    Creates the parameterized transform. The operation method is given by `getMethod()` and the parameter values should have been set on the group returned by `parameters()` before to invoke this constructor. Example:

        MathTransformFactory  factory = ...;
        MathTransformBuilder builder = factory.builder("Transverse_Mercator");
        ParameterValueGroup   pg = builder.parameters();
        pg.parameter("semi_major").setValue(6378137.000);
        pg.parameter("semi_minor").setValue(6356752.314);
        MathTransform mt = builder.create();

    Returns:
      the parameterized transform.
    Throws:
      `FactoryException` - if the transform creation failed. This exception is thrown if some required parameters have not been supplied, or have illegal values.

  - ### unique

    protected MathTransform unique(MathTransform result)
    Eventually replaces the given transform by a unique instance. The replacement is done only if the factory is an instance of `DefaultMathTransformFactory` and caching is enabled.

    This is a helper method for `create()` implementations.

    Parameters:
      `result` - the newly created transform.
    Returns:
      a transform equals to the given transform (may be the given transform itself).

  - ### toString

    public String toString()
    Returns a string representation of this builder for debugging purposes.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this builder.