org.apache.sis.referencing.operation.builder

## Class LinearTransformBuilder

- Object
- - TransformBuilder
  - - LinearTransformBuilder

-     public class LinearTransformBuilder
      extends TransformBuilder

  Creates an affine transform which will map approximatively the given source positions to the given target positions. In many cases, the source positions are grid indices and the target positions are geographic or projected coordinates, but this is not mandatory. If the source positions are known to be grid indices, then a builder created by the `LinearTransformBuilder(int...)` constructor will be more efficient. Otherwise a builder created by the `LinearTransformBuilder()` constructor will be able to handle randomly distributed coordinates.

  The transform coefficients are determined using a least squares estimation method, with the assumption that source positions are exact and all the uncertainty is in the target positions.

  Since:
    0.5
  See Also:
    `LocalizationGridBuilder`, `LinearTransform`, `Line`, `Plane`

  Defined in the `sis-referencing` module

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `LinearTransformBuilder()` Creates a new linear transform builder for randomly distributed positions.
    `LinearTransformBuilder(int... gridSize)` Creates a new linear transform builder for source positions distributed on a regular grid.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `double[]` | `correlation()` Returns the correlation coefficients of the last transform created by `create()`, or `null` if none.
    `LinearTransform` | `create()` Deprecated. Replaced by `create(MathTransformFactory)`.
    `LinearTransform` | `create(MathTransformFactory factory)` Creates a linear transform approximation from the source positions to the target positions.
    `double[]` | `getControlPoint(int[] source)` Returns a single target coordinate for the given source coordinate, or `null` if none.
    `int` | `getSourceDimensions()` Returns the number of dimensions in source positions.
    `int` | `getTargetDimensions()` Returns the number of dimensions in target positions.
    `void` | `setControlPoint(int[] source, double[] target)` Sets a single matching control point pair.
    `void` | `setControlPoints(Map<? extends Position,? extends Position> sourceToTarget)` Sets all matching control point pairs, overwriting any previous setting.
    `void` | `setSourcePoints(DirectPosition... points)` Deprecated. Replaced by `setControlPoints(Map)`.
    `void` | `setTargetPoints(DirectPosition... points)` Deprecated. Replaced by `setControlPoints(Map)`.
    `String` | `toString()` Returns a string representation of this builder for debugging purpose.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### LinearTransformBuilder

          public LinearTransformBuilder()

      Creates a new linear transform builder for randomly distributed positions.
      Tip: if the source coordinates are grid indices, then the `LinearTransformBuilder(int...)` constructor will create a more efficient builder.

    - #### LinearTransformBuilder

          public LinearTransformBuilder(int... gridSize)

      Creates a new linear transform builder for source positions distributed on a regular grid. This constructor notifies `LinearTransformBuilder` that ordinate values of all source positions will be integers in the [0 … `gridSize[0]`-1] range for the first dimension (typically column indices), in the [0 … `gridSize[1]`-1] range for the second dimension (typically row indices), etc. The dimension of all source positions is the length of the given `gridSize` array.

      An empty array is equivalent to invoking the no-argument constructor, i.e. no restriction is put on the source coordinates.

      Parameters:
        `gridSize` - the number of integer ordinate values in each grid dimension.
      Throws:
        `IllegalArgumentException` - if a grid size is not strictly positive, or if the product of all values (∏`gridSize`) is greater than `Integer​.MAX_VALUE`.
      Since:
        0.8

  - ### Method Detail

    - #### getSourceDimensions

          public int getSourceDimensions()

      Returns the number of dimensions in source positions.
      Returns:
        the dimension of source points.
      Throws:
        `IllegalStateException` - if the number of source dimensions is not yet known.
      Since:
        0.8
      See Also:
        `MathTransform​.getSourceDimensions()`

    - #### getTargetDimensions

          public int getTargetDimensions()

      Returns the number of dimensions in target positions.
      Returns:
        the dimension of target points.
      Throws:
        `IllegalStateException` - if the number of target dimensions is not yet known.
      Since:
        0.8
      See Also:
        `MathTransform​.getTargetDimensions()`

    - #### setControlPoints

          public void setControlPoints(Map<? extends Position,? extends Position> sourceToTarget)
                                throws MismatchedDimensionException

      Sets all matching control point pairs, overwriting any previous setting. The source positions are the keys in the given map, and the target positions are the associated values in the map. The map should not contain two entries with the same source position. Coordinate reference systems are ignored. Null positions are silently ignored.

      All source positions shall have the same number of dimensions (the source dimension), and all target positions shall have the same number of dimensions (the target dimension). However the source dimension does not need to be the same the target dimension. Apache SIS currently supports only one- or two-dimensional source positions, together with arbitrary target dimension.

      If this builder has been created with the `LinearTransformBuilder(int...)` constructor, then the ordinate values of all source positions shall be integers in the [0 … `gridSize[0]`-1] range for the first dimension (typically column indices), in the [0 … `gridSize[1]`-1] range for the second dimension (typically row indices), etc. This constraint does not apply for builders created with the `LinearTransformBuilder()` constructor.

      Parameters:
        `sourceToTarget` - a map of source positions to target positions. Source positions are assumed precise and target positions are assumed uncertain.
      Throws:
        `IllegalArgumentException` - if this builder has been created for a grid but some source ordinates are not indices in that grid.
        `MismatchedDimensionException` - if some positions do not have the expected number of dimensions.
      Since:
        0.8

    - #### setControlPoint

          public void setControlPoint(int[] source,
                                      double[] target)

      Sets a single matching control point pair. Source position is assumed precise and target position is assumed uncertain. If the given source position was already associated with another target position, then the old target position is discarded.
      Performance note: current implementation is efficient for builders created for a grid but inefficient for builders created for randomly distributed points. In the later case, the `setControlPoints(Map)` method is a more efficient alternative.
      Parameters:
        `source` - the source coordinates. If this builder has been created with the `LinearTransformBuilder(int...)` constructor, then for every index i the `source[i]` value shall be in the [0 … `gridSize[i]`-1] range inclusive. If this builder has been created with the `LinearTransformBuilder()` constructor, then no constraint apply.
        `target` - the target coordinates, assumed uncertain.
      Throws:
        `IllegalArgumentException` - if this builder has been created for a grid but some source ordinates are out of index range.
        `MismatchedDimensionException` - if the source or target position does not have the expected number of dimensions.
      Since:
        0.8

    - #### getControlPoint

          public double[] getControlPoint(int[] source)

      Returns a single target coordinate for the given source coordinate, or `null` if none. This method can be used for retrieving points set by previous calls to `setControlPoint(int[], double[])` or `setControlPoints(Map)`.
      Performance note: current implementation is efficient for builders created for a grid but inefficient for builders created for randomly distributed points.
      Parameters:
        `source` - the source coordinates. If this builder has been created with the `LinearTransformBuilder(int...)` constructor, then for every index i the `source[i]` value shall be in the [0 … `gridSize[i]`-1] range inclusive. If this builder has been created with the `LinearTransformBuilder()` constructor, then no constraint apply.
      Returns:
        the target coordinates associated to the given source, or `null` if none.
      Throws:
        `IllegalArgumentException` - if this builder has been created for a grid but some source ordinates are out of index range.
        `MismatchedDimensionException` - if the source position does not have the expected number of dimensions.
      Since:
        0.8

    - #### setSourcePoints

          @Deprecated
          public void setSourcePoints(DirectPosition... points)
                                           throws MismatchedDimensionException

      Deprecated. Replaced by `setControlPoints(Map)`.
      Sets the source points, overwriting any previous setting. The number of source points will need to be the same than the number of target points when the `create()` method will be invoked. In current Apache SIS implementation, the source points must be one or two-dimensional.

      If this builder has been created with the `LinearTransformBuilder(int...)` constructor, then all given points must be two-dimensional and all ordinate values must be integers in the [0 … width-1] or [0 … height-1] range for the first and second dimension respectively. This constraint does not apply if this builder has been created with the `LinearTransformBuilder()` constructor.

      It is caller's responsibility to ensure that no source point is duplicated. If the same source point is repeated twice, then `LinearTransformBuilder` behavior is undefined.

      Parameters:
        `points` - the source points, assumed precise.
      Throws:
        `MismatchedDimensionException` - if at least one point does not have the expected number of dimensions.

    - #### setTargetPoints

          @Deprecated
          public void setTargetPoints(DirectPosition... points)
                                           throws MismatchedDimensionException

      Deprecated. Replaced by `setControlPoints(Map)`.
      Sets the target points, overwriting any previous setting. The number of target points will need to be the same than the number of source points when the `create()` method will be invoked. Target points can have any number of dimensions (not necessarily 2), but all points shall have the same number of dimensions.
      Parameters:
        `points` - the target points, assumed uncertain.
      Throws:
        `MismatchedDimensionException` - if not all points have the same number of dimensions.

    - #### create

          @Deprecated
          public LinearTransform create()

      Deprecated. Replaced by `create(MathTransformFactory)`.
      Creates a linear transform approximation from the source positions to the target positions. This method assumes that source positions are precise and that all uncertainty is in the target positions.
      Returns:
        the fitted linear transform.

    - #### create

          public LinearTransform create(MathTransformFactory factory)
                                 throws FactoryException

      Creates a linear transform approximation from the source positions to the target positions. This method assumes that source positions are precise and that all uncertainty is in the target positions.
      Specified by:
        `create` in class `TransformBuilder`
      Parameters:
        `factory` - the factory to use for creating the transform, or `null` for the default factory. The `MathTransformFactory​.createAffineTransform(Matrix)` method of that factory shall return `LinearTransform` instances.
      Returns:
        the fitted linear transform.
      Throws:
        `FactoryException` - if the transform can not be created, for example because the source or target points have not be specified.
      Since:
        0.8

    - #### correlation

          public double[] correlation()

      Returns the correlation coefficients of the last transform created by `create()`, or `null` if none. If non-null, the array length is equals to the number of target dimensions.
      Returns:
        estimation of correlation coefficients for each target dimension, or `null`.

    - #### toString

          @Debug
          public String toString()

      Returns a string representation of this builder for debugging purpose.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this builder.

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