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 Default­Math­Transform­Factory​.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 Details

    • factory

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

      protected OperationMethod provider
      The provider that created the parameterized Math­Transform 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 Math­Transform­Provider, but not necessarily.

      See Also:
  • 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).set­Value(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 get­Method() 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:
      Factory­Exception - 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 Default­Math­Transform­Factory 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:
      to­String in class Object
      Returns:
      a string representation of this builder.